antpath 0.1.0 → 0.1.1

package/references/research-sources.md

@@ -1,30 +1,41 @@
----
-title: antpath research sources
-status: reference
-scope: architecture research
----
-
-# Research sources
-
-Primary sources used to frame the MVP architecture.
-
-| Topic | Source | Notes |
-| --- | --- | --- |
-| Claude Managed Agents overview | https://platform.claude.com/docs/en/managed-agents/overview.md | Agent, Environment, Session, Event primitives; provider-managed autonomous sessions. |
-| Claude Managed Agents environments | https://platform.claude.com/docs/en/managed-agents/environments.md | Environments define container/package/network configuration; sessions get isolated instances. |
-| Claude Managed Agents events | https://platform.claude.com/docs/en/managed-agents/events-and-streaming.md | Event stream, idle/running/terminated states, user messages, interruptions. |
-| Claude Managed Agents files | https://platform.claude.com/docs/en/managed-agents/files.md | Session-scoped files can be listed by `scope_id` and downloaded by file ID. |
-| Claude Managed Agents vaults | https://platform.claude.com/docs/en/managed-agents/vaults.md | Provider-side MCP credentials via vault IDs; static bearer and OAuth credentials. |
-| Claude Managed Agents MCP connector | https://platform.claude.com/docs/en/managed-agents/mcp-connector.md | Agent declares MCP URLs; session supplies vault IDs. |
-| Claude Managed Agents permission policies | https://platform.claude.com/docs/en/managed-agents/permission-policies.md | `always_allow` vs `always_ask`; MVP must avoid approval-required tools. |
-| Anthropic API and data retention | https://platform.claude.com/docs/en/manage-claude/api-and-data-retention.md | Managed Agents are stateful and not automatically deleted. |
-| OpenAI data controls | https://developers.openai.com/api/docs/guides/your-data | Responses retention, `store`, files, container lifecycle, ZDR behavior. |
-| OpenAI remote MCP tools | https://developers.openai.com/api/docs/guides/tools-remote-mcp | Remote MCP `authorization` is sent per request and not stored by OpenAI. |
-| MCP transports | https://modelcontextprotocol.io/specification/2025-11-25/basic/transports.md | Stdio and Streamable HTTP requirements, session IDs, Origin validation. |
-| MCP authorization | https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization.md | OAuth 2.1/OIDC discovery, protected resource metadata, scopes/resource binding. |
-| MCP tools | https://modelcontextprotocol.io/specification/2025-11-25/server/tools.md | Tool schemas, structured content, task support, HITL considerations. |
-| MCP security best practices | https://modelcontextprotocol.io/docs/tutorials/security/security_best_practices.md | Confused deputy and token passthrough risks. |
-| MCP client best practices | https://modelcontextprotocol.io/docs/develop/clients/client-best-practices.md | Progressive discovery, dynamic server management, prompt-cache considerations. |
-| OpenAI Agents SDK JS | https://openai.github.io/openai-agents-js/ | Future comparison point for OpenAI support. |
-| Vercel AI SDK agents | https://ai-sdk.dev/docs/agents/building-agents | Future comparison point for TypeScript agent abstractions. |
-| Temporal TypeScript workflows | https://docs.temporal.io/develop/typescript/workflows/basics | Future reference if antpath adds durable cloud orchestration. |
+---
+title: antpath research sources
+status: reference
+scope: architecture research
+---
+
+# Research sources
+
+Primary sources used to frame the platform MVP architecture.
+
+| Topic | Source | Notes |
+| --- | --- | --- |
+| Claude Managed Agents overview | https://platform.claude.com/docs/en/managed-agents/overview.md | Agent, Environment, Session, Event primitives; provider-managed autonomous sessions. |
+| Claude Managed Agents environments | https://platform.claude.com/docs/en/managed-agents/environments.md | Environments define container/package/network configuration; sessions get isolated instances. |
+| Claude Managed Agents events | https://platform.claude.com/docs/en/managed-agents/events-and-streaming.md | Event stream, idle/running/terminated states, user messages, interruptions. |
+| Claude Managed Agents files | https://platform.claude.com/docs/en/managed-agents/files.md | Session-scoped files can be listed by `scope_id` and downloaded by file ID. |
+| Claude Managed Agents vaults | https://platform.claude.com/docs/en/managed-agents/vaults.md | Provider-side MCP credentials via vault IDs; static bearer and OAuth credentials. |
+| Claude Managed Agents MCP connector | https://platform.claude.com/docs/en/managed-agents/mcp-connector.md | Agent declares MCP URLs; session supplies vault IDs. |
+| Claude Managed Agents permission policies | https://platform.claude.com/docs/en/managed-agents/permission-policies.md | `always_allow` vs `always_ask`; MVP must avoid approval-required tools. |
+| Anthropic API and data retention | https://platform.claude.com/docs/en/manage-claude/api-and-data-retention.md | Managed Agents are stateful and not automatically deleted. |
+| Anthropic webhooks | https://docs.anthropic.com/en/api/webhooks | Webhooks are backlog; if used, treat as wakeup/reconciliation signals, not primary state. |
+| Supabase Postgres RLS | https://supabase.com/docs/guides/database/postgres/row-level-security | RLS is not the MVP browser boundary because Auth.js is primary auth and browser data access goes through BFF. |
+| Supabase Realtime | https://supabase.com/docs/guides/realtime | Realtime is backlog until Auth.js-to-Supabase authorization is explicitly solved. |
+| Supabase Storage access control | https://supabase.com/docs/guides/storage/security/access-control | Private buckets and signed/server-mediated access for captured outputs. |
+| Supabase Vault | https://supabase.com/docs/guides/database/vault | Encrypted storage for workspace BYO provider keys. |
+| Auth.js | https://authjs.dev/ | Dashboard user auth; BFF resolves identity and workspace membership. |
+| Vercel | https://vercel.com/docs | Dashboard deployment baseline. |
+| Railway | https://docs.railway.com/ | Persistent worker deployment baseline. |
+| PostgreSQL `SELECT` locking | https://www.postgresql.org/docs/current/sql-select.html | `FOR UPDATE SKIP LOCKED` for concurrent worker claims. |
+| PostgreSQL `LISTEN`/`NOTIFY` | https://www.postgresql.org/docs/current/sql-notify.html | `NOTIFY` is wakeup only; polling remains source of truth. |
+| npm workspaces | https://docs.npmjs.com/cli/using-npm/workspaces | Repository migration to a TypeScript workspace. |
+| OpenAI data controls | https://developers.openai.com/api/docs/guides/your-data | Responses retention, `store`, files, container lifecycle, ZDR behavior. |
+| OpenAI remote MCP tools | https://developers.openai.com/api/docs/guides/tools-remote-mcp | Remote MCP `authorization` is sent per request and not stored by OpenAI. |
+| MCP transports | https://modelcontextprotocol.io/specification/2025-11-25/basic/transports.md | Stdio and Streamable HTTP requirements, session IDs, Origin validation. |
+| MCP authorization | https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization.md | OAuth 2.1/OIDC discovery, protected resource metadata, scopes/resource binding. |
+| MCP tools | https://modelcontextprotocol.io/specification/2025-11-25/server/tools.md | Tool schemas, structured content, task support, HITL considerations. |
+| MCP security best practices | https://modelcontextprotocol.io/docs/tutorials/security/security_best_practices.md | Confused deputy and token passthrough risks. |
+| MCP client best practices | https://modelcontextprotocol.io/docs/develop/clients/client-best-practices.md | Progressive discovery, dynamic server management, prompt-cache considerations. |
+| OpenAI Agents SDK JS | https://openai.github.io/openai-agents-js/ | Future comparison point for OpenAI support. |
+| Vercel AI SDK agents | https://ai-sdk.dev/docs/agents/building-agents | Future comparison point for TypeScript agent abstractions. |
+| Temporal TypeScript workflows | https://docs.temporal.io/develop/typescript/workflows/basics | Future reference if antpath adds durable cloud orchestration. |

