antpath 0.1.0 → 0.2.0

package/docs/credentials.md

@@ -1,23 +1,105 @@
----
-title: Credentials
----
-
-# Credentials
-
-antpath does not store provider keys or MCP credential values.
-
-The caller creates `AntpathClient` with a provider key. MCP credentials are passed at run time and validated against Template requirements.
-
-MVP credential types:
-
-- `static_bearer`;
-- `oauth_access_token`.
-
-Unsupported in MVP:
-
-- arbitrary headers;
-- OAuth refresh;
-- persisted antpath vault;
-- antpath MCP proxy.
-
-For Claude Managed Agents, the SDK creates per-run provider vault credentials and tracks provider IDs for cleanup.
+---
+title: Credentials
+---
+
+# Credentials
+
+antpath does not store provider keys or MCP credential values.
+
+The caller creates `AntpathClient` with a provider key. MCP credentials are passed at run time and validated against Template requirements.
+
+MVP credential types:
+
+- `static_bearer`;
+- `oauth_access_token`.
+
+Unsupported in MVP:
+
+- arbitrary headers;
+- OAuth refresh;
+- persisted antpath vault.
+
+For Claude Managed Agents, the SDK creates per-run provider vault credentials and tracks provider IDs for cleanup.
+
+## Proxy endpoints (per-run custom HTTP credentials)
+
+Some skills need to call non-MCP HTTP services (e.g. Stripe, internal APIs). Embedding the credential in the skill content puts the raw secret on disk in the agent container and in the model's context — both prompt-injection-readable.
+
+The platform's managed HTTP proxy is the agent-first alternative. The caller declares **policy** at the top level of the submission (hashed for idempotency) and supplies the matching **auth value** inside `secrets` (not hashed, so key rotation does not collapse onto a stale run). The raw credential value never enters the container.
+
+```ts
+import {
+  AntpathPlatformClient,
+  validateProxyAuth,
+  buildPlatformAllowedHosts
+} from "antpath";
+
+const client = new AntpathPlatformClient({
+  baseUrl: "https://dashboard.antpath.dev",
+  apiToken: "ant_..."
+});
+
+const proxyEndpoints = [
+  {
+    name: "stripe",
+    baseUrl: "https://api.stripe.com",
+    authShape: { type: "bearer" },
+    allowMethods: ["GET", "POST"],
+    allowPathPrefixes: ["/v1/charges", "/v1/refunds"],
+    maxRequestBytes: 65_536,
+    maxResponseBytes: 65_536,
+    timeoutMs: 10_000,
+    responseMode: "headers_only",
+    perCallBudget: 60,
+    responseByteBudget: 1_048_576
+  }
+] as const;
+
+const proxyEndpointAuth = [
+  {
+    name: "stripe",
+    value: { type: "bearer", token: process.env.STRIPE_API_KEY! }
+  }
+] as const;
+
+// Fail fast at submission time when policy and auth disagree.
+validateProxyAuth(proxyEndpoints, proxyEndpointAuth);
+
+const run = await client.submitRun({
+  templateId: "tmpl_xxx",
+  proxyEndpoints,
+  secrets: {
+    anthropic: { apiKey: process.env.ANTHROPIC_API_KEY! },
+    proxyEndpointAuth
+  }
+});
+```
+
+Inside the run container, every session has the platform CLI mounted at `/antpath/antpath` (a Node ESM bundle) and a manifest at `/antpath/index.json` describing the declared endpoints. The skill calls the proxy via the CLI:
+
+```bash
+node /antpath/antpath proxy stripe \
+  --method GET \
+  --path /v1/charges/ch_123 \
+  --response-mode headers_only
+```
+
+The CLI reads the per-run bearer from `/antpath/run-token`, attaches the `X-Antpath-Proxy-Protocol` header, and the BFF injects the bearer/header/query/basic credential before dispatching the outbound call. Only the response (subject to `responseMode` and `maxResponseBytes`) reaches the container. `--response-mode` can only narrow below the policy ceiling.
+
+`node /antpath/antpath --help` reads endpoint details from `/antpath/index.json`. Runs that do not declare any `proxyEndpoints` still have the CLI and an empty manifest mounted, so agents never need to introspect whether the surface exists.
+
+### Networking
+
+When a Template uses `limited` networking, the platform host must appear in `allowed_hosts`. The worker injects it automatically; for advance validation in user-built Templates use:
+
+```ts
+const allowedHosts = buildPlatformAllowedHosts({
+  dashboardBaseUrl: "https://dashboard.antpath.dev",
+  extraHosts: ["api.stripe.com"]
+});
+```
+
+### Deprecation: `defaultSecrets`
+
+`AntpathPlatformClientOptions.defaultSecrets` is deprecated. Pass `secrets` explicitly on every `submitRun` call so the active credentials are visible at the call site (agent-first design). The client emits a one-time deprecation warning when constructed with `defaultSecrets`.
+

