antpath 0.3.1 → 0.4.0

package/docs/credentials.md

@@ -35,9 +35,7 @@ import {
 } from "antpath";
 
 const client = new AntpathClient({
-  baseUrl: "https://dashboard.antpath.dev",
-  apiToken: "ant_...",
-  workspaceId: "ws_..."
+  apiToken: "ant_..."
 });
 
 const proxyEndpoints = [

package/docs/quickstart.md

@@ -4,18 +4,17 @@ title: antpath quickstart
 
 # Quickstart
 
-1. Get an antpath dashboard URL, a workspace-scoped SDK API token (`ant_…`), and your workspace id.
+1. Get an antpath SDK API token (`ant_…`).
 2. Define a secret-free Template in TypeScript (or JSON / a `.mjs` default export).
-3. Create `AntpathClient`.
+3. Create `AntpathClient` — the workspace is derived server-side from the token.
 4. Submit the run with an inline `secrets` bundle. Wait for terminal status. Fetch outputs.
 
 ```ts
 import { AntpathClient, defineTemplate, string } from "antpath";
 
 const client = new AntpathClient({
-  baseUrl: "https://antpath.example.com",
-  apiToken: process.env.ANTPATH_API_TOKEN!,
-  workspaceId: process.env.ANTPATH_WORKSPACE_ID!
+  apiToken: process.env.ANTPATH_API_TOKEN!
+  // baseUrl defaults to https://antpath.ai — set it for self-hosted deployments.
 });
 
 const template = defineTemplate({
@@ -40,8 +39,6 @@ Or from the shell:
 ```bash
 antpath run ./template.json \
   --api-token "$ANTPATH_API_TOKEN" \
-  --workspace "$ANTPATH_WORKSPACE_ID" \
-  --dashboard-url https://antpath.example.com \
   --anthropic-api-key "$ANTHROPIC_API_KEY" \
   --var topic="agent-first SDK design" \
   --follow

package/docs/release.md

@@ -4,19 +4,64 @@ title: Release
 
 # Release
 
-CI runs on pull requests and pushes to `main`.
+Releasing is **atomic** and **driven by `packages/sdk/package.json#version`**: bump the SDK version on `main` and the publish pipeline carries that exact version through npm → git tag → GitHub Release in one job. Any push to `main` that does not bump the version is a publish no-op.
 
-Publishing runs when a GitHub release is published, or when the publish workflow is manually dispatched.
+## How to ship a release
 
-Repository setup required:
+1. On a branch, bump `packages/sdk/package.json#version` to the next semver. Land any companion code/doc changes in the same PR.
+2. Merge into `main` (or push directly if you have the right). The pre-push hook (see [Local guard rails](#local-guard-rails)) refuses the push if the local version still matches what's on npm or has already been git-tagged.
+3. CI (`.github/workflows/ci.yml`) runs the `version-gate` job on every PR and direct push to `main`. It diffs against the base ref using [`scripts/check-version-drift.mjs --strict`](../../scripts/check-version-drift.mjs) and fails fast if anything under `packages/{sdk,cli,shared}/src/` or the listed exact paths changed without a fresh version. **`--strict` treats unreachable npm as a hard failure** so we never publish on top of an existing version.
+4. After merge, the `Publish package` workflow (`.github/workflows/publish.yml`) is triggered automatically on push to `main` and decides whether to ship.
 
-1. Create or reserve the `antpath` package on npm.
-2. Add a Trusted Publisher for this GitHub repository.
-3. Set **Organization or user** to `weilueluo`.
-4. Set **Repository** to `antpath`.
-5. Set **Workflow filename** to `publish.yml`.
-6. Leave **Environment name** empty unless the workflow uses a matching GitHub Actions environment.
-7. Update `packages/sdk/package.json` version before publishing a release.
-8. Publish a GitHub release for that version.
+You don't tag locally and you don't open a GitHub Release manually — the workflow does both. If the workflow ends red after a successful `npm publish`, the npm version is the source of truth and a human can tag/release retroactively.
 
-The publish workflow uses GitHub OIDC through `id-token: write`; it does not require an npm token secret. It runs type-checks, tests, build, then publishes the `antpath` SDK workspace with provenance.
+## Publish pipeline
+
+The workflow has three jobs, in this order:
+
+1. **`decide`** — compares the local `packages/sdk/package.json#version` with `npm view antpath@latest version`.
+   - If they match → output `proceed=false` and the rest of the pipeline no-ops. Documentation-only commits, refactors that ride along with a previous version, and any other non-publishable change pass through cleanly.
+   - If they differ → `proceed=true`, with the local version flowing forward as the canonical `v<version>` for tagging and release notes.
+2. **`publish`** (gated on `proceed=true`) — single linear job:
+   - `pnpm install --frozen-lockfile`, `pnpm lint`, `pnpm test`, `pnpm build`.
+   - `pnpm --filter antpath pack` into `$RUNNER_TEMP`.
+   - **Pre-publish user-tests gate**: runs `apps/user-tests` `user-test:offline` against the packed tarball. A broken artifact (missing `bin`, broken shebang, leaked workspace dep, ESM-only contract violation, …) never reaches npm.
+   - **Final freshness check**: `npm view antpath@${VERSION} version` — guards the rare race where someone else publishes the same version between `decide` and here.
+   - `pnpm publish --provenance --no-git-checks` from `packages/sdk`. Auth is GitHub OIDC via `id-token: write` plus npm Trusted Publishers — there is no `NPM_TOKEN` secret.
+   - `git tag -a v${VERSION}` signed as the canonical commit identity, then `git push origin v${VERSION}`.
+   - `gh release create v${VERSION} --generate-notes`.
+3. **`user-tests-post-publish`** (matrix `ubuntu-latest, windows-latest`) — waits for registry visibility with `scripts/wait-for-npm.mjs antpath <version>` (catches the "metadata says yes but CDN tarball 404s" case), then runs `user-test:offline` against the published version on both runners.
+
+Atomicity boundary: **publish + tag + GitHub Release happen in the same job**. Until that job goes green, the release is not done — even if `npm publish` already succeeded. Post-publish user-tests are a follow-on signal, not part of the atomic act.
+
+## What ships in the tarball
+
+The published tarball is **self-contained**. It declares **zero `@antpath/*` runtime dependencies** and is installable from a clean `npm install antpath` with no workspace access:
+
+- `@antpath/shared` lives in `packages/sdk/package.json#devDependencies` only. At build time, [`packages/sdk/scripts/inline-shared.mjs`](../scripts/inline-shared.mjs) copies `packages/shared/dist/**` (minus the test-only `testing/` directory and sourcemaps) into `packages/sdk/dist/_shared/` and rewrites `from "@antpath/shared"` to `from "./_shared/index.js"` across the SDK dist tree. A sanity check at the end of that script refuses to finish if any bare `@antpath/shared` specifier survives.
+- `@antpath/cli` is bundled at build time by [`packages/sdk/scripts/bundle-cli.mjs`](../scripts/bundle-cli.mjs) into a single `dist/cli.mjs`, which is the `bin: antpath` entry in `packages/sdk/package.json`.
+- This invariant is mechanically enforced by `apps/user-tests/test/offline/install.test.ts` ("declares no @antpath/* runtime dependencies") — the pre-publish gate fails before npm if any workspace dep leaks back into `dependencies`/`peerDependencies`/`optionalDependencies`.
+
+## Local guard rails
+
+Every contributor who pushes is expected to install the tracked pre-push hook from the repo root once:
+
+```text
+pnpm hooks:install
+```
+
+The hook runs lint, tests, build, an SDK pack dry-run, and `check-version-drift.mjs` (advisory mode — unreachable npm is a warning so offline development still works). It catches "I bumped a runtime file but forgot to bump the version" or "the new version is already on npm" before the push leaves the laptop.
+
+## Repository setup (one-time)
+
+1. Reserve `antpath` on npm.
+2. Add a Trusted Publisher for this repository (`npmjs.com` → *Settings* → *Publishing access*):
+   - **Organization or user**: `weilueluo`
+   - **Repository**: `antpath`
+   - **Workflow filename**: `publish.yml`
+   - **Environment name**: leave empty.
+3. No `NPM_TOKEN` secret is required — OIDC handles auth.
+
+## Rollback
+
+There is no "unpublish" path: npm prevents reuse of a published version, and a bad release is fixed by publishing a higher version. If the atomic publish job dies between `npm publish` and `gh release create`, retag manually (`git tag -a v<version>`, push, `gh release create`); npm is already truthful.

package/examples/mcp-static-bearer.ts

@@ -1,9 +1,7 @@
 import { AntpathClient, defineTemplate, requiredStaticBearer } from "antpath";
 
 const client = new AntpathClient({
-  baseUrl: process.env.ANTPATH_DASHBOARD_URL!,
-  apiToken: process.env.ANTPATH_API_TOKEN!,
-  workspaceId: process.env.ANTPATH_WORKSPACE_ID!
+  apiToken: process.env.ANTPATH_API_TOKEN!
 });
 
 const template = defineTemplate({

package/examples/quickstart.ts

@@ -1,9 +1,7 @@
 import { AntpathClient, defineTemplate, string } from "antpath";
 
 const client = new AntpathClient({
-  baseUrl: process.env.ANTPATH_DASHBOARD_URL!,
-  apiToken: process.env.ANTPATH_API_TOKEN!,
-  workspaceId: process.env.ANTPATH_WORKSPACE_ID!
+  apiToken: process.env.ANTPATH_API_TOKEN!
 });
 
 const template = defineTemplate({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "antpath",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "TypeScript SDK for running autonomous Claude Managed Agents sessions.",
   "repository": {
     "type": "git",
@@ -22,8 +22,7 @@
     "dist",
     "README.md",
     "docs",
-    "examples",
-    "references"
+    "examples"
   ],
   "devDependencies": {
     "@antpath/shared": "0.1.0"

package/references/architecture-decisions.md

@@ -1,473 +0,0 @@
----
-title: antpath architecture decisions
-status: accepted
-scope: platform MVP
----
-
-# antpath architecture decisions
-
-## Product framing
-
-antpath is a TypeScript-first platform plus SDK for running autonomous sessions on provider-managed agent infrastructure. Claude Managed Agents remains the execution runtime. antpath provides the durable control plane around it: submit jobs, dispatch provider sessions, track tenant-scoped metadata, observe lifecycle state, capture configured outputs, enforce quotas, and retain or clean up provider resources according to run policy.
-
-The platform is intentionally not a custom agent loop or sandbox runtime. The worker dispatches, observes, stores metadata, captures outputs, and applies retention/cleanup policy. It does not execute tools, approve tool calls, or participate in provider-side reasoning.
-
-This supersedes the earlier SDK-only MVP boundary.
-
-## Goals
-
-- Stable start-to-finish lifecycle for provider-managed agent runs.
-- Minimal tenant-scoped dashboard metadata for monitoring run execution.
-- Durable worker recovery after restarts, deploys, crashes, or missed notifications.
-- Horizontal worker scaling without duplicate run ownership.
-- Provider cleanup by default after terminal states, with optional retention of Claude-side resources when configured per-request or per-deployment.
-- Per-session BYO provider key custody: keys arrive inline with each run, are encrypted in Supabase Vault for the lifetime of that single run, and are deleted at cleanup. Persistent workspace-level provider key custody is backlog.
-- Unconditional capture of every session-scoped Claude artifact into private Supabase Storage, bounded only by the workspace storage cap.
-- Programmatic SDK access for submitting and observing platform runs.
-- Test-driven implementation across SDK, dashboard, worker, database, storage, and provider adapters.
-
-## Non-goals for platform MVP
-
-- No custom agent loop.
-- No antpath-managed sandbox.
-- No runtime human approval/tool approval flow.
-- No direct browser access to provider APIs.
-- No direct browser Supabase data access.
-- No raw prompt, raw model output, raw provider event payload, MCP credential, provider key, or output file content in normal application tables.
-- No persistent workspace-level provider connections (no "saved Anthropic keys"). Every run carries its own secrets bundle; nothing about the user's Anthropic key persists past run cleanup. Persistent BYO custody is backlog.
-- No user-configurable output capture: every artifact Claude exposes on the run's session is captured. There are no globs, no `capture: false`, no per-file or per-run user-visible caps.
-- No provider Agent/Environment caching in MVP.
-- No provider webhooks in MVP.
-- No Supabase Realtime in MVP.
-- No OpenAI or other provider integration in MVP.
-
-## Core decisions
-
-| Area | Decision |
-| --- | --- |
-| Product surface | Platform plus SDK. |
-| Repository | Convert the repository to a pnpm TypeScript workspace. |
-| SDK location | Move the existing SDK package to `packages/sdk`. |
-| SDK role | The SDK submits runs and observes status, metadata, outputs, cancellation, and deletion through the platform API. |
-| Dashboard | Build a first-party minimal dashboard. |
-| Worker | Run a Railway persistent service, designed as ephemeral and horizontally scalable. |
-| Database | Use Supabase Postgres as the source of truth. |
-| Storage | Use private Supabase Storage buckets for captured outputs. |
-| Auth | Use Auth.js for user authentication, not Supabase Auth. |
-| Tenant model | Workspace is the tenant boundary. |
-| Membership | Users access workspaces through `workspace_memberships`. |
-| Authorization boundary | Vercel BFF/server actions validate Auth.js sessions or SDK API tokens and scope every DB operation by workspace membership/scope. |
-| Browser data access | Browser code talks to the BFF/server actions, not directly to Supabase data APIs. |
-| Service credentials | Supabase service-role credentials are server/worker only. |
-| SDK auth | SDK uses hashed, workspace-scoped API tokens. Dashboard uses Auth.js sessions. |
-| API token attribution | Token-authenticated runs are attributed to the token creator at submission time unless a future service-account model is introduced. |
-| Provider key custody | BYO Anthropic key arrives inline with every run submission. The BFF stores the secrets bundle in Supabase Vault, attaches the secret id to the run row, and deletes the Vault entry as part of cleanup. Persistent workspace-level provider connections are backlog. |
-| Secret lifetime | Worker resolves the per-run secrets bundle once per claimed lifecycle step, keeps the decoded payload only in memory for that step, and drops it before lease release. The Vault entry itself is destroyed when the run reaches terminal cleanup. |
-| Provider resources | Create provider Agent, Environment, Vault/Credential, Session, and file resources per run in MVP. |
-| Provider resource caching | Backlog; later cache Agent/Environment by Template/config hash. |
-| Worker wakeup | Poll due rows from the runs table. Postgres `NOTIFY` is a latency optimization only. |
-| Worker ownership | Use DB leases, `FOR UPDATE SKIP LOCKED`, lease tokens, and expiry for horizontally scaled workers. |
-| Provider observation | Poll provider session status and list provider events since the last cursor/timestamp where available. |
-| Event dedupe | Provider event id is the dedupe authority; cursor/timestamp is advisory. |
-| Webhooks | Backlog only; if added, use as wakeup/reconciliation signals, not sole source of truth. |
-| SSE | Not the primary monitoring mechanism in MVP. |
-| MCP approvals | Disallow approval-required tools. Worker must not approve tools or return custom tool results. |
-| Template boundary | Templates are code-first, secret-free snapshots with stable hashes. |
-| Idempotency | Run submission idempotency is scoped by `(workspace_id, idempotency_key)` and request hash. Same key and same hash returns the existing run; same key and different hash returns conflict. |
-| Quotas | Enforce workspace storage and concurrency quotas. Storage is the only user-visible cap on output capture. |
-| Run caps | Plan-based caps cover duration, concurrency, polling, retries, and workspace storage. There are no user-visible per-file or per-run output caps. |
-| Operational config | Exact cap/tier values are environment-configurable defaults with conservative fallbacks and run-level snapshots. |
-| Boot-time env validation | Worker and dashboard validate required environment variables at startup through a shared role-scoped helper and exit/abort with an aggregated error when any are missing. No silent defaults for identity, credentials, or required URLs. |
-| Output capture | Unconditional. Every file Claude exposes on the run's session is captured into private Supabase Storage. The workspace storage cap is the only user-visible quota; capture failures (quota exceeded, download failed) are persisted as `output_capture_failures` rows and surfaced in the dashboard alongside successful outputs. |
-| Output access | BFF returns signed links only after workspace authorization. |
-| Cleanup | Clean up Claude provider resources by default after terminal state and output capture; explicit run policy or worker default can retain Claude-side resources for inspection. The per-run Vault secret is always deleted at cleanup regardless of the Claude-side retention knob. |
-| Delete semantics | User delete is soft/pending while execution, cleanup, or storage deletion is active. Hard purge happens only after cleanup/storage deletion succeeds. |
-| Retention | Run metadata and stored outputs remain until user deletion in MVP. |
-| Realtime | Defer from MVP; use BFF-mediated refresh/polling first. Revisit with custom Supabase JWT/RLS or a server-mediated realtime bridge. |
-| Development workflow | Use test-driven development: write or update the failing test at the narrowest useful layer before implementation. |
-
-## Workspace layout
-
-Target structure:
-
-```text
-apps/
-  dashboard/
-    app/
-    server/
-    components/
-    auth/
-    db/
-  worker/
-    src/
-      main.ts
-      polling/
-      providers/
-      lifecycle/
-      cleanup/
-      storage/
-      observability/
-packages/
-  sdk/
-    src/
-  shared/
-    src/
-      types/
-      status/
-      redaction/
-      templates/
-  db/
-    migrations/
-    schema/
-    queries/
-```
-
-`packages/shared` and `packages/db` may start small and grow only when invariants or schema/query helpers are shared by dashboard, worker, and SDK.
-
-## Core data model
-
-### Identity and tenancy
-
-- Auth.js adapter tables: `users`, `accounts`, `sessions`, and `verification_token`
-  - Auth.js owns OAuth account linking and email magic-link verification persistence in the same Supabase Postgres database.
-  - Active application sessions use Auth.js JWT strategy; the `sessions` table exists for adapter compatibility but is not the active session store.
-  - Auth.js OAuth tokens remain confined to Auth.js adapter tables and never become antpath provider credentials.
-- `app_users`
-  - Antpath-owned user identity row linked to Auth.js `users.id` through `auth_user_id`.
-  - Workspace membership, run attribution, API-token ownership, disable state, and JWT token-version checks use `app_users.id`.
-  - `disabled_at` and `token_version` are checked by privileged BFF routes to reject disabled or stale JWT users.
-  - No provider secrets.
-- `workspaces`
-  - Tenant boundary.
-  - Plan, quota, status, and retention settings.
-- `workspace_memberships`
-  - Workspace, `app_user_id`, role, and membership status.
-  - Every dashboard/API operation must prove membership/scope.
-- `api_tokens`
-  - Workspace-scoped SDK credentials.
-  - Store hashed token material only, plus scopes, `creator_app_user_id`, last-used timestamp, and revoked timestamp.
-  - API-token submissions freeze the attributed user on the run row at creation time.
-
-### Per-run secrets
-
-There is no `provider_connections` table in MVP. Every run carries its own secrets.
-
-- The submission contract has a top-level `secrets` block: `{ anthropic: { apiKey }, mcpServers?: [{ name, url, headers? }], skills?: [...] }`. The shared parser enforces that **no other field** carries secret-bearing keys; the `secrets` block is the single allowlisted carrier and never serializes into normal metadata, logs, events, audit rows, or stored snapshots.
-- The dashboard BFF stores the JSON-encoded bundle in Supabase Vault at submission time and writes the resulting `vault_secret_id` into `runs.execution_secret_id`. The bundle is the only durable trace of the user's Anthropic key, MCP credentials, and skill references for that run.
-- Worker code reads `runs.execution_secret_id` once per claimed step, decodes the bundle in memory, builds the Claude provider, and drops the decoded values before lease release.
-- At terminal cleanup the worker deletes the Vault entry and clears `runs.execution_secret_id`. Cleanup of the Vault secret happens regardless of the Claude-side retention knob.
-- If the user revokes (rotates) the Anthropic key on Anthropic's side mid-run, antpath has no knowledge of this until the next provider call fails. Active runs surface a `tenant_permanent` failure with a redacted reason; cleanup proceeds with the previously vaulted key while it remains valid and gives up gracefully if it does not.
-
-### Runs
-
-- `runs`
-  - User-visible logical run.
-  - Workspace, `creator_app_user_id`, template snapshot/hash, status, lifecycle phase, plan caps, timestamps.
-  - Submission idempotency key and request hash.
-  - Unique constraint: `(workspace_id, idempotency_key)`.
-  - `execution_secret_id` — Supabase Vault secret id for the per-run secrets bundle (Anthropic key + MCP credentials + skill references). Cleared at cleanup.
-  - Lease fields: `lease_owner`, `lease_token`, `lease_expires_at`, `attempt_count`, `next_check_at`, `priority`.
-  - Cancellation/deletion fields: `cancel_requested_at`, `pending_delete_at`, `deleted_at`.
-  - Provider observation cursor/watermark where available.
-- `run_attempts`
-  - A logical run may have multiple provider attempts.
-  - Tracks provider session id, attempt state, start/end timestamps, and error classification.
-- `provider_resources`
-  - Journal of intended and created provider resources.
-  - Resource type, local idempotency key, deterministic provider name/metadata tags, provider id when known, cleanup status.
-  - Insert an intended row before provider side effects whenever possible.
-- `run_events`
-  - Metadata only.
-  - Provider event id/type, processed timestamp, redacted summary fields, usage metadata.
-  - Unique constraint on `(run_attempt_id, provider_event_id)`.
-  - No raw prompts, raw outputs, tool inputs/results, file contents, or credentials.
-
-### Outputs and cleanup
-
-- `output_objects`
-  - Workspace/run owner, storage bucket/path, size, checksum if available, content type, provider file id.
-  - One row per artifact successfully captured from the run's session into private Supabase Storage.
-  - Used for quota accounting and signed-link generation.
-- `output_capture_failures`
-  - Workspace/run owner, provider file id, filename, byte size as reported by the provider, reason (`workspace_quota_exceeded`, `download_failed`, etc.), redacted error message.
-  - Surfaced in the dashboard alongside `output_objects` so the user can see exactly which session artifacts didn't make it to storage and why.
-- `cleanup_attempts`
-  - Per-resource cleanup action, status, retry count, redacted error code/message, timestamps.
-- `usage_ledger`
-  - Token/cost/storage attribution by workspace and attributed user.
-  - Written transactionally with source event/output rows to avoid drift.
-- `audit_logs`
-  - Safe security audit trail for sign-in user upsert, API-token changes, run cancellation/deletion, signed-link creation, and cleanup failures.
-  - Stores safe identifiers, action names, redacted errors, and non-secret metadata only.
-- `rate_limit_buckets`
-  - Durable token-bucket-style counters for abuse-sensitive BFF/API operations.
-  - Used before side effects for run submission, run cancellation/deletion, signed-link creation, API-token creation/revocation, and email-auth throttling where practical.
-
-## Run lifecycle
-
-1. SDK/dashboard submits a run to the BFF. The submission carries a top-level `secrets` bundle (Anthropic key, optional MCP credentials, optional skill references) plus the non-secret template/variables/cleanup payload.
-2. BFF validates Auth.js session or SDK API token.
-3. BFF resolves active workspace membership/scope.
-4. BFF validates Template/request shape, plan limits, and idempotency key/request hash. The shared parser rejects every secret-bearing key outside the allowlisted `secrets` block.
-5. BFF stores the JSON-encoded `secrets` bundle in Supabase Vault and writes a `runs` row with execution-affecting cap values snapshotted from plan/env defaults plus `execution_secret_id` pointing at the Vault entry.
-6. BFF emits Postgres `NOTIFY` for fast wakeup.
-7. Worker claims due runs with row locking, `SKIP LOCKED`, lease token, and lease expiry.
-8. Worker resolves the per-run secrets bundle from Supabase Vault for the claimed step.
-9. Worker validates platform constraints: no approval-required tools, no custom antpath-executed tools.
-10. Worker pre-journals intended provider resources.
-11. Worker creates provider resources and records provider IDs immediately after successful calls.
-12. Worker creates provider session and sends the initial user event.
-13. Worker schedules provider polling through `next_check_at`.
-14. Worker later reclaims the run and polls provider session status plus event list.
-15. Worker stores only metadata events and usage, deduped by provider event id.
-16. Before every side effect, worker checks lease token and cancellation/deletion requests.
-17. On terminal provider state or antpath timeout, worker lists session-scoped files via the Claude Files API and unconditionally captures every file the workspace storage quota still has room for, persisting `output_capture_failures` rows for any file that would exceed the cap.
-18. Worker cleans up Claude-side provider resources by default, or records them as retained when the run/deployment policy asks to retain them. The per-run Vault entry is deleted regardless.
-19. Worker marks the run terminal and releases the lease.
-20. Dashboard/SDK read tenant-scoped metadata and signed output links through BFF APIs.
-
-## Worker concurrency and recovery
-
-The database is the coordination primitive. Worker instances are stateless and can be added or removed without losing correctness.
-
-Claiming rules:
-
-- Query due rows ordered by priority, fairness across workspaces, and `next_check_at`.
-- Use `FOR UPDATE SKIP LOCKED`.
-- Set `lease_owner`, `lease_token`, `lease_expires_at`, and attempt counters.
-- Commit immediately.
-- Execute one bounded lifecycle step outside long transactions.
-- Persist result and either schedule next step or mark terminal.
-
-Safety rules:
-
-- Every status-mutating update includes `WHERE lease_token = $token AND lease_expires_at > now()` and verifies exactly one affected row.
-- Every side-effecting step checks `cancel_requested_at` and `pending_delete_at`.
-- Expired leases are reclaimable by any worker.
-- `next_check_at` includes jitter.
-- Claiming enforces per-workspace active-run caps and provider-key-scoped rate limits.
-- Workers handle SIGTERM by stopping new claims and relying on bounded steps, idempotency, leases, and reconciliation for in-flight work.
-- Polling is always enabled; `NOTIFY` only reduces latency.
-
-## Provider observation
-
-MVP source of truth:
-
-- Provider session retrieve for status.
-- Provider session events list for event metadata and usage.
-
-Rules:
-
-- Cursor/timestamp filters are used when available.
-- Provider event id is always used for dedupe.
-- Phase 5 must verify Claude Managed Agents event pagination/filter semantics.
-- If no stable cursor or since filter exists, use a bounded re-list strategy with event-id dedupe instead of unbounded full-history scans.
-
-Excluded from MVP:
-
-- SSE as primary monitoring.
-- Anthropic webhooks as primary monitoring.
-
-## Auth and dashboard security
-
-Auth.js handles interactive user sign-in. SDK API tokens handle programmatic access.
-
-BFF/server actions must:
-
-- validate Auth.js session or API token;
-- resolve user identity and active workspace;
-- check workspace membership or token scope;
-- scope every query/mutation by workspace id;
-- return only metadata allowed by the user's role/scope;
-- keep Supabase service-role credentials out of browser bundles.
-
-Auth.js and antpath authorization stay separate in the database. Auth.js owns `users`, `accounts`, `sessions`, and `verification_token`; antpath owns `app_users` and links each row to Auth.js `users.id`. JWT callbacks expose only safe identity fields such as `app_user_id` and token version. BFF routes must load the current `app_users` row and reject disabled users or stale token versions before privileged actions.
-
-All platform and Auth.js tables have RLS enabled and `anon`/`authenticated` table privileges revoked. This is a defense-in-depth guard against accidental Supabase Data API exposure; direct `pg` repository code remains the primary BFF/worker authorization boundary for this phase.
-
-Supabase Realtime is backlog until antpath either mints short-lived Supabase-compatible JWTs with RLS policies or exposes a server-mediated realtime bridge.
-
-## Secret handling
-
-- Provider keys arrive inline with each submission and are stored in Supabase Vault tied to a single run via `runs.execution_secret_id`.
-- MCP credentials and any skill payloads referenced by the run live alongside the provider key inside the same per-run Vault bundle.
-- Normal app tables store only the Vault secret id, not decoded provider keys, MCP credentials, or skill payloads.
-- Worker resolves the decoded bundle only for a claimed lifecycle step and drops the decoded values before lease release.
-- The shared submission parser keeps an allowlist of exactly one carrier (`secrets`) and rejects every other field that looks like a secret-bearing key (`apiKey`, `accessToken`, `password`, `mcpCredentials`, etc.).
-- Secret values use explicit redacted wrappers in code so they cannot serialize into logs, metrics, errors, events, or fixtures.
-- Secret redaction applies to logs, errors, run metadata, provider events, tests, fixtures, and docs.
-- The per-run Vault entry is deleted as part of run cleanup. Cleanup of the Vault entry happens regardless of the Claude-side retention knob.
-- If a provider key is revoked or rotated on the provider side mid-run, the next provider call fails with a `tenant_permanent` error. The worker fails the affected run, attempts cleanup with whatever credentials are still valid, and surfaces a redacted reason on the dashboard.
-- There is no platform-side rotation/revocation flow because there is no persistent provider connection. To "rotate" the user simply submits the next run with a different key.
-
-## Output storage and quotas
-
-Output capture is unconditional. Every artifact the user's Claude session exposes is downloaded to private Supabase Storage. There are no user-facing knobs to opt out, no globs, and no per-file or per-run user-visible caps.
-
-Output flow:
-
-1. Worker lists files scoped to the run's Claude session: `GET /v1/files?scope_id=<session_id>`. Each entry includes `id`, `filename`, and `size_bytes`.
-2. For each file, before downloading, the worker checks `(workspace.storage_used_bytes + size_bytes)` against the workspace storage cap.
-3. If the file would exceed the cap, the worker writes an `output_capture_failures` row (`reason = "workspace_quota_exceeded"`, with filename and reported byte size) and moves on without downloading.
-4. Otherwise the worker downloads via `GET /v1/files/{file_id}/content` with a hard streaming safety cap so a malformed listing response cannot OOM the worker, uploads to private Supabase Storage at a workspace-scoped path, and writes an `output_objects` row.
-5. Other download/upload failures (network, storage, unexpected size) are recorded as `output_capture_failures` with the redacted reason.
-6. Dashboard/SDK request signed links through the BFF for any `output_objects` row.
-
-Quota rules:
-
-- Workspace storage cap is the only hard enforcement boundary. Default is generous (configurable via env, see [`environment-variables.md`](./environment-variables.md)).
-- There is no per-user quota. Per-user attribution still freezes on the run row at submission time for billing/audit purposes, but it is not a quota dimension.
-- There are no user-visible per-file or per-run caps. A worker-internal streaming safety cap protects against malformed listings.
-- Capture failures are first-class data: the dashboard renders `<filename> (<size>) — skipped: workspace quota exceeded` next to successful outputs so the user can see exactly what didn't make it.
-
-## Cleanup and reconciliation
-
-Claude provider-resource cleanup is mandatory by default after terminal provider state and output capture so antpath does not leave behind provider state. Retention is opt-in for **Claude-side resources only** through `cleanup.claudeSession = "retain"` or `ANTPATH_WORKER_CLAUDE_SESSION_CLEANUP_DEFAULT=retain`. Retained resources are recorded in `provider_resources.cleanup_status = retained` and remain reachable via the provider API. Antpath-side metadata, output objects, and the per-run Vault entry are not affected by this knob — Vault entries are always deleted at cleanup; metadata and outputs persist until the user explicitly deletes the run.
-
-Explicit cleanup order:
-
-1. Capture session-scoped files into private Supabase Storage (with quota pre-check; failures persisted).
-2. Provider session files / session where supported.
-3. Agent / archive.
-4. Environment / archive or delete where allowed.
-5. Skills uploaded for this session and any other ephemeral provider resources created for this run.
-6. Provider Vault/Credentials created on Claude's side for MCP wiring.
-7. The antpath per-run Vault entry: `vault.deleteSecret(runs.execution_secret_id)`, then clear the column.
-8. Local output metadata/storage only when the user deletes a run.
-
-Cleanup properties:
-
-- Retried independently from run execution.
-- Idempotent where provider APIs allow.
-- Redacted errors recorded in `cleanup_attempts`.
-- Runs can be terminal while cleanup remains pending or retryable-failed.
-- User deletion sets `pending_delete_at` while cleanup/storage deletion is active.
-
-Resource leak recovery:
-
-- Every provider create starts from a local intended row with deterministic provider name/metadata where provider APIs allow.
-- A reconciliation sweeper reviews unfinished intended rows, expired leases, and provider-listable resources tagged with antpath metadata.
-- If provider create succeeded but provider id was not persisted before a crash, the sweeper attempts to match by deterministic name/metadata and attach the provider id for cleanup.
-
-Workspace deletion:
-
-- Workspace deletion blocks new runs, requests cancellation for active runs, drains cleanup, deletes stored outputs, then purges metadata.
-- There is no separate "provider key revocation" flow because there is no persistent provider key. Submitting the next run with a different key is the rotation mechanism.
-
-## Audit, rate limits, quotas, and deletion
-
-- Abuse-sensitive actions are rate-limited before provider, Vault, Storage, or mutation side effects where practical.
-- Audit logs must never include provider keys, OAuth tokens, MCP credentials, raw prompts, raw outputs, signed URLs, or service-role credentials.
-- Workspace storage quota is enforced before output download/upload when file size is known, with streaming hard caps for unknown-size files.
-- App-user deletion is soft/disable-first; hard deletion must not break historical run, usage, output, or audit references.
-- Workspace deletion is pending-first: block new submissions, mark active runs pending-delete, allow cleanup/storage deletion to drain, then purge only safe metadata.
-- Recovery operations should be driven by explicit cleanup/deletion state and audit logs, not manual DB guessing.
-
-## Run state model
-
-Suggested run statuses:
-
-- `queued`
-- `claiming`
-- `provisioning`
-- `session_created`
-- `dispatched`
-- `provider_running`
-- `provider_idle`
-- `provider_rescheduled`
-- `cancelling`
-- `capturing_outputs`
-- `cleaning_up`
-- `succeeded`
-- `failed`
-- `timed_out`
-- `cancelled`
-- `cleanup_failed`
-- `pending_delete`
-- `deleted`
-
-Terminal user-facing run status is separate from cleanup state so a successful provider run can still show cleanup retry warnings.
-
-Error classes:
-
-- `transient_provider`: retry with backoff and jitter.
-- `provider_permanent`: fail attempt/run and cleanup.
-- `tenant_permanent`: invalid key, quota exceeded, invalid Template, approval-required event observed.
-- `antpath_bug`: fail safely, alert, and preserve cleanup work.
-- `cancelled_by_user`: cleanup and mark cancelled.
-
-## Deployment baseline
-
-- Dashboard: Vercel.
-- Worker: Railway persistent service with configurable replicas.
-- Database: Supabase Postgres.
-- Storage: Supabase Storage private bucket.
-- Secrets: Vercel/Railway environment variables plus Supabase Vault for tenant provider keys.
-- CI: GitHub Actions with pnpm, default lint/test/build/package checks, and a separate local Supabase integration job.
-- Local dev stack: `pnpm dev:stack` starts Supabase without printing local keys, validates local config, checks migrations, builds shared packages, and runs the dashboard and worker together. Missing Auth.js providers do not block local service startup unless `ANTPATH_DEV_STACK_REQUIRE_AUTH_PROVIDER=1` is set.
-
-Required runtime config includes:
-
-- database URL;
-- Supabase service credentials;
-- Supabase Storage bucket;
-- Supabase Vault access function/schema;
-- Auth.js secret/providers;
-- SDK token hashing secret/pepper;
-- worker identity;
-- provider API base/version settings;
-- dashboard BFF rate-limit defaults;
-- worker polling/lease/metrics settings.
-- dev stack ports for dashboard and worker.
-
-Environment-configurable defaults include:
-
-- max run duration;
-- max active runs per workspace;
-- max active runs per user/token;
-- polling base interval;
-- polling max interval;
-- polling jitter;
-- provider create/delete/poll token-bucket limits;
-- provider retry backoff;
-- lease duration;
-- lease renewal threshold;
-- max provider attempts;
-- cleanup retry count;
-- cleanup retry backoff;
-- per-file output cap;
-- per-run output cap;
-- workspace storage cap;
-- signed URL TTL;
-- free user allowance;
-- metadata retention toggles;
-- audit/rate-limit windows for sensitive BFF actions.
-- live e2e opt-in flags for provider sessions, public MCP endpoints, Anthropic skill IDs, and timeouts.
-
-Missing optional env vars must fall back to conservative low limits. Missing required secret/connectivity env vars must fail service startup.
-
-Live public MCP/skills e2e tests are intentionally opt-in because they depend on external provider and public MCP availability. Deterministic unit/component tests validate request wiring for MCP server declarations, tool policies, skill references, and secret non-leakage; the live e2e validates the real provider accepts and runs that configuration end to end.
-
-No-cost provider resilience and load testing uses sanitized replay snapshots from real Managed Agents sessions. Replay tests inject network disconnects, transient HTTP failures, provider latency, slow SSE chunks, cleanup failures, and concurrent full-session load around those snapshots. Idempotent read/delete-style calls may retry with bounded backoff; provider create/send POST calls are not retried by default because their side effects may already have happened.
-
-## Open implementation details
-
-These are not architecture blockers, but must be pinned during implementation planning:
-
-- Production plan tier values for duration, concurrency, storage, polling, and free user allowance.
-- Provider metadata naming convention.
-- Provider list/search capabilities and reconciliation coverage for each resource type.
-- Exact Claude Managed Agents event pagination/filter semantics and bounded polling fallback.
-
-## Backlog
-
-- Persistent workspace-level provider connections (BYO Anthropic key custody across runs, with rotation, revocation, and re-use). The MVP submission contract carries the key inline per run instead.
-- Provider webhooks as wakeup/reconciliation accelerator.
-- SSE live event stream for richer UI.
-- Supabase Realtime with explicit Auth.js-to-Supabase authorization design.
-- Agent/Environment caching by Template/config hash.
-- More providers.
-- Runtime human approval flow if product scope changes.
-- Advanced billing and plan management.
-- Cloud Template registry.
-- Curated MCP adapter catalog.