antpath 0.10.14 → 0.11.0

package/dist/_shared/submission.d.ts

@@ -5,58 +5,124 @@ 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
+ * Networking + runtime-package snapshot carried inside a flat submission
+ * 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`.
+ * `envVars` is the customer-controlled key/value bag delivered into the
+ * container via the mounted `RUNTIME.env` / `RUNTIME.json` files (the
+ * Anthropic session API does NOT expose a process env-vars knob today
+ * — verified by reading the `/v1/environments` config shape). The same
+ * keys become `__KEY__` substitution targets in agent-facing markdown
+ * inside skill / agentsmd / file bundles. Antpath-set runtime keys use
+ * the reserved `ANTPATH_*` prefix; customer keys MUST NOT collide with
+ * that prefix.
  */
-export interface PlatformTemplateEnvironment {
-    readonly networking?: PlatformTemplateNetworking;
-    readonly packages?: readonly PlatformTemplatePackage[];
+export interface PlatformEnvironment {
+    readonly networking?: PlatformNetworking;
+    readonly packages?: readonly PlatformPackage[];
+    readonly envVars?: Readonly<Record<string, string>>;
 }
-export interface PlatformTemplateNetworking {
+/**
+ * Reserved prefix for antpath-set runtime env vars (`ANTPATH_OUTPUTS`,
+ * `ANTPATH_CLI`, …). Customer `environment.envVars` keys carrying this
+ * prefix are rejected at submission parse time so platform-set values
+ * cannot be silently overwritten.
+ */
+export declare const ANTPATH_RESERVED_ENV_PREFIX = "ANTPATH_";
+/**
+ * Maximum number of `environment.envVars` entries accepted per
+ * submission. Picked to be generous for real customer config bags
+ * (the broll case ships a handful — `BROLL_STORE`, `BROLL_OUTPUTS`,
+ * `BROLL_MODE`, …) while still bounding the size of every RUNTIME
+ * file we mount into the container.
+ */
+export declare const ENV_VARS_MAX_ENTRIES = 64;
+/** Maximum byte length of a single `environment.envVars` value. */
+export declare const ENV_VARS_MAX_VALUE_BYTES = 4096;
+/** Maximum total byte length of all `environment.envVars` keys+values combined. */
+export declare const ENV_VARS_MAX_TOTAL_BYTES = 65536;
+export interface PlatformNetworking {
     readonly mode: "limited" | "open";
     /** Lowercase host names. The worker always appends the proxy host. */
     readonly allowedHosts?: readonly string[];
 }
-export interface PlatformTemplatePackage {
+export interface PlatformPackage {
     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 PlatformDeepseekSecrets {
+    readonly apiKey: string;
+    readonly baseUrl?: string;
+}
+export interface PlatformOpenAISecrets {
+    readonly apiKey: string;
+    readonly baseUrl?: string;
+}
+export interface PlatformGeminiSecrets {
+    readonly apiKey: string;
+    readonly baseUrl?: string;
+}
+export interface PlatformMistralSecrets {
+    readonly apiKey: string;
+    readonly baseUrl?: string;
+}
+/**
+ * Run-time provider selector. Antpath exposes one customer interface
+ * for every provider; the runtime that backs each provider is decided
+ * by {@link selectRuntime}.
+ *
+ *   - `anthropic` — defaults to the Anthropic Native runtime (Anthropic
+ *                   Managed Agents API). Customers can opt into the
+ *                   Goose Managed runtime via `runtime: "managed"`.
+ *   - `deepseek` | `openai` | `gemini` | `mistral` — only the Goose
+ *                   Managed runtime is supported (LiteLLM-gateway'd
+ *                   call into the upstream).
+ *
+ * See `references/platform-rebuild-2026.md`.
+ */
+export declare const RUN_PROVIDERS: readonly ["anthropic", "deepseek", "openai", "gemini", "mistral"];
+export type RunProvider = (typeof RUN_PROVIDERS)[number];
+export declare const DEFAULT_RUN_PROVIDER: RunProvider;
+/**
+ * Customer-facing runtime selector. Optional on the wire — absent means
+ * "let the dispatcher route based on provider" ({@link selectRuntime}).
+ *
+ *   - `native`  — Anthropic Native runtime. Only valid for
+ *                 `provider: "anthropic"`. Routes through Anthropic's
+ *                 Managed Agents API.
+ *   - `managed` — Goose Managed runtime. The only option for
+ *                 non-Anthropic providers; also available as an opt-out
+ *                 for `provider: "anthropic"` when the customer wants
+ *                 cross-provider parity.
+ *
+ * Stored verbatim in `runs.runtime`. See
+ * `references/platform-rebuild-2026.md` (Runtime dispatcher logic).
+ */
+export declare const RUNTIME_KINDS: readonly ["native", "managed"];
+export type RuntimeKind = (typeof RUNTIME_KINDS)[number];
+/**
+ * Providers whose runtime is implemented by Anthropic Native. Every
+ * other provider in {@link RUN_PROVIDERS} routes through Goose Managed.
+ * Kept as a constant so the dispatcher logic and the validation tests
+ * share one source of truth.
+ */
+export declare const NATIVE_RUNTIME_PROVIDERS: readonly ["anthropic"];
+export type NativeRuntimeProvider = (typeof NATIVE_RUNTIME_PROVIDERS)[number];
 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
@@ -81,10 +147,23 @@ export type PlatformProxyAuthValue = {
     readonly type: "query";
     readonly value: string;
 };
+/**
+ * Per-run inline secrets bundle. Exactly one of `anthropic` | `deepseek`
+ * | `openai` | `gemini` | `mistral` is required, matching the run's
+ * `provider`; the cross-provider coupling is enforced in
+ * `parseRunSubmissionRequest` so the wire shape stays simple and
+ * individual provider keys remain optional in the type system.
+ * `mcpServers` and `proxyEndpointAuth` are cross-provider (an MCP
+ * credential is the same secret whether Anthropic or another model is
+ * driving the MCP client).
+ */
 export interface PlatformInlineSecrets {
-    readonly anthropic: PlatformAnthropicSecrets;
+    readonly anthropic?: PlatformAnthropicSecrets;
+    readonly deepseek?: PlatformDeepseekSecrets;
+    readonly openai?: PlatformOpenAISecrets;
+    readonly gemini?: PlatformGeminiSecrets;
+    readonly mistral?: PlatformMistralSecrets;
     readonly mcpServers?: readonly PlatformMcpServerSecret[];
-    readonly skills?: readonly PlatformSkillReference[];
     readonly proxyEndpointAuth?: readonly PlatformProxyEndpointAuth[];
 }
 /**
@@ -111,37 +190,6 @@ export interface PlatformProxyEndpoint {
     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 per-run manifest the CLI reads
-     * (`/mnt/session/uploads/antpath/index.json` in-container) shows
-     * `endpoints: []` and the `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-
@@ -156,7 +204,6 @@ export declare const PROXY_ENDPOINT_DEFAULTS: {
     readonly perCallBudget: 60;
     readonly responseByteBudget: number;
 };
