antpath 0.1.1 → 0.2.1

package/README.md

@@ -6,12 +6,30 @@ title: antpath
 
 antpath is a TypeScript-first SDK for running autonomous Claude Managed Agents sessions from code-defined, secret-free Templates.
 
-## MVP boundaries
+Everything ships from a single import path:
+
+```ts
+import {
+  AntpathClient,           // direct in-process Claude runs (caller-held key)
+  AntpathPlatformClient,   // submit durable runs to an antpath dashboard
+  defineTemplate,
+  string,
+  validateProxyAuth        // helper for per-run proxy endpoint auth
+} from "antpath";
+```
+
+There is no `antpath/platform`, `antpath/proxy`, or other sub-path. The two
+clients are distinct classes for distinct use cases but live behind the same
+single agent-visible surface — see [Agent-first surface design](../../references/development-principles.md#agent-first-surface-design).
+
+- **Direct (`AntpathClient`)** — runs Claude in your own process with a caller-held key. This README covers the direct surface.
+- **Platform (`AntpathPlatformClient`)** — submits durable runs to an antpath dashboard. Every submission carries an inline `secrets` bundle (Anthropic key, optional MCP credentials, optional skill references, and optional per-run proxy endpoint auth); the dashboard vaults the bundle for the lifetime of one run and deletes it at cleanup. Per-run named secrets accessed through the managed HTTP proxy are declared via the `proxyEndpoints` submission field and authenticated via `secrets.proxyEndpointAuth` — see [Credentials](docs/credentials.md). The same npm package also ships the `antpath` CLI as its `bin` entry; the worker mounts that CLI at `/antpath/antpath` in every run for skills to invoke (`node /antpath/antpath proxy …`).
+
+## MVP boundaries (direct SDK)
 
-- SDK-only.
 - Claude Managed Agents only.
-- Caller-held provider key.
-- No stored provider keys, MCP credentials, or output file contents.
+- Caller-held provider key — the direct SDK never persists keys.
+- No SDK-side storage of provider keys, MCP credentials, or output file contents.
 - Manual cleanup by default.
 
 ## Quickstart
@@ -43,6 +61,23 @@ await handle.downloadOutputs("./outputs");
 await handle.cleanup();
 ```
 
+Observe events live by passing `onEvent` in `RunOptions`:
+
+```ts
+const handle = await client.run(template, {
+  onEvent: (event) => {
+    if (event.type === "provider.event") {
+      // event.event is a ProviderEvent (raw type stays `unknown`).
+    }
+  }
+});
+await handle.wait();
+```
+
+By the time `wait()` returns, every `onEvent` invocation triggered before
+terminal status has settled. See [Events](docs/events.md) for the full
+contract and a list of typed helpers.
+
 ## Test commands
 
 ```text
@@ -61,6 +96,7 @@ Unit tests are deterministic and may use fakes or sanitized recorded snapshots.
 - [MCP](docs/mcp.md)
 - [Skills](docs/skills.md)
 - [Outputs](docs/outputs.md)
+- [Events](docs/events.md)
 - [Cleanup](docs/cleanup.md)
 - [Testing](docs/testing.md)
 - [Release](docs/release.md)

package/dist/cli.mjs

@@ -0,0 +1,367 @@
+#!/usr/bin/env node
+// dist/cli.js
+import { readFile } from "node:fs/promises";
+
+// ../shared/dist/config.js
+var DEFAULT_CAPS = {
+  maxRunDurationMs: 5 * 60 * 1e3,
+  maxActiveRunsPerWorkspace: 1,
+  maxActiveRunsPerUserOrToken: 1,
+  pollingBaseIntervalMs: 5e3,
+  pollingMaxIntervalMs: 6e4,
+  pollingJitterRatio: 0.2,
+  providerCreateTokensPerMinute: 20,
+  providerDeleteTokensPerMinute: 30,
+  providerPollTokensPerMinute: 60,
+  providerRetryBackoffMs: 5e3,
+  leaseDurationMs: 6e4,
+  leaseRenewalThresholdMs: 2e4,
+  maxProviderAttempts: 1,
+  cleanupRetryCount: 3,
+  cleanupRetryBackoffMs: 1e4,
+  outputDownloadSafetyCapBytes: 1024 * 1024 * 1024,
+  workspaceStorageCapBytes: 5 * 1024 * 1024 * 1024,
+  signedUrlTtlSeconds: 300
+};
+
+// ../shared/dist/proxy-protocol.js
+var PROXY_PROTOCOL_VERSION = "1";
+var PROXY_PROTOCOL_HEADER = "x-antpath-proxy-protocol";
+var PROXY_METHOD_HEADER = "x-antpath-method";
+var PROXY_PATH_HEADER = "x-antpath-path";
+var PROXY_QUERY_HEADER = "x-antpath-query";
+var PROXY_HEADERS_HEADER = "x-antpath-headers";
+var PROXY_RESPONSE_MODE_HEADER = "x-antpath-response-mode";
+var PROXY_RESPONSE_MODES = ["status_only", "headers_only", "full"];
+
+// ../shared/dist/status.js
+var TERMINAL_RUN_STATUSES = [
+  "succeeded",
+  "failed",
+  "timed_out",
+  "cancelled",
+  "cleanup_failed",
+  "pending_delete",
+  "deleted"
+];
+var terminalRunStatuses = new Set(TERMINAL_RUN_STATUSES);
+
+// ../shared/dist/submission.js
+var PROXY_ENDPOINT_DEFAULTS = {
+  allowHeaders: [],
+  responseMode: "headers_only",
+  maxRequestBytes: 64 * 1024,
+  maxResponseBytes: 1024 * 1024,
+  timeoutMs: 1e4,
+  perCallBudget: 60,
+  responseByteBudget: 1024 * 1024
+};
+
+// dist/internal.js
+var ANTPATH_INDEX_PATH = "/antpath/index.json";
+var ANTPATH_RUN_TOKEN_PATH = "/antpath/run-token";
+
+// dist/run.js
+var SUCCESS = { code: 0 };
+var USAGE_ERR = { code: 2 };
+var RUNTIME_ERR = { code: 1 };
+async function runCli(io2) {
+  const args = io2.argv.slice(2);
+  try {
+    const exit = await dispatch(io2, args);
+    io2.exit(exit.code);
+  } catch (err) {
+    const body = { error: "internal_error", message: err.message ?? "unknown error" };
+    io2.stderr(JSON.stringify(body) + "\n");
+    io2.exit(RUNTIME_ERR.code);
+  }
+}
+async function dispatch(io2, args) {
+  if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+    return await printGlobalHelp(io2);
+  }
+  const sub = args[0];
+  const rest = args.slice(1);
+  switch (sub) {
+    case "proxy":
+      return await runProxy(io2, rest);
+    default:
+      io2.stderr(`unknown subcommand: ${sub}
+`);
+      io2.stderr("run `antpath --help` for usage\n");
+      return USAGE_ERR;
+  }
+}
+async function printGlobalHelp(io2) {
+  const manifest = await tryReadManifest(io2);
+  io2.stdout("antpath \u2014 managed proxy CLI for skill scripts\n\n");
+  io2.stdout("Usage:\n");
+  io2.stdout("  antpath proxy <endpoint-name> [flags]\n");
+  io2.stdout("  antpath --help\n\n");
+  if (manifest) {
+    if (manifest.endpoints.length === 0) {
+      io2.stdout("This run declared no proxy endpoints.\n");
+    } else {
+      io2.stdout("Declared proxy endpoints for this run:\n");
+      for (const ep of manifest.endpoints) {
+        io2.stdout(`  \u2022 ${ep.name}  (${ep.allowMethods.join("/")} ${ep.allowPathPrefixes.join(",")}, mode=${ep.responseMode})
+`);
+      }
+    }
+    io2.stdout(`
+Protocol version: ${manifest.protocolVersion}
+`);
+  } else {
+    io2.stdout("(no manifest mounted \u2014 run `antpath proxy --help` for details)\n");
+  }
+  return SUCCESS;
+}
+async function printProxyHelp(io2) {
+  io2.stdout("antpath proxy \u2014 call an upstream HTTP endpoint via the managed proxy.\n\n");
+  io2.stdout("Usage:\n");
+  io2.stdout("  antpath proxy <endpoint-name> [flags]\n\n");
+  io2.stdout("Flags:\n");
+  io2.stdout("  --method <verb>          HTTP method (default: GET)\n");
+  io2.stdout("  --path <path>            Caller-supplied path; must match policy prefixes\n");
+  io2.stdout(`  --query <json>           JSON object of query parameters (e.g. '{"q":"x"}')
+`);
+  io2.stdout("  --header K=V             Add a caller header (repeatable)\n");
+  io2.stdout("  --data <value>           Request body. Use '-' for stdin, '@<file>' for file content\n");
+  io2.stdout("  --response-mode <mode>   status_only | headers_only | full (may only narrow policy)\n");
+  io2.stdout("  --help                   Show this message\n\n");
+  const manifest = await tryReadManifest(io2);
+  if (manifest && manifest.endpoints.length > 0) {
+    io2.stdout("Declared endpoints:\n");
+    for (const ep of manifest.endpoints) {
+      io2.stdout(`  \u2022 ${ep.name}: ${ep.allowMethods.join(",")} ${ep.allowPathPrefixes.join(",")} (mode=${ep.responseMode}, budget=${ep.perCallBudget}/run)
+`);
+    }
+  }
+  return SUCCESS;
+}
+function parseProxyFlags(rest) {
+  let endpointName = null;
+  let method = "GET";
+  let path = "/";
+  let query = null;
+  const headers = /* @__PURE__ */ new Map();
+  let dataSpec = null;
+  let responseMode = null;
+  let showHelp = false;
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    if (arg === "--help" || arg === "-h") {
+      showHelp = true;
+      continue;
+    }
+    if (arg === "--method") {
+      method = expect(rest, ++i, "--method");
+      continue;
+    }
+    if (arg === "--path") {
+      path = expect(rest, ++i, "--path");
+      continue;
+    }
+    if (arg === "--query") {
+      query = expect(rest, ++i, "--query");
+      continue;
+    }
+    if (arg === "--header") {
+      const kv = expect(rest, ++i, "--header");
+      const eq = kv.indexOf("=");
+      if (eq <= 0)
+        return { ok: false, reason: "--header must be in the form KEY=VALUE" };
+      headers.set(kv.slice(0, eq).toLowerCase(), kv.slice(eq + 1));
+      continue;
+    }
+    if (arg === "--data") {
+      dataSpec = expect(rest, ++i, "--data");
+      continue;
+    }
+    if (arg === "--response-mode") {
+      responseMode = expect(rest, ++i, "--response-mode");
+      continue;
+    }
+    if (arg.startsWith("--")) {
+      return { ok: false, reason: `unknown flag: ${arg}` };
+    }
+    if (endpointName === null) {
+      endpointName = arg;
+      continue;
+    }
+    return { ok: false, reason: `unexpected positional argument: ${arg}` };
+  }
+  return { ok: true, flags: { endpointName, method, path, query, headers, dataSpec, responseMode, showHelp } };
+}
+function expect(arr, idx, flag) {
+  const v = arr[idx];
+  if (v === void 0) {
+    throw new CliUsageError(`${flag} requires a value`);
+  }
+  return v;
+}
+var CliUsageError = class extends Error {
+};
+async function runProxy(io2, rest) {
+  let parsed;
+  try {
+    parsed = parseProxyFlags(rest);
+  } catch (err) {
+    if (err instanceof CliUsageError) {
+      io2.stderr(`${err.message}
+`);
+      return USAGE_ERR;
+    }
+    throw err;
+  }
+  if (!parsed.ok) {
+    io2.stderr(`${parsed.reason}
+`);
+    return USAGE_ERR;
+  }
+  const f = parsed.flags;
+  if (f.showHelp) {
+    return await printProxyHelp(io2);
+  }
+  if (!f.endpointName) {
+    io2.stderr("missing endpoint-name\n");
+    io2.stderr("usage: antpath proxy <endpoint-name> [flags]\n");
+    return USAGE_ERR;
+  }
+  if (f.responseMode && !PROXY_RESPONSE_MODES.includes(f.responseMode)) {
+    io2.stderr(`--response-mode must be one of: ${PROXY_RESPONSE_MODES.join(", ")}
+`);
+    return USAGE_ERR;
+  }
+  const manifest = await tryReadManifest(io2);
+  if (!manifest) {
+    emitError(io2, {
+      error: "internal_error",
+      message: "manifest not mounted; this CLI must run inside an antpath-managed run"
+    });
+    return RUNTIME_ERR;
+  }
+  if (!manifest.proxyBaseUrl) {
+    emitError(io2, {
+      error: "endpoint_not_found",
+      message: "this run has no proxy endpoints declared",
+      endpointName: f.endpointName
+    });
+    return RUNTIME_ERR;
+  }
+  let token;
+  try {
+    token = (await io2.readFile(ANTPATH_RUN_TOKEN_PATH)).trim();
+  } catch {
+    emitError(io2, {
+      error: "unauthorized",
+      message: "run token file missing; this run has no proxy bearer"
+    });
+    return RUNTIME_ERR;
+  }
+  if (!token) {
+    emitError(io2, { error: "unauthorized", message: "run token is empty" });
+    return RUNTIME_ERR;
+  }
+  let body;
+  if (f.dataSpec !== null) {
+    try {
+      body = await resolveBody(io2, f.dataSpec);
+    } catch (err) {
+      io2.stderr(`failed to read request body: ${err.message}
+`);
+      return RUNTIME_ERR;
+    }
+  }
+  const url = `${manifest.proxyBaseUrl.replace(/\/+$/, "")}/${encodeURIComponent(f.endpointName)}`;
+  const requestHeaders = new Headers();
+  requestHeaders.set("authorization", `Bearer ${token}`);
+  requestHeaders.set(PROXY_PROTOCOL_HEADER, PROXY_PROTOCOL_VERSION);
+  requestHeaders.set(PROXY_METHOD_HEADER, f.method.toUpperCase());
+  requestHeaders.set(PROXY_PATH_HEADER, f.path);
+  if (f.query) {
+    requestHeaders.set(PROXY_QUERY_HEADER, f.query);
+  }
+  if (f.headers.size > 0) {
+    requestHeaders.set(PROXY_HEADERS_HEADER, JSON.stringify(Object.fromEntries(f.headers)));
+  }
+  if (f.responseMode) {
+    requestHeaders.set(PROXY_RESPONSE_MODE_HEADER, f.responseMode);
+  }
+  if (body !== void 0) {
+    requestHeaders.set("content-length", String(body.byteLength));
+  }
+  const init = {
+    method: "POST",
+    headers: requestHeaders,
+    redirect: "manual"
+  };
+  if (body !== void 0) {
+    init.body = body;
+  }
+  let response;
+  try {
+    response = await io2.fetchImpl(url, init);
+  } catch (err) {
+    emitError(io2, {
+      error: "upstream_error",
+      message: `proxy request failed: ${err.message}`,
+      endpointName: f.endpointName
+    });
+    return RUNTIME_ERR;
+  }
+  const text = await response.text();
+  let parsedBody;
+  try {
+    parsedBody = text ? JSON.parse(text) : {};
+  } catch {
+    emitError(io2, {
+      error: "internal_error",
+      message: "proxy returned non-JSON response",
+      endpointName: f.endpointName
+    });
+    return RUNTIME_ERR;
+  }
+  if (!response.ok) {
+    io2.stderr(JSON.stringify(parsedBody) + "\n");
+    return RUNTIME_ERR;
+  }
+  io2.stdout(JSON.stringify(parsedBody) + "\n");
+  return SUCCESS;
+}
+async function resolveBody(io2, spec) {
+  if (spec === "-") {
+    const data = await io2.readFile("/dev/stdin");
+    return new Uint8Array(Buffer.from(data, "utf8"));
+  }
+  if (spec.startsWith("@")) {
+    const path = spec.slice(1);
+    if (!path)
+      throw new Error("--data @<file> requires a path");
+    const data = await io2.readFile(path);
+    return new Uint8Array(Buffer.from(data, "utf8"));
+  }
+  return new Uint8Array(Buffer.from(spec, "utf8"));
+}
+function emitError(io2, body) {
+  io2.stderr(JSON.stringify(body) + "\n");
+}
+async function tryReadManifest(io2) {
+  try {
+    const raw = await io2.readFile(ANTPATH_INDEX_PATH);
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+// dist/cli.js
+var io = {
+  readFile: (path) => readFile(path, "utf8"),
+  fetchImpl: fetch,
+  stdout: (chunk) => process.stdout.write(chunk),
+  stderr: (chunk) => process.stderr.write(chunk),
+  exit: (code) => process.exit(code),
+  argv: process.argv
+};
+await runCli(io);

package/dist/cli.mjs.sha256

@@ -0,0 +1 @@
+e4adb3ee5b4053a78a8ddaf9cd653fbaf6a0ddf98432411308964c8fd40909f8  cli.mjs

package/dist/client.js

@@ -27,7 +27,10 @@ export class AntpathClient {
             cleanupPolicy: options.cleanupPolicy ?? this.#cleanupPolicy,
             timeoutMs: options.timeoutMs,
             signal: options.signal,
-            logger: options.logger
+            logger: options.logger,
+            onEvent: options.onEvent,
+            onEventAbortOnError: options.onEventAbortOnError ?? false,
+            sessionResources: options.sessionResources ?? []
         });
         await controller.start();
         return controller;

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,8BAA8B,EAAE,MAAM,mCAAmC,CAAC;AAEnF,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAWzD,MAAM,OAAO,aAAa;IACf,SAAS,CAAuB;IAChC,cAAc,CAAgB;IAEvC,YAAY,OAA6B;QACvC,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;YACrB,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,QAAQ,CAAC;QACpC,CAAC;aAAM,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;YACnC,IAAI,CAAC,SAAS,GAAG,IAAI,8BAA8B,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;QAC3F,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;QACxE,CAAC;QACD,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC,aAAa,IAAI,QAAQ,CAAC;IAC1D,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,QAA4B,EAAE,UAAsB,EAAE;QAC9D,MAAM,QAAQ,GAAG,eAAe,CAAC,QAAQ,EAAE,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC;QACpE,mBAAmB,CAAC,QAAQ,EAAE,OAAO,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC;QACzD,MAAM,UAAU,GAAG,IAAI,aAAa,CAAC;YACnC,QAAQ,EAAE,IAAI,CAAC,SAAS;YACxB,QAAQ,EAAE,QAAQ;YAClB,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,EAAE;YACtC,aAAa,EAAE,OAAO,CAAC,aAAa,IAAI,IAAI,CAAC,cAAc;YAC3D,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CAAC,CAAC;QACH,MAAM,UAAU,CAAC,KAAK,EAAE,CAAC;QACzB,OAAO,UAAU,CAAC;IACpB,CAAC;CACF"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,8BAA8B,EAAE,MAAM,mCAAmC,CAAC;AAEnF,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAWzD,MAAM,OAAO,aAAa;IACf,SAAS,CAAuB;IAChC,cAAc,CAAgB;IAEvC,YAAY,OAA6B;QACvC,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;YACrB,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,QAAQ,CAAC;QACpC,CAAC;aAAM,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;YACnC,IAAI,CAAC,SAAS,GAAG,IAAI,8BAA8B,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;QAC3F,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;QACxE,CAAC;QACD,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC,aAAa,IAAI,QAAQ,CAAC;IAC1D,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,QAA4B,EAAE,UAAsB,EAAE;QAC9D,MAAM,QAAQ,GAAG,eAAe,CAAC,QAAQ,EAAE,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC;QACpE,mBAAmB,CAAC,QAAQ,EAAE,OAAO,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC;QACzD,MAAM,UAAU,GAAG,IAAI,aAAa,CAAC;YACnC,QAAQ,EAAE,IAAI,CAAC,SAAS;YACxB,QAAQ,EAAE,QAAQ;YAClB,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,EAAE;YACtC,aAAa,EAAE,OAAO,CAAC,aAAa,IAAI,IAAI,CAAC,cAAc;YAC3D,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,mBAAmB,EAAE,OAAO,CAAC,mBAAmB,IAAI,KAAK;YACzD,gBAAgB,EAAE,OAAO,CAAC,gBAAgB,IAAI,EAAE;SACjD,CAAC,CAAC;QACH,MAAM,UAAU,CAAC,KAAK,EAAE,CAAC;QACzB,OAAO,UAAU,CAAC;IACpB,CAAC;CACF"}