package/docs/events.md

@@ -0,0 +1,129 @@
+---
+title: Events
+---
+
+# Events
+
+Claude Managed Agents sessions run autonomously on Anthropic's infrastructure.
+They are **non-blocking**: the SDK opens a long-lived SSE stream while the
+agent thinks, calls tools, and emits messages on its own schedule. The SDK
+cannot intercept a tool call to return a value — `permission_policy` is
+`always_allow`. This guide covers the observe-only event surface.
+
+## Two ways to consume events
+
+```ts
+// Push: register a callback in RunOptions.
+const handle = await client.run(template, {
+  onEvent: async (event) => {
+    if (event.type === "provider.event") {
+      // event.event is a ProviderEvent (typed via a type guard below).
+    }
+  }
+});
+await handle.wait();
+```
+
+```ts
+// Pull: iterate the stream concurrently with handle.wait().
+const handle = await client.run(template);
+const collect = (async () => {
+  for await (const event of handle.streamEvents()) {
+    // ...
+  }
+})();
+const result = await handle.wait();
+await collect;
+```
+
+Both surfaces observe the same events. They can be used together; every
+subscriber sees every event. A subscriber attached after `client.run()`
+returns replays the events it missed (including the initial
+`sdk.status` emitted while provider resources were being created), then
+continues live.
+
+## Event shape
+
+```ts
+type RunEvent =
+  | { type: "sdk.status"; status: RunStatus; at: string }
+  | { type: "sdk.message_sent"; index: number; at: string }
+  | { type: "sdk.cleanup"; ... }       // see "Cleanup events" below
+  | { type: "provider.event"; event: ProviderEvent; at: string };
+
+interface ProviderEvent {
+  type: string;       // documented Claude event type, e.g. "agent.tool_use"
+  payload: unknown;   // raw provider payload, redacted
+  receivedAt: string;
+}
+```
+
+All events pass through the SDK's secret redaction before reaching any
+subscriber, so payloads do not contain the Anthropic key or MCP credentials
+that were supplied to `client.run()`.
+
+## Drain-before-`wait()` guarantee
+
+By the time `await handle.wait()` resolves, every `onEvent` invocation
+triggered by events emitted before the terminal `sdk.status` has itself
+resolved or rejected. Async handlers are invoked serially in event order on
+a single per-listener promise chain, so callers can persist events in order
+without their own queue.
+
+The same drain applies to handlers that throw — both modes (warn-only and
+abort-on-error, see below) wait for the offending invocation to settle
+before resolving.
+
+## Error semantics
+
+Default: a handler that throws (or returns a rejecting promise) is logged
+via the SDK's configured `logger` at `warn`. The run continues, and the
+final result is unaffected.
+
+Opt-in: `onEventAbortOnError: true` upgrades the **first** pre-terminal
+handler error into a `RunStateError` that fails the run. Once terminal
+status has been reached, listener errors are always logged only — they
+never mutate the result, and they cannot trigger recursion when the
+terminal `sdk.status: failed` event itself causes another error.
+
+`RunStateError.message` and its `cause` field pass through the same
+redaction layer used for events.
+
+## Cleanup events
+
+`sdk.cleanup` events are part of the `RunEvent` union, but they are
+emitted by `handle.cleanup()` after `handle.wait()` has already resolved.
+By that time the event bus has been closed; subscribers attached during
+the run do **not** see them. Inspect cleanup outcomes via the
+`CleanupResult.operations` array returned by `cleanup()` instead.
+
+## Typed helpers
+
+`packages/sdk/src/providers/known-events.ts` exports conservative type
+guards that narrow `ProviderEvent.type` to documented Claude event strings.
+They do **not** assert payload field shapes — the raw provider payload
+stays `unknown` until callers parse it themselves.
+
+```ts
+import {
+  isAgentMessage,
+  isAgentToolUse,
+  isAgentToolResult,
+  isAgentMcpToolUse,
+  isAgentMcpToolResult,
+  isAgentCustomToolUse,
+  isAgentThinking,
+  isUserMessage,
+  isSessionStatusRunning,
+  isSessionStatusIdle,
+  isSessionStatusTerminated,
+  isSessionError,
+  isAgentEvent,
+  isUserEvent,
+  isSessionEvent,
+  isSpanEvent
+} from "antpath";
+```
+
+The official list of event types is maintained at
+[`platform.claude.com/docs/en/managed-agents/events-and-streaming`](https://platform.claude.com/docs/en/managed-agents/events-and-streaming).

package/docs/mcp.md

@@ -1,18 +1,18 @@
----
-title: MCP
----
-
-# MCP
-
-MVP MCP support is provider-native remote HTTPS MCP only.
-
-Rules:
-
-- MCP servers are declared in Templates.
-- Runtime HITL is disabled.
-- Tool policy must be configured before session start.
-- Enabled MCP tools use `always_allow` provider permissions.
-- `always_ask` is not used by antpath MVP.
-- Only provider-native bearer/OAuth auth is supported.
-
-Use allowlists for sensitive servers whenever possible.
+---
+title: MCP
+---
+
+# MCP
+
+MVP MCP support is provider-native remote HTTPS MCP only.
+
+Rules:
+
+- MCP servers are declared in Templates.
+- Runtime HITL is disabled.
+- Tool policy must be configured before session start.
+- Enabled MCP tools use `always_allow` provider permissions.
+- `always_ask` is not used by antpath MVP.
+- Only provider-native bearer/OAuth auth is supported.
+
+Use allowlists for sensitive servers whenever possible.

package/docs/outputs.md

@@ -1,16 +1,16 @@
----
-title: Outputs
----
-
-# Outputs
-
-`downloadOutputs()` downloads all session-scoped provider files by default.
-
-`/antpath/outputs` is a recommended convention, not a provider default. Templates may instruct agents to write important artifacts there, but MVP output download still uses session-scoped files.
-
-Safety rules:
-
-- filenames are sanitized;
-- downloads stay within the requested local directory;
-- max file count and max total bytes are enforced;
-- manifests contain provider file IDs, local paths, names, and sizes only.
+---
+title: Outputs
+---
+
+# Outputs
+
+`downloadOutputs()` downloads all session-scoped provider files by default.
+
+`/antpath/outputs` is a recommended convention, not a provider default. Templates may instruct agents to write important artifacts there, but MVP output download still uses session-scoped files.
+
+Safety rules:
+
+- filenames are sanitized;
+- downloads stay within the requested local directory;
+- max file count and max total bytes are enforced;
+- manifests contain provider file IDs, local paths, names, and sizes only.

package/docs/quickstart.md

@@ -1,13 +1,13 @@
----
-title: antpath quickstart
----
-
-# Quickstart
-
-1. Put `ANTHROPIC_API_KEY` in `.env.local`.
-2. Define a secret-free Template in TypeScript.
-3. Create `AntpathClient`.
-4. Run the Template.
-5. Wait, download files, then call `cleanup()`.
-
-See `README.md` for a minimal example.
+---
+title: antpath quickstart
+---
+
+# Quickstart
+
+1. Put `ANTHROPIC_API_KEY` in `.env.local`.
+2. Define a secret-free Template in TypeScript.
+3. Create `AntpathClient`.
+4. Run the Template.
+5. Wait, download files, then call `cleanup()`.
+
+See `README.md` for a minimal example.

package/docs/release.md

@@ -1,22 +1,22 @@
----
-title: Release
----
-
-# Release
-
-CI runs on pull requests and pushes to `main`.
-
-Publishing runs when a GitHub release is published, or when the publish workflow is manually dispatched.
-
-Repository setup required:
-
-1. Create or reserve the `antpath` package on npm.
-2. Add a Trusted Publisher for this GitHub repository.
-3. Set **Organization or user** to `weilueluo`.
-4. Set **Repository** to `antpath`.
-5. Set **Workflow filename** to `publish.yml`.
-6. Leave **Environment name** empty unless the workflow uses a matching GitHub Actions environment.
-7. Update `package.json` version before publishing a release.
-8. Publish a GitHub release for that version.
-
-The publish workflow uses GitHub OIDC through `id-token: write`; it does not require an npm token secret. It runs type-checks, tests, build, then `npm publish --provenance`.
+---
+title: Release
+---
+
+# Release
+
+CI runs on pull requests and pushes to `main`.
+
+Publishing runs when a GitHub release is published, or when the publish workflow is manually dispatched.
+
+Repository setup required:
+
+1. Create or reserve the `antpath` package on npm.
+2. Add a Trusted Publisher for this GitHub repository.
+3. Set **Organization or user** to `weilueluo`.
+4. Set **Repository** to `antpath`.
+5. Set **Workflow filename** to `publish.yml`.
+6. Leave **Environment name** empty unless the workflow uses a matching GitHub Actions environment.
+7. Update `packages/sdk/package.json` version before publishing a release.
+8. Publish a GitHub release for that version.
+
+The publish workflow uses GitHub OIDC through `id-token: write`; it does not require an npm token secret. It runs type-checks, tests, build, then publishes the `antpath` SDK workspace with provenance.

package/docs/skills.md

@@ -1,16 +1,18 @@
----
-title: Skills
----
-
-# Skills
-
-MVP skill inputs:
-
-- provider-managed Anthropic skills;
-- existing custom provider skill IDs;
-- local files/directories uploaded as session resources;
-- inline skill content uploaded as session resources.
-
-Local directories are packaged as zip files and mounted under `/antpath/skills/` unless overridden.
-
-Inline skills are uploaded as markdown files and mounted under `/antpath/skills/` unless overridden.
+---
+title: Skills
+---
+
+# Skills
+
+MVP skill inputs:
+
+- provider-managed Anthropic skills;
+- existing custom provider skill IDs;
+- local files/directories uploaded as session resources;
+- inline skill content uploaded as session resources.
+
+Local directories are packaged as zip files and mounted under `/antpath/skills/` unless overridden.
+
+Inline skills are uploaded as markdown files and mounted under `/antpath/skills/` unless overridden.
+
+The platform also mounts the `antpath` CLI at `/antpath/antpath` and a per-run manifest at `/antpath/index.json` on **every** run. Skills can invoke the managed HTTP proxy via `node /antpath/antpath proxy …` — see `credentials.md` for the policy/auth model.

package/docs/templates.md

@@ -1,24 +1,24 @@
----
-title: Templates
----
-
-# Templates
-
-Templates are code-defined, immutable, secret-free run configurations.
-
-Allowed Template content:
-
-- model;
-- system prompt;
-- queued user messages;
-- typed variables;
-- MCP server declarations;
-- MCP tool allow/deny policy;
-- environment package and network configuration;
-- inline/local/provider skills;
-- output conventions;
-- non-secret metadata.
-
-Variables use `{{name}}` and are resolved before provider calls. Use `\{{name}}` for a literal placeholder.
-
-Secrets must not appear in Templates. Pass credentials through `run({ credentials })`.
+---
+title: Templates
+---
+
+# Templates
+
+Templates are code-defined, immutable, secret-free run configurations.
+
+Allowed Template content:
+
+- model;
+- system prompt;
+- queued user messages;
+- typed variables;
+- MCP server declarations;
+- MCP tool allow/deny policy;
+- environment package and network configuration;
+- inline/local/provider skills;
+- output conventions;
+- non-secret metadata.
+
+Variables use `{{name}}` and are resolved before provider calls. Use `\{{name}}` for a literal placeholder.
+
+Secrets must not appear in Templates. Pass credentials through `run({ credentials })`.

package/docs/testing.md

@@ -1,27 +1,26 @@
----
-title: Testing
----
-
-# Testing
-
-antpath uses test-first development.
-
-Commands:
-
-```text
-npm run test:unit
-npm run test:integration:components
-npm run test:integration:api
-npm run test:e2e:live
-```
-
-Live tests require `.env.local` and `RUN_LIVE_ANTPATH_TESTS=1`.
-
-Recorded API fixtures are created with:
-
-```text
-npm run fixtures:record:anthropic
-npm run fixtures:sanitize
-```
-
-Raw fixtures and secret-shaped fixture files are ignored.
+---
+title: Testing
+---
+
+# Testing
+
+antpath uses test-first development.
+
+Commands:
+
+```text
+npm run test:unit
+npm run test:unit:recorded
+npm run test:e2e:live
+```
+
+Unit tests are deterministic and may use fakes or sanitized recorded snapshots. Live tests run when `npm run test:e2e:live` is invoked with `.env.local` containing `ANTHROPIC_API_KEY`.
+
+Recorded API fixtures are created with:
+
+```text
+npm run fixtures:record:anthropic
+npm run fixtures:sanitize
+```
+
+Raw fixtures and secret-shaped fixture files are ignored.

package/examples/mcp-static-bearer.ts

@@ -1,30 +1,30 @@
-import { AntpathClient, defineTemplate, requiredStaticBearer } from "antpath";
-
-const client = new AntpathClient({
-  anthropicApiKey: process.env.ANTHROPIC_API_KEY
-});
-
-const template = defineTemplate({
-  name: "mcp-static-bearer",
-  model: "claude-haiku-4-5",
-  messages: ["List the relevant records and summarize them."],
-  mcpServers: {
-    example: {
-      url: "https://mcp.example.com/mcp",
-      auth: requiredStaticBearer(),
-      tools: { allow: ["search", "fetch"] }
-    }
-  }
-});
-
-const handle = await client.run(template, {
-  credentials: {
-    example: {
-      type: "static_bearer",
-      token: process.env.EXAMPLE_MCP_TOKEN ?? ""
-    }
-  }
-});
-
-await handle.wait();
-await handle.cleanup();
+import { AntpathClient, defineTemplate, requiredStaticBearer } from "antpath";
+
+const client = new AntpathClient({
+  anthropicApiKey: process.env.ANTHROPIC_API_KEY
+});
+
+const template = defineTemplate({
+  name: "mcp-static-bearer",
+  model: "claude-haiku-4-5",
+  messages: ["List the relevant records and summarize them."],
+  mcpServers: {
+    example: {
+      url: "https://mcp.example.com/mcp",
+      auth: requiredStaticBearer(),
+      tools: { allow: ["search", "fetch"] }
+    }
+  }
+});
+
+const handle = await client.run(template, {
+  credentials: {
+    example: {
+      type: "static_bearer",
+      token: process.env.EXAMPLE_MCP_TOKEN ?? ""
+    }
+  }
+});
+
+await handle.wait();
+await handle.cleanup();

package/examples/quickstart.ts

@@ -1,23 +1,23 @@
-import { AntpathClient, defineTemplate, string } from "antpath";
-
-const client = new AntpathClient({
-  anthropicApiKey: process.env.ANTHROPIC_API_KEY
-});
-
-const template = defineTemplate({
-  name: "quickstart",
-  model: "claude-haiku-4-5",
-  system: "You are a concise automation agent.",
-  messages: ["Write a short answer about {{topic}}."],
-  variables: {
-    topic: string()
-  }
-});
-
-const handle = await client.run(template, {
-  variables: { topic: "test-first SDK design" }
-});
-
-const result = await handle.wait();
-console.log(result.status);
-await handle.cleanup();
+import { AntpathClient, defineTemplate, string } from "antpath";
+
+const client = new AntpathClient({
+  anthropicApiKey: process.env.ANTHROPIC_API_KEY
+});
+
+const template = defineTemplate({
+  name: "quickstart",
+  model: "claude-haiku-4-5",
+  system: "You are a concise automation agent.",
+  messages: ["Write a short answer about {{topic}}."],
+  variables: {
+    topic: string()
+  }
+});
+
+const handle = await client.run(template, {
+  variables: { topic: "test-first SDK design" }
+});
+
+const result = await handle.wait();
+console.log(result.status);
+await handle.cleanup();