antpath 0.1.1 → 0.2.0

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/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 {};

package/dist/platform/client.js

@@ -12,10 +12,11 @@ export class AntpathPlatformClient {
     baseUrl;
     apiToken;
     fetchImpl;
+    defaultSecrets;
     constructor(options) {
         const record = options;
         if ("anthropicApiKey" in record || "providerApiKey" in record) {
-            throw new Error("Platform client does not accept provider keys");
+            throw new Error("Platform client does not accept provider keys at the client root — pass them inside `defaultSecrets.anthropic` or per-call `secrets.anthropic`");
         }
         if (!options.apiToken) {
             throw new Error("apiToken is required");
@@ -23,11 +24,26 @@ export class AntpathPlatformClient {
         this.baseUrl = new URL(options.baseUrl.endsWith("/") ? options.baseUrl : `${options.baseUrl}/`);
         this.apiToken = options.apiToken;
         this.fetchImpl = options.fetch ?? fetch;
+        if (options.defaultSecrets) {
+            this.defaultSecrets = options.defaultSecrets;
+            emitDefaultSecretsDeprecationWarning();
+        }
     }
     async submitRun(request) {
+        const secrets = request.secrets ?? this.defaultSecrets;
+        if (!secrets) {
+            throw new Error("submitRun requires `secrets` either per-call or via `defaultSecrets` on the client");
+        }
+        if (request.proxyEndpoints && request.proxyEndpoints.length > 0) {
+            // Catch the most common mistake at submission time so the error
+            // doesn't only surface deep inside the BFF parser. The BFF still
+            // performs the same cross-validation authoritatively.
+            validateProxyAuth(request.proxyEndpoints, secrets.proxyEndpointAuth);
+        }
+        const payload = { ...request, secrets };
         return this.request("/api/runs", {
             method: "POST",
-            body: JSON.stringify(request)
+            body: JSON.stringify(payload)
         });
     }
     async getRun(workspaceId, runId) {
@@ -104,4 +120,84 @@ function extractErrorMessage(body) {
 function hasRun(input) {
     return Boolean(input && typeof input === "object" && "run" in input);
 }
+let defaultSecretsWarned = false;
+function emitDefaultSecretsDeprecationWarning() {
+    // Emit once per process to avoid log spam in long-running apps that
+    // construct many clients (e.g. one per workspace). Tests that need
+    // to observe the warning can reset the flag via
+    // {@link resetDefaultSecretsDeprecationWarning}.
+    if (defaultSecretsWarned)
+        return;
+    defaultSecretsWarned = true;
+    console.warn("[antpath] AntpathPlatformClientOptions.defaultSecrets is deprecated and will be removed in a future release. " +
+        "Pass `secrets` explicitly on every submitRun call so the active credentials are visible to the agent reading the call site.");
+}
+/**
+ * Test-only: reset the "warn once" guard for the `defaultSecrets`
+ * deprecation message. Production code should not call this.
+ *
+ * @internal
+ */
+export function resetDefaultSecretsDeprecationWarning() {
+    defaultSecretsWarned = false;
+}
+/**
+ * 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 function validateProxyAuth(endpoints, auth) {
+    const authList = auth ?? [];
+    const endpointNames = new Set(endpoints.map((e) => e.name));
+    const authNames = new Set();
+    for (const entry of authList) {
+        if (authNames.has(entry.name)) {
+            throw new Error(`secrets.proxyEndpointAuth contains duplicate name '${entry.name}'`);
+        }
+        authNames.add(entry.name);
+        if (!endpointNames.has(entry.name)) {
+            throw new Error(`secrets.proxyEndpointAuth[].name='${entry.name}' has no matching proxyEndpoints[].name`);
+        }
+    }
+    for (const endpoint of endpoints) {
+        const match = authList.find((a) => a.name === endpoint.name);
+        if (!match) {
+            throw new Error(`proxyEndpoints[].name='${endpoint.name}' is missing a matching secrets.proxyEndpointAuth entry`);
+        }
+        if (match.value.type !== endpoint.authShape.type) {
+            throw new Error(`secrets.proxyEndpointAuth[name='${endpoint.name}'].value.type='${match.value.type}' does not match proxyEndpoints[name='${endpoint.name}'].authShape.type='${endpoint.authShape.type}'`);
+        }
+    }
+}
+/**
+ * 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 function buildPlatformAllowedHosts(input) {
+    const result = [];
+    try {
+        result.push(new URL(input.dashboardBaseUrl).host);
+    }
+    catch {
+        throw new Error("buildPlatformAllowedHosts: dashboardBaseUrl must be an absolute URL");
+    }
+    for (const host of input.extraHosts ?? []) {
+        if (!result.includes(host))
+            result.push(host);
+    }
+    return result;
+}
 //# sourceMappingURL=client.js.map

package/dist/platform/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/platform/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/platform/client.ts"],"names":[],"mappings":"AA0JA,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAChC,MAAM,CAAS;IACf,OAAO,CAAU;IAE1B,YAAY,MAAc,EAAE,OAAe,EAAE,OAAgB;QAC3D,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF;AAED,MAAM,OAAO,qBAAqB;IACf,OAAO,CAAM;IACb,QAAQ,CAAS;IACjB,SAAS,CAAY;IACrB,cAAc,CAAyB;IAExD,YAAY,OAAqC;QAC/C,MAAM,MAAM,GAAG,OAA6C,CAAC;QAC7D,IAAI,iBAAiB,IAAI,MAAM,IAAI,gBAAgB,IAAI,MAAM,EAAE,CAAC;YAC9D,MAAM,IAAI,KAAK,CAAC,gJAAgJ,CAAC,CAAC;QACpK,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CAAC,sBAAsB,CAAC,CAAC;QAC1C,CAAC;QAED,IAAI,CAAC,OAAO,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,GAAG,CAAC,CAAC;QAChG,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACjC,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,KAAK,IAAI,KAAK,CAAC;QACxC,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;YAC3B,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;YAC7C,oCAAoC,EAAE,CAAC;QACzC,CAAC;IACH,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,OAAqC;QACnD,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,IAAI,CAAC,cAAc,CAAC;QACvD,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,oFAAoF,CAAC,CAAC;QACxG,CAAC;QACD,IAAI,OAAO,CAAC,cAAc,IAAI,OAAO,CAAC,cAAc,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAChE,gEAAgE;YAChE,iEAAiE;YACjE,sDAAsD;YACtD,iBAAiB,CAAC,OAAO,CAAC,cAAc,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC;QACvE,CAAC;QACD,MAAM,OAAO,GAAiC,EAAE,GAAG,OAAO,EAAE,OAAO,EAAE,CAAC;QACtE,OAAO,IAAI,CAAC,OAAO,CAAc,WAAW,EAAE;YAC5C,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;SAC9B,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,WAAmB,EAAE,KAAa;QAC7C,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CACjC,aAAa,kBAAkB,CAAC,KAAK,CAAC,EAAE,EACxC,EAAE,EACF,EAAE,WAAW,EAAE,CAChB,CAAC;QACF,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC;IACpD,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,WAAmB,EAAE,KAAa;QACpD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CACjC,aAAa,kBAAkB,CAAC,KAAK,CAAC,SAAS,EAC/C,EAAE,EACF,EAAE,WAAW,EAAE,CAChB,CAAC;QACF,OAAO,QAAQ,CAAC,MAAM,CAAC;IACzB,CAAC;IAED,KAAK,CAAC,WAAW,CAAC,WAAmB,EAAE,KAAa;QAClD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CACjC,aAAa,kBAAkB,CAAC,KAAK,CAAC,UAAU,EAChD,EAAE,EACF,EAAE,WAAW,EAAE,CAChB,CAAC;QACF,OAAO,QAAQ,CAAC,OAAO,CAAC;IAC1B,CAAC;IAED,KAAK,CAAC,gBAAgB,CAAC,WAAmB,EAAE,KAAa,EAAE,QAAgB;QACzE,OAAO,IAAI,CAAC,OAAO,CACjB,aAAa,kBAAkB,CAAC,KAAK,CAAC,YAAY,kBAAkB,CAAC,QAAQ,CAAC,OAAO,EACrF,EAAE,MAAM,EAAE,MAAM,EAAE,EAClB,EAAE,WAAW,EAAE,CAChB,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,WAAmB,EAAE,KAAa;QAChD,MAAM,IAAI,CAAC,OAAO,CAAU,aAAa,kBAAkB,CAAC,KAAK,CAAC,SAAS,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,WAAW,EAAE,CAAC,CAAC;IACpH,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,WAAmB,EAAE,KAAa;QAChD,MAAM,IAAI,CAAC,OAAO,CAAU,aAAa,kBAAkB,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,EAAE,WAAW,EAAE,CAAC,CAAC;IAC/G,CAAC;IAEO,KAAK,CAAC,OAAO,CACnB,IAAY,EACZ,OAAoB,EAAE,EACtB,QAAgC,EAAE;QAElC,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAC3D,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACjD,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACnC,CAAC;QACD,MAAM,OAAO,GAAG;YACd,MAAM,EAAE,kBAAkB;YAC1B,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC5D,aAAa,EAAE,UAAU,IAAI,CAAC,QAAQ,EAAE;YACxC,GAAG,gBAAgB,CAAC,IAAI,CAAC,OAAO,CAAC;SAClC,CAAC;QAEF,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;QACjE,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,CAAC;QACtC,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,gBAAgB,CAAC,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;QAC/E,CAAC;QACD,OAAO,IAAS,CAAC;IACnB,CAAC;CACF;AAED,SAAS,gBAAgB,CAAC,OAAgC;IACxD,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,IAAI,OAAO,YAAY,OAAO,EAAE,CAAC;QAC/B,OAAO,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAC/C,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3B,OAAO,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,KAAK,UAAU,QAAQ,CAAC,QAAkB;IACxC,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;IACnC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAY,CAAC;AACrC,CAAC;AAED,SAAS,mBAAmB,CAAC,IAAa;IACxC,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,OAAO,IAAI,IAAI,EAAE,CAAC;QACxD,MAAM,KAAK,GAAI,IAAqC,CAAC,KAAK,CAAC;QAC3D,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,SAAS,IAAI,KAAK,EAAE,CAAC;YAC7D,MAAM,OAAO,GAAI,KAAwC,CAAC,OAAO,CAAC;YAClE,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;gBAChC,OAAO,OAAO,CAAC;YACjB,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,yBAAyB,CAAC;AACnC,CAAC;AAED,SAAS,MAAM,CAAC,KAAkD;IAChE,OAAO,OAAO,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,IAAI,KAAK,CAAC,CAAC;AACvE,CAAC;AAED,IAAI,oBAAoB,GAAG,KAAK,CAAC;AACjC,SAAS,oCAAoC;IAC3C,oEAAoE;IACpE,mEAAmE;IACnE,gDAAgD;IAChD,iDAAiD;IACjD,IAAI,oBAAoB;QAAE,OAAO;IACjC,oBAAoB,GAAG,IAAI,CAAC;IAC5B,OAAO,CAAC,IAAI,CACV,+GAA+G;QAC7G,6HAA6H,CAChI,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qCAAqC;IACnD,oBAAoB,GAAG,KAAK,CAAC;AAC/B,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAC/B,SAA2C,EAC3C,IAAsD;IAEtD,MAAM,QAAQ,GAAG,IAAI,IAAI,EAAE,CAAC;IAC5B,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IAC5D,MAAM,SAAS,GAAG,IAAI,GAAG,EAAU,CAAC;IACpC,KAAK,MAAM,KAAK,IAAI,QAAQ,EAAE,CAAC;QAC7B,IAAI,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CAAC,sDAAsD,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC;QACvF,CAAC;QACD,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC1B,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YACnC,MAAM,IAAI,KAAK,CAAC,qCAAqC,KAAK,CAAC,IAAI,yCAAyC,CAAC,CAAC;QAC5G,CAAC;IACH,CAAC;IACD,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC7D,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CAAC,0BAA0B,QAAQ,CAAC,IAAI,yDAAyD,CAAC,CAAC;QACpH,CAAC;QACD,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;YACjD,MAAM,IAAI,KAAK,CACb,mCAAmC,QAAQ,CAAC,IAAI,kBAAkB,KAAK,CAAC,KAAK,CAAC,IAAI,yCAAyC,QAAQ,CAAC,IAAI,sBAAsB,QAAQ,CAAC,SAAS,CAAC,IAAI,GAAG,CACzL,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,yBAAyB,CAAC,KAGzC;IACC,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,CAAC;QACH,MAAM,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,IAAI,CAAC,CAAC;IACpD,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,qEAAqE,CAAC,CAAC;IACzF,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,UAAU,IAAI,EAAE,EAAE,CAAC;QAC1C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;YAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAChD,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/providers/known-events.d.ts

@@ -0,0 +1,60 @@
+import type { ProviderEvent } from "../types.js";
+/**
+ * Type guards that narrow a `ProviderEvent` by the documented Claude Managed
+ * Agents event `type` strings. These do not assert anything about the event
+ * payload shape beyond the `type` field — payload contents are passed through
+ * verbatim from the provider and may evolve.
+ *
+ * Reference: https://platform.claude.com/docs/en/managed-agents/events-and-streaming.md
+ */
+export declare function isAgentEvent<E extends ProviderEvent>(event: E): event is E & {
+    type: `agent.${string}`;
+};
+export declare function isUserEvent<E extends ProviderEvent>(event: E): event is E & {
+    type: `user.${string}`;
+};
+export declare function isSessionEvent<E extends ProviderEvent>(event: E): event is E & {
+    type: `session.${string}`;
+};
+export declare function isSpanEvent<E extends ProviderEvent>(event: E): event is E & {
+    type: `span.${string}`;
+};
+export declare function isAgentMessage<E extends ProviderEvent>(event: E): event is E & {
+    type: "agent.message";
+};
+export declare function isAgentThinking<E extends ProviderEvent>(event: E): event is E & {
+    type: "agent.thinking";
+};
+export declare function isAgentToolUse<E extends ProviderEvent>(event: E): event is E & {
+    type: "agent.tool_use";
+};
+export declare function isAgentToolResult<E extends ProviderEvent>(event: E): event is E & {
+    type: "agent.tool_result";
+};
+export declare function isAgentMcpToolUse<E extends ProviderEvent>(event: E): event is E & {
+    type: "agent.mcp_tool_use";
+};
+export declare function isAgentMcpToolResult<E extends ProviderEvent>(event: E): event is E & {
+    type: "agent.mcp_tool_result";
+};
+export declare function isAgentCustomToolUse<E extends ProviderEvent>(event: E): event is E & {
+    type: "agent.custom_tool_use";
+};
+export declare function isUserMessage<E extends ProviderEvent>(event: E): event is E & {
+    type: "user.message";
+};
+export declare function isSessionStatusRunning<E extends ProviderEvent>(event: E): event is E & {
+    type: "session.status_running";
+};
+export declare function isSessionStatusIdle<E extends ProviderEvent>(event: E): event is E & {
+    type: "session.status_idle";
+};
+export declare function isSessionStatusRescheduled<E extends ProviderEvent>(event: E): event is E & {
+    type: "session.status_rescheduled";
+};
+export declare function isSessionStatusTerminated<E extends ProviderEvent>(event: E): event is E & {
+    type: "session.status_terminated";
+};
+export declare function isSessionError<E extends ProviderEvent>(event: E): event is E & {
+    type: "session.error";
+};

package/dist/providers/known-events.js

@@ -0,0 +1,64 @@
+/**
+ * Type guards that narrow a `ProviderEvent` by the documented Claude Managed
+ * Agents event `type` strings. These do not assert anything about the event
+ * payload shape beyond the `type` field — payload contents are passed through
+ * verbatim from the provider and may evolve.
+ *
+ * Reference: https://platform.claude.com/docs/en/managed-agents/events-and-streaming.md
+ */
+// Prefix groupers — documented `{domain}.{action}` convention.
+export function isAgentEvent(event) {
+    return typeof event.type === "string" && event.type.startsWith("agent.");
+}
+export function isUserEvent(event) {
+    return typeof event.type === "string" && event.type.startsWith("user.");
+}
+export function isSessionEvent(event) {
+    return typeof event.type === "string" && event.type.startsWith("session.");
+}
+export function isSpanEvent(event) {
+    return typeof event.type === "string" && event.type.startsWith("span.");
+}
+// Agent events.
+export function isAgentMessage(event) {
+    return event.type === "agent.message";
+}
+export function isAgentThinking(event) {
+    return event.type === "agent.thinking";
+}
+export function isAgentToolUse(event) {
+    return event.type === "agent.tool_use";
+}
+export function isAgentToolResult(event) {
+    return event.type === "agent.tool_result";
+}
+export function isAgentMcpToolUse(event) {
+    return event.type === "agent.mcp_tool_use";
+}
+export function isAgentMcpToolResult(event) {
+    return event.type === "agent.mcp_tool_result";
+}
+export function isAgentCustomToolUse(event) {
+    return event.type === "agent.custom_tool_use";
+}
+// User events.
+export function isUserMessage(event) {
+    return event.type === "user.message";
+}
+// Session events.
+export function isSessionStatusRunning(event) {
+    return event.type === "session.status_running";
+}
+export function isSessionStatusIdle(event) {
+    return event.type === "session.status_idle";
+}
+export function isSessionStatusRescheduled(event) {
+    return event.type === "session.status_rescheduled";
+}
+export function isSessionStatusTerminated(event) {
+    return event.type === "session.status_terminated";
+}
+export function isSessionError(event) {
+    return event.type === "session.error";
+}
+//# sourceMappingURL=known-events.js.map

package/dist/providers/known-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"known-events.js","sourceRoot":"","sources":["../../src/providers/known-events.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AAEH,+DAA+D;AAE/D,MAAM,UAAU,YAAY,CAA0B,KAAQ;IAC5D,OAAO,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;AAC3E,CAAC;AAED,MAAM,UAAU,WAAW,CAA0B,KAAQ;IAC3D,OAAO,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;AAC1E,CAAC;AAED,MAAM,UAAU,cAAc,CAA0B,KAAQ;IAC9D,OAAO,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;AAC7E,CAAC;AAED,MAAM,UAAU,WAAW,CAA0B,KAAQ;IAC3D,OAAO,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;AAC1E,CAAC;AAED,gBAAgB;AAEhB,MAAM,UAAU,cAAc,CAA0B,KAAQ;IAC9D,OAAO,KAAK,CAAC,IAAI,KAAK,eAAe,CAAC;AACxC,CAAC;AAED,MAAM,UAAU,eAAe,CAA0B,KAAQ;IAC/D,OAAO,KAAK,CAAC,IAAI,KAAK,gBAAgB,CAAC;AACzC,CAAC;AAED,MAAM,UAAU,cAAc,CAA0B,KAAQ;IAC9D,OAAO,KAAK,CAAC,IAAI,KAAK,gBAAgB,CAAC;AACzC,CAAC;AAED,MAAM,UAAU,iBAAiB,CAA0B,KAAQ;IACjE,OAAO,KAAK,CAAC,IAAI,KAAK,mBAAmB,CAAC;AAC5C,CAAC;AAED,MAAM,UAAU,iBAAiB,CAA0B,KAAQ;IACjE,OAAO,KAAK,CAAC,IAAI,KAAK,oBAAoB,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,oBAAoB,CAA0B,KAAQ;IACpE,OAAO,KAAK,CAAC,IAAI,KAAK,uBAAuB,CAAC;AAChD,CAAC;AAED,MAAM,UAAU,oBAAoB,CAA0B,KAAQ;IACpE,OAAO,KAAK,CAAC,IAAI,KAAK,uBAAuB,CAAC;AAChD,CAAC;AAED,eAAe;AAEf,MAAM,UAAU,aAAa,CAA0B,KAAQ;IAC7D,OAAO,KAAK,CAAC,IAAI,KAAK,cAAc,CAAC;AACvC,CAAC;AAED,kBAAkB;AAElB,MAAM,UAAU,sBAAsB,CAA0B,KAAQ;IACtE,OAAO,KAAK,CAAC,IAAI,KAAK,wBAAwB,CAAC;AACjD,CAAC;AAED,MAAM,UAAU,mBAAmB,CAA0B,KAAQ;IACnE,OAAO,KAAK,CAAC,IAAI,KAAK,qBAAqB,CAAC;AAC9C,CAAC;AAED,MAAM,UAAU,0BAA0B,CAA0B,KAAQ;IAC1E,OAAO,KAAK,CAAC,IAAI,KAAK,4BAA4B,CAAC;AACrD,CAAC;AAED,MAAM,UAAU,yBAAyB,CAA0B,KAAQ;IACzE,OAAO,KAAK,CAAC,IAAI,KAAK,2BAA2B,CAAC;AACpD,CAAC;AAED,MAAM,UAAU,cAAc,CAA0B,KAAQ;IAC9D,OAAO,KAAK,CAAC,IAAI,KAAK,eAAe,CAAC;AACxC,CAAC"}

package/dist/run/controller.d.ts

@@ -1,6 +1,6 @@
 import type { ManagedAgentProvider } from "../providers/types.js";
 import type { ResolvedTemplate } from "../template/compiler.js";
-import type { CleanupPolicy, CleanupResult, CredentialInput, DownloadOutputsOptions, DownloadOutputsResult, Logger, ProviderFile, RunEvent, RunResult, RunStatus, UsageSummary } from "../types.js";
+import type { CleanupPolicy, CleanupResult, CredentialInput, DownloadOutputsOptions, DownloadOutputsResult, Logger, ProviderFile, RunEvent, RunEventHandler, RunResult, RunStatus, SessionResourceUpload, UsageSummary } from "../types.js";
 export interface RunControllerOptions {
     provider: ManagedAgentProvider;
     template: ResolvedTemplate;
@@ -9,6 +9,9 @@ export interface RunControllerOptions {
     timeoutMs?: number | undefined;
     signal?: AbortSignal | undefined;
     logger?: Logger | undefined;
+    onEvent?: RunEventHandler | undefined;
+    onEventAbortOnError?: boolean | undefined;
+    sessionResources?: readonly SessionResourceUpload[] | undefined;
 }
 export declare class RunController {
     #private;