package/dist/index.d.ts

@@ -1,9 +1,10 @@
 export { AntpathClient } from "./client.js";
-export { AntpathPlatformClient, PlatformApiError } from "./platform/index.js";
+export { AntpathPlatformClient, PlatformApiError, validateProxyAuth, buildPlatformAllowedHosts, resetDefaultSecretsDeprecationWarning } from "./platform/index.js";
+export type { PlatformEvent, PlatformOutput, PlatformRun, SignedOutputLink, PlatformInlineSecrets, PlatformRunSubmissionRequest, PlatformProxyEndpoint, PlatformProxyEndpointAuth, PlatformProxyAuthShape, PlatformProxyMethod, PlatformProxyResponseMode, AntpathPlatformClientOptions } from "./platform/index.js";
 export { AnthropicManagedAgentsProvider } from "./providers/anthropic/provider.js";
 export type { ManagedAgentProvider, ProviderSkillRef, SessionResourceInput, UploadFileInput } from "./providers/types.js";
-export type { PlatformEvent, PlatformOutput, PlatformRun, SignedOutputLink } from "./platform/index.js";
-export { compileTemplate, defineTemplate, requiredOAuthAccessToken, requiredStaticBearer, string, type TemplateDefinition, type TemplateVariableDefinition } from "./template/index.js";
-export type { CleanupPolicy, CleanupResult, CredentialInput, DownloadOutputsOptions, DownloadOutputsResult, Logger, OutputManifest, ProviderEvent, ProviderFile, ProviderResourceIds, RunEvent, RunHandle, RunOptions, RunResult, RunStatus, UsageSummary } from "./types.js";
+export { isAgentEvent, isAgentCustomToolUse, isAgentMcpToolResult, isAgentMcpToolUse, isAgentMessage, isAgentThinking, isAgentToolResult, isAgentToolUse, isSessionError, isSessionEvent, isSessionStatusIdle, isSessionStatusRescheduled, isSessionStatusRunning, isSessionStatusTerminated, isSpanEvent, isUserEvent, isUserMessage } from "./providers/known-events.js";
+export { compileTemplate, defineTemplate, requiredOAuthAccessToken, requiredStaticBearer, string, type EnvironmentDefinition, type ResolvedTemplate, type TemplateDefinition, type TemplateVariableDefinition } from "./template/index.js";
+export type { CleanupPolicy, CleanupResult, CredentialInput, DownloadOutputsOptions, DownloadOutputsResult, Logger, OutputManifest, ProviderEvent, ProviderFile, ProviderResourceIds, RunEvent, RunEventHandler, RunHandle, RunOptions, RunResult, RunStatus, SessionResourceUpload, UsageSummary } from "./types.js";
 export { SecretString, redactSecrets } from "./utils/secrets.js";
 export { AntpathError, CleanupError, CredentialValidationError, ProviderError, RunStateError, TemplateValidationError } from "./errors.js";

