antpath 0.10.13 → 0.10.15

package/docs/events.md

@@ -25,16 +25,17 @@ for await (const event of ref.stream({ intervalMs: 1000 })) {
 
 > **Transport.** `stream()` polls under the hood — it issues `GET
 > /api/runs/:id/events?since=…` calls at `intervalMs` until the run
-> reaches a terminal status. There is no SSE / WebSocket push from the
-> BFF today. For latency-sensitive UIs this is acceptable down to about
-> 500 ms; below that, every dashboard request is one round-trip. A push
-> transport is on the public backlog — not committed to a release.
+> reaches a terminal status. The dashboard BFF also exposes an SSE
+> endpoint (`GET /api/runs/:id/events/stream`) that the dashboard UI
+> consumes; an SSE-backed SDK transport is on the public backlog. For
+> latency-sensitive consumers the polling baseline is acceptable down
+> to about 500 ms.
 
 The CLI mirrors the same surface:
 
 ```bash
-antpath events <run-id> --api-token … --workspace … --dashboard-url …            # snapshot
-antpath events <run-id> --follow --api-token … --workspace … --dashboard-url …   # stream until terminal
+antpath events <run-id> --api-token … [--dashboard-url …]            # snapshot
+antpath events <run-id> --follow --api-token … [--dashboard-url …]   # stream until terminal
 ```
 
 Both surfaces observe the same events. A subscriber attached after `submitRun()` returns replays the events it missed, then continues live.

package/docs/quickstart.md

@@ -5,27 +5,20 @@ title: antpath quickstart
 # Quickstart
 
 1. Get an antpath SDK API token (`ant_…`).
-2. Define a secret-free Template in TypeScript (or JSON / a `.mjs` default export).
-3. Create `AntpathClient` — the workspace is derived server-side from the token.
-4. Submit the run with an inline `secrets` bundle. Wait for terminal status. Fetch outputs.
+2. Create `AntpathClient` — the workspace is derived server-side from the token.
+3. Submit the run with the agent's brief plus an inline `secrets` bundle. Wait for terminal status. Fetch outputs.
 
 ```ts
-import { AntpathClient, defineTemplate, string } from "antpath";
+import { AntpathClient } from "antpath";
 
 const client = new AntpathClient({
   apiToken: process.env.ANTPATH_API_TOKEN!
   // baseUrl defaults to https://www.antpath.ai — set it for self-hosted deployments.
 });
 
-const template = defineTemplate({
-  name: "hello",
+const ref = await client.submitRun({
   model: "claude-haiku-4-5",
-  messages: ["Write a short answer about {{topic}}."],
-  variables: { topic: string() }
-});
-
-const ref = await client.submitRun(template, {
-  variables: { topic: "agent-first SDK design" },
+  prompt: "Write a short answer about agent-first SDK design.",
   secrets: { anthropic: { apiKey: process.env.ANTHROPIC_API_KEY! } }
 });
 
@@ -34,17 +27,34 @@ console.log(run.status);
 console.log(await ref.outputs());
 ```
 
+For reusable, credential-free configs, wrap a producer with `defineRun`:
+
+```ts
+import { defineRun } from "antpath";
+
+const summarise = defineRun((topic: string) => ({
+  model: "claude-haiku-4-5",
+  prompt: `Write a short answer about ${topic}.`
+}));
+
+const ref = await client.submitRun({
+  ...summarise("agent-first SDK design"),
+  secrets: { anthropic: { apiKey: process.env.ANTHROPIC_API_KEY! } }
+});
+```
+
 Or from the shell:
 
 ```bash
-antpath run ./template.json \
+antpath run \
   --api-token "$ANTPATH_API_TOKEN" \
   --anthropic-api-key "$ANTHROPIC_API_KEY" \
-  --var topic="agent-first SDK design" \
+  --model claude-haiku-4-5 \
+  --prompt "Write a short answer about agent-first SDK design." \
   --follow
 ```
 
-Both surfaces hit the same dashboard BFF and operate on the same durable run records — pick whichever is most convenient.
+For a config-file flow, pass `--config <path>` with a JSON file matching the `Blueprint` shape (`{ model, system?, prompt, skills?, mcpServers?, environment?, cleanup?, proxyEndpoints?, metadata? }`). Both surfaces hit the same dashboard BFF and operate on the same durable run records — pick whichever is most convenient.
 
 ## Safe retries with `idempotencyKey`
 
@@ -57,7 +67,7 @@ Every `submitRun` call carries an `idempotencyKey`. When omitted the SDK auto-ge
 | Same key + **different** request body hash | HTTP 409 — body `{ error: { message, code: "idempotency_conflict", details: { existingRunId } } }`. The SDK throws an `HttpError` carrying that body. Use `details.existingRunId` to adopt the pre-existing run, or pick a fresh key. |
 | Omitted `idempotencyKey` | A new UUID is generated on every call — repeat submissions create new runs. |
 
-The request hash is computed server-side over the canonical submission JSON (model, prompt, system, environment, skill refs, MCP server descriptors, proxy endpoints, `outputDirs`, etc.) so reordering JSON keys, adding whitespace, or rotating the inline secret bundle does **not** change the hash. Bumping a variable or changing the prompt does.
+The request hash is computed server-side over the canonical submission JSON (model, prompt, system, environment, skill refs, MCP server descriptors, proxy endpoints, `outputDirs`, etc.) so reordering JSON keys, adding whitespace, or rotating the inline secret bundle does **not** change the hash. Changing the prompt, model, system, or any other non-secret field does.
 
 Pattern for safe retries:
 

package/docs/templates.md

@@ -1,24 +1,53 @@
 ---
-title: Templates
+title: Blueprints (run configuration)
 ---
 
-# Templates
+# Blueprints
 
-Templates are code-defined, immutable, secret-free run configurations.
+A `Blueprint` is the credential-free shape that drives a run. The legacy `Template` wrapper and `{{var}}` DSL are gone — interpolate values at the call site, then pass the blueprint to `submitRun`.
 
-Allowed Template content:
+Allowed `Blueprint` fields:
 
-- 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.
+- `model` — required.
+- `prompt` — required (string or array of strings).
+- `system` — optional system message.
+- `skills` — array of `Skill` instances (workspace, provider, or inline).
+- `mcpServers` — array of `McpServer` instances (headers are split into `secrets.mcpServers` server-side).
+- `proxyEndpoints` — array of `ProxyEndpoint` instances.
+- `agentsMd` / `files` — array of `AgentsMd` / `File` instances.
+- `environment` — packages + networking + `outputDirs`.
+- `cleanup` — `{ session: "retain" | "delete" }`.
+- `metadata` — non-secret structured metadata.
 
-Variables use `{{name}}` and are resolved before provider calls. Use `\{{name}}` for a literal placeholder.
+Secrets never live in a `Blueprint`. Pass credentials through `submitRun({ ...blueprint, secrets, proxyEndpointAuth })` (SDK) or the equivalent host-mode flags (`--anthropic-api-key`, `--mcp-auth`, `--proxy-auth`).
 
-Secrets must not appear in Templates. Pass credentials through `submitRun(template, { secrets, proxyEndpointAuth })` (SDK) or the equivalent host-mode flags (`--anthropic-api-key`, `--mcp-secret`, `--proxy-auth`).
+## `defineRun` — typed, reusable factory
+
+`defineRun` is identity at runtime; its value is the type boundary. The producer must return a `Blueprint`, so callers cannot accidentally bake credentials into a reusable artifact.
+
+```ts
+import { defineRun } from "antpath";
+
+const summarise = defineRun((topic: string) => ({
+  model: "claude-haiku-4-5",
+  system: "You are a concise automation agent.",
+  prompt: `Write a short answer about ${topic}.`
+}));
+
+await client.submitRun({
+  ...summarise("agent-first SDK design"),
+  secrets: { anthropic: { apiKey } }
+});
+```
+
+## CLI
+
+The `antpath run` host subcommand accepts the same blueprint either as a JSON config file:
+
+```bash
+antpath run --config ./blueprint.json \
+  --api-token "$ANTPATH_API_TOKEN" \
+  --anthropic-api-key "$ANTHROPIC_API_KEY"
+```
+
+…or as explicit flags (`--model`, `--system`, `--prompt`, `--skill`, `--provider-skill`, `--mcp`, `--mcp-auth`, `--proxy-endpoint`, `--proxy-auth`, `--metadata`, `--cleanup`). The two modes are mutually exclusive.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "antpath",
-  "version": "0.10.13",
+  "version": "0.10.15",
   "description": "TypeScript SDK for running autonomous Claude Managed Agents sessions.",
   "repository": {
     "type": "git",