antpath 0.2.1 → 0.4.0

package/dist/_shared/index.d.ts

@@ -0,0 +1,17 @@
+export * from "./cleanup-policy.js";
+export * from "./config.js";
+export * from "./dev-stack.js";
+export * from "./errors.js";
+export * from "./proxy-protocol.js";
+export * from "./secrets.js";
+export * from "./status.js";
+export * from "./submission.js";
+export * from "./stable.js";
+export * from "./sdk-secrets.js";
+export * from "./sdk-errors.js";
+export * from "./template/index.js";
+export * from "./runtime-types.js";
+export * from "./known-events.js";
+export * from "./http.js";
+export * as operations from "./operations.js";
+export * from "./proxy-validation.js";

package/dist/_shared/index.js

@@ -0,0 +1,20 @@
+export * from "./cleanup-policy.js";
+export * from "./config.js";
+export * from "./dev-stack.js";
+export * from "./errors.js";
+export * from "./proxy-protocol.js";
+export * from "./secrets.js";
+export * from "./status.js";
+export * from "./submission.js";
+// SDK + CLI shared surface — moved here so the published `antpath` SDK
+// and the in-container `antpath` CLI consume the SAME implementation.
+export * from "./stable.js";
+export * from "./sdk-secrets.js";
+export * from "./sdk-errors.js";
+export * from "./template/index.js";
+export * from "./runtime-types.js";
+export * from "./known-events.js";
+export * from "./http.js";
+export * as operations from "./operations.js";
+export * from "./proxy-validation.js";
+//# sourceMappingURL=index.js.map

package/dist/{providers → _shared}/known-events.d.ts

@@ -1,4 +1,4 @@
-import type { ProviderEvent } from "../types.js";
+import type { ProviderEvent } from "./runtime-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
@@ -22,33 +22,33 @@ export declare function isSpanEvent<E extends ProviderEvent>(event: E): event is
 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 isAgentThinking<E extends ProviderEvent>(event: E): event is E & {
+    type: "agent.thinking";
+};
+export declare function isAgentCustomToolUse<E extends ProviderEvent>(event: E): event is E & {
+    type: "agent.custom_tool_use";
+};
 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 isSessionStatusRunning<E extends ProviderEvent>(event: E): event is E & {
+    type: "session.status_running";
+};
 export declare function isSessionStatusRescheduled<E extends ProviderEvent>(event: E): event is E & {
     type: "session.status_rescheduled";
 };

package/dist/{providers → _shared}/known-events.js

