@aexhq/sdk 0.13.6

package/dist/_contracts/sse.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Tiny SSE (text/event-stream) parser used by the SDK / CLI to consume
+ * the dashboard's `/api/runs/:id/events/stream` endpoint without
+ * pulling in a DOM `EventSource` dependency. Node's `fetch` returns a
+ * web `ReadableStream<Uint8Array>` body; this parser turns that into
+ * an async iterable of `SseFrame`s.
+ *
+ * The wire grammar follows the WHATWG HTML spec § Server-sent events:
+ *
+ *   - Lines are separated by `\n`, `\r`, or `\r\n`.
+ *   - A `:` prefix marks a comment — ignored.
+ *   - `field: value` (or `field:value`, with no space) — leading space
+ *     after the colon is stripped.
+ *   - Recognised fields: `event`, `data`, `id`, `retry`.
+ *   - Multiple `data:` lines join with `\n`.
+ *   - A blank line dispatches the current frame and resets the buffer.
+ *   - `event:` defaults to `"message"` when absent.
+ *
+ * The parser is deliberately a free function so it can be unit-tested
+ * against synthesized chunk boundaries (one byte at a time, mid-frame,
+ * across UTF-8 multi-byte sequences) without spinning up a real
+ * connection.
+ */
+export interface SseFrame {
+    readonly id?: string;
+    readonly event: string;
+    readonly data: string;
+    readonly retry?: number;
+}
+/**
+ * Stateful parser: feed in chunks (in any size), pull out completed
+ * frames. Designed for `for await` consumption — see `iterateSse`.
+ */
+export declare class SseParser {
+    #private;
+    /**
+     * Push a chunk of raw bytes through the parser. Returns any frames
+     * that completed during this chunk. Chunks may contain zero, one,
+     * or many frame boundaries — the parser handles partial trailing
+     * data internally.
+     */
+    pushBytes(chunk: Uint8Array): readonly SseFrame[];
+    /**
+     * Push a text chunk directly. Used by the parser tests so they can
+     * exercise byte-boundary edge cases without manufacturing a
+     * `TextDecoder` round-trip.
+     */
+    pushText(text: string): readonly SseFrame[];
+    /**
+     * Indicate end-of-stream. Returns any final frame that the dispatcher
+     * was holding when the stream closed mid-frame (no trailing blank
+     * line). The dispatcher pattern is: blank line dispatches; if the
+     * remote closes after a partial frame, that frame is dropped per the
+     * spec.
+     */
+    flush(): void;
+    /**
+     * Current "last event id" — the cursor the SSE spec instructs the
+     * client to replay on automatic reconnection. Callers use this to
+     * resume after a disconnect.
+     */
+    get lastEventId(): string | undefined;
+}
+/**
+ * Convert a web `ReadableStream<Uint8Array>` (the body of a fetch
+ * Response) into an async iterable of SSE frames. The stream is
+ * consumed exactly once; the caller is responsible for cancelling
+ * the underlying reader on abort.
+ *
+ * The reader is raced against the abort signal so a long-blocked
+ * server (no chunks for many seconds) still releases the loop
+ * promptly when the consumer aborts.
+ */
+export declare function iterateSse(body: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncIterable<SseFrame>;

package/dist/_contracts/stable.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Canonical hosted aex API plane URL. Used as the default `baseUrl`
+ * for the SDK `AexClient` and the host-side CLI `--aex-url`
+ * flag.
+ *
+ * Pinned to `api.aex.dev` on purpose: the dashboard at
+ * `aex.dev` is the human UX surface, while `api.aex.dev`
+ * owns the runtime/API plane (run submission, provider proxy, MCP
+ * proxy, runner callbacks). Both the apex `aex.dev` and `www.` host
+ * may issue redirects, and HTTP clients strip the `Authorization`
+ * header on cross-origin redirects (WHATWG Fetch §5.5) — hitting them
+ * would make authenticated calls land as 401s. Always go direct to
+ * the API plane.
+ *
+ * A single canonical default is not a "footnote mode" — it is the
+ * canonical product. Self-hosted deployments override via the
+ * explicit `baseUrl` / `--aex-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.
+ *
+ * Kept in source with no env-var override so callers and agents can see the
+ * exact default API plane.
+ */
+export declare const AEX_DEFAULT_BASE_URL = "https://api.aex.dev";
+export declare function stableStringify(value: unknown): string;
+export declare function sha256(value: unknown): string;

package/dist/_contracts/stable.js

@@ -0,0 +1,44 @@
+import { createHash } from "node:crypto";
+/**
+ * Canonical hosted aex API plane URL. Used as the default `baseUrl`
+ * for the SDK `AexClient` and the host-side CLI `--aex-url`
+ * flag.
+ *
+ * Pinned to `api.aex.dev` on purpose: the dashboard at
+ * `aex.dev` is the human UX surface, while `api.aex.dev`
+ * owns the runtime/API plane (run submission, provider proxy, MCP
+ * proxy, runner callbacks). Both the apex `aex.dev` and `www.` host
+ * may issue redirects, and HTTP clients strip the `Authorization`
+ * header on cross-origin redirects (WHATWG Fetch §5.5) — hitting them
+ * would make authenticated calls land as 401s. Always go direct to
+ * the API plane.
+ *
+ * A single canonical default is not a "footnote mode" — it is the
+ * canonical product. Self-hosted deployments override via the
+ * explicit `baseUrl` / `--aex-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.
+ *
+ * Kept in source with no env-var override so callers and agents can see the
+ * exact default API plane.
+ */
+export const AEX_DEFAULT_BASE_URL = "https://api.aex.dev";
+export function stableStringify(value) {
+    return JSON.stringify(sortValue(value));
+}
+export function sha256(value) {
+    return createHash("sha256").update(typeof value === "string" ? value : stableStringify(value)).digest("hex");
+}
+function sortValue(value) {
+    if (Array.isArray(value)) {
+        return value.map(sortValue);
+    }
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value)
+            .filter(([, item]) => item !== undefined)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([key, item]) => [key, sortValue(item)]));
+    }
+    return value;
+}
+//# sourceMappingURL=stable.js.map

