antpath 0.2.1 → 0.4.0

package/dist/{errors.js → _shared/sdk-errors.js}

@@ -1,4 +1,4 @@
-import { redactSecrets } from "./utils/secrets.js";
+import { redactSecrets } from "./sdk-secrets.js";
 export class AntpathError extends Error {
     code;
     details;
@@ -36,4 +36,17 @@ export class CleanupError extends AntpathError {
         super("CLEANUP_ERROR", message, details);
     }
 }
-//# sourceMappingURL=errors.js.map
+/**
+ * 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 class AntpathApiError extends AntpathError {
+    status;
+    body;
+    constructor(status, message, body) {
+        super("API_ERROR", message, body);
+        this.status = status;
+        this.body = redactSecrets(body);
+    }
+}
+//# sourceMappingURL=sdk-errors.js.map

package/dist/{utils/secrets.js → _shared/sdk-secrets.js}

@@ -56,4 +56,4 @@ export function containsSecretLikeValue(input) {
 function isSecretKey(key) {
     return /(?:api[_-]?key|authorization|token|secret|password|credential)/i.test(key);
 }
-//# sourceMappingURL=secrets.js.map
+//# sourceMappingURL=sdk-secrets.js.map

package/dist/_shared/secrets.d.ts

@@ -0,0 +1,7 @@
+export interface RedactedSecret {
+    expose(): string;
+    toJSON(): string;
+    toString(): string;
+}
+export declare function redactedSecret(value: string): RedactedSecret;
+export declare function redactKnownSecrets(input: string, secrets: readonly RedactedSecret[]): string;

package/dist/_shared/secrets.js

@@ -0,0 +1,20 @@
+const REDACTED = "[secret]";
+export function redactedSecret(value) {
+    if (value.length === 0) {
+        throw new Error("Secret value must not be empty");
+    }
+    return Object.freeze({
+        expose: () => value,
+        toJSON: () => REDACTED,
+        toString: () => REDACTED
+    });
+}
+export function redactKnownSecrets(input, secrets) {
+    let output = input;
+    const longestFirst = [...secrets].sort((a, b) => b.expose().length - a.expose().length);
+    for (const secret of longestFirst) {
+        output = output.split(secret.expose()).join(REDACTED);
+    }
+    return output;
+}
+//# sourceMappingURL=secrets.js.map

package/dist/_shared/stable.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Canonical hosted antpath URL. Used as the default `baseUrl` for the
+ * SDK `AntpathClient` and the host-side CLI `--dashboard-url` flag.
+ *
+ * A single canonical default is not a "footnote mode" — it is the
+ * canonical product. Self-hosted deployments override via the
+ * explicit `baseUrl` / `--dashboard-url` parameter. The value lives in
+ * source (no env-var override) so the agent reading the SDK call site
+ * can see exactly where the call goes.
+ *
+ * See `references/development-principles.md` (Agent-first surface
+ * design, Concrete rule 3).
+ */
+export declare const ANTPATH_DEFAULT_BASE_URL = "https://antpath.ai";
+export declare function stableStringify(value: unknown): string;
+export declare function sha256(value: unknown): string;

package/dist/{utils → _shared}/stable.js

@@ -1,4 +1,18 @@
 import { createHash } from "node:crypto";
+/**
+ * Canonical hosted antpath URL. Used as the default `baseUrl` for the
+ * SDK `AntpathClient` and the host-side CLI `--dashboard-url` flag.
+ *
+ * A single canonical default is not a "footnote mode" — it is the
+ * canonical product. Self-hosted deployments override via the
+ * explicit `baseUrl` / `--dashboard-url` parameter. The value lives in
+ * source (no env-var override) so the agent reading the SDK call site
+ * can see exactly where the call goes.
+ *
+ * See `references/development-principles.md` (Agent-first surface
+ * design, Concrete rule 3).
+ */
+export const ANTPATH_DEFAULT_BASE_URL = "https://antpath.ai";
 export function stableStringify(value) {
     return JSON.stringify(sortValue(value));
 }

