antpath 0.1.0

package/references/implementation-plan.md

@@ -0,0 +1,527 @@
+---
+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.

package/references/research-sources.md

@@ -0,0 +1,30 @@
+---
+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. |

package/references/testing-strategy.md

@@ -0,0 +1,108 @@
+---
+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.