-export declare function parseRunSubmissionRequest(input: unknown): PlatformRunSubmissionRequest;
 /**
  * Wire-level submission posted to /api/runs in the flat surface. The
  * `prompt` is always an array internally so the worker, the audit log,
@@ -168,7 +215,7 @@ export declare function parseRunSubmissionRequest(input: unknown): PlatformRunSu
  * `skill_bundles.id` (validated by the BFF before acceptance and pinned
  * into `run_skill_snapshots`), provider refs pass through unchanged.
  */
-export interface PlatformFlatSubmission {
+export interface PlatformSubmission {
     readonly model: string;
     readonly system?: string;
     readonly prompt: readonly string[];
@@ -176,7 +223,7 @@ export interface PlatformFlatSubmission {
     readonly agentsMd: readonly AgentsMdRef[];
     readonly files: readonly FileRef[];
     readonly mcpServers: readonly McpServerRef[];
-    readonly environment?: PlatformTemplateEnvironment;
+    readonly environment?: PlatformEnvironment;
     readonly metadata?: Record<string, JsonValue>;
     /**
      * Opt-in container paths to capture as `output_objects` at session
@@ -200,22 +247,101 @@ export interface PlatformFlatSubmission {
      */
     readonly outputDirs?: readonly string[];
 }
-export interface PlatformFlatRunSubmissionRequest {
+export interface PlatformRunSubmissionRequest {
     readonly workspaceId: string;
     readonly idempotencyKey: string;
-    readonly submission: PlatformFlatSubmission;
+    /**
+     * Provider selector. Always populated after parsing — absent on the
+     * wire means {@link DEFAULT_RUN_PROVIDER}. The runtime selector
+     * ({@link selectRuntime}) decides which Workflow class the run is
+     * dispatched to. See `references/platform-rebuild-2026.md`.
+     */
+    readonly provider: RunProvider;
+    /**
+     * Customer's explicit runtime choice. `undefined` (the default) lets
+     * {@link selectRuntime} auto-route based on `provider`. When set,
+     * `parseRunSubmissionRequest` already verified that the choice is
+     * compatible with `provider`; the dispatcher still re-validates
+     * feature compatibility before enqueueing.
+     */
+    readonly runtime?: RuntimeKind;
+    readonly submission: PlatformSubmission;
     readonly cleanup?: PlatformCleanupPolicy;
     readonly secrets: PlatformInlineSecrets;
     readonly proxyEndpoints?: readonly PlatformProxyEndpoint[];
 }
 /**
- * Same `workspaceId is optional` rule as the template-path
- * `PlatformRunSubmissionInput`: token-authenticated clients leave it
- * out, the BFF route injects it from the token before invoking the
- * parser. Dashboard UI callers (Auth.js user principal) pass it
- * explicitly.
+ * 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 the parser. The dashboard UI (Auth.js user principal,
+ * multi-workspace) is the only caller that supplies `workspaceId`
+ * itself.
+ *
+ * `provider` is also optional on the wire — absent means
+ * {@link DEFAULT_RUN_PROVIDER} (`anthropic`). The parser fills it in
+ * before the value enters the run snapshot. See
+ * `references/development-principles.md` (Agent-first surface design,
+ * Concrete rule 3) and `references/deepseek-runtime-mcp-plan.md`.
  */
-export type PlatformFlatRunSubmissionInput = Omit<PlatformFlatRunSubmissionRequest, "workspaceId"> & {
+export type PlatformRunSubmissionInput = Omit<PlatformRunSubmissionRequest, "workspaceId" | "provider" | "runtime"> & {
     readonly workspaceId?: string;
+    readonly provider?: RunProvider;
+    /**
+     * Optional runtime opt-out. Set `"managed"` to force the Goose
+     * Managed runtime (rejects features that only work natively).
+     * `"native"` is only valid when `provider === "anthropic"`.
+     * Absent = auto-route. See {@link selectRuntime}.
+     */
+    readonly runtime?: RuntimeKind;
 };
-export declare function parseFlatRunSubmissionRequest(input: unknown): PlatformFlatRunSubmissionRequest;
+export declare function parseRunSubmissionRequest(input: unknown): PlatformRunSubmissionRequest;
+/**
+ * Codes the dispatcher emits when a submission can't be served by the
+ * selected runtime. Surfaced both at parse time (cross-field shape
+ * mismatch) and at dispatch time (feature mismatch). Code values are
+ * stable so dashboard / SDK error rendering can branch on them.
+ */
+export declare const RUNTIME_VALIDATION_CODES: readonly ["runtime_native_unsupported", "feature_runtime_mismatch"];
+export type RuntimeValidationCode = (typeof RUNTIME_VALIDATION_CODES)[number];
+/**
+ * Thrown by `parseRunSubmissionRequest` (wire-shape mismatch) and by
+ * `selectRuntime` (feature mismatch) when the submitted run cannot be
+ * served by the chosen runtime. The `code` field is part of the public
+ * contract — keep it stable when phrasings change.
+ */
+export declare class RuntimeValidationError extends Error {
+    readonly code: RuntimeValidationCode;
+    constructor(code: RuntimeValidationCode, message: string);
+}
+/**
+ * Walk the parsed submission and collect every feature that **only**
+ * works on the Anthropic Native runtime. Today the only such feature
+ * is a provider built-in skill ref (`Skill.provider(...)` — the
+ * Anthropic Skills API is the resolver). Adding a new native-only
+ * feature means extending this function AND the matching error string
+ * in {@link selectRuntime}.
+ *
+ * Exported because Phase 5's runtime dispatcher route handler reuses
+ * it to format the API error body and the dashboard reuses it to point
+ * the user at the offending submission field.
+ */
+export declare function collectNativeOnlyFeatures(req: PlatformRunSubmissionRequest): string[];
+/**
+ * The runtime dispatcher. Pure function with no I/O — call it after
+ * `parseRunSubmissionRequest` to decide which Workflow class consumes
+ * the run.
+ *
+ *   1. If the customer set `runtime` explicitly, validate that choice
+ *      against the submission's provider and feature set. Reject with
+ *      a typed error on mismatch — no silent re-routing.
+ *   2. Otherwise auto-route: `provider: "anthropic"` → `"native"` (the
+ *      cheapest + fastest path for Anthropic runs); everything else →
+ *      `"managed"`.
+ *
+ * Returns the resolved {@link RuntimeKind}; the Workflow dispatcher
+ * (Phase 5) maps that 1:1 to the matching `WorkflowEntrypoint` class.
+ * See `references/platform-rebuild-2026.md` (Runtime dispatcher logic).
+ */
+export declare function selectRuntime(req: PlatformRunSubmissionRequest): RuntimeKind;