package/dist/_shared/status.d.ts

@@ -0,0 +1,8 @@
+export declare const RUN_STATUSES: readonly ["queued", "claiming", "provisioning", "session_created", "dispatched", "provider_running", "provider_idle", "provider_rescheduled", "cancelling", "capturing_outputs", "cleaning_up", "succeeded", "failed", "timed_out", "cancelled", "cleanup_failed", "pending_delete", "deleted"];
+export type RunStatus = typeof RUN_STATUSES[number];
+export type RunStatusKind = "active" | "terminal";
+export declare const TERMINAL_RUN_STATUSES: readonly ["succeeded", "failed", "timed_out", "cancelled", "cleanup_failed", "pending_delete", "deleted"];
+export declare function isTerminalRunStatus(status: RunStatus): boolean;
+export declare function getRunStatusKind(status: RunStatus): RunStatusKind;
+export declare const CLEANUP_STATUSES: readonly ["not_started", "pending", "running", "succeeded", "failed_retryable", "failed_terminal", "skipped"];
+export type CleanupStatus = typeof CLEANUP_STATUSES[number];

package/dist/_shared/status.js

@@ -0,0 +1,46 @@
+export const RUN_STATUSES = [
+    "queued",
+    "claiming",
+    "provisioning",
+    "session_created",
+    "dispatched",
+    "provider_running",
+    "provider_idle",
+    "provider_rescheduled",
+    "cancelling",
+    "capturing_outputs",
+    "cleaning_up",
+    "succeeded",
+    "failed",
+    "timed_out",
+    "cancelled",
+    "cleanup_failed",
+    "pending_delete",
+    "deleted"
+];
+export const TERMINAL_RUN_STATUSES = [
+    "succeeded",
+    "failed",
+    "timed_out",
+    "cancelled",
+    "cleanup_failed",
+    "pending_delete",
+    "deleted"
+];
+const terminalRunStatuses = new Set(TERMINAL_RUN_STATUSES);
+export function isTerminalRunStatus(status) {
+    return terminalRunStatuses.has(status);
+}
+export function getRunStatusKind(status) {
+    return isTerminalRunStatus(status) ? "terminal" : "active";
+}
+export const CLEANUP_STATUSES = [
+    "not_started",
+    "pending",
+    "running",
+    "succeeded",
+    "failed_retryable",
+    "failed_terminal",
+    "skipped"
+];
+//# sourceMappingURL=status.js.map

package/dist/_shared/submission.d.ts

