antpath 0.1.1 → 0.2.1

package/dist/utils/events.js

@@ -1,39 +1,118 @@
 export class AsyncEventBus {
     #history = [];
-    #waiters = [];
+    #streamSubscribers = new Set();
+    #listeners = new Set();
     #closed = false;
     emit(event) {
         if (this.#closed) {
             return;
         }
         this.#history.push(event);
-        const waiter = this.#waiters.shift();
-        if (waiter) {
-            waiter({ value: event, done: false });
+        for (const subscriber of this.#streamSubscribers) {
+            const wake = subscriber.wake;
+            if (wake) {
+                subscriber.wake = undefined;
+                wake();
+            }
+        }
+        for (const listener of this.#listeners) {
+            listener.chain = listener.chain.then(() => listener.handler(event)).catch((error) => {
+                try {
+                    listener.onError(error, event);
+                }
+                catch {
+                    // onError must never throw; swallow to keep the chain alive for future events.
+                }
+            });
         }
     }
     close() {
+        if (this.#closed) {
+            return;
+        }
         this.#closed = true;
-        for (const waiter of this.#waiters.splice(0)) {
-            waiter({ value: undefined, done: true });
+        for (const subscriber of this.#streamSubscribers) {
+            const wake = subscriber.wake;
+            if (wake) {
+                subscriber.wake = undefined;
+                wake();
+            }
         }
     }
+    closed() {
+        return this.#closed;
+    }
+    /**
+     * Register a callback that is invoked for every emitted event in order.
+     *
+     * Async handlers are serialized through a per-listener promise chain so
+     * invocation order matches emission order. Errors thrown synchronously or
+     * via rejected promises are routed to onError. The chain stays fulfilled
+     * even when handlers fail, so subsequent events still trigger the handler.
+     */
+    addListener(handler, onError) {
+        const listener = {
+            handler,
+            onError,
+            chain: Promise.resolve()
+        };
+        this.#listeners.add(listener);
+        return () => {
+            this.#listeners.delete(listener);
+        };
+    }
+    /**
+     * Await every queued listener invocation that has already been scheduled at
+     * the moment this method is called. Callers (e.g., the run controller)
+     * must finish emitting before invoking drainListeners; emits that happen
+     * after drainListeners is awaited are not guaranteed to be observed by the
+     * returned promise.
+     */
+    async drainListeners() {
+        if (this.#listeners.size === 0) {
+            return;
+        }
+        const snapshot = [...this.#listeners].map((listener) => listener.chain);
+        await Promise.all(snapshot);
+    }
     stream() {
         const self = this;
         return {
-            async *[Symbol.asyncIterator]() {
-                let index = 0;
-                while (index < self.#history.length) {
-                    yield self.#history[index++];
-                }
-                while (!self.#closed) {
-                    const next = await new Promise((resolve) => self.#waiters.push(resolve));
-                    if (next.done) {
-                        return;
+            [Symbol.asyncIterator]() {
+                const subscriber = { wake: undefined, done: false };
+                self.#streamSubscribers.add(subscriber);
+                let cursor = 0;
+                return {
+                    async next() {
+                        while (true) {
+                            if (subscriber.done) {
+                                self.#streamSubscribers.delete(subscriber);
+                                return { value: undefined, done: true };
+                            }
+                            if (cursor < self.#history.length) {
+                                const value = self.#history[cursor++];
+                                return { value, done: false };
+                            }
+                            if (self.#closed) {
+                                self.#streamSubscribers.delete(subscriber);
+                                return { value: undefined, done: true };
+                            }
+                            await new Promise((resolve) => {
+                                subscriber.wake = resolve;
+                            });
+                        }
+                    },
+                    async return() {
+                        subscriber.done = true;
+                        const wake = subscriber.wake;
+                        if (wake) {
+                            subscriber.wake = undefined;
+                            wake();
+                        }
+                        self.#streamSubscribers.delete(subscriber);
+                        return { value: undefined, done: true };
                     }
-                    index++;
-                    yield next.value;
-                }
+                };
             }
         };
     }

package/dist/utils/events.js.map

@@ -1 +1 @@
-{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/utils/events.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,aAAa;IACf,QAAQ,GAAQ,EAAE,CAAC;IACnB,QAAQ,GAA8C,EAAE,CAAC;IAClE,OAAO,GAAG,KAAK,CAAC;IAEhB,IAAI,CAAC,KAAQ;QACX,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,OAAO;QACT,CAAC;QACD,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC1B,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;QACrC,IAAI,MAAM,EAAE,CAAC;YACX,MAAM,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QACxC,CAAC;IACH,CAAC;IAED,KAAK;QACH,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;YAC7C,MAAM,CAAC,EAAE,KAAK,EAAE,SAAc,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAChD,CAAC;IACH,CAAC;IAED,MAAM;QACJ,MAAM,IAAI,GAAG,IAAI,CAAC;QAClB,OAAO;YACL,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC;gBAC3B,IAAI,KAAK,GAAG,CAAC,CAAC;gBACd,OAAO,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;oBACpC,MAAM,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAM,CAAC;gBACpC,CAAC;gBACD,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;oBACrB,MAAM,IAAI,GAAG,MAAM,IAAI,OAAO,CAAoB,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;oBAC5F,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;wBACd,OAAO;oBACT,CAAC;oBACD,KAAK,EAAE,CAAC;oBACR,MAAM,IAAI,CAAC,KAAK,CAAC;gBACnB,CAAC;YACH,CAAC;SACF,CAAC;IACJ,CAAC;CACF"}
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/utils/events.ts"],"names":[],"mappings":"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"}

package/docs/credentials.md

@@ -17,7 +17,89 @@ Unsupported in MVP:
 
 - arbitrary headers;
 - OAuth refresh;
-- persisted antpath vault;
-- antpath MCP proxy.
+- 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/skills.md

@@ -14,3 +14,5 @@ MVP skill inputs:
 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "antpath",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "TypeScript SDK for running autonomous Claude Managed Agents sessions.",
   "repository": {
     "type": "git",
@@ -15,6 +15,9 @@
       "import": "./dist/index.js"
     }
   },
+  "bin": {
+    "antpath": "./dist/cli.mjs"
+  },
   "files": [
     "dist",
     "README.md",
@@ -30,7 +33,7 @@
     "node": ">=20"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "pnpm --filter @antpath/cli run build && tsc -p tsconfig.build.json && node ./scripts/bundle-cli.mjs",
     "lint": "tsc --noEmit",
     "test": "vitest run test/unit",
     "test:unit": "vitest run test/unit",