package/dist/_contracts/status.d.ts

@@ -0,0 +1,19 @@
+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;
+/**
+ * The closed set of terminal OUTCOMES the run-lifecycle funnel writes via
+ * `markRunTerminal` (and that a `run/terminal` event carries). This is a
+ * STRICT SUBSET of {@link TERMINAL_RUN_STATUSES}: the read-terminal set also
+ * includes the post-terminal housekeeping states (`cleanup_failed`,
+ * `pending_delete`, `deleted`) which the funnel never writes as an outcome.
+ * The worker's `TerminalRunStatus` and the workflow `TerminalOutcome` both
+ * derive from this so the four call sites can't drift.
+ */
+export declare const RUN_TERMINAL_OUTCOMES: readonly ["succeeded", "failed", "timed_out", "cancelled"];
+export type RunTerminalOutcome = typeof RUN_TERMINAL_OUTCOMES[number];
+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/_contracts/status.js

@@ -0,0 +1,61 @@
+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);
+}
+/**
+ * The closed set of terminal OUTCOMES the run-lifecycle funnel writes via
+ * `markRunTerminal` (and that a `run/terminal` event carries). This is a
+ * STRICT SUBSET of {@link TERMINAL_RUN_STATUSES}: the read-terminal set also
+ * includes the post-terminal housekeeping states (`cleanup_failed`,
+ * `pending_delete`, `deleted`) which the funnel never writes as an outcome.
+ * The worker's `TerminalRunStatus` and the workflow `TerminalOutcome` both
+ * derive from this so the four call sites can't drift.
+ */
+export const RUN_TERMINAL_OUTCOMES = [
+    "succeeded",
+    "failed",
+    "timed_out",
+    "cancelled"
+];
+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/_contracts/submission.d.ts

