antpath 0.2.1 → 0.3.1

package/README.md

@@ -4,41 +4,48 @@ title: antpath
 
 # antpath
 
-antpath is a TypeScript-first SDK for running autonomous Claude Managed Agents sessions from code-defined, secret-free Templates.
-
-Everything ships from a single import path:
+antpath is a TypeScript-first SDK + CLI for running autonomous Claude Managed Agents sessions through a managed antpath dashboard. Everything an agent or human needs is reachable through **one** import and **one** binary.
 
 ```ts
 import {
-  AntpathClient,           // direct in-process Claude runs (caller-held key)
-  AntpathPlatformClient,   // submit durable runs to an antpath dashboard
+  AntpathClient,        // the only public class — submits durable runs to a dashboard
   defineTemplate,
   string,
-  validateProxyAuth        // helper for per-run proxy endpoint auth
+  validateProxyAuth     // helper for per-run proxy endpoint auth
 } from "antpath";
 ```
 
-There is no `antpath/platform`, `antpath/proxy`, or other sub-path. The two
-clients are distinct classes for distinct use cases but live behind the same
-single agent-visible surface — see [Agent-first surface design](../../references/development-principles.md#agent-first-surface-design).
+```bash
+antpath run ./template.json --api-token ant_… --workspace … --dashboard-url … \
+  --anthropic-api-key sk-ant-… --follow
+antpath status   <run-id> --api-token … --workspace … --dashboard-url …
+antpath events   <run-id> --api-token … --workspace … --dashboard-url … --follow
+antpath outputs  <run-id> --api-token … --workspace … --dashboard-url …
+antpath download <run-id> <output-id> --out ./local --api-token … --workspace … --dashboard-url …
+antpath cancel   <run-id> --api-token … --workspace … --dashboard-url …
+antpath delete   <run-id> --api-token … --workspace … --dashboard-url …
+antpath whoami            --api-token … --dashboard-url …
+```
 
-- **Direct (`AntpathClient`)** — runs Claude in your own process with a caller-held key. This README covers the direct surface.
-- **Platform (`AntpathPlatformClient`)** — submits durable runs to an antpath dashboard. Every submission carries an inline `secrets` bundle (Anthropic key, optional MCP credentials, optional skill references, and optional per-run proxy endpoint auth); the dashboard vaults the bundle for the lifetime of one run and deletes it at cleanup. Per-run named secrets accessed through the managed HTTP proxy are declared via the `proxyEndpoints` submission field and authenticated via `secrets.proxyEndpointAuth` — see [Credentials](docs/credentials.md). The same npm package also ships the `antpath` CLI as its `bin` entry; the worker mounts that CLI at `/antpath/antpath` in every run for skills to invoke (`node /antpath/antpath proxy …`).
+The SDK class and the CLI are backed by the same `@antpath/shared` operations module — any read or write you can do through one, you can do through the other, against the same durable run records. The same npm package also ships the in-container `antpath` CLI as its `bin` entry; the worker mounts that CLI at `/antpath/antpath` inside every run so skills can call `antpath proxy …` against the per-run manifest. See [Agent-first surface design](../../references/development-principles.md#agent-first-surface-design).
 
-## MVP boundaries (direct SDK)
+## MVP boundaries
 
 - Claude Managed Agents only.
-- Caller-held provider key — the direct SDK never persists keys.
+- BYO Anthropic key + MCP credentials + skill references — passed inline on every submission, vaulted for the lifetime of a single run, destroyed at cleanup.
+- Workspace is the tenant boundary. Every operation is scoped to the workspace bound at client construction.
 - No SDK-side storage of provider keys, MCP credentials, or output file contents.
-- Manual cleanup by default.
+- Cleanup runs by default; opt into retention with `cleanup.session: "retain"`.
 
-## Quickstart
+## Quickstart (SDK)
 
 ```ts
 import { AntpathClient, defineTemplate, string } from "antpath";
 
 const client = new AntpathClient({
-  anthropicApiKey: process.env.ANTHROPIC_API_KEY
+  baseUrl: "https://antpath.example.com",
+  apiToken: process.env.ANTPATH_API_TOKEN!,
+  workspaceId: process.env.ANTPATH_WORKSPACE_ID!
 });
 
 const template = defineTemplate({
@@ -46,47 +53,54 @@ const template = defineTemplate({
   model: "claude-haiku-4-5",
   system: "You are a concise automation agent.",
   messages: ["Write a short answer about {{topic}}."],
-  variables: {
-    topic: string()
-  }
+  variables: { topic: string() }
 });
 
-const handle = await client.run(template, {
-  variables: { topic: "test-first SDK design" }
+const ref = await client.submitRun(template, {
+  variables: { topic: "agent-first SDK design" },
+  secrets: { anthropic: { apiKey: process.env.ANTHROPIC_API_KEY! } }
 });
 
-const result = await handle.wait();
-console.log(result.status, await handle.usage());
-await handle.downloadOutputs("./outputs");
-await handle.cleanup();
+const run = await ref.wait();
+console.log(run.status);
+
+for (const output of await ref.outputs()) {
+  console.log(output.id, output.path);
+}
 ```
 
-Observe events live by passing `onEvent` in `RunOptions`:
+Stream events live with `ref.stream()`:
 
 ```ts
-const handle = await client.run(template, {
-  onEvent: (event) => {
-    if (event.type === "provider.event") {
-      // event.event is a ProviderEvent (raw type stays `unknown`).
-    }
+for await (const event of ref.stream()) {
+  if (event.type === "agent.message") {
+    // typed event helpers live under `antpath`'s event guard exports.
   }
-});
-await handle.wait();
+}
 ```
 
-By the time `wait()` returns, every `onEvent` invocation triggered before
-terminal status has settled. See [Events](docs/events.md) for the full
-contract and a list of typed helpers.
+The same flow from the CLI:
+
+```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
+```
 
 ## Test commands
 
 ```text
-npm run test:unit
-npm run test:unit:recorded
-npm run test:e2e:live
+pnpm test                # unit (deterministic; uses fakes/snapshots)
+pnpm test:e2e:live       # full top-to-bottom against a real dashboard + Anthropic
+pnpm test:user           # offline; exercises the published package via npm install
+pnpm test:user:live      # live; same but hits the real platform
 ```
 
-Unit tests are deterministic and may use fakes or sanitized recorded snapshots. Live e2e tests run when `pnpm test:e2e:live` is invoked with `.env.local` containing `ANTHROPIC_API_KEY`.
+`pnpm test:user*` requires `ANTPATH_USER_TEST_TARBALL`/`ANTPATH_USER_TEST_VERSION` (+ live target vars for `:live`). Missing required env is a hard error — there is no silent skip.
 
 ## Guides
 
@@ -100,3 +114,4 @@ Unit tests are deterministic and may use fakes or sanitized recorded snapshots.
 - [Cleanup](docs/cleanup.md)
 - [Testing](docs/testing.md)
 - [Release](docs/release.md)
+

package/dist/_shared/cleanup-policy.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Provider-neutral cleanup-policy resolution.
+ *
+ * Reads `cleanup.session` (canonical) and falls back to legacy `cleanup.claudeSession`.
+ * Returns the worker default for any malformed shape — never throws.
+ */
+export type SessionCleanupPolicy = "retain" | "delete";
+export declare function resolveCleanupPolicyFromSnapshot(snapshot: unknown, fallback: SessionCleanupPolicy): SessionCleanupPolicy;

package/dist/_shared/cleanup-policy.js

@@ -0,0 +1,24 @@
+/**
+ * Provider-neutral cleanup-policy resolution.
+ *
+ * Reads `cleanup.session` (canonical) and falls back to legacy `cleanup.claudeSession`.
+ * Returns the worker default for any malformed shape — never throws.
+ */
+export function resolveCleanupPolicyFromSnapshot(snapshot, fallback) {
+    if (snapshot === null || snapshot === undefined || typeof snapshot !== "object" || Array.isArray(snapshot)) {
+        return fallback;
+    }
+    const cleanup = snapshot.cleanup;
+    if (!cleanup || typeof cleanup !== "object" || Array.isArray(cleanup)) {
+        return fallback;
+    }
+    const policy = cleanup;
+    if (policy.session === "retain" || policy.session === "delete") {
+        return policy.session;
+    }
+    if (policy.claudeSession === "retain" || policy.claudeSession === "delete") {
+        return policy.claudeSession;
+    }
+    return fallback;
+}
+//# sourceMappingURL=cleanup-policy.js.map

package/dist/_shared/config.d.ts

@@ -0,0 +1,47 @@
+export interface PlatformRequiredConfig {
+    readonly databaseUrl: string;
+    readonly supabaseUrl: string;
+    readonly supabaseServiceRoleKey: string;
+    readonly supabaseStorageBucket: string;
+    readonly supabaseVaultSchema: string;
+    readonly authSecret: string;
+    readonly sdkTokenPepper: string;
+    readonly workerId: string;
+    readonly providerApiBaseUrl: string;
+    readonly providerApiVersion: string;
+    readonly proxyPublicBaseUrl: string;
+    readonly proxyTokenPepper: string;
+}
+export interface PlatformProxyConfig {
+    readonly rateLimitPerRunPerMinute: number;
+    readonly defaultResponseByteBudget: number;
+    readonly sweeperIntervalMs: number;
+}
+export interface PlatformCaps {
+    readonly maxRunDurationMs: number;
+    readonly maxActiveRunsPerWorkspace: number;
+    readonly maxActiveRunsPerUserOrToken: number;
+    readonly pollingBaseIntervalMs: number;
+    readonly pollingMaxIntervalMs: number;
+    readonly pollingJitterRatio: number;
+    readonly providerCreateTokensPerMinute: number;
+    readonly providerDeleteTokensPerMinute: number;
+    readonly providerPollTokensPerMinute: number;
+    readonly providerRetryBackoffMs: number;
+    readonly leaseDurationMs: number;
+    readonly leaseRenewalThresholdMs: number;
+    readonly maxProviderAttempts: number;
+    readonly cleanupRetryCount: number;
+    readonly cleanupRetryBackoffMs: number;
+    readonly outputDownloadSafetyCapBytes: number;
+    readonly workspaceStorageCapBytes: number;
+    readonly signedUrlTtlSeconds: number;
+}
+export interface PlatformConfig extends PlatformRequiredConfig {
+    readonly caps: PlatformCaps;
+    readonly proxy: PlatformProxyConfig;
+}
+type Env = Record<string, string | undefined>;
+export declare function parsePlatformConfig(env: Env): PlatformConfig;
+export declare function snapshotRunCaps(config: PlatformConfig): PlatformCaps;
+export {};

package/dist/_shared/config.js

@@ -0,0 +1,150 @@
+const DEFAULT_CAPS = {
+    maxRunDurationMs: 5 * 60 * 1000,
+    maxActiveRunsPerWorkspace: 1,
+    maxActiveRunsPerUserOrToken: 1,
+    pollingBaseIntervalMs: 5_000,
+    pollingMaxIntervalMs: 60_000,
+    pollingJitterRatio: 0.2,
+    providerCreateTokensPerMinute: 20,
+    providerDeleteTokensPerMinute: 30,
+    providerPollTokensPerMinute: 60,
+    providerRetryBackoffMs: 5_000,
+    leaseDurationMs: 60_000,
+    leaseRenewalThresholdMs: 20_000,
+    maxProviderAttempts: 1,
+    cleanupRetryCount: 3,
+    cleanupRetryBackoffMs: 10_000,
+    outputDownloadSafetyCapBytes: 1024 * 1024 * 1024,
+    workspaceStorageCapBytes: 5 * 1024 * 1024 * 1024,
+    signedUrlTtlSeconds: 300
+};
+const requiredEnvNames = [
+    "ANTPATH_DATABASE_URL",
+    "ANTPATH_SUPABASE_URL",
+    "ANTPATH_SUPABASE_SERVICE_ROLE_KEY",
+    "ANTPATH_SUPABASE_STORAGE_BUCKET",
+    "ANTPATH_SUPABASE_VAULT_SCHEMA",
+    "ANTPATH_AUTH_SECRET",
+    "ANTPATH_SDK_TOKEN_PEPPER",
+    "ANTPATH_WORKER_ID",
+    "ANTPATH_PROVIDER_API_BASE_URL",
+    "ANTPATH_PROVIDER_API_VERSION",
+    "ANTPATH_PROXY_PUBLIC_BASE_URL",
+    "ANTPATH_PROXY_TOKEN_PEPPER"
+];
+const DEFAULT_PROXY_RATE_LIMIT_PER_RUN_PER_MINUTE = 60;
+const DEFAULT_PROXY_RESPONSE_BYTE_BUDGET = 1_048_576;
+const DEFAULT_PROXY_SWEEPER_INTERVAL_MS = 60_000;
+export function parsePlatformConfig(env) {
+    const missing = requiredEnvNames.filter((name) => !env[name]);
+    if (missing.length > 0) {
+        throw new Error(`Missing required environment variables: ${missing.join(", ")}`);
+    }
+    const caps = {
+        maxRunDurationMs: optionalPositiveInt(env, "ANTPATH_MAX_RUN_DURATION_MS", DEFAULT_CAPS.maxRunDurationMs),
+        maxActiveRunsPerWorkspace: optionalPositiveInt(env, "ANTPATH_MAX_ACTIVE_RUNS_PER_WORKSPACE", DEFAULT_CAPS.maxActiveRunsPerWorkspace),
+        maxActiveRunsPerUserOrToken: optionalPositiveInt(env, "ANTPATH_MAX_ACTIVE_RUNS_PER_USER_OR_TOKEN", DEFAULT_CAPS.maxActiveRunsPerUserOrToken),
+        pollingBaseIntervalMs: optionalPositiveInt(env, "ANTPATH_POLLING_BASE_INTERVAL_MS", DEFAULT_CAPS.pollingBaseIntervalMs),
+        pollingMaxIntervalMs: optionalPositiveInt(env, "ANTPATH_POLLING_MAX_INTERVAL_MS", DEFAULT_CAPS.pollingMaxIntervalMs),
+        pollingJitterRatio: optionalRatio(env, "ANTPATH_POLLING_JITTER_RATIO", DEFAULT_CAPS.pollingJitterRatio),
+        providerCreateTokensPerMinute: optionalPositiveInt(env, "ANTPATH_PROVIDER_CREATE_TOKENS_PER_MINUTE", DEFAULT_CAPS.providerCreateTokensPerMinute),
+        providerDeleteTokensPerMinute: optionalPositiveInt(env, "ANTPATH_PROVIDER_DELETE_TOKENS_PER_MINUTE", DEFAULT_CAPS.providerDeleteTokensPerMinute),
+        providerPollTokensPerMinute: optionalPositiveInt(env, "ANTPATH_PROVIDER_POLL_TOKENS_PER_MINUTE", DEFAULT_CAPS.providerPollTokensPerMinute),
+        providerRetryBackoffMs: optionalPositiveInt(env, "ANTPATH_PROVIDER_RETRY_BACKOFF_MS", DEFAULT_CAPS.providerRetryBackoffMs),
+        leaseDurationMs: optionalPositiveInt(env, "ANTPATH_LEASE_DURATION_MS", DEFAULT_CAPS.leaseDurationMs),
+        leaseRenewalThresholdMs: optionalPositiveInt(env, "ANTPATH_LEASE_RENEWAL_THRESHOLD_MS", DEFAULT_CAPS.leaseRenewalThresholdMs),
+        maxProviderAttempts: optionalPositiveInt(env, "ANTPATH_MAX_PROVIDER_ATTEMPTS", DEFAULT_CAPS.maxProviderAttempts),
+        cleanupRetryCount: optionalNonNegativeInt(env, "ANTPATH_CLEANUP_RETRY_COUNT", DEFAULT_CAPS.cleanupRetryCount),
+        cleanupRetryBackoffMs: optionalPositiveInt(env, "ANTPATH_CLEANUP_RETRY_BACKOFF_MS", DEFAULT_CAPS.cleanupRetryBackoffMs),
+        outputDownloadSafetyCapBytes: optionalPositiveInt(env, "ANTPATH_OUTPUT_DOWNLOAD_SAFETY_CAP_BYTES", DEFAULT_CAPS.outputDownloadSafetyCapBytes),
+        workspaceStorageCapBytes: optionalPositiveInt(env, "ANTPATH_WORKSPACE_STORAGE_CAP_BYTES", DEFAULT_CAPS.workspaceStorageCapBytes),
+        signedUrlTtlSeconds: optionalPositiveInt(env, "ANTPATH_SIGNED_URL_TTL_SECONDS", DEFAULT_CAPS.signedUrlTtlSeconds)
+    };
+    validateCaps(caps);
+    const proxy = {
+        rateLimitPerRunPerMinute: optionalPositiveInt(env, "ANTPATH_PROXY_RATE_LIMIT_PER_RUN_PER_MINUTE", DEFAULT_PROXY_RATE_LIMIT_PER_RUN_PER_MINUTE),
+        defaultResponseByteBudget: optionalPositiveInt(env, "ANTPATH_PROXY_DEFAULT_RESPONSE_BYTE_BUDGET", DEFAULT_PROXY_RESPONSE_BYTE_BUDGET),
+        sweeperIntervalMs: optionalPositiveInt(env, "ANTPATH_PROXY_SWEEPER_INTERVAL_MS", DEFAULT_PROXY_SWEEPER_INTERVAL_MS)
+    };
+    const proxyPublicBaseUrl = requireProxyBaseUrl(env, "ANTPATH_PROXY_PUBLIC_BASE_URL");
+    return {
+        databaseUrl: requireEnv(env, "ANTPATH_DATABASE_URL"),
+        supabaseUrl: requireEnv(env, "ANTPATH_SUPABASE_URL"),
+        supabaseServiceRoleKey: requireEnv(env, "ANTPATH_SUPABASE_SERVICE_ROLE_KEY"),
+        supabaseStorageBucket: requireEnv(env, "ANTPATH_SUPABASE_STORAGE_BUCKET"),
+        supabaseVaultSchema: requireEnv(env, "ANTPATH_SUPABASE_VAULT_SCHEMA"),
+        authSecret: requireEnv(env, "ANTPATH_AUTH_SECRET"),
+        sdkTokenPepper: requireEnv(env, "ANTPATH_SDK_TOKEN_PEPPER"),
+        workerId: requireEnv(env, "ANTPATH_WORKER_ID"),
+        providerApiBaseUrl: requireEnv(env, "ANTPATH_PROVIDER_API_BASE_URL"),
+        providerApiVersion: requireEnv(env, "ANTPATH_PROVIDER_API_VERSION"),
+        proxyPublicBaseUrl,
+        proxyTokenPepper: requireEnv(env, "ANTPATH_PROXY_TOKEN_PEPPER"),
+        caps,
+        proxy
+    };
+}
+export function snapshotRunCaps(config) {
+    return { ...config.caps };
+}
+function requireEnv(env, name) {
+    const value = env[name];
+    if (!value) {
+        throw new Error(`Missing required environment variable: ${name}`);
+    }
+    return value;
+}
+function optionalPositiveInt(env, name, fallback) {
+    return optionalInt(env, name, fallback, 1);
+}
+function optionalNonNegativeInt(env, name, fallback) {
+    return optionalInt(env, name, fallback, 0);
+}
+function optionalInt(env, name, fallback, minimum) {
+    const raw = env[name];
+    if (raw === undefined || raw === "") {
+        return fallback;
+    }
+    const value = Number(raw);
+    if (!Number.isSafeInteger(value) || value < minimum) {
+        throw new Error(`${name} must be a safe integer greater than or equal to ${minimum}`);
+    }
+    return value;
+}
+function optionalRatio(env, name, fallback) {
+    const raw = env[name];
+    if (raw === undefined || raw === "") {
+        return fallback;
+    }
+    const value = Number(raw);
+    if (!Number.isFinite(value) || value < 0 || value > 1) {
+        throw new Error(`${name} must be a number between 0 and 1`);
+    }
+    return value;
+}
+function validateCaps(caps) {
+    if (caps.leaseRenewalThresholdMs >= caps.leaseDurationMs) {
+        throw new Error("ANTPATH_LEASE_RENEWAL_THRESHOLD_MS must be less than ANTPATH_LEASE_DURATION_MS");
+    }
+}
+function requireProxyBaseUrl(env, name) {
+    const raw = requireEnv(env, name);
+    let parsed;
+    try {
+        parsed = new URL(raw);
+    }
+    catch {
+        throw new Error(`${name} must be a valid absolute URL`);
+    }
+    if (parsed.protocol !== "https:") {
+        throw new Error(`${name} must use https://`);
+    }
+    if (parsed.username || parsed.password) {
+        throw new Error(`${name} must not embed credentials`);
+    }
+    if (parsed.search || parsed.hash) {
+        throw new Error(`${name} must not include a query string or fragment`);
+    }
+    return `${parsed.origin}${parsed.pathname.replace(/\/+$/, "")}`;
+}
+//# sourceMappingURL=config.js.map

package/dist/_shared/dev-stack.d.ts

@@ -0,0 +1,19 @@
+export interface DevStackConfig {
+    readonly supabaseUrl: string;
+    readonly supabaseDbUrl: string;
+    readonly supabaseServiceRoleKey: string;
+    readonly authSecret: string;
+    readonly sdkTokenPepper: string;
+    readonly storageBucket: string;
+    readonly authProvider: "email" | "google" | "none";
+    readonly dashboardPort: number;
+    readonly workerPort: number;
+    readonly workerId: string;
+}
+export type AntpathRole = "worker" | "dashboard";
+type Env = Record<string, string | undefined>;
+export declare function collectRoleEnvErrors(env: Env, role: AntpathRole): readonly string[];
+export declare function assertRoleEnv(env: Env, role: AntpathRole): void;
+export declare function parseDevStackConfig(env: Env): DevStackConfig;
+export declare function collectDevStackConfigErrors(env: Env): readonly string[];
+export {};

package/dist/_shared/dev-stack.js

@@ -0,0 +1,105 @@
+const ROLE_REQUIREMENTS = {
+    worker: [
+        { names: ["SUPABASE_DB_URL", "DATABASE_URL", "DB_URL"], label: "Supabase database URL" },
+        { names: ["ANTPATH_WORKER_ID"], label: "worker ID" },
+        { names: ["ANTPATH_PROXY_PUBLIC_BASE_URL"], label: "antpath proxy public base URL" }
+    ],
+    dashboard: [
+        { names: ["SUPABASE_DB_URL", "DATABASE_URL", "DB_URL"], label: "Supabase database URL" },
+        { names: ["SUPABASE_URL", "API_URL"], label: "Supabase API URL" },
+        { names: ["SUPABASE_SECRET_KEY", "SUPABASE_SERVICE_ROLE_KEY", "SERVICE_ROLE_KEY", "SECRET_KEY"], label: "Supabase secret key" },
+        { names: ["AUTH_SECRET"], label: "Auth.js secret" },
+        { names: ["ANTPATH_SDK_TOKEN_PEPPER"], label: "antpath SDK token pepper" },
+        { names: ["ANTPATH_PROXY_PUBLIC_BASE_URL"], label: "antpath proxy public base URL" },
+        { names: ["ANTPATH_PROXY_TOKEN_PEPPER"], label: "antpath proxy token pepper" }
+    ]
+};
+export function collectRoleEnvErrors(env, role) {
+    const errors = [];
+    for (const requirement of ROLE_REQUIREMENTS[role]) {
+        if (!requirement.names.some((name) => Boolean(env[name]))) {
+            errors.push(`missing ${requirement.label}: set one of ${requirement.names.join(", ")}`);
+        }
+    }
+    return errors;
+}
+export function assertRoleEnv(env, role) {
+    const errors = collectRoleEnvErrors(env, role);
+    if (errors.length > 0) {
+        throw new Error(`Missing required environment variables for antpath ${role}:\n${errors.map((error) => `  - ${error}`).join("\n")}`);
+    }
+}
+export function parseDevStackConfig(env) {
+    const errors = collectDevStackConfigErrors(env);
+    if (errors.length > 0) {
+        throw new Error(`Invalid dev stack configuration:\n${errors.map((error) => `- ${error}`).join("\n")}`);
+    }
+    return {
+        supabaseUrl: requireOne(env, ["SUPABASE_URL", "API_URL"]),
+        supabaseDbUrl: requireOne(env, ["SUPABASE_DB_URL", "DATABASE_URL", "DB_URL"]),
+        supabaseServiceRoleKey: requireOne(env, ["SUPABASE_SECRET_KEY", "SUPABASE_SERVICE_ROLE_KEY", "SERVICE_ROLE_KEY", "SECRET_KEY"]),
+        authSecret: requireOne(env, ["AUTH_SECRET"]),
+        sdkTokenPepper: requireOne(env, ["ANTPATH_SDK_TOKEN_PEPPER"]),
+        storageBucket: env.ANTPATH_SUPABASE_STORAGE_BUCKET ?? "antpath-outputs",
+        authProvider: authProviderFromEnv(env),
+        dashboardPort: optionalPort(env, "ANTPATH_DASHBOARD_PORT", 3000),
+        workerPort: optionalPort(env, "ANTPATH_WORKER_PORT", optionalPort(env, "PORT", 8787)),
+        workerId: env.ANTPATH_WORKER_ID ?? "local-worker"
+    };
+}
+export function collectDevStackConfigErrors(env) {
+    const errors = [];
+    requireAny(errors, env, ["SUPABASE_URL", "API_URL"], "local Supabase API URL");
+    requireAny(errors, env, ["SUPABASE_DB_URL", "DATABASE_URL", "DB_URL"], "local Supabase database URL");
+    requireAny(errors, env, ["SUPABASE_SECRET_KEY", "SUPABASE_SERVICE_ROLE_KEY", "SERVICE_ROLE_KEY", "SECRET_KEY"], "local Supabase secret key");
+    requireAny(errors, env, ["AUTH_SECRET"], "Auth.js secret");
+    requireAny(errors, env, ["ANTPATH_SDK_TOKEN_PEPPER"], "SDK token pepper");
+    if (env.ANTPATH_DEV_STACK_REQUIRE_AUTH_PROVIDER === "1" && authProviderFromEnv(env) === "none") {
+        errors.push("configure either AUTH_GOOGLE_ID/AUTH_GOOGLE_SECRET or AUTH_POSTMARK_KEY/AUTH_EMAIL_FROM");
+    }
+    validatePort(errors, env, "ANTPATH_DASHBOARD_PORT");
+    validatePort(errors, env, "ANTPATH_WORKER_PORT");
+    validatePort(errors, env, "PORT");
+    return errors;
+}
+function requireAny(errors, env, names, label) {
+    if (!names.some((name) => Boolean(env[name]))) {
+        errors.push(`missing ${label}: set one of ${names.join(", ")}`);
+    }
+}
+function requireOne(env, names) {
+    for (const name of names) {
+        const value = env[name];
+        if (value) {
+            return value;
+        }
+    }
+    throw new Error(`Missing required environment variable: ${names.join(" or ")}`);
+}
+function hasAll(env, names) {
+    return names.every((name) => Boolean(env[name]));
+}
+function authProviderFromEnv(env) {
+    if (hasAll(env, ["AUTH_GOOGLE_ID", "AUTH_GOOGLE_SECRET"])) {
+        return "google";
+    }
+    if (hasAll(env, ["AUTH_POSTMARK_KEY", "AUTH_EMAIL_FROM"])) {
+        return "email";
+    }
+    return "none";
+}
+function optionalPort(env, name, fallback) {
+    const value = env[name];
+    return value ? Number(value) : fallback;
+}
+function validatePort(errors, env, name) {
+    const raw = env[name];
+    if (!raw) {
+        return;
+    }
+    const value = Number(raw);
+    if (!Number.isSafeInteger(value) || value < 1 || value > 65_535) {
+        errors.push(`${name} must be an integer port between 1 and 65535`);
+    }
+}
+//# sourceMappingURL=dev-stack.js.map

package/dist/_shared/errors.d.ts

@@ -0,0 +1,8 @@
+export declare const ERROR_CLASSES: readonly ["transient_provider", "provider_permanent", "tenant_permanent", "antpath_bug", "cancelled_by_user"];
+export type ErrorClass = typeof ERROR_CLASSES[number];
+export interface ErrorPolicy {
+    readonly retryable: boolean;
+    readonly terminal: boolean;
+}
+export declare const ERROR_POLICIES: Record<ErrorClass, ErrorPolicy>;
+export declare function isRetryableErrorClass(errorClass: ErrorClass): boolean;

package/dist/_shared/errors.js

@@ -0,0 +1,18 @@
+export const ERROR_CLASSES = [
+    "transient_provider",
+    "provider_permanent",
+    "tenant_permanent",
+    "antpath_bug",
+    "cancelled_by_user"
+];
+export const ERROR_POLICIES = {
+    transient_provider: { retryable: true, terminal: false },
+    provider_permanent: { retryable: false, terminal: true },
+    tenant_permanent: { retryable: false, terminal: true },
+    antpath_bug: { retryable: false, terminal: true },
+    cancelled_by_user: { retryable: false, terminal: true }
+};
+export function isRetryableErrorClass(errorClass) {
+    return ERROR_POLICIES[errorClass].retryable;
+}
+//# sourceMappingURL=errors.js.map

package/dist/_shared/http.d.ts

@@ -0,0 +1,20 @@
+export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+export interface HttpClientOptions {
+    readonly baseUrl: string;
+    readonly apiToken: string;
+    readonly fetch?: FetchLike;
+}
+/**
+ * Thin transport used by every BFF-bound operation. The SDK class and
+ * the CLI subcommands BOTH build an `HttpClient` and pass it to the
+ * operations module — so they cannot drift in how they auth, encode
+ * query parameters, or decode error responses.
+ */
+export declare class HttpClient {
+    #private;
+    constructor(options: HttpClientOptions);
+    request<T>(path: string, init?: RequestInit, query?: Record<string, string>): Promise<T>;
+    download(path: string, init?: RequestInit, query?: Record<string, string>): Promise<{
+        readonly response: Response;
+    }>;
+}

package/dist/_shared/http.js

@@ -0,0 +1,94 @@
+import { AntpathApiError } from "./sdk-errors.js";
+/**
+ * Thin transport used by every BFF-bound operation. The SDK class and
+ * the CLI subcommands BOTH build an `HttpClient` and pass it to the
+ * operations module — so they cannot drift in how they auth, encode
+ * query parameters, or decode error responses.
+ */
+export class HttpClient {
+    #baseUrl;
+    #apiToken;
+    #fetch;
+    constructor(options) {
+        if (!options.baseUrl) {
+            throw new Error("HttpClient: baseUrl is required");
+        }
+        if (!options.apiToken) {
+            throw new Error("HttpClient: apiToken is required");
+        }
+        const normalized = options.baseUrl.endsWith("/") ? options.baseUrl : `${options.baseUrl}/`;
+        this.#baseUrl = new URL(normalized);
+        this.#apiToken = options.apiToken;
+        this.#fetch = options.fetch ?? fetch;
+    }
+    async request(path, init = {}, query = {}) {
+        const url = new URL(path.replace(/^\//, ""), this.#baseUrl);
+        for (const [key, value] of Object.entries(query)) {
+            url.searchParams.set(key, value);
+        }
+        const headers = {
+            accept: "application/json",
+            authorization: `Bearer ${this.#apiToken}`,
+            ...normalizeHeaders(init.headers)
+        };
+        if (init.body !== undefined && init.body !== null && !headers["content-type"]) {
+            headers["content-type"] = "application/json";
+        }
+        const response = await this.#fetch(url, { ...init, headers });
+        const body = await readJson(response);
+        if (!response.ok) {
+            throw new AntpathApiError(response.status, extractErrorMessage(body), body);
+        }
+        return body;
+    }
+    async download(path, init = {}, query = {}) {
+        const url = new URL(path.replace(/^\//, ""), this.#baseUrl);
+        for (const [key, value] of Object.entries(query)) {
+            url.searchParams.set(key, value);
+        }
+        const headers = {
+            authorization: `Bearer ${this.#apiToken}`,
+            ...normalizeHeaders(init.headers)
+        };
+        const response = await this.#fetch(url, { ...init, headers });
+        if (!response.ok) {
+            const body = await readJson(response);
+            throw new AntpathApiError(response.status, extractErrorMessage(body), body);
+        }
+        return { response };
+    }
+}
+function normalizeHeaders(headers) {
+    if (!headers)
+        return {};
+    if (headers instanceof Headers)
+        return Object.fromEntries(headers.entries());
+    if (Array.isArray(headers))
+        return Object.fromEntries(headers);
+    return headers;
+}
+async function readJson(response) {
+    const text = await response.text();
+    if (text.length === 0)
+        return {};
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { raw: text };
+    }
+}
+function extractErrorMessage(body) {
+    if (body && typeof body === "object" && "error" in body) {
+        const error = body.error;
+        if (typeof error === "string")
+            return error;
+        if (error && typeof error === "object" && "message" in error) {
+            const message = error.message;
+            if (typeof message === "string")
+                return message;
+        }
+    }
+    return "antpath API request failed";
+}
+//# sourceMappingURL=http.js.map