antpath 0.1.0

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "antpath",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for running autonomous Claude Managed Agents sessions.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/weilueluo/antpath.git"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "docs",
+    "examples",
+    "references"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "lint": "tsc --noEmit",
+    "test": "vitest run test/unit test/integration/components test/integration/api-recorded",
+    "test:unit": "vitest run test/unit",
+    "test:integration:components": "vitest run test/integration/components",
+    "test:integration:api": "vitest run test/integration/api-recorded",
+    "test:e2e:live": "vitest run test/integration/live",
+    "fixtures:record:anthropic": "tsx scripts/record-api-fixtures.ts",
+    "fixtures:sanitize": "tsx scripts/sanitize-api-fixtures.ts",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "eventsource-parser": "3.0.6",
+    "fflate": "0.8.2"
+  },
+  "devDependencies": {
+    "@types/node": "22.15.3",
+    "dotenv": "16.5.0",
+    "tsx": "4.19.4",
+    "typescript": "5.8.3",
+    "vitest": "3.1.2"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/references/architecture-decisions.md

@@ -0,0 +1,203 @@
+---
+title: antpath architecture decisions
+status: accepted
+scope: sdk-only MVP
+---
+
+# antpath architecture decisions
+
+## Product framing
+
+antpath starts as a **TypeScript-first SDK** for launching autonomous agent runs on provider-managed agent infrastructure. The MVP is intentionally not a dashboard, not a cloud control plane, not an agent-loop framework, and not a sandbox provider.
+
+The SDK gives users a typed way to define reusable, code-first Templates and run them with caller-held provider credentials. The SDK returns a handle for monitoring, waiting, streaming events, downloading files, terminating, and cleaning up provider resources.
+
+## Non-goals for MVP
+
+- No dashboard.
+- No antpath-hosted run orchestration service.
+- No stored provider API keys.
+- No stored MCP credentials.
+- No stored output file contents.
+- No local stdio MCP bridge.
+- No arbitrary MCP auth headers.
+- No OpenAI integration in MVP.
+- No runtime human approval flow.
+- No antpath-managed sandbox.
+
+## Core MVP decisions
+
+| Area | Decision |
+| --- | --- |
+| Product surface | SDK-only MVP. |
+| Primary language | TypeScript first. |
+| Provider | Claude Managed Agents only. |
+| Future providers | OpenAI is backlog; do not force a lowest-common-denominator abstraction into MVP. |
+| Template model | Code-only, immutable, secret-free Template snapshots. |
+| Template name | Use `Template`, not `Environment`, to avoid collision with provider environment objects. |
+| Provider key handling | User creates a SDK `Client` with the provider key; antpath does not store it. |
+| MCP credential handling | Credentials are supplied at run time in typed objects; antpath creates provider vault credentials per run where needed. |
+| MCP auth scope | Provider-native static bearer and OAuth access token only. |
+| Runtime approvals | No runtime approval/HITL. Tool allow/deny policy is configured before session start. |
+| MCP server scope | User-provided remote HTTPS MCP servers only. |
+| Provider objects | SDK creates Agent, Environment, Vault/Credentials, and Session per run. |
+| Cleanup default | Manual cleanup via `handle.cleanup()` by default. |
+| Orphan risk | Accepted for MVP if the SDK process exits before cleanup. |
+| Run input | One or more queued `user.message` events. |
+| Queue behavior | First message starts the session; subsequent messages are sent whenever the session becomes idle. |
+| Completion | First idle state after all queued messages have been sent. |
+| Error behavior | Abort on any provider session error or terminated state. |
+| Budget guardrails | Timeout and manual terminate only. |
+| Outputs | `downloadOutputs()` downloads all session-scoped files by default. `/antpath/outputs` is a recommended convention, not a provider default. |
+| Skills | Support local skill upload plus inline skill definitions. |
+| Variables | Strict Template variable resolution with escaping for literal placeholders. |
+| Secret boundary | Secrets are allowed only in typed credential inputs, never interpolated as Template variables. |
+| Handle API | `status`, `streamEvents`, `wait`, `listFiles`, `downloadFile`, `downloadOutputs`, `cleanup`, `terminate`, `usage`, `result`. |
+| Development workflow | Test-first development with unit, component integration, recorded API integration, and live e2e tests. |
+
+## Template contract
+
+Templates are code-defined, immutable configuration snapshots. A Template may include:
+
+- model;
+- system prompt;
+- one or more user messages;
+- inline skills;
+- local skill paths to upload;
+- MCP server declarations;
+- MCP tool allow/deny policy;
+- required credential declarations;
+- environment packages and setup commands;
+- network allowlist;
+- output path conventions or file filters;
+- non-secret metadata.
+
+Templates may use typed variables in:
+
+- system prompt;
+- user messages;
+- skill content/config;
+- MCP URLs;
+- MCP tool policy;
+- environment packages/setup;
+- network allowlist;
+- output paths;
+- metadata.
+
+All variables must resolve before provider object creation. Unresolved variables fail fast. Literal placeholder syntax must be escaped explicitly.
+
+## Credential contract
+
+Templates declare credential requirements but never contain credential values.
+
+MVP credential types:
+
+- `static_bearer`;
+- `oauth_access_token`.
+
+Out of scope for MVP:
+
+- arbitrary headers;
+- OAuth refresh handling;
+- persisted credential vault in antpath;
+- antpath-hosted MCP proxy.
+
+For Claude Managed Agents, the SDK creates a per-run provider vault and credentials, passes the vault ID to session creation, and deletes the provider vault during cleanup. Since the SDK caller owns the provider key, cleanup requires the SDK process or a later caller with the same key.
+
+## Run lifecycle
+
+1. Resolve Template variables and validate the resolved Template.
+2. Validate typed credentials against Template credential requirements.
+3. Create provider Environment.
+4. Upload local skill/resources and create inline skill resources as required.
+5. Create provider Agent with tools, skills, MCP servers, and permission policies.
+6. Create per-run provider Vault and Credentials when MCP credentials are supplied.
+7. Create provider Session with Agent, Environment, resources, and vault IDs.
+8. Send the first queued `user.message`.
+9. Stream provider events and update local run state.
+10. If the session becomes idle and queued messages remain, send the next message.
+11. If any provider error or terminated state occurs, abort and return a failed result.
+12. When the session becomes idle and no queued messages remain, mark the run succeeded.
+13. On `downloadOutputs()`, list and download session-scoped files.
+14. On `cleanup()`, delete/cleanup created provider resources according to policy.
+
+## State model
+
+MVP state lives in the SDK handle and returned result. There is no cloud persistence requirement.
+
+Run states:
+
+- `initializing`;
+- `creating_provider_resources`;
+- `running`;
+- `idle_waiting_to_send_next_message`;
+- `downloading_outputs`;
+- `succeeded`;
+- `failed`;
+- `terminating`;
+- `terminated`;
+- `cleanup_pending`;
+- `cleaned_up`;
+
+The handle should retain enough non-secret data to support local inspection:
+
+- provider object IDs;
+- Template version/hash;
+- status timestamps;
+- usage/cost summary when available;
+- error details;
+- cleanup state;
+- downloaded file manifest if files were downloaded locally.
+
+## Cleanup policy
+
+Manual cleanup is the default. This preserves post-run provider access and avoids surprising users by deleting files/events before they inspect them.
+
+The SDK may support configurable cleanup policies:
+
+- manual;
+- cleanup after successful output download;
+- cleanup on success;
+- cleanup always after terminal state;
+- delete only vault/credentials.
+
+If the process exits before cleanup, provider resources may remain in the user's provider workspace. The SDK should expose cleanup state and enough provider IDs to support later cleanup when the user recreates a Client with the same provider key.
+
+## Risks accepted for MVP
+
+| Risk | Status | Mitigation |
+| --- | --- | --- |
+| Provider objects can be orphaned if the SDK process dies before cleanup. | Accepted | Manual cleanup default; expose cleanup state and provider IDs. |
+| Per-run Environment creation may be slow. | Accepted | Keep design simple for MVP; later cache by Template hash if needed. |
+| Timeout-only budgeting does not cap token/tool spend. | Accepted | BYOK MVP; expose usage summary where provider supports it. |
+| Arbitrary remote MCP servers can exfiltrate context. | Accepted with guardrails | Require explicit MCP declarations and tool allow/deny config; no runtime approvals. |
+| No dashboard/cloud persistence. | Accepted | SDK-only MVP; dashboard is backlog. |
+| OpenAI MCP auth differs from Claude vaults. | Backlog design risk | Add provider-specific auth adapters later; avoid pretending uniform support exists now. |
+
+## Verification contract
+
+Every feature starts with the narrowest failing test that describes the intended behavior. Implementation follows only after the test shape is clear.
+
+Required test layers:
+
+1. Unit tests for pure functions and small state transitions.
+2. Component integration tests across SDK modules using fake providers and local fixtures.
+3. Recorded API integration tests using persisted, sanitized responses captured from real provider API calls and reproducible recording scripts.
+4. Live e2e tests gated behind local credentials in `.env.local`.
+
+Secrets must never appear in committed fixtures, logs, snapshots, manifests, errors, or reference docs.
+
+## Backlog
+
+- Dashboard and cloud metadata sync.
+- Cloud Template registry.
+- OpenAI Responses/Agents adapter.
+- Encrypted run-scoped keys for guaranteed cleanup.
+- Cost/token/iteration caps.
+- OAuth refresh credential support.
+- Arbitrary MCP headers through an antpath MCP proxy.
+- Curated MCP adapter catalog.
+- Provider Environment caching by Template hash.
+- Artifact retention service.
+- Webhook-based monitoring.
+- Team/workspace/multi-tenant permissions.