@@ -0,0 +1,383 @@
+import { PROXY_ENDPOINT_DEFAULTS, type ProxyAuthShape, type ProxyMethod, type ProxyResponseMode } from "./proxy-protocol.js";
+export { PROXY_ENDPOINT_DEFAULTS };
+import type { AgentsMdRef, FileRef, McpServerRef, SkillRef } from "./run-config.js";
+import { type RuntimeSize } from "./runtime-sizes.js";
+import { type RuntimeSecurityProfileName } from "./runtime-security-profile.js";
+import { type CredentialMode, type ManagedKeyPolicyV1 } from "./managed-key.js";
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+/**
+ * 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`) without sharing state across
+ * concurrent runs.
+ *
+ * `envVars` is the customer-controlled key/value bag delivered into the
+ * managed container process and mirrored in the mounted `RUNTIME.env` /
+ * `RUNTIME.json` files. The same keys become `__KEY__` substitution targets
+ * in agent-facing markdown inside skill / agentsmd / file bundles. Aex-set
+ * runtime keys use the reserved `AEX_*` prefix; customer keys MUST NOT
+ * collide with that prefix.
+ */
+export interface PlatformEnvironment {
+    readonly networking?: PlatformNetworking;
+    readonly packages?: readonly PlatformPackage[];
+    readonly envVars?: Readonly<Record<string, string>>;
+}
+/**
+ * Reserved prefix for aex-set runtime env vars (`AEX_CLI`,
+ * `AEX_RUNTIME_JSON`, …). Customer `environment.envVars` keys carrying this
+ * prefix are rejected at submission parse time so platform-set values
+ * cannot be silently overwritten.
+ */
+export declare const AEX_RESERVED_ENV_PREFIX = "AEX_";
+/**
+ * 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[];
+}
+/**
+ * Package-manager ecosystems accepted by the public submission schema.
+ * The customer encodes the target manager as a `name` prefix
+ * `"<eco>:<pkg>"` (e.g. "pip:pandas", "npm:express", "apt:ffmpeg"); an
+ * UNPREFIXED name defaults to `apt`. After parsing, `PlatformPackage.name`
+ * is the bare package and `PlatformPackage.ecosystem` is the resolved
+ * manager.
+ */
+export declare const PLATFORM_PACKAGE_ECOSYSTEMS: readonly ["apt", "npm", "pip"];
+export type PlatformPackageEcosystem = (typeof PLATFORM_PACKAGE_ECOSYSTEMS)[number];
+export interface PlatformPackage {
+    readonly name: string;
+    readonly version?: string;
+    readonly ecosystem: PlatformPackageEcosystem;
+}
+/**
+ * Render a parsed {@link PlatformPackage} as the version-embedded install
+ * string used by runtime materialization. The join differs per manager:
+ *   - pip  → `name==version`
+ *   - npm  → `name@version`
+ *   - apt  → `name=version`
+ * With no `version`, just the bare `name`. Pure; used by the managed runner
+ * package installer.
+ */
+export declare function packageInstallString(pkg: PlatformPackage): string;
+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. Aex exposes one customer interface
+ * for every provider. All new submissions execute through the managed
+ * runtime; provider selection only decides which upstream model route
+ * the managed provider-proxy uses.
+ */
+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 resolves
+ * to the same managed runtime as `"managed"`. `"native"` is no longer an
+ * accepted submission value and fails schema validation.
+ */
+export declare const RUNTIME_KINDS: readonly ["managed"];
+export type RuntimeKind = (typeof RUNTIME_KINDS)[number];
+/** Outcome of the centralized runtime-support check. */
+export interface RuntimeSupportCheck {
+    readonly ok: boolean;
+    readonly message?: string;
+}
+/**
+ * Centralized runtime-support validator. Native is removed from the public
+ * runtime enum, so an absent runtime and `"managed"` are the only supported
+ * inputs. Schema parsing rejects other runtime strings before this helper is
+ * reached, but the result type remains for SDK preflight checks.
+ */
+export declare function checkRuntimeSupported(provider: RunProvider, runtime: RuntimeKind | undefined): RuntimeSupportCheck;
+export interface PlatformMcpServerSecret {
+    readonly name: string;
+    readonly url: string;
+    readonly headers?: Record<string, 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;
+};
+/**
+ * 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 deepseek?: PlatformDeepseekSecrets;
+    readonly openai?: PlatformOpenAISecrets;
+    readonly gemini?: PlatformGeminiSecrets;
+    readonly mistral?: PlatformMistralSecrets;
+    readonly mcpServers?: readonly PlatformMcpServerSecret[];
+    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;
+}
+/**
+ * The proxy body-redactor refuses to mask any derived target string shorter
+ * than this many bytes — masking a 1-byte literal would corrupt the response
+ * body. This is the floor for the *derived* redaction targets (e.g.
+ * `Bearer <token>`, base64 fragments), used by
+ * the hosted proxy redactor, which imports this constant so the two sides can
+ * never silently diverge.
+ */
+export declare const MIN_REDACTION_TARGET_BYTES = 4;
+/**
+ * Wire-level submission posted to /api/runs in the flat surface. The
+ * `prompt` is always an array internally so the worker, the audit log,
+ * and the BFF idempotency hash all see one shape. `mcpServers` carries
+ * only the non-secret half; bearer headers travel in
+ * `secrets.mcpServers` keyed by `name`.
+ *
+ * `skills` is a list of `SkillRef`s — workspace refs point at
+ * `skill_bundles.id` (validated by the BFF before acceptance and pinned
+ * into `run_skill_snapshots`), provider refs pass through unchanged.
+ */
+export interface PlatformSubmission {
+    readonly model: string;
+    readonly system?: string;
+    readonly prompt: readonly string[];
+    readonly skills: readonly SkillRef[];
+    readonly agentsMd: readonly AgentsMdRef[];
+    readonly files: readonly FileRef[];
+    readonly mcpServers: readonly McpServerRef[];
+    readonly environment?: PlatformEnvironment;
+    readonly securityProfile?: RuntimeSecurityProfileName;
+    readonly metadata?: Record<string, JsonValue>;
+    /**
+     * Output capture policy. Omit `outputs.allowedDirs` to capture the whole
+     * filesystem delta; provide it to narrow capture to the listed roots.
+     * `outputs.deniedDirs` subtracts denied roots/patterns from the allowed set.
+     */
+    readonly outputs?: PlatformOutputCaptureConfig;
+    /**
+     * Optional override for the Goose builtin extensions enabled inside
+     * the runner container. Each entry is the bare name accepted by
+     * `goose run --with-builtin <NAME>` (see Goose v1.34.1's
+     * `crates/goose-cli/src/cli.rs` `with-builtin` flag). The platform
+     * default is `["developer"]` which gives the agent shell + write +
+     * edit + tree tools (bash, grep via shell, file read via shell or
+     * editor, file edit). To opt in to more tools (e.g. web search via
+     * the `computercontroller` extension), pass the full list. To opt
+     * out of all builtins (pure-MCP setup), pass an empty array.
+     *
+     * Validation:
+     *   - Each entry matches /^[a-z][a-z0-9_-]{0,63}$/ (Goose builtin
+     *     naming convention).
+     *   - Max 16 entries.
+     *   - Deduplicated.
+     *
+     * The dispatcher accepts and persists it for snapshot fidelity.
+     */
+    readonly builtins?: readonly string[];
+    /**
+     * Platform-injection controls. The platform prepends a small system
+     * prompt (see `platformSystemPrompt`) ahead of `system` to explain
+     * managed-run expectations such as durable file capture. Set
+     * `systemPrompt: "off"` to suppress that injection and have the runtime
+     * see only the customer's own `system`. Omitting the field (or
+     * `systemPrompt: "default"`) keeps the injection on.
+     *
+     * This does not change output capture scope. Omitted
+     * `outputs.allowedDirs` means capture all created/modified files; explicit
+     * `outputs.allowedDirs` narrows it.
+     */
+    readonly platform?: PlatformInjectionConfig;
+}
+export interface PlatformOutputCaptureConfig {
+    /**
+     * Allowed capture roots. Omit or pass an empty list to use the default
+     * whole-filesystem delta capture. Entries are absolute UNIX paths.
+     */
+    readonly allowedDirs?: readonly string[];
+    /**
+     * Denied capture roots/patterns. These are subtracted from the allowed roots;
+     * platform-mandatory denies always apply and cannot be re-included.
+     */
+    readonly deniedDirs?: readonly string[];
+}
+export interface PlatformInjectionConfig {
+    readonly systemPrompt?: "default" | "off";
+}
+export interface PlatformRunSubmissionRequest {
+    readonly workspaceId: string;
+    readonly idempotencyKey: string;
+    /**
+     * Credential source for upstream provider access. Omitted means
+     * `"byok"` for compatibility with the current production path.
+     * `"managed"` is a public contract value but remains fail-closed until
+     * credential resolution and billing admission are available.
+     */
+    readonly credentialMode: CredentialMode;
+    /**
+     * Provider selector. Always populated after parsing — absent on the
+     * wire means {@link DEFAULT_RUN_PROVIDER}. All providers are dispatched
+     * through the managed runtime.
+     */
+    readonly provider: RunProvider;
+    /**
+     * Customer's explicit runtime choice. `undefined` and `"managed"` both
+     * resolve to the managed runtime. Other runtime values are rejected by
+     * `parseRunSubmissionRequest`.
+     */
+    readonly runtime?: RuntimeKind;
+    readonly submission: PlatformSubmission;
+    readonly secrets: PlatformInlineSecrets;
+    readonly proxyEndpoints?: readonly PlatformProxyEndpoint[];
+    /**
+     * Managed runtime size. One of the closed {@link RuntimeSize} preset tokens
+     * or absent (downstream applies the default).
+     */
+    readonly runtimeSize?: RuntimeSize;
+    /**
+     * Run deadline in milliseconds, normalised by the parser from the wire
+     * `timeout` duration string (bounded to [1m, 6h]). Absent ⇒
+     * {@link DEFAULT_RUN_TIMEOUT_MS} (1h). Applies to the managed runner's
+     * terminal wait window and self-kill deadline.
+     */
+    readonly timeoutMs?: number;
+}
+/**
+ * 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.
+ */
+export type PlatformRunSubmissionInput = Omit<PlatformRunSubmissionRequest, "workspaceId" | "credentialMode" | "provider" | "runtime" | "timeoutMs"> & {
+    readonly workspaceId?: string;
+    readonly credentialMode?: CredentialMode;
+    readonly provider?: RunProvider;
+    /**
+     * Optional runtime selector. Set `"managed"` explicitly or omit the
+     * field; both resolve to the managed runtime. `"native"` is no longer
+     * accepted.
+     */
+    readonly runtime?: RuntimeKind;
+    /**
+     * Run deadline as a human duration string (`"1h"`, `"90m"`, `"30s"`).
+     * Parsed + bounded to [1m, 6h] server-side into
+     * {@link PlatformRunSubmissionRequest.timeoutMs}. Absent ⇒ 1h default.
+     */
+    readonly timeout?: string;
+};
+export interface ParseRunSubmissionOptions {
+    readonly managedKeyPolicy?: ManagedKeyPolicyV1;
+}
+export declare function parseRunSubmissionRequest(input: unknown, options?: ParseRunSubmissionOptions): PlatformRunSubmissionRequest;
+/**
+ * Codes emitted when a submission contains features the active runtime cannot
+ * serve. Code values are stable so dashboard / SDK error rendering can branch
+ * on them.
+ */
+export declare const RUNTIME_VALIDATION_CODES: readonly ["feature_runtime_mismatch"];
+export type RuntimeValidationCode = (typeof RUNTIME_VALIDATION_CODES)[number];
+/**
+ * Thrown by `parseRunSubmissionRequest` and `selectRuntime` when the submitted
+ * run cannot be served by the active managed runtime. The `code` field is part
+ * of the public contract; keep it stable when phrasing changes.
+ */
+export declare class RuntimeValidationError extends Error {
+    readonly code: RuntimeValidationCode;
+    constructor(code: RuntimeValidationCode, message: string);
+}
+/**
+ * Walk the parsed submission and collect features that the active managed
+ * runtime cannot serve. Provider-hosted skill refs (`Skill.provider(...)`) are
+ * rejected now that new submissions only dispatch through managed runs.
+ */
+export declare function collectManagedUnsupportedFeatures(req: PlatformRunSubmissionRequest): string[];
+/**
+ * Backward-incompatible replacement for the old dual-runtime dispatcher. It is
+ * kept as a pure helper so SDK, CLI, and tests can resolve the runtime without
+ * I/O.
+ */
+export declare function selectRuntime(req: PlatformRunSubmissionRequest): RuntimeKind;