package/dist/index.js

@@ -1,6 +1,7 @@
 export { AntpathClient } from "./client.js";
-export { AntpathPlatformClient, PlatformApiError } from "./platform/index.js";
+export { AntpathPlatformClient, PlatformApiError, validateProxyAuth, buildPlatformAllowedHosts, resetDefaultSecretsDeprecationWarning } from "./platform/index.js";
 export { AnthropicManagedAgentsProvider } from "./providers/anthropic/provider.js";
+export { isAgentEvent, isAgentCustomToolUse, isAgentMcpToolResult, isAgentMcpToolUse, isAgentMessage, isAgentThinking, isAgentToolResult, isAgentToolUse, isSessionError, isSessionEvent, isSessionStatusIdle, isSessionStatusRescheduled, isSessionStatusRunning, isSessionStatusTerminated, isSpanEvent, isUserEvent, isUserMessage } from "./providers/known-events.js";
 export { compileTemplate, defineTemplate, requiredOAuthAccessToken, requiredStaticBearer, string } from "./template/index.js";
 export { SecretString, redactSecrets } from "./utils/secrets.js";
 export { AntpathError, CleanupError, CredentialValidationError, ProviderError, RunStateError, TemplateValidationError } from "./errors.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC9E,OAAO,EAAE,8BAA8B,EAAE,MAAM,mCAAmC,CAAC;AAGnF,OAAO,EACL,eAAe,EACf,cAAc,EACd,wBAAwB,EACxB,oBAAoB,EACpB,MAAM,EAGP,MAAM,qBAAqB,CAAC;AAmB7B,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACjE,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,yBAAyB,EACzB,aAAa,EACb,aAAa,EACb,uBAAuB,EACxB,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EACL,qBAAqB,EACrB,gBAAgB,EAChB,iBAAiB,EACjB,yBAAyB,EACzB,qCAAqC,EACtC,MAAM,qBAAqB,CAAC;AAe7B,OAAO,EAAE,8BAA8B,EAAE,MAAM,mCAAmC,CAAC;AAEnF,OAAO,EACL,YAAY,EACZ,oBAAoB,EACpB,oBAAoB,EACpB,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,cAAc,EACd,mBAAmB,EACnB,0BAA0B,EAC1B,sBAAsB,EACtB,yBAAyB,EACzB,WAAW,EACX,WAAW,EACX,aAAa,EACd,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,eAAe,EACf,cAAc,EACd,wBAAwB,EACxB,oBAAoB,EACpB,MAAM,EAKP,MAAM,qBAAqB,CAAC;AAqB7B,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACjE,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,yBAAyB,EACzB,aAAa,EACb,aAAa,EACb,uBAAuB,EACxB,MAAM,aAAa,CAAC"}