package/references/testing-strategy.md

@@ -1,108 +1,29 @@
----
-title: antpath testing strategy
-status: accepted
-scope: sdk-only MVP
----
-
-# antpath testing strategy
-
-antpath uses **test-first development**. For every behavior change, write or update the relevant failing test first, then implement the smallest maintainable change that passes it.
-
-## Test layers
-
-| Layer | Name | Purpose | Default CI |
-| --- | --- | --- | --- |
-| 1 | Unit | Pure logic and small state transitions. | Yes |
-| 2 | Component integration | Multiple SDK components with fake providers and local fixtures. | Yes |
-| 3 | Recorded API integration | Provider adapter behavior using sanitized real API recordings. | Yes, if fixtures are present |
-| 4 | Live e2e | Full lifecycle against real Claude Managed Agents. | No |
-
-## Layer 1: unit tests
-
-Unit tests must have no network, provider, or real filesystem dependency unless the unit being tested is explicitly a path utility.
-
-Targets:
-
-- Template compiler;
-- variable resolution and escaping;
-- credential parser;
-- redaction utilities;
-- state-machine reducer;
-- cleanup plan builder;
-- output path sanitizer.
-
-## Layer 2: component integration tests
-
-Component integration tests verify collaboration between modules with fake providers.
-
-Targets:
-
-- Client plus Template compiler plus credential validator;
-- RunController plus fake provider stream;
-- queued message scheduler;
-- output downloader plus fake file service;
-- cleanup manager plus fake provider resources;
-- logger/event hooks with redaction.
-
-## Layer 3: recorded API integration tests
-
-Recorded API integration tests use persisted responses from real provider calls. These tests make provider adapter behavior reproducible without live network calls.
-
-Rules:
-
-- Recordings are created only by explicit scripts.
-- Raw recordings are ignored and must not be committed.
-- Sanitized recordings may be committed.
-- Sanitization must remove request headers, API keys, bearer tokens, OAuth tokens, raw credentials, and any secret-shaped values.
-- Tests must fail if a fixture contains known secret patterns.
-- Fixtures should include provider API version and beta headers in non-secret metadata.
-
-Expected scripts:
-
-```text
-npm run fixtures:record:anthropic
-npm run fixtures:sanitize
-npm run test:integration:api
-```
-
-## Layer 4: live e2e tests
-
-Live e2e tests verify the complete lifecycle against Claude Managed Agents.
-
-Rules:
-
-- Never run by default.
-- Require `.env.local` with `ANTHROPIC_API_KEY`.
-- Use low-cost prompts and short timeouts.
-- Always attempt cleanup in `finally`.
-- Never print credentials or auth headers.
-- Keep assertions focused on lifecycle invariants, not model prose.
-
-Expected command:
-
-```text
-npm run test:e2e:live
-```
-
-## Secret handling
-
-`.env.local` may be used for local live testing and must stay ignored. Do not inspect, print, snapshot, or commit it.
-
-Secrets must never appear in:
-
-- committed fixtures;
-- logs;
-- snapshots;
-- error messages;
-- Template snapshots;
-- output manifests;
-- reference documents.
-
-## Test-first workflow
-
-1. Choose the narrowest test layer that can prove the behavior.
-2. Add a failing test.
-3. Implement the behavior.
-4. Run the target test command.
-5. Run broader tests only when the behavior crosses module/provider boundaries.
-6. Update recorded fixtures only through recording and sanitization scripts.
+---
+title: antpath testing strategy
+status: accepted
+scope: SDK package
+---
+
+# antpath SDK testing strategy
+
+The SDK follows the repository taxonomy: unit, integration, and e2e only.
+
+## Unit
+
+`pnpm test` and `pnpm test:unit` run deterministic unit tests. Unit tests may use fakes, generated data, and sanitized recorded snapshots, including expensive provider responses captured once and replayed later.
+
+```text
+pnpm test
+pnpm test:unit
+pnpm test:property
+pnpm test:unit:recorded
+pnpm test:load:replay
+```
+
+## Integration
+
+Integration tests run live external systems with no fakes and no skip flags. SDK package integration is currently covered through the workspace Supabase integration and worker provider integration commands.
+
+## E2E
+
+`pnpm test:e2e:live` runs the live top-to-bottom Claude Managed Agents flow. The command itself is the opt-in and requires `ANTHROPIC_API_KEY`; missing credentials fail the command rather than skipping.