@@ -23,35 +23,35 @@ export function isSpanEvent(event) {
 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 isAgentThinking(event) {
+    return event.type === "agent.thinking";
+}
+export function isAgentCustomToolUse(event) {
+    return event.type === "agent.custom_tool_use";
+}
 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 isSessionStatusRunning(event) {
+    return event.type === "session.status_running";
+}
 export function isSessionStatusRescheduled(event) {
     return event.type === "session.status_rescheduled";
 }

package/dist/_shared/operations.d.ts

@@ -0,0 +1,24 @@
+import type { HttpClient } from "./http.js";
+import type { Output, Run, RunEvent, SignedOutputLink, WhoAmI } from "./runtime-types.js";
+import type { PlatformRunSubmissionInput } from "./submission.js";
+/**
+ * The single source of truth for SDK<->BFF transport. The SDK class
+ * AND the CLI subcommands both call these functions; neither
+ * surface re-implements HTTP requests against the dashboard.
+ *
+ * Every function takes an HttpClient (so callers control auth + fetch
+ * injection) and returns parsed responses.
+ *
+ * Workspace identity is derived server-side from the API token on
+ * every request — callers do not pass `workspaceId`. See
+ * `references/development-principles.md` (Agent-first surface design,
+ * Concrete rule 3).
+ */
+export declare function submitRun(http: HttpClient, request: PlatformRunSubmissionInput): Promise<Run>;
+export declare function getRun(http: HttpClient, runId: string): Promise<Run>;
+export declare function listRunEvents(http: HttpClient, runId: string): Promise<readonly RunEvent[]>;
+export declare function listOutputs(http: HttpClient, runId: string): Promise<readonly Output[]>;
+export declare function createOutputLink(http: HttpClient, runId: string, outputId: string): Promise<SignedOutputLink>;
+export declare function cancelRun(http: HttpClient, runId: string): Promise<void>;
+export declare function deleteRun(http: HttpClient, runId: string): Promise<void>;
+export declare function whoami(http: HttpClient): Promise<WhoAmI>;

package/dist/_shared/operations.js

@@ -0,0 +1,47 @@
+/**
+ * The single source of truth for SDK<->BFF transport. The SDK class
+ * AND the CLI subcommands both call these functions; neither
+ * surface re-implements HTTP requests against the dashboard.
+ *
+ * Every function takes an HttpClient (so callers control auth + fetch
+ * injection) and returns parsed responses.
+ *
+ * Workspace identity is derived server-side from the API token on
+ * every request — callers do not pass `workspaceId`. See
+ * `references/development-principles.md` (Agent-first surface design,
+ * Concrete rule 3).
+ */
+export async function submitRun(http, request) {
+    return http.request("/api/runs", {
+        method: "POST",
+        body: JSON.stringify(request)
+    });
+}
+export async function getRun(http, runId) {
+    const result = await http.request(`/api/runs/${encodeURIComponent(runId)}`);
+    return hasRun(result) ? result.run : result;
+}
+export async function listRunEvents(http, runId) {
+    const result = await http.request(`/api/runs/${encodeURIComponent(runId)}/events`);
+    return result.events;
+}
+export async function listOutputs(http, runId) {
+    const result = await http.request(`/api/runs/${encodeURIComponent(runId)}/outputs`);
+    return result.outputs;
+}
+export async function createOutputLink(http, runId, outputId) {
+    return http.request(`/api/runs/${encodeURIComponent(runId)}/outputs/${encodeURIComponent(outputId)}/link`, { method: "POST" });
+}
+export async function cancelRun(http, runId) {
+    await http.request(`/api/runs/${encodeURIComponent(runId)}/cancel`, { method: "POST" });
+}
+export async function deleteRun(http, runId) {
+    await http.request(`/api/runs/${encodeURIComponent(runId)}`, { method: "DELETE" });
+}
+export async function whoami(http) {
+    return http.request("/api/whoami");
+}
+function hasRun(value) {
+    return Boolean(value && typeof value === "object" && "run" in value);
+}
+//# sourceMappingURL=operations.js.map

package/dist/_shared/proxy-protocol.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Wire-protocol version. Bumped on any breaking change to the request or
+ * response shape. The CLI sends this in the `X-Antpath-Proxy-Protocol`
+ * header on every request; the BFF rejects mismatches with HTTP 426
+ * `unsupported_protocol`.
+ *
+ * Bumps are coordinated: CLI and BFF release together, the worker
+ * bundles the matching CLI artifact, and the e2e suite runs both with
+ * the new version. See plan.md "CLI design".
+ */
+export declare const PROXY_PROTOCOL_VERSION: "1";
+export declare const PROXY_PROTOCOL_HEADER = "x-antpath-proxy-protocol";
+export declare const PROXY_METHOD_HEADER = "x-antpath-method";
+export declare const PROXY_PATH_HEADER = "x-antpath-path";
+export declare const PROXY_QUERY_HEADER = "x-antpath-query";
+export declare const PROXY_HEADERS_HEADER = "x-antpath-headers";
+export declare const PROXY_RESPONSE_MODE_HEADER = "x-antpath-response-mode";
+export declare const PROXY_ALLOWED_METHODS: readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"];
+export type ProxyMethod = (typeof PROXY_ALLOWED_METHODS)[number];
+export declare const PROXY_RESPONSE_MODES: readonly ["status_only", "headers_only", "full"];
+export type ProxyResponseMode = (typeof PROXY_RESPONSE_MODES)[number];
+/**
+ * Returns the narrower of the two response modes (lower width wins).
+ * Pure function so the CLI and BFF can both call it without import cycles.
+ */
+export declare function narrowResponseMode(policy: ProxyResponseMode, requested: ProxyResponseMode): ProxyResponseMode;
+/**
+ * Error codes returned by the proxy route. Stable strings — the CLI
+ * matches against them in scripts. Adding a new code is non-breaking;
+ * removing or renaming an existing code requires a protocol bump.
+ */
+export declare const PROXY_ERROR_CODES: readonly ["unsupported_protocol", "unauthorized", "endpoint_not_found", "policy_denied", "rate_limited", "budget_exceeded", "ssrf_denied", "upstream_timeout", "upstream_error", "exceeded_cap", "bad_request", "internal_error"];
+export type ProxyErrorCode = (typeof PROXY_ERROR_CODES)[number];
+/**
+ * Shape of the JSON written to `/antpath/index.json` inside the container.
+ *
+ * Always present (every run), regardless of whether any proxy endpoints
+ * were declared. With zero endpoints, `endpoints` is `[]` and
+ * `proxyBaseUrl` is `null` — this keeps `antpath --help` working
+ * uniformly and makes the always-on surface observable in tests.
+ *
+ * Auth values NEVER appear in this file. The file is mounted into the
+ * container; treat it as world-readable from the agent's perspective.
+ */
+export interface ProxyIndexFile {
+    readonly protocolVersion: typeof PROXY_PROTOCOL_VERSION;
+    readonly runId: string;
+    readonly proxyBaseUrl: string | null;
+    readonly endpoints: readonly ProxyIndexEntry[];
+}
+export interface ProxyIndexEntry {
+    readonly name: string;
+    readonly baseUrl: string;
+    readonly authShape: ProxyAuthShape;
+    readonly allowMethods: readonly ProxyMethod[];
+    readonly allowPathPrefixes: readonly string[];
+    readonly allowHeaders: readonly string[];
+    readonly responseMode: ProxyResponseMode;
+    readonly maxRequestBytes: number;
+    readonly maxResponseBytes: number;
+    readonly timeoutMs: number;
+    readonly perCallBudget: number;
+    readonly responseByteBudget: number;
+}
+/**
+ * Structural description of how the upstream endpoint expects auth.
+ * The actual auth value lives in the run's Vault bundle under
+ * `secrets.proxyEndpointAuth[i].value` and is never reflected back
+ * into the container or index file.
+ */
+export type ProxyAuthShape = {
+    readonly type: "bearer";
+} | {
+    readonly type: "basic";
+} | {
+    readonly type: "header";
+    readonly name: string;
+} | {
+    readonly type: "query";
+    readonly name: string;
+};
+export type ProxyAuthType = ProxyAuthShape["type"];
+/**
+ * Header name (lowercase) that an upstream auth shape uses as its
+ * carrier. Returns `undefined` for query-based auth.
+ *
+ * Used by the submission parser to forbid `allowHeaders` from listing
+ * the auth header (avoids leaks via caller-supplied headers), and by
+ * the proxy route to strip any caller header that would collide with
+ * the auth carrier at request time.
+ */
+export declare function authShapeHeaderName(shape: ProxyAuthShape): string | undefined;
+/**
+ * Query-string key that an upstream query-based auth shape uses as its
+ * carrier. Returns `undefined` for non-query shapes.
+ */
+export declare function authShapeQueryName(shape: ProxyAuthShape): string | undefined;
+/**
+ * JSON body returned on a successful proxy call. The actual HTTP
+ * response from the BFF to the CLI is always 200 once the BFF accepts
+ * the request; the upstream's status/headers/body are reflected inside
+ * this envelope so the CLI can decide what to write to stdout/stderr.
+ */
+export interface ProxyResponseEnvelope {
+    readonly endpointName: string;
+    readonly upstreamStatus: number;
+    /** Lowercase header names → values. Allowlist-filtered by the BFF. */
+    readonly upstreamHeaders: Readonly<Record<string, string>>;
+    /**
+     * Base64-encoded upstream body. Present only when the effective
+     * response mode is `full`. Truncated to `maxResponseBytes`; if the
+     * upstream exceeded the cap, `truncated` is `true`.
+     */
+    readonly upstreamBodyBase64?: string;
+    readonly truncated?: boolean;
+    /**
+     * Echoed back so the CLI can warn the agent when its requested mode
+     * was clamped against the policy ceiling.
+     */
+    readonly effectiveResponseMode: ProxyResponseMode;
+    readonly modeClamped: boolean;
+    /** Remaining per-endpoint per-run budget after this call. */
+    readonly remainingCalls: number;
+    readonly remainingResponseBytes: number;
+}
+/**
+ * JSON body returned on any error. The CLI emits this verbatim on
+ * stderr and exits non-zero. Audit row carries the same `code`.
+ */
+export interface ProxyErrorBody {
+    readonly error: ProxyErrorCode;
+    /** Human-readable message. Never includes auth values. */
+    readonly message: string;
+    /**
+     * Optional diagnostic fields. Always safe to surface — auth values
+     * and full URLs are stripped at the BFF.
+     */
+    readonly endpointName?: string;
+    readonly upstreamStatus?: number;
+    /** Server-supplied protocol version on `unsupported_protocol`. */
+    readonly serverProtocolVersion?: string;
+}
+/**
+ * Status code → error code mapping used by the BFF to ensure the audit
+ * row's error code and the HTTP response line up. Kept here so callers
+ * can do a sanity check in tests.
+ */
+export declare const PROXY_ERROR_HTTP_STATUS: Record<ProxyErrorCode, number>;

package/dist/_shared/proxy-protocol.js

@@ -0,0 +1,113 @@
+// Wire format between the in-container CLI (`/antpath/antpath`) and the
+// dashboard BFF proxy route (`POST /api/runs/:runId/proxy/:endpointName`).
+//
+// This module is the single source of truth for the request shape, the
+// response shape, the error-code enum, and the protocol version header.
+// CLI and BFF both import from here; drift becomes a build-time type error.
+//
+// References:
+//   - plan.md sections "Proxy route" and "CLI design"
+//   - references/development-principles.md (Agent-first surface design)
+/**
+ * Wire-protocol version. Bumped on any breaking change to the request or
+ * response shape. The CLI sends this in the `X-Antpath-Proxy-Protocol`
+ * header on every request; the BFF rejects mismatches with HTTP 426
+ * `unsupported_protocol`.
+ *
+ * Bumps are coordinated: CLI and BFF release together, the worker
+ * bundles the matching CLI artifact, and the e2e suite runs both with
+ * the new version. See plan.md "CLI design".
+ */
+export const PROXY_PROTOCOL_VERSION = "1";
+export const PROXY_PROTOCOL_HEADER = "x-antpath-proxy-protocol";
+export const PROXY_METHOD_HEADER = "x-antpath-method";
+export const PROXY_PATH_HEADER = "x-antpath-path";
+export const PROXY_QUERY_HEADER = "x-antpath-query";
+export const PROXY_HEADERS_HEADER = "x-antpath-headers";
+export const PROXY_RESPONSE_MODE_HEADER = "x-antpath-response-mode";
+export const PROXY_ALLOWED_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"];
+export const PROXY_RESPONSE_MODES = ["status_only", "headers_only", "full"];
+/**
+ * Narrowing order: a request may only narrow below the policy ceiling.
+ * `status_only` is narrowest, `full` is widest. The BFF computes
+ * `narrowest(policyMode, headerMode)` and ignores escalation attempts,
+ * auditing them as `mode_clamped`.
+ */
+const RESPONSE_MODE_WIDTH = {
+    status_only: 0,
+    headers_only: 1,
+    full: 2
+};
+/**
+ * Returns the narrower of the two response modes (lower width wins).
+ * Pure function so the CLI and BFF can both call it without import cycles.
+ */
+export function narrowResponseMode(policy, requested) {
+    return RESPONSE_MODE_WIDTH[requested] < RESPONSE_MODE_WIDTH[policy] ? requested : policy;
+}
+/**
+ * Error codes returned by the proxy route. Stable strings — the CLI
+ * matches against them in scripts. Adding a new code is non-breaking;
+ * removing or renaming an existing code requires a protocol bump.
+ */
+export const PROXY_ERROR_CODES = [
+    "unsupported_protocol",
+    "unauthorized",
+    "endpoint_not_found",
+    "policy_denied",
+    "rate_limited",
+    "budget_exceeded",
+    "ssrf_denied",
+    "upstream_timeout",
+    "upstream_error",
+    "exceeded_cap",
+    "bad_request",
+    "internal_error"
+];
+/**
+ * Header name (lowercase) that an upstream auth shape uses as its
+ * carrier. Returns `undefined` for query-based auth.
+ *
+ * Used by the submission parser to forbid `allowHeaders` from listing
+ * the auth header (avoids leaks via caller-supplied headers), and by
+ * the proxy route to strip any caller header that would collide with
+ * the auth carrier at request time.
+ */
+export function authShapeHeaderName(shape) {
+    switch (shape.type) {
+        case "bearer":
+        case "basic":
+            return "authorization";
+        case "header":
+            return shape.name.toLowerCase();
+        case "query":
+            return undefined;
+    }
+}
+/**
+ * Query-string key that an upstream query-based auth shape uses as its
+ * carrier. Returns `undefined` for non-query shapes.
+ */
+export function authShapeQueryName(shape) {
+    return shape.type === "query" ? shape.name : undefined;
+}
+/**
+ * Status code → error code mapping used by the BFF to ensure the audit
+ * row's error code and the HTTP response line up. Kept here so callers
+ * can do a sanity check in tests.
+ */
+export const PROXY_ERROR_HTTP_STATUS = {
+    unsupported_protocol: 426,
+    unauthorized: 401,
+    endpoint_not_found: 404,
+    policy_denied: 403,
+    rate_limited: 429,
+    budget_exceeded: 429,
+    ssrf_denied: 403,
+    upstream_timeout: 504,
+    upstream_error: 502,
+    exceeded_cap: 502,
+    bad_request: 400,
+    internal_error: 500
+};
+//# sourceMappingURL=proxy-protocol.js.map

package/dist/_shared/proxy-validation.d.ts

@@ -0,0 +1,19 @@
+import type { PlatformProxyEndpoint, PlatformProxyEndpointAuth } from "./submission.js";
+/**
+ * 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/CLI before going over the wire.
+ */
+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.
+ */
+export declare function buildPlatformAllowedHosts(input: {
+    readonly dashboardBaseUrl: string;
+    readonly extraHosts?: readonly string[];
+}): readonly string[];

package/dist/_shared/proxy-validation.js

@@ -0,0 +1,51 @@
+/**
+ * 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/CLI before going over the wire.
+ */
+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.
+ */
+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=proxy-validation.js.map

package/dist/_shared/runtime-types.d.ts

@@ -0,0 +1,90 @@
+import type { JsonValue, PlatformInlineSecrets, PlatformProxyEndpoint } from "./submission.js";
+/**
+ * Loose record describing a run as the dashboard BFF returns it. Concrete
+ * dashboard-managed fields appear in the index signature; the SDK and CLI
+ * may surface them without strong typing per-field.
+ */
+export interface Run {
+    readonly id: string;
+    readonly status: string;
+    readonly workspaceId?: string;
+    readonly templateName?: string;
+    readonly templateHash?: string;
+    readonly createdAt?: string;
+    readonly updatedAt?: string;
+    readonly terminalAt?: string | null;
+    readonly errorMessage?: string | null;
+    readonly usage?: UsageSummary;
+    readonly [key: string]: unknown;
+}
+export interface UsageSummary {
+    readonly inputTokens?: number;
+    readonly outputTokens?: number;
+    readonly cacheReadInputTokens?: number;
+    readonly cacheCreationInputTokens?: number;
+    readonly totalTokens?: number;
+    readonly estimatedCostUsd?: number;
+}
+/**
+ * A run event as recorded by the dashboard. Includes the `type` field
+ * that the `is*Event` type guards narrow on plus any provider payload.
+ */
+export interface RunEvent {
+    readonly id: string;
+    readonly type: string;
+    readonly runId?: string;
+    readonly recordedAt?: string;
+    readonly [key: string]: unknown;
+}
+/**
+ * Provider-emitted event payload, kept structurally identical to the
+ * upstream Claude Managed Agents event so type guards work uniformly
+ * whether the event came from the worker (live) or the dashboard
+ * (replayed).
+ */
+export interface ProviderEvent {
+    readonly type: string;
+    readonly id?: string | undefined;
+    readonly created_at?: string | undefined;
+    readonly [key: string]: unknown;
+}
+/**
+ * One captured output file as the dashboard reports it. Use
+ * `createOutputLink` to get a short-lived signed URL for download.
+ */
+export interface Output {
+    readonly id: string;
+    readonly filename?: string;
+    readonly sizeBytes?: number;
+    readonly contentType?: string;
+    readonly createdAt?: string;
+    readonly [key: string]: unknown;
+}
+export interface SignedOutputLink {
+    readonly url: string;
+    readonly expiresAt?: string;
+    readonly [key: string]: unknown;
+}
+export interface WhoAmI {
+    readonly principalType: "api_token" | "user";
+    readonly workspaceId?: string;
+    readonly tokenId?: string;
+    readonly tokenName?: string | null;
+    readonly scopes?: readonly string[];
+    readonly [key: string]: unknown;
+}
+/**
+ * Full submission as the SDK and CLI assemble it before posting. The
+ * `template` is the SDK-level ResolvedTemplate (or a JSON-encoded one);
+ * the SDK/CLI converts to PlatformTemplateSubmission via the mapper.
+ */
+export interface RunSubmissionInput {
+    readonly workspaceId: string;
+    readonly idempotencyKey?: string;
+    readonly variables?: Record<string, JsonValue>;
+    readonly secrets: PlatformInlineSecrets;
+    readonly proxyEndpoints?: readonly PlatformProxyEndpoint[];
+    readonly cleanup?: {
+        readonly session?: "retain" | "delete";
+    };
+}

package/dist/_shared/runtime-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=runtime-types.js.map

package/dist/{errors.d.ts → _shared/sdk-errors.d.ts}

@@ -1,4 +1,4 @@
-export type AntpathErrorCode = "TEMPLATE_INVALID" | "CREDENTIAL_INVALID" | "PROVIDER_ERROR" | "RUN_STATE_ERROR" | "CLEANUP_ERROR";
+export type AntpathErrorCode = "TEMPLATE_INVALID" | "CREDENTIAL_INVALID" | "PROVIDER_ERROR" | "RUN_STATE_ERROR" | "CLEANUP_ERROR" | "API_ERROR";
 export declare class AntpathError extends Error {
     readonly code: AntpathErrorCode;
     readonly details?: unknown;
@@ -23,3 +23,12 @@ export declare class RunStateError extends AntpathError {
 export declare class CleanupError extends AntpathError {
     constructor(message: string, details?: unknown);
 }
+/**
+ * Thrown by SDK and CLI operations when the dashboard BFF returns a non-2xx
+ * response. Carries the HTTP status and parsed body for the caller to inspect.
+ */
+export declare class AntpathApiError extends AntpathError {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, message: string, body: unknown);
+}