@@ -0,0 +1,157 @@
+import { type ProxyAuthShape, type ProxyMethod, type ProxyResponseMode } from "./proxy-protocol.js";
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+/**
+ * Networking + runtime-package snapshot carried alongside the template
+ * so the worker can deep-clone and mutate it per run (e.g. injecting
+ * the proxy hostname into `allowed_hosts` or the `node` runtime into
+ * `packages`) without sharing state across concurrent runs.
+ *
+ * Today this is consumed only by the worker's `templateFromSnapshot`
+ * reconstruction. The shape stays intentionally narrow: only fields
+ * the worker can act on land here; freeform extensions belong in
+ * `metadata`.
+ */
+export interface PlatformTemplateEnvironment {
+    readonly networking?: PlatformTemplateNetworking;
+    readonly packages?: readonly PlatformTemplatePackage[];
+}
+export interface PlatformTemplateNetworking {
+    readonly mode: "limited" | "open";
+    /** Lowercase host names. The worker always appends the proxy host. */
+    readonly allowedHosts?: readonly string[];
+}
+export interface PlatformTemplatePackage {
+    readonly name: string;
+    readonly version?: string;
+}
+export interface PlatformTemplateSubmission {
+    readonly name: string;
+    readonly model: string;
+    readonly templateHash: string;
+    readonly system?: string;
+    readonly messages: readonly string[];
+    readonly metadata?: Record<string, JsonValue>;
+    readonly environment?: PlatformTemplateEnvironment;
+}
+export type PlatformClaudeSessionCleanup = "retain" | "delete";
+export type PlatformSessionCleanup = "retain" | "delete";
+export interface PlatformCleanupPolicy {
+    readonly session?: PlatformSessionCleanup;
+    /** @deprecated use `session` instead. Accepted for one release for back-compat. */
+    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;
+}
+/**
+ * Per-run auth value for a declared proxy endpoint. The `name` must
+ * match a `proxyEndpoints[i].name` in the same submission, and `value`'s
+ * shape must match that endpoint's `authShape.type`. The cross-validation
+ * lives in `parseRunSubmissionRequest`.
+ */
+export interface PlatformProxyEndpointAuth {
+    readonly name: string;
+    readonly value: PlatformProxyAuthValue;
+}
+export type PlatformProxyAuthValue = {
+    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;
+};
+export interface PlatformInlineSecrets {
+    readonly anthropic: PlatformAnthropicSecrets;
+    readonly mcpServers?: readonly PlatformMcpServerSecret[];
+    readonly skills?: readonly PlatformSkillReference[];
+    readonly proxyEndpointAuth?: readonly PlatformProxyEndpointAuth[];
+}
+/**
+ * Per-run named HTTP proxy endpoint. The `authShape` describes how the
+ * upstream expects auth; the actual value is supplied separately via
+ * `secrets.proxyEndpointAuth`. The auth value never enters the
+ * container — the BFF proxy injects it on outbound calls.
+ *
+ * Caps and allow-lists below are intentionally pessimistic by default
+ * so a misconfigured endpoint can't accidentally permit a wide attack
+ * surface; raise per endpoint if needed.
+ */
+export interface PlatformProxyEndpoint {
+    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;
+}
+export interface PlatformRunSubmissionRequest {
+    readonly workspaceId: string;
+    readonly idempotencyKey: string;
+    readonly template: PlatformTemplateSubmission;
+    readonly variables?: Record<string, JsonValue>;
+    readonly cleanup?: PlatformCleanupPolicy;
+    readonly secrets: PlatformInlineSecrets;
+    /**
+     * Declared HTTP endpoints reachable via the antpath managed proxy
+     * during this run. Empty array (or omitted) → no proxy surface is
+     * provisioned; the CLI's `/antpath/index.json` shows `endpoints: []`
+     * and the `/antpath/run-token` mount is omitted.
+     */
+    readonly proxyEndpoints?: readonly PlatformProxyEndpoint[];
+}
+/**
+ * Wire shape posted by the SDK and CLI. `workspaceId` is **omitted by
+ * design** — token-authenticated clients never name the workspace
+ * because it is derived from their API token on the server. The BFF
+ * route resolves the workspace from the token and injects it before
+ * calling `parseRunSubmissionRequest`. The dashboard UI (Auth.js user
+ * principal, multi-workspace) is the only caller that supplies
+ * `workspaceId` itself.
+ *
+ * See `references/development-principles.md` (Agent-first surface
+ * design, Concrete rule 3).
+ */
+export type PlatformRunSubmissionInput = Omit<PlatformRunSubmissionRequest, "workspaceId"> & {
+    readonly workspaceId?: string;
+};
+/**
+ * Default caps for a proxy endpoint when the submission doesn't specify
+ * one. Conservative on purpose. Operators can override the platform-
+ * wide ceiling through env vars (see `references/environment-variables.md`).
+ */
+export declare const PROXY_ENDPOINT_DEFAULTS: {
+    readonly allowHeaders: readonly string[];
+    readonly responseMode: ProxyResponseMode;
+    readonly maxRequestBytes: number;
+    readonly maxResponseBytes: number;
+    readonly timeoutMs: 10000;
+    readonly perCallBudget: 60;
+    readonly responseByteBudget: number;
+};
+export declare function parseRunSubmissionRequest(input: unknown): PlatformRunSubmissionRequest;