package/dist/platform/client.d.ts

@@ -11,28 +11,124 @@ export interface PlatformTemplateSubmission {
     readonly messages: readonly string[];
     readonly metadata?: Record<string, PlatformJsonValue>;
 }
-export interface PlatformOutputPolicy {
-    readonly capture: boolean;
-    readonly globs?: readonly string[];
-}
 export type PlatformClaudeSessionCleanup = "retain" | "delete";
 export interface PlatformCleanupPolicy {
+    readonly session?: PlatformClaudeSessionCleanup;
     readonly claudeSession?: PlatformClaudeSessionCleanup;
 }
+export interface PlatformAnthropicSecrets {
+    readonly apiKey: string;
+    readonly baseUrl?: string;
+}
+export interface PlatformMcpServerSecret {
+    readonly name: string;
+    readonly url: string;
+    readonly headers?: Record<string, string>;
+}
+export interface PlatformSkillReference {
+    readonly skillId: string;
+    readonly version?: string;
+}
+export interface PlatformInlineSecrets {
+    readonly anthropic: PlatformAnthropicSecrets;
+    readonly mcpServers?: readonly PlatformMcpServerSecret[];
+    readonly skills?: readonly PlatformSkillReference[];
+    /**
+     * Auth values for proxy endpoints declared at the top level of the
+     * submission. Each entry's `name` must match a declared
+     * `proxyEndpoints[i].name` and its `value.type` must match the
+     * declared `authShape.type`. Validate eagerly with
+     * {@link validateProxyAuth}.
+     */
+    readonly proxyEndpointAuth?: readonly PlatformProxyEndpointAuth[];
+}
+/**
+ * Structural description of how the upstream endpoint expects auth.
+ * The actual value lives in {@link PlatformProxyEndpointAuth.value} and
+ * is supplied separately so it never enters the idempotency hash.
+ */
+export type PlatformProxyAuthShape = {
+    readonly type: "bearer";
+} | {
+    readonly type: "basic";
+} | {
+    readonly type: "header";
+    readonly name: string;
+} | {
+    readonly type: "query";
+    readonly name: string;
+};
+export type PlatformProxyMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+export type PlatformProxyResponseMode = "full" | "status_only" | "headers_only";
+export interface PlatformProxyEndpoint {
+    readonly name: string;
+    readonly baseUrl: string;
+    readonly authShape: PlatformProxyAuthShape;
+    readonly allowMethods: readonly PlatformProxyMethod[];
+    readonly allowPathPrefixes: readonly string[];
+    readonly allowHeaders?: readonly string[];
+    readonly responseMode?: PlatformProxyResponseMode;
+    readonly maxRequestBytes?: number;
+    readonly maxResponseBytes?: number;
+    readonly timeoutMs?: number;
+    readonly perCallBudget?: number;
+    readonly responseByteBudget?: number;
+}
+export interface PlatformProxyEndpointAuth {
+    readonly name: string;
+    readonly value: {
+        readonly type: "bearer";
+        readonly token: string;
+    } | {
+        readonly type: "basic";
+        readonly username: string;
+        readonly password: string;
+    } | {
+        readonly type: "header";
+        readonly value: string;
+    } | {
+        readonly type: "query";
+        readonly value: string;
+    };
+}
+/**
+ * Submission shape accepted by `AntpathPlatformClient.submitRun`. The `secrets`
+ * block may be omitted at the call site if a client-level default was provided
+ * to the constructor; the merged value is always sent on the wire.
+ */
 export interface PlatformRunSubmissionRequest {
     readonly workspaceId: string;
-    readonly providerConnectionId: string;
     readonly idempotencyKey: string;
     readonly template: PlatformTemplateSubmission;
     readonly variables?: Record<string, PlatformJsonValue>;
-    readonly credentialReferences?: Record<string, string>;
-    readonly output?: PlatformOutputPolicy;
     readonly cleanup?: PlatformCleanupPolicy;
+    readonly secrets?: PlatformInlineSecrets;
+    /**
+     * HTTP endpoints reachable via the antpath managed proxy during this
+     * run. Each entry declares the policy (URL, allow lists, caps); the
+     * corresponding auth value goes in
+     * `secrets.proxyEndpointAuth[i]` with a matching `name`.
+     *
+     * Empty / omitted → no proxy surface is provisioned (the in-container
+     * `/antpath/index.json` reports `endpoints: []`).
+     */
+    readonly proxyEndpoints?: readonly PlatformProxyEndpoint[];
 }
 export interface AntpathPlatformClientOptions {
     readonly baseUrl: string;
     readonly apiToken: string;
     readonly fetch?: FetchLike;
+    /**
+     * Optional default secrets applied to every submission that does not
+     * override the `secrets` block per-call.
+     *
+     * @deprecated The agent-first invariant requires every secret-bearing
+     * field to be visible at the call site. Pass `secrets` explicitly on
+     * each `submitRun` call instead; this option will be removed in a
+     * future release. See
+     * `references/development-principles.md` (Agent-first surface design).
+     */
+    readonly defaultSecrets?: PlatformInlineSecrets;
 }
 export interface PlatformRun {
     readonly id: string;
@@ -60,6 +156,7 @@ export declare class AntpathPlatformClient {
     private readonly baseUrl;
     private readonly apiToken;
     private readonly fetchImpl;
+    private readonly defaultSecrets?;
     constructor(options: AntpathPlatformClientOptions);
     submitRun(request: PlatformRunSubmissionRequest): Promise<PlatformRun>;
     getRun(workspaceId: string, runId: string): Promise<PlatformRun>;
@@ -70,4 +167,38 @@ export declare class AntpathPlatformClient {
     deleteRun(workspaceId: string, runId: string): Promise<void>;
     private request;
 }
+/**
+ * Test-only: reset the "warn once" guard for the `defaultSecrets`
+ * deprecation message. Production code should not call this.
+ *
+ * @internal
+ */
+export declare function resetDefaultSecretsDeprecationWarning(): void;
+/**
+ * Cross-validate a `proxyEndpoints` policy list against a
+ * `secrets.proxyEndpointAuth` value list. Throws on the first
+ * mismatch with an actionable, field-named error message.
+ *
+ * Mirrors the BFF's authoritative validator so misconfigured
+ * submissions fail fast in the SDK before going over the wire. Use it
+ * directly in tests or wrappers — `submitRun` already invokes it when
+ * `proxyEndpoints` is non-empty.
+ */
+export declare function validateProxyAuth(endpoints: readonly PlatformProxyEndpoint[], auth: readonly PlatformProxyEndpointAuth[] | undefined): void;
+/**
+ * Build an `allowedHosts` list for `environment.network` that includes
+ * the antpath proxy host (and optionally Anthropic's MCP host) when
+ * the caller is hand-rolling networking. The worker auto-injects the
+ * proxy host server-side when proxy endpoints are declared; use this
+ * helper when you also want client-side template validation parity
+ * (e.g. to assert at build time that a `limited` config can reach the
+ * surfaces you intended).
+ *
+ * The proxy host is derived from the dashboard URL. Pass the same
+ * value you used for the `AntpathPlatformClient` `baseUrl`.
+ */
+export declare function buildPlatformAllowedHosts(input: {
+    readonly dashboardBaseUrl: string;
+    readonly extraHosts?: readonly string[];
+}): readonly string[];
 export {};