antpath 0.1.0 → 0.2.0

package/references/implementation-plan.md

@@ -1,527 +1,452 @@
----
-title: antpath implementation plan
-status: proposed
-scope: sdk-only MVP
----
-
-# antpath implementation plan
-
-## Goal
-
-Build the SDK-only MVP for antpath with test-first development: a TypeScript SDK that runs code-defined Templates on Claude Managed Agents, using caller-held provider credentials, typed credential inputs, provider-side vaults, queued user messages, event streaming, output downloads, and manual cleanup.
-
-## Acceptance criteria
-
-- A user can define a secret-free Template in TypeScript.
-- A user can create a Client with their provider key.
-- A user can run a Template with typed variables and credentials.
-- The SDK creates all required provider resources per run.
-- The SDK sends queued user messages, one at a time, when the session is idle.
-- The SDK aborts on any provider error or terminated state.
-- The SDK resolves completion as the first idle state after all queued messages are sent.
-- The SDK can stream events, wait for completion, terminate, list files, download a file, download all outputs, read usage, return a final result, and cleanup.
-- The SDK never persists or logs provider keys or MCP credential values.
-- Unit tests cover Template parsing, variable resolution, credential validation, provider request mapping, run state transitions, output handling, and cleanup.
-- Component integration tests cover interactions between SDK modules using fake providers and local fixtures.
-- Recorded API integration tests replay sanitized responses captured from real Claude API calls and are reproducible with scripts.
-- Live e2e tests exercise the real Claude Managed Agents lifecycle and are gated behind local credentials.
-
-## Phase 1: Repository and package foundation
-
-Create the TypeScript package foundation.
-
-Deliverables:
-
-- package manager configuration;
-- TypeScript configuration;
-- lint/format/test commands;
-- source/test directory layout;
-- public package entrypoint;
-- typed error base classes;
-- test fixtures and fake provider harness;
-- four test commands: unit, component integration, recorded API integration, and live e2e;
-- fixture recording/sanitization scripts for real API responses.
-
-Recommended structure:
-
-```text
-src/
-  index.ts
-  client.ts
-  template/
-  credentials/
-  providers/
-    anthropic/
-  run/
-  files/
-  skills/
-  utils/
-test/
-  unit/
-  integration/
-    components/
-    api-recorded/
-    live/
-  fixtures/
-    api-recordings/
-references/
-scripts/
-  record-api-fixtures.ts
-  sanitize-api-fixtures.ts
-```
-
-Validation:
-
-- `npm test` or equivalent test command passes.
-- test commands exist for all four layers.
-- TypeScript build emits declarations.
-
-## Phase 2: Public SDK types
-
-Define the public API before provider implementation.
-
-Deliverables:
-
-- `AntpathClient`;
-- `Template`;
-- `RunOptions`;
-- `RunHandle`;
-- `RunResult`;
-- `RunStatus`;
-- `RunEvent`;
-- `UsageSummary`;
-- `OutputManifest`;
-- `CleanupPolicy`;
-- typed credential unions.
-
-Initial API shape:
-
-```ts
-const client = new AntpathClient({
-  anthropicApiKey: process.env.ANTHROPIC_API_KEY
-});
-
-const template = defineTemplate({
-  name: "example",
-  model: "claude-sonnet-4-6",
-  system: "You are a focused automation agent.",
-  messages: ["Do the task: {{task}}"],
-  variables: {
-    task: string()
-  },
-  mcpServers: {
-    linear: {
-      url: "https://mcp.linear.app/mcp",
-      auth: requiredStaticBearer(),
-      tools: { allow: ["list_issues"] }
-    }
-  },
-  outputs: {
-    recommendedPath: "/antpath/outputs"
-  }
-});
-
-const handle = await client.run(template, {
-  variables: { task: "Summarize open issues" },
-  credentials: {
-    linear: { type: "static_bearer", token: process.env.LINEAR_API_KEY! }
-  }
-});
-
-const result = await handle.wait();
-await handle.downloadOutputs("./outputs");
-await handle.cleanup();
-```
-
-Validation:
-
-- Compile-time tests assert supported and unsupported credential shapes.
-- Runtime schema tests reject invalid Template and run inputs.
-- Public types are defined test-first with type tests before implementation.
-
-## Phase 3: Template compiler
-
-Implement a strict compiler from user Template to resolved, provider-neutral internal configuration.
-
-Deliverables:
-
-- immutable Template snapshot/hash;
-- variable declaration and resolution;
-- escaping for literal placeholders;
-- strict unresolved variable failures;
-- secret boundary enforcement;
-- MCP declaration normalization;
-- tool allow/deny normalization;
-- environment package/setup normalization;
-- output configuration normalization.
-
-Validation:
-
-- unresolved variables fail before provider calls;
-- escaped placeholders remain literal;
-- secrets cannot be supplied through variables;
-- Template hash is stable for semantically identical inputs;
-- Template edits produce a different hash.
-- Recorded fixtures do not include resolved secret values.
-
-## Phase 4: Credential validation
-
-Implement typed credential validation independent of provider calls.
-
-Deliverables:
-
-- `static_bearer` credential type;
-- `oauth_access_token` credential type;
-- Template credential requirements;
-- run-time credential matching by MCP server key;
-- redacted error messages;
-- no credential values in logs/errors/result objects.
-
-Validation:
-
-- missing required credentials fail before provider calls;
-- unsupported arbitrary headers fail with explicit out-of-scope error;
-- credential values are redacted in snapshots, errors, and debug output.
-- redaction is tested in unit, component integration, and recorded API fixture sanitization.
-
-## Phase 5: Anthropic Managed Agents adapter
-
-Build the provider adapter as the only MVP backend.
-
-Deliverables:
-
-- provider client wrapper;
-- create Environment per run;
-- upload local skills/resources;
-- create inline skills where provider supports them;
-- create Agent with model, system prompt, MCP servers, skills, tools, permission policies;
-- create per-run Vault and Credentials;
-- create Session;
-- send user messages;
-- stream/list events;
-- retrieve status/session metadata;
-- terminate session;
-- list/download session-scoped files;
-- retrieve usage/cost where provider exposes it;
-- cleanup created resources.
-
-Provider invariants:
-
-- MCP tools must not reach provider with an approval-required policy.
-- Enabled MCP tools must be explicitly allow/deny configured.
-- Credentials are submitted only to provider vault APIs, never persisted locally beyond active process memory.
-- Created provider IDs are captured for cleanup and debugging.
-
-Validation:
-
-- fake provider tests assert exact request order and payloads;
-- recorded API integration tests assert adapter parsing against sanitized real provider responses;
-- errors from each create step trigger correct cleanup state;
-- cleanup is idempotent where possible;
-- provider IDs are retained even after partial failures.
-
-## Phase 6: Run state machine
-
-Implement deterministic orchestration around provider events.
-
-Deliverables:
-
-- `RunController`;
-- event stream consumer;
-- queued message scheduler;
-- timeout controller;
-- termination controller;
-- local status transitions;
-- final result builder.
-
-State-machine rules:
-
-- Send first message after Session creation.
-- On idle with queued messages remaining, send next message.
-- On idle with no queued messages remaining, succeed.
-- On any provider error, fail and do not send further messages.
-- On terminated, fail unless termination was user-requested.
-- On timeout, terminate and mark timed out.
-
-Validation:
-
-- table-driven tests for event sequences;
-- component integration tests cover event stream plus queued message scheduling;
-- duplicate/replayed events do not corrupt state;
-- queued messages are sent exactly once;
-- abort prevents later queued messages;
-- timeout cannot race into success.
-
-## Phase 7: Run handle API
-
-Expose the MVP handle methods.
-
-Deliverables:
-
-- `status()`;
-- `streamEvents()`;
-- `wait()`;
-- `listFiles()`;
-- `downloadFile()`;
-- `downloadOutputs()`;
-- `cleanup()`;
-- `terminate()`;
-- `usage()`;
-- `result()`.
-
-Behavior:
-
-- `wait()` resolves once the run reaches terminal SDK state.
-- `streamEvents()` yields provider events plus SDK lifecycle events.
-- `downloadOutputs()` downloads all session-scoped files by default.
-- `cleanup()` is manual and can be called after success, failure, or termination.
-- `cleanup()` reports skipped/failed cleanup operations rather than hiding them.
-
-Validation:
-
-- methods have deterministic behavior before, during, and after terminal states;
-- cleanup can be retried safely;
-- file downloads preserve names and avoid unsafe path traversal.
-- live e2e test covers the happy path from Template to cleanup.
-
-## Phase 8: Output download subsystem
-
-Implement local output handling without antpath storage.
-
-Deliverables:
-
-- session-scoped file listing;
-- safe local path mapping;
-- download all files by default;
-- optional filters/globs;
-- optional `/antpath/outputs` convention in prompts/config;
-- local output manifest;
-- checksum/size metadata when feasible.
-
-Validation:
-
-- path traversal filenames are sanitized;
-- duplicate filenames are handled deterministically;
-- partial download failures are reported clearly;
-- downloaded output manifest contains no secrets.
-- recorded API fixtures cover session-scoped file listing and download metadata.
-
-## Phase 9: Skill packaging
-
-Support local uploads and inline skills.
-
-Deliverables:
-
-- local skill path validation;
-- package/zip local skill directory;
-- upload skill artifact/resource per run;
-- inline skill declaration support;
-- variable resolution in skill content/config;
-- skill resource cleanup tracking.
-
-Validation:
-
-- missing local paths fail before provider calls;
-- packaging is deterministic;
-- large/unsupported skill inputs fail with actionable errors;
-- inline and local skills can be combined.
-
-## Phase 10: Cleanup and orphan handling
-
-Implement explicit cleanup as a first-class handle operation.
-
-Deliverables:
-
-- cleanup policy model;
-- manual default;
-- provider resource cleanup ordering;
-- vault/credential cleanup;
-- environment/agent/session/file cleanup where supported;
-- cleanup state reporting;
-- orphan recovery inputs.
-
-Cleanup order should prefer removing credentials first, then optional file/session resources, then Agent/Environment where safe.
-
-Validation:
-
-- cleanup works after success, failure, timeout, and partial provider creation failure;
-- cleanup failures are returned with provider IDs and redacted messages;
-- calling cleanup twice is safe;
-- orphan recovery can accept persisted provider IDs from a previous result.
-- live e2e cleanup verifies provider vault/session/resource cleanup behavior where provider APIs allow it.
-
-## Phase 11: Observability and safe logging
-
-Add structured, redacted observability suitable for SDK users.
-
-Deliverables:
-
-- event hooks/callbacks;
-- debug logger interface;
-- redaction utility;
-- structured SDK lifecycle events;
-- provider request metadata without secrets;
-- error taxonomy.
-
-Validation:
-
-- tests prove secret values are never emitted through logs/events/errors;
-- debug logs include enough provider IDs and state to diagnose failures.
-
-## Phase 12: Documentation and examples
-
-Create user-facing SDK docs and runnable examples.
-
-Deliverables:
-
-- quickstart;
-- Template guide;
-- credentials guide;
-- MCP guide;
-- skills guide;
-- cleanup/orphan guide;
-- output download guide;
-- examples for static bearer and OAuth access-token MCP credentials.
-
-Validation:
-
-- examples compile;
-- docs state MVP non-goals and accepted risks.
-
-## Phase 13: Release readiness
-
-Prepare the SDK for first external use.
-
-Deliverables:
-
-- package metadata;
-- changelog;
-- versioning policy;
-- README;
-- API reference generation if practical;
-- CI workflow once repository hosting is established.
-
-Validation:
-
-- clean install works;
-- build/test pass from a fresh checkout;
-- package dry-run includes only intended files.
-
-## Test strategy
-
-Use test-first development for every phase. Start each feature by adding or updating the narrowest failing test in the appropriate layer, then implement only enough code to pass it.
-
-Use a fake provider for most tests. Do not rely on live provider calls for the core state machine.
-
-### Layer 1: Unit tests
-
-Purpose: verify pure logic and small state transitions with no provider, filesystem, or network dependency.
-
-Coverage:
-
-- Template compiler;
-- variable resolution and escaping;
-- credential parser;
-- redaction utilities;
-- state reducer/state-machine transitions;
-- safe local path mapping;
-- cleanup plan construction.
-
-Command:
-
-```text
-npm run test:unit
-```
-
-### Layer 2: Component integration tests
-
-Purpose: verify interactions between SDK components using fake providers, fake clocks, and local fixtures.
-
-Coverage:
-
-- Client + Template compiler + credential validator;
-- RunController + fake provider event stream;
-- queued message scheduling;
-- output downloader + fake file service;
-- cleanup manager + fake provider resources;
-- logger/event hooks with redaction.
-
-Command:
-
-```text
-npm run test:integration:components
-```
-
-### Layer 3: Recorded API integration tests
-
-Purpose: verify provider adapter behavior against sanitized responses captured from real Claude API calls, without requiring network access during normal CI.
-
-Requirements:
-
-- Real API responses are captured by explicit scripts.
-- Recordings are sanitized before being committed.
-- Secret values, request headers, API keys, bearer tokens, OAuth tokens, and raw sensitive prompts are never stored.
-- Fixtures are deterministic and versioned by provider API/beta header.
-- Tests fail if fixture sanitization leaves secret-shaped values.
-
-Commands:
-
-```text
-npm run fixtures:record:anthropic
-npm run fixtures:sanitize
-npm run test:integration:api
-```
-
-### Layer 4: Live e2e tests
-
-Purpose: verify the full real Claude Managed Agents lifecycle using a local credential.
-
-Coverage:
-
-- create Environment;
-- create Agent;
-- create Vault/Credential when needed;
-- create Session;
-- send queued messages;
-- observe idle completion;
-- list/download session-scoped files;
-- retrieve usage/status where available;
-- terminate if needed;
-- cleanup if configured or explicitly requested.
-
-Rules:
-
-- Live tests are never part of default CI.
-- Live tests require `.env.local` with `ANTHROPIC_API_KEY`.
-- Live tests must use low-cost prompts, strict timeouts, and cleanup guards.
-- Live tests must not print the key or provider auth headers.
-
-Command:
-
-```text
-npm run test:e2e:live
-```
-
-Key invariants:
-
-- no provider call before Template and credentials are fully parsed;
-- no secret value appears in logs, errors, Template snapshots, result objects, or manifests;
-- no secret value appears in recorded API fixtures;
-- every created provider resource is tracked for cleanup;
-- message queue sends each message at most once;
-- cleanup is manual by default and retryable;
-- output download never writes outside the requested local directory.
-
-## Backlog plan
-
-After MVP:
-
-1. Add cloud metadata sync and dashboard.
-2. Add encrypted run-scoped key support for guaranteed cleanup.
-3. Add OpenAI adapter.
-4. Add provider Environment caching by Template hash.
-5. Add cost/token/iteration caps.
-6. Add OAuth refresh credentials.
-7. Add arbitrary MCP headers through an antpath MCP proxy.
-8. Add Template registry and sharing.
-9. Add artifact retention service.
+---
+title: antpath implementation plan
+status: accepted
+scope: platform MVP
+---
+
+# antpath implementation plan
+
+## Goal
+
+Convert antpath from an SDK-only package into a pnpm TypeScript workspace containing:
+
+- a platform SDK in `packages/sdk`;
+- a dashboard app in `apps/dashboard`;
+- a worker service in `apps/worker`;
+- shared packages for types, schema, configuration, redaction, and database helpers as needed.
+
+The platform must submit, dispatch, observe, store metadata for, capture outputs from, and clean up Claude Managed Agents runs while preserving tenant isolation and secret boundaries.
+
+Implementation is test-driven. Each behavior starts with the narrowest failing test that proves the desired invariant.
+
+## Acceptance criteria
+
+- The repository is a pnpm workspace and the current SDK is moved to `packages/sdk`.
+- Dashboard and worker app folders exist with build/test integration.
+- Auth.js authenticates dashboard users.
+- SDK API tokens authenticate programmatic clients.
+- Workspaces are the tenant boundary.
+- BFF/server actions scope every dashboard/API operation by workspace membership or API-token scope.
+- Supabase service-role credentials are never exposed to browser/client bundles.
+- Supabase Postgres stores durable run, attempt, provider resource, event, output, output-capture-failure, cleanup, usage, workspace, and membership metadata. There is no persistent `provider_connections` table in MVP.
+- Per-run secrets bundles (Anthropic key, optional MCP credentials, optional skill references) arrive inline on submission, are encrypted through Supabase Vault for the lifetime of that single run, and are deleted at terminal cleanup. The Vault entry is the only durable trace of the user's provider key.
+- Run submission idempotency is enforced by workspace and request hash. The hash excludes the `secrets` block so re-submitting the same logical run with a new key still matches.
+- Workers claim due runs with leases and `FOR UPDATE SKIP LOCKED`.
+- Multiple workers can run concurrently without duplicate lifecycle ownership.
+- Worker polling recovers from missed `NOTIFY`, worker restart, deploy, and expired leases.
+- Worker creates per-run provider resources and journals them for cleanup.
+- Worker polls provider status and events and stores only redacted metadata.
+- Output capture is unconditional: every artifact Claude exposes on the run's session is written to private Supabase Storage, bounded only by the workspace storage cap. Files that would exceed the cap are persisted as `output_capture_failures` rows.
+- BFF returns signed output links only after workspace authorization.
+- Cleanup runs after terminal provider state and output capture, deletes the per-run Vault entry, and (by default) deletes Claude-side resources. `cleanup.claudeSession: "retain"` only affects Claude-side resources.
+- Reconciliation can recover intended provider resources after partial worker crashes.
+- User deletion is pending/soft until cleanup and storage deletion are complete.
+- Exact tier/cap values are configurable through environment variables with conservative defaults and run-level snapshots.
+- Security-sensitive BFF/API actions are audited and rate-limited.
+- Workspace storage quota and workspace deletion are enforced before provider/storage side effects proceed.
+- CI runs pnpm lint/test/build/package checks plus a local Supabase integration job.
+- Tests follow the accepted taxonomy: deterministic unit tests (including fakes and sanitized recorded snapshots), live external-system integration tests with no skip flags, and top-to-bottom live e2e tests.
+
+## Phase 1: Workspace foundation
+
+Create the workspace structure without changing runtime behavior.
+
+Deliverables:
+
+- Root pnpm workspace configuration.
+- Current SDK moved to `packages/sdk`.
+- `apps/dashboard` placeholder.
+- `apps/worker` placeholder.
+- Shared TypeScript config/build/test commands.
+- Existing SDK exports preserved or intentionally migrated with compatibility notes.
+- Root validation commands:
+  - `pnpm lint`
+  - `pnpm test`
+  - `pnpm build`
+
+TDD gate:
+
+- Add tests or CI command checks proving the moved SDK still builds/tests from the root workspace.
+
+Validation:
+
+- Clean install works from root.
+- Existing SDK tests still pass from root and package scope.
+- Build emits SDK declarations.
+
+## Phase 2: Shared contracts and configuration
+
+Define shared platform contracts before implementing dashboard/worker behavior.
+
+Deliverables:
+
+- Shared run status and cleanup status types.
+- Shared error taxonomy.
+- Shared redaction helpers and secret wrapper.
+- Shared Template/platform submission request schemas.
+- Environment config parser with required-secret validation and conservative defaults.
+- Plan/cap config defaults for:
+  - max run duration;
+  - workspace/user/token concurrency;
+  - polling intervals and jitter;
+  - provider token-bucket rates;
+  - retry backoffs;
+  - lease duration/renewal threshold;
+  - max attempts;
+  - cleanup retries;
+  - output caps;
+  - storage caps;
+  - signed-link TTL;
+  - free user allowance.
+
+TDD gate:
+
+- Unit tests for env parsing, missing required env failure, optional fallback defaults, cap snapshot values, redaction, and status transitions.
+
+Validation:
+
+- Missing required secrets/connectivity config fails service startup.
+- Missing optional config falls back to conservative low limits.
+
+## Phase 3: Database foundation
+
+Create the durable source of truth.
+
+Deliverables:
+
+- Migration framework.
+- Tables:
+  - Auth.js adapter tables: `users`, `accounts`, `sessions`, `verification_token`;
+  - antpath `app_users`;
+  - `workspaces`;
+  - `workspace_memberships`;
+  - `api_tokens`;
+  - `runs` (includes `execution_secret_id` referencing the per-run Vault entry);
+  - `run_attempts`;
+  - `provider_resources`;
+  - `run_events`;
+  - `output_objects`;
+  - `output_capture_failures`;
+  - `cleanup_attempts`;
+  - `usage_ledger`.
+- Constraints:
+  - unique `(workspace_id, idempotency_key)` on runs;
+  - request-hash conflict handling;
+  - unique `(run_attempt_id, provider_event_id)` on events;
+  - foreign keys for workspace and attributed `app_user_id` where practical;
+  - RLS enabled and `anon`/`authenticated` direct table access revoked for platform/Auth.js tables.
+- DB query helpers for tenant-scoped access.
+
+TDD gate:
+
+- Add failing database/security integration tests for migrations, idempotency, lease claim behavior, event dedupe, usage ledger idempotency, and cross-workspace access denial.
+
+Validation:
+
+- Migrations apply from a clean database.
+- Concurrent claims use `FOR UPDATE SKIP LOCKED`.
+- Event and usage ledger writes are transactional.
+
+## Phase 4: Auth, BFF, and SDK API-token access
+
+Establish the authorization boundary.
+
+Deliverables:
+
+- Auth.js dashboard authentication.
+- User mirror or Auth.js adapter integration.
+- Workspace membership resolution.
+- Workspace switch/active workspace model.
+- Hashed SDK API tokens with scopes, creator, revocation, and last-used tracking.
+- Shared authorization helper for Auth.js sessions and API tokens.
+- BFF/server-action routes for run submission/read/update operations.
+- Browser/client bundle boundary preventing service-role import.
+
+TDD gate:
+
+- Add failing tests for membership-scoped queries, cross-workspace denial, API-token scope enforcement, revoked token rejection, attributed user freezing, and no browser service-role imports.
+
+Validation:
+
+- Dashboard reads and mutates only authorized workspace data.
+- SDK token cannot access another workspace.
+- Service-role credentials are server/worker only.
+
+## Phase 5: Platform SDK client
+
+Turn the SDK into the programmatic client for the platform while preserving Template ergonomics where practical.
+
+Deliverables:
+
+- SDK client for platform API base URL and API token.
+- `AntpathPlatformClient` constructor accepts a default `secrets` bundle (Anthropic key + optional MCP credentials + optional skill references); every method accepts a per-call override.
+- Submit run API (carries inline `secrets`).
+- Get run status/detail API.
+- List metadata events API.
+- List outputs API (returns successful captures and capture failures).
+- Create signed output link API.
+- Cancel run API.
+- Delete run API.
+- Typed errors for auth, quota, validation, conflict, not found, and provider/platform failures.
+- Compatibility path from existing Template definitions to platform submission requests.
+
+TDD gate:
+
+- Type/contract tests for public SDK API and runtime tests with fake platform responses.
+- Tests asserting `secrets` never appears in serialized request hashes, error metadata, or retry telemetry.
+
+Validation:
+
+- SDK does not persist provider keys: it forwards them to the platform per submission, where they are vaulted for the lifetime of one run and then deleted.
+- SDK handles idempotency conflict, unauthorized, quota, and terminal states deterministically.
+
+## Phase 6: Worker claim loop and state machine
+
+Implement durable lifecycle ownership independent of provider details.
+
+Deliverables:
+
+- Polling loop for due runs.
+- Optional Postgres `NOTIFY` listener for fast wakeup.
+- Lease claim/release helpers.
+- Lease-guarded status update helper.
+- Per-workspace rate limit hooks.
+- Fair due-run ordering across workspaces.
+- Cancellation/delete request checks before side effects.
+- Timeout handling.
+- Error classification.
+- Retry/backoff scheduling through `next_check_at`.
+
+TDD gate:
+
+- Add failing component and database tests for concurrent fake workers, expired lease reclaim, lease-token update failures, cancellation races, timeout races, and polling fallback after missed `NOTIFY`.
+
+Validation:
+
+- Multiple workers do not process the same run step.
+- Expired leases recover.
+- Worker restart leaves no required in-memory state.
+
+## Phase 7: Fake provider lifecycle harness
+
+Prove worker behavior with deterministic provider boundaries before live provider integration.
+
+Deliverables:
+
+- Fake provider implementing create resources, create session, send event, retrieve status, list events, list files, download file, and cleanup.
+- Fake storage adapter.
+- Fake Vault adapter.
+- Table-driven lifecycle tests.
+
+TDD gate:
+
+- Add component tests for happy path, provider errors, terminal states, duplicate events, output capture, cleanup failures, and retryable failures.
+
+Validation:
+
+- Core run lifecycle is correct without network calls.
+- Duplicate/replayed provider events do not double-count usage.
+
+## Phase 8: Claude provider adapter
+
+Adapt existing Claude Managed Agents provider code for the platform worker.
+
+Deliverables:
+
+- Provider client wrapper for worker.
+- Create Environment per run.
+- Upload skills/resources as needed.
+- Create Agent with model/system/MCP/skills/tool policy.
+- Create provider Vault/Credentials for MCP credentials.
+- Create Session.
+- Send initial user event.
+- Retrieve session status.
+- List session events with cursor/filter where available.
+- List/download session files.
+- Cleanup/archive/delete resources.
+- Provider metadata naming/tagging for reconciliation.
+- Provider error classification.
+
+TDD gate:
+
+- Add sanitized recorded provider snapshot unit tests for parsing and cleanup behavior before live e2e.
+- Verify exact Claude events pagination/filter semantics and document bounded fallback if needed.
+
+Validation:
+
+- No approval-required tool policy reaches the provider.
+- Provider IDs are persisted for cleanup.
+- Sanitized fixtures contain no secrets.
+
+## Phase 9: Provider resource journaling and reconciliation sweeper
+
+Close resource leak windows.
+
+Deliverables:
+
+- Pre-insert intended `provider_resources` rows before provider side effects where possible.
+- Deterministic provider names/metadata with antpath workspace/run/attempt identifiers.
+- Sweeper for expired leases and unfinished intended resources.
+- Orphan matching by provider list/search APIs where available.
+- Reschedule recoverable runs.
+- Cleanup orphaned resources.
+
+TDD gate:
+
+- Add tests that simulate worker crashes after provider create succeeds but before provider id persistence.
+
+Validation:
+
+- Sweeper can attach or cleanup recoverable resources.
+- Cleanup remains idempotent after partial failures.
+
+## Phase 10: Output capture and Supabase Storage
+
+Unconditionally capture every artifact the user's Claude session exposes into private Supabase Storage. The workspace storage cap is the only user-visible quota.
+
+Deliverables:
+
+- Worker terminal-state list of session-scoped files via the Claude Files API (`GET /v1/files?scope_id=<sessionId>`), returning `id`, `filename`, and `size_bytes`.
+- Workspace storage usage accounting helper.
+- Pre-download quota check: if `(workspace_used + size_bytes) > workspace cap`, write an `output_capture_failures` row with `reason = "workspace_quota_exceeded"` and continue without downloading.
+- Streaming download via `GET /v1/files/{file_id}/content` with a worker-internal safety cap so malformed listing responses cannot OOM the worker; safety-cap aborts are recorded as `output_capture_failures` with `reason = "download_failed"`.
+- Private Supabase Storage upload with workspace-scoped path policy.
+- `output_objects` metadata insert for each successful capture.
+- Per-user attribution frozen from the run row (audit/billing dimension only; not a quota).
+- Signed-link BFF action/API for both `output_objects` rows; capture failures are read-only.
+
+TDD gate:
+
+- Add failing tests for: pre-download quota check choosing failure-row over download when over cap; safety-cap abort recording a failure row; happy path writing both an `output_objects` row and an audit entry; signed-link authorization; cross-workspace denial; listing returning zero files producing zero rows; listing returning N files with mixed sizes recording the expected mix of successes and failures.
+- Tests must assert there is no user-facing knob for `capture: boolean`, `globs`, or per-file caps.
+
+Validation:
+
+- Output capture is unconditional and cannot be opted out by the submitter.
+- Oversized output payloads do not OOM the worker.
+- BFF only creates signed links for authorized workspace users/tokens.
+- Dashboard renders successful captures and capture failures side by side.
+
+## Phase 11: Cleanup, deletion, and retention
+
+Make cleanup and deletion first-class state machines. Cleanup must also destroy the per-run Vault secret.
+
+Deliverables:
+
+- Cleanup ordering (per the architecture decisions doc):
+  - capture session-scoped files (Phase 10);
+  - provider session files / session where supported;
+  - agent / archive;
+  - environment / archive or delete;
+  - skills uploaded for this session and other ephemeral provider resources;
+  - provider Vault/credentials created on Claude's side for MCP wiring;
+  - the antpath per-run Vault entry: `vault.deleteSecret(runs.execution_secret_id)` and clear the column;
+  - local Supabase Storage and metadata only on user deletion.
+- The Claude-side cleanup steps are skipped when `cleanup.claudeSession === "retain"` (or the worker default is `retain`); the per-run Vault deletion still runs.
+- Cleanup retry/backoff with idempotent calls.
+- `cleanup_attempts` records.
+- Cleanup state separate from user-facing run terminal state.
+- User `pending_delete` flow.
+- Workspace deletion flow.
+- Audit logs and rate limits for delete/cancel/signed-link/API-token mutations.
+
+TDD gate:
+
+- Add tests for cleanup after success, failure, timeout, cancellation, partial provider creation, duplicate cleanup calls, and pending-delete races.
+- Add tests that the per-run Vault entry is deleted exactly once and `runs.execution_secret_id` is cleared whether or not Claude-side resources are retained.
+- Add tests that a key rotated on the provider side mid-run produces a `tenant_permanent` failure on the next provider call and that cleanup still runs (and the Vault entry is still deleted).
+
+Validation:
+
+- Cleanup failures surface actionable redacted errors.
+- Hard deletion only happens after cleanup/storage deletion succeeds.
+- The per-run Vault entry is always destroyed at terminal cleanup, regardless of retention knobs.
+
+## Phase 12: Minimal dashboard
+
+Build the tenant-scoped monitoring surface.
+
+Deliverables:
+
+- Sign-in/out.
+- Workspace switcher.
+- Runs list.
+- Run detail page.
+- Status, timestamps, attributed user, template hash, provider IDs where safe, usage, cleanup state, and redacted metadata events.
+- Output list and signed-link actions.
+- Cancel/delete actions.
+- Quota/cap warnings.
+
+TDD gate:
+
+- Add component or integration tests for tenant-scoped data loading through BFF only and role/scope behavior for actions.
+
+Validation:
+
+- Dashboard cannot read another workspace's runs or outputs.
+- Dashboard displays cleanup retry/failure separately from run success/failure.
+
+## Phase 13: Observability and operations
+
+Make the platform operable for future agents.
+
+Deliverables:
+
+- Structured worker logs.
+- Redacted error reporting.
+- Run lifecycle metrics.
+- Worker health endpoint.
+- Queue depth/due run metrics.
+- Cleanup retry/dead-letter visibility.
+- Reconciliation summary logs.
+- Admin-only recovery tools if needed.
+
+TDD gate:
+
+- Add tests proving logs/events/errors cannot serialize secret wrappers and include enough non-secret identifiers for diagnosis.
+
+Validation:
+
+- Worker `/health` reports readiness.
+- Operational traces include run id, workspace id, phase, attempt id, provider resource ids where safe, and cleanup status.
+
+## Phase 14: Live-gated e2e and release readiness
+
+Verify the complete lifecycle only when credentials are intentionally present.
+
+Deliverables:
+
+- Live e2e command guarded by explicit env flag.
+- Low-cost Claude Managed Agents fixture Template.
+- Cleanup in `finally`.
+- Release/readiness docs.
+- Updated README and examples for platform SDK usage.
+- GitHub Actions pnpm CI and local Supabase integration job.
+- Vercel dashboard and Railway worker environment-variable contracts.
+- `pnpm dev:stack` for local Supabase/dashboard/worker startup with fail-fast config checks.
+- Deterministic MCP/skills request-wiring tests for SDK and worker providers.
+- Separately gated public MCP plus Anthropic skill full-session e2e.
+
+TDD gate:
+
+- Live e2e is not a TDD driver for core logic, but must prove final integration before release.
+- MCP/skills request shape, permission policy, and secret non-leakage must be covered by normal deterministic tests before relying on public live e2e.
+
+Validation:
+
+- Full submit -> provider session -> metadata poll -> output capture -> signed link -> cleanup works.
+- Public MCP/skills e2e runs through the explicit `pnpm test:e2e:live` command with live credentials, reaches success, emits SDK/provider events, records safe provider IDs, exercises the default cleanup path, and exercises the `cleanup.claudeSession = "retain"` override path with a follow-up provider API check.
+- Default `pnpm lint`, `pnpm test`, and `pnpm build` pass.
+
+## Backlog
+
+- Persistent workspace-level provider connections (saved Anthropic keys with rotation/revocation/re-use). The MVP submission contract carries the key inline per run.
+- Provider webhooks as wakeup/reconciliation accelerator.
+- SSE live event stream for richer dashboard UI.
+- Supabase Realtime with explicit Auth.js-to-Supabase authorization design.
+- Agent/Environment caching by Template/config hash.
+- Additional provider adapters.
+- Runtime human approval flow if product scope changes.
+- Advanced billing and plan management.
+- Cloud Template registry.
+- Curated MCP adapter catalog.