@aexhq/sdk 0.15.2 → 0.16.1

package/README.md

@@ -9,7 +9,8 @@ aex is a TypeScript-first SDK + CLI for running autonomous agent sessions across
 ```ts
 import {
   AgentExecutor,        // the only client class — submits durable runs to aex
-  Skill,                // workspace / provider / inline skill bundles
+  RunModels,            // closed public model id constants
+  Skill,                // local, URL, and catalog skill bundles normalized to assets
   McpServer,            // MCP server declarations (headers split into secrets server-side)
   ProxyEndpoint,        // per-run managed HTTP proxy endpoint
   AgentsMd,             // AGENTS.md / CLAUDE.md uploads
@@ -55,15 +56,15 @@ The aex URL defaults to `https://api.aex.dev`. Set `--aex-url` on the CLI or `ba
 ## Quickstart (SDK)
 
 ```ts
-import { AgentExecutor } from "@aexhq/sdk";
+import { AgentExecutor, RunModels } from "@aexhq/sdk";
 
 const aex = new AgentExecutor({
-  apiToken: process.env.AEX_API_TOKEN!
+  apiToken: process.env.AEX_API_TOKEN!,
   // baseUrl defaults to https://api.aex.dev - set it for local or staging planes.
 });
 
 const runId = await aex.submitRun({
-  model: "claude-haiku-4-5",
+  model: RunModels.CLAUDE_HAIKU_4_5,
   system: "You are a concise automation agent.",
   prompt: "Write a short answer about agent-first SDK design.",
   secrets: { apiKey: process.env.ANTHROPIC_API_KEY! }
@@ -87,9 +88,9 @@ Reusable, credential-free configs can be ordinary functions:
 ```ts
 function summarise(topic: string) {
   return {
-  model: "claude-haiku-4-5",
-  system: "You are a concise automation agent.",
-  prompt: `Write a short answer about ${topic}.`
+    model: RunModels.CLAUDE_HAIKU_4_5,
+    system: "You are a concise automation agent.",
+    prompt: `Write a short answer about ${topic}.`
   };
 }
 
@@ -127,7 +128,9 @@ aex run \
   --follow
 ```
 
-`--config` accepts a plain run-config JSON file for a single run request: `{ model, system?, prompt, skills?, mcpServers?, environment?, proxyEndpoints?, metadata? }`. There is no saved-definition product or interpolation DSL — build the JSON at the call site.
+`--config` accepts a plain run-config JSON file for a single run request: `{ model, system?, prompt, skills?, mcpServers?, environment?, runtimeSize?, timeout?, postHook?, proxyEndpoints?, metadata? }`. There is no saved-definition product or interpolation DSL — build the JSON at the call site. SDK code should use `RunModels`; config JSON is validated against the same `RUN_MODELS` allowlist.
+
+Runtime controls: omit `builtins` to use the default `["developer"]` toolkit, pass `builtins: []` to disable builtins for a pure-MCP run, use `outputMode: "stream"` for per-token assistant text, prefer `RuntimeSizes` for `runtimeSize`, and use `postHook` to run a verifier command after the agent exits successfully.
 
 ## Test commands
 

package/dist/_contracts/index.d.ts

@@ -1,8 +1,10 @@
 export * from "./proxy-protocol.js";
 export * from "./provider-support.js";
+export * from "./models.js";
 export * from "./status.js";
 export * from "./submission.js";
 export * from "./runtime-sizes.js";
+export * from "./post-hook.js";
 export * from "./runner-event.js";
 export * from "./event-envelope.js";
 export * from "./connection-ticket.js";

package/dist/_contracts/index.js

@@ -1,8 +1,10 @@
 export * from "./proxy-protocol.js";
 export * from "./provider-support.js";
+export * from "./models.js";
 export * from "./status.js";
 export * from "./submission.js";
 export * from "./runtime-sizes.js";
+export * from "./post-hook.js";
 export * from "./runner-event.js";
 export * from "./event-envelope.js";
 export * from "./connection-ticket.js";

package/dist/_contracts/internal.d.ts

@@ -1 +1,3 @@
+export * from "./models.js";
+export * from "./post-hook.js";
 export * from "./submission.js";

package/dist/_contracts/internal.js

@@ -4,5 +4,7 @@
 // of validator code. NOT part of the public `@aexhq/contracts` surface — do
 // NOT add this to the package `index`; consumers reach it via the explicit
 // `@aexhq/contracts/internal` subpath.
+export * from "./models.js";
+export * from "./post-hook.js";
 export * from "./submission.js";
 //# sourceMappingURL=internal.js.map

package/dist/_contracts/managed-key.d.ts

@@ -1,4 +1,5 @@
 import type { RunProvider, RuntimeKind } from "./submission.js";
+import type { RunModel } from "./models.js";
 export declare const CREDENTIAL_MODES: readonly ["byok", "managed"];
 export type CredentialMode = (typeof CREDENTIAL_MODES)[number];
 export declare const DEFAULT_CREDENTIAL_MODE: CredentialMode;
@@ -31,7 +32,7 @@ export interface ManagedKeyPolicyV1 {
     readonly billingRequired: true;
     readonly providers: readonly RunProvider[];
     readonly runtimes: readonly RuntimeKind[];
-    readonly models?: readonly string[];
+    readonly models?: readonly RunModel[];
     readonly features: ManagedKeyFeaturePolicyV1;
 }
 /**
@@ -75,7 +76,7 @@ export interface ManagedCredentialResolutionInput {
     readonly runId: string;
     readonly provider: RunProvider;
     readonly runtime: RuntimeKind;
-    readonly model: string;
+    readonly model: RunModel;
     readonly policy: ManagedKeyPolicyV1;
 }
 export interface ManagedCredentialLease {

package/dist/_contracts/models.d.ts

@@ -0,0 +1,33 @@
+import type { RunProvider } from "./submission.js";
+/**
+ * Closed set of model ids accepted by the public run-submission schema.
+ *
+ * The provider-proxy still sends the model id through to the selected upstream
+ * provider, but callers cannot submit arbitrary strings. Additions belong here
+ * first so SDK types, CLI validation, docs examples, and platform parsing move
+ * together.
+ */
+export declare const RUN_MODELS: readonly ["claude-haiku-4-5", "claude-3-5-haiku-latest", "claude-3-5-sonnet-latest", "deepseek-chat", "gpt-4.1", "gpt-4o-mini", "gemini-2.0-flash", "gemini-2.5-flash", "mistral-large-latest", "mistral-small-latest"];
+export type RunModel = (typeof RUN_MODELS)[number];
+export declare const RunModels: {
+    readonly CLAUDE_HAIKU_4_5: "claude-haiku-4-5";
+    readonly CLAUDE_3_5_HAIKU_LATEST: "claude-3-5-haiku-latest";
+    readonly CLAUDE_3_5_SONNET_LATEST: "claude-3-5-sonnet-latest";
+    readonly DEEPSEEK_CHAT: "deepseek-chat";
+    readonly GPT_4_1: "gpt-4.1";
+    readonly GPT_4O_MINI: "gpt-4o-mini";
+    readonly GEMINI_2_0_FLASH: "gemini-2.0-flash";
+    readonly GEMINI_2_5_FLASH: "gemini-2.5-flash";
+    readonly MISTRAL_LARGE_LATEST: "mistral-large-latest";
+    readonly MISTRAL_SMALL_LATEST: "mistral-small-latest";
+};
+export declare const RUN_MODELS_BY_PROVIDER: {
+    readonly anthropic: readonly ["claude-haiku-4-5", "claude-3-5-haiku-latest", "claude-3-5-sonnet-latest"];
+    readonly deepseek: readonly ["deepseek-chat"];
+    readonly openai: readonly ["gpt-4.1", "gpt-4o-mini"];
+    readonly gemini: readonly ["gemini-2.0-flash", "gemini-2.5-flash"];
+    readonly mistral: readonly ["mistral-large-latest", "mistral-small-latest"];
+};
+export declare function isRunModel(input: unknown): input is RunModel;
+export declare function parseRunModel(input: unknown, field?: string): RunModel;
+export declare function assertRunModelMatchesProvider(provider: RunProvider, model: RunModel, field?: string): void;

package/dist/_contracts/models.js

@@ -0,0 +1,59 @@
+/**
+ * Closed set of model ids accepted by the public run-submission schema.
+ *
+ * The provider-proxy still sends the model id through to the selected upstream
+ * provider, but callers cannot submit arbitrary strings. Additions belong here
+ * first so SDK types, CLI validation, docs examples, and platform parsing move
+ * together.
+ */
+export const RUN_MODELS = [
+    "claude-haiku-4-5",
+    "claude-3-5-haiku-latest",
+    "claude-3-5-sonnet-latest",
+    "deepseek-chat",
+    "gpt-4.1",
+    "gpt-4o-mini",
+    "gemini-2.0-flash",
+    "gemini-2.5-flash",
+    "mistral-large-latest",
+    "mistral-small-latest"
+];
+export const RunModels = {
+    CLAUDE_HAIKU_4_5: "claude-haiku-4-5",
+    CLAUDE_3_5_HAIKU_LATEST: "claude-3-5-haiku-latest",
+    CLAUDE_3_5_SONNET_LATEST: "claude-3-5-sonnet-latest",
+    DEEPSEEK_CHAT: "deepseek-chat",
+    GPT_4_1: "gpt-4.1",
+    GPT_4O_MINI: "gpt-4o-mini",
+    GEMINI_2_0_FLASH: "gemini-2.0-flash",
+    GEMINI_2_5_FLASH: "gemini-2.5-flash",
+    MISTRAL_LARGE_LATEST: "mistral-large-latest",
+    MISTRAL_SMALL_LATEST: "mistral-small-latest"
+};
+export const RUN_MODELS_BY_PROVIDER = {
+    anthropic: [
+        RunModels.CLAUDE_HAIKU_4_5,
+        RunModels.CLAUDE_3_5_HAIKU_LATEST,
+        RunModels.CLAUDE_3_5_SONNET_LATEST
+    ],
+    deepseek: [RunModels.DEEPSEEK_CHAT],
+    openai: [RunModels.GPT_4_1, RunModels.GPT_4O_MINI],
+    gemini: [RunModels.GEMINI_2_0_FLASH, RunModels.GEMINI_2_5_FLASH],
+    mistral: [RunModels.MISTRAL_LARGE_LATEST, RunModels.MISTRAL_SMALL_LATEST]
+};
+export function isRunModel(input) {
+    return typeof input === "string" && RUN_MODELS.includes(input);
+}
+export function parseRunModel(input, field = "submission.model") {
+    if (!isRunModel(input)) {
+        throw new Error(`${field} must be one of: ${RUN_MODELS.join(", ")}`);
+    }
+    return input;
+}
+export function assertRunModelMatchesProvider(provider, model, field = "submission.model") {
+    if (!RUN_MODELS_BY_PROVIDER[provider].includes(model)) {
+        throw new Error(`${field} ${JSON.stringify(model)} is not supported for provider ${provider}; ` +
+            `expected one of: ${RUN_MODELS_BY_PROVIDER[provider].join(", ")}`);
+    }
+}
+//# sourceMappingURL=models.js.map

package/dist/_contracts/post-hook.d.ts

@@ -0,0 +1,28 @@
+/** Default post-agent-run hook timeout (5 minutes). */
+export declare const DEFAULT_POST_HOOK_TIMEOUT_MS: number;
+/** Default number of repair turns after a failing hook. */
+export declare const DEFAULT_POST_HOOK_MAX_TURNS = 10;
+/**
+ * Customer-facing post-agent-run verifier shape. The SDK and run-config JSON
+ * send this form on the wire; the server parser normalizes it to
+ * {@link PlatformPostHook}.
+ */
+export interface PlatformPostHookInput {
+    readonly command: string;
+    readonly timeout?: string;
+    readonly maxTurns?: number;
+    readonly maxChars?: number | null;
+}
+/** Parsed post-agent-run verifier carried through dispatch to the runner. */
+export interface PlatformPostHook {
+    readonly command: string;
+    readonly timeoutMs: number;
+    readonly maxTurns: number;
+    readonly maxChars: number | null;
+}
+/**
+ * Parse the public `postHook` option. An omitted hook, null hook, or hook with
+ * an empty/whitespace-only command is treated as omitted so callers can pre-fill
+ * configs without enabling the verifier accidentally.
+ */
+export declare function parsePostHook(input: unknown, path?: string): PlatformPostHook | undefined;

package/dist/_contracts/post-hook.js

@@ -0,0 +1,68 @@
+import { parseDurationToMs } from "./runtime-sizes.js";
+/** Default post-agent-run hook timeout (5 minutes). */
+export const DEFAULT_POST_HOOK_TIMEOUT_MS = 5 * 60 * 1000;
+/** Default number of repair turns after a failing hook. */
+export const DEFAULT_POST_HOOK_MAX_TURNS = 10;
+/**
+ * Parse the public `postHook` option. An omitted hook, null hook, or hook with
+ * an empty/whitespace-only command is treated as omitted so callers can pre-fill
+ * configs without enabling the verifier accidentally.
+ */
+export function parsePostHook(input, path = "postHook") {
+    if (input === undefined || input === null) {
+        return undefined;
+    }
+    const value = requirePostHookRecord(input, path);
+    const allowed = new Set(["command", "timeout", "maxTurns", "maxChars"]);
+    for (const key of Object.keys(value)) {
+        if (!allowed.has(key)) {
+            throw new Error(`${path}.${key} is not an allowed field; permitted: command, timeout, maxTurns, maxChars`);
+        }
+    }
+    if (typeof value.command !== "string") {
+        throw new Error(`${path}.command must be a string`);
+    }
+    if (value.command.trim().length === 0) {
+        return undefined;
+    }
+    const timeoutMs = parsePostHookTimeout(value.timeout, `${path}.timeout`);
+    const maxTurns = parseNonNegativeInteger(value.maxTurns, `${path}.maxTurns`, DEFAULT_POST_HOOK_MAX_TURNS);
+    const maxChars = value.maxChars === null
+        ? null
+        : parseNonNegativeInteger(value.maxChars, `${path}.maxChars`, null);
+    return {
+        command: value.command,
+        timeoutMs,
+        maxTurns,
+        maxChars
+    };
+}
+function parsePostHookTimeout(input, path) {
+    if (input === undefined) {
+        return DEFAULT_POST_HOOK_TIMEOUT_MS;
+    }
+    if (typeof input !== "string") {
+        throw new Error(`${path} must be a duration string (e.g. "5m", "30s"); got ${JSON.stringify(input)}`);
+    }
+    const ms = parseDurationToMs(input);
+    if (ms <= 0) {
+        throw new Error(`${path} must be greater than 0ms; got ${ms}ms`);
+    }
+    return ms;
+}
+function parseNonNegativeInteger(input, path, defaultValue) {
+    if (input === undefined) {
+        return defaultValue;
+    }
+    if (typeof input !== "number" || !Number.isSafeInteger(input) || input < 0) {
+        throw new Error(`${path} must be a non-negative integer`);
+    }
+    return input;
+}
+function requirePostHookRecord(input, path) {
+    if (input === null || typeof input !== "object" || Array.isArray(input)) {
+        throw new Error(`${path} must be an object`);
+    }
+    return input;
+}
+//# sourceMappingURL=post-hook.js.map

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

@@ -39,8 +39,6 @@ export declare const PROXY_RESP_MODE_HEADER = "x-aex-proxy-effective-mode";
  * without buffering). See the streaming byte-cap note in proxy-routes.ts.
  */
 export declare const PROXY_RESP_TRUNCATED_HEADER = "x-aex-proxy-truncated";
-export declare const PROXY_RESP_REMAINING_CALLS_HEADER = "x-aex-proxy-remaining-calls";
-export declare const PROXY_RESP_REMAINING_BYTES_HEADER = "x-aex-proxy-remaining-bytes";
 /** JSON object of lowercase upstream header names → values (mode-filtered). */
 export declare const PROXY_RESP_UPSTREAM_HEADERS_HEADER = "x-aex-proxy-upstream-headers";
 /**
@@ -77,7 +75,7 @@ export declare function narrowResponseMode(policy: ProxyResponseMode, requested:
  * 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 declare const PROXY_ERROR_CODES: readonly ["unsupported_protocol", "unauthorized", "endpoint_not_found", "policy_denied", "rate_limited", "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 the per-run manifest mounted inside
@@ -108,23 +106,26 @@ export interface ProxyIndexEntry {
     readonly maxRequestBytes: number;
     readonly maxResponseBytes: number;
     readonly timeoutMs: number;
-    readonly perCallBudget: number;
-    readonly responseByteBudget: number;
 }
 /**
- * Default caps for a proxy endpoint when the submission doesn't specify
- * one. Conservative on purpose. Lives in the protocol module (next to the
- * index-file shape) so {@link buildProxyIndexFile} can fill every optional
- * cap with a concrete value; the submission parser re-exports it.
+ * Default caps for a proxy endpoint when the submission doesn't specify one.
+ * Lives in the protocol module (next to the index-file shape) so
+ * {@link buildProxyIndexFile} can fill every optional cap with a concrete
+ * value; the submission parser re-exports it.
+ *
+ * `maxResponseBytes: 0` means UNLIMITED — the v2 path streams the upstream body
+ * unbuffered (O(1) memory regardless of size), so there is no cap to apply by
+ * default. A customer can opt into a per-response truncation cap by setting a
+ * positive value. There is no cumulative per-run call/byte budget: it needed a
+ * per-call counter on the hot path and only existed to bound memory, which
+ * streaming already does.
  */
 export declare const PROXY_ENDPOINT_DEFAULTS: {
     readonly allowHeaders: readonly string[];
     readonly responseMode: ProxyResponseMode;
     readonly maxRequestBytes: number;
-    readonly maxResponseBytes: number;
+    readonly maxResponseBytes: 0;
     readonly timeoutMs: 10000;
-    readonly perCallBudget: 60;
-    readonly responseByteBudget: number;
 };
 /**
  * Non-secret endpoint policy the index builder consumes. Structurally a
@@ -142,8 +143,6 @@ export interface ProxyEndpointPolicy {
     readonly maxRequestBytes?: number;
     readonly maxResponseBytes?: number;
     readonly timeoutMs?: number;
-    readonly perCallBudget?: number;
-    readonly responseByteBudget?: number;
 }
 export interface BuildProxyIndexFileInput {
     readonly runId: string;
@@ -176,7 +175,7 @@ export declare function buildProxyIndexFile(input: BuildProxyIndexFileInput): Pr
  *
  * The `none` variant declares an upstream that takes no auth (public
  * APIs like Wikimedia Commons or NASA Images). It still routes through
- * the proxy for unified egress, audit, and budget enforcement, but
+ * the proxy for unified egress and audit, but
  * carries no `proxyEndpointAuth[]` entry and the BFF injects no
  * header or query value.
  */
@@ -261,9 +260,6 @@ export interface ProxyResponseEnvelope {
      */
     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

package/dist/_contracts/proxy-protocol.js

@@ -48,8 +48,6 @@ export const PROXY_RESP_MODE_HEADER = "x-aex-proxy-effective-mode";
  * without buffering). See the streaming byte-cap note in proxy-routes.ts.
  */
 export const PROXY_RESP_TRUNCATED_HEADER = "x-aex-proxy-truncated";
-export const PROXY_RESP_REMAINING_CALLS_HEADER = "x-aex-proxy-remaining-calls";
-export const PROXY_RESP_REMAINING_BYTES_HEADER = "x-aex-proxy-remaining-bytes";
 /** JSON object of lowercase upstream header names → values (mode-filtered). */
 export const PROXY_RESP_UPSTREAM_HEADERS_HEADER = "x-aex-proxy-upstream-headers";
 /**
@@ -103,7 +101,6 @@ export const PROXY_ERROR_CODES = [
     "endpoint_not_found",
     "policy_denied",
     "rate_limited",
-    "budget_exceeded",
     "ssrf_denied",
     "upstream_timeout",
     "upstream_error",
@@ -112,19 +109,26 @@ export const PROXY_ERROR_CODES = [
     "internal_error"
 ];
 /**
- * Default caps for a proxy endpoint when the submission doesn't specify
- * one. Conservative on purpose. Lives in the protocol module (next to the
- * index-file shape) so {@link buildProxyIndexFile} can fill every optional
- * cap with a concrete value; the submission parser re-exports it.
+ * Default caps for a proxy endpoint when the submission doesn't specify one.
+ * Lives in the protocol module (next to the index-file shape) so
+ * {@link buildProxyIndexFile} can fill every optional cap with a concrete
+ * value; the submission parser re-exports it.
+ *
+ * `maxResponseBytes: 0` means UNLIMITED — the v2 path streams the upstream body
+ * unbuffered (O(1) memory regardless of size), so there is no cap to apply by
+ * default. A customer can opt into a per-response truncation cap by setting a
+ * positive value. There is no cumulative per-run call/byte budget: it needed a
+ * per-call counter on the hot path and only existed to bound memory, which
+ * streaming already does.
  */
 export const PROXY_ENDPOINT_DEFAULTS = {
     allowHeaders: [],
     responseMode: "headers_only",
     maxRequestBytes: 64 * 1024,
-    maxResponseBytes: 1024 * 1024,
-    timeoutMs: 10_000,
-    perCallBudget: 60,
-    responseByteBudget: 1024 * 1024
+    // Unlimited (0). The request body is buffered to enforce its cap, so that
+    // stays finite; the response is streamed, so it does not need one.
+    maxResponseBytes: 0,
+    timeoutMs: 10_000
 };
 /**
  * Build the per-run {@link ProxyIndexFile} mounted into the container at
@@ -158,9 +162,7 @@ export function buildProxyIndexFile(input) {
             responseMode: e.responseMode ?? PROXY_ENDPOINT_DEFAULTS.responseMode,
             maxRequestBytes: e.maxRequestBytes ?? PROXY_ENDPOINT_DEFAULTS.maxRequestBytes,
             maxResponseBytes: e.maxResponseBytes ?? PROXY_ENDPOINT_DEFAULTS.maxResponseBytes,
-            timeoutMs: e.timeoutMs ?? PROXY_ENDPOINT_DEFAULTS.timeoutMs,
-            perCallBudget: e.perCallBudget ?? PROXY_ENDPOINT_DEFAULTS.perCallBudget,
-            responseByteBudget: e.responseByteBudget ?? PROXY_ENDPOINT_DEFAULTS.responseByteBudget
+            timeoutMs: e.timeoutMs ?? PROXY_ENDPOINT_DEFAULTS.timeoutMs
         }))
     };
 }
@@ -256,7 +258,6 @@ export const PROXY_ERROR_HTTP_STATUS = {
     endpoint_not_found: 404,
     policy_denied: 403,
     rate_limited: 429,
-    budget_exceeded: 429,
     ssrf_denied: 403,
     upstream_timeout: 504,
     upstream_error: 502,

package/dist/_contracts/run-config.d.ts

@@ -3,17 +3,11 @@
  *
  * Public composition concepts:
  *
- *   - `SkillRef` is the wire-level reference to a skill — either an
- *     `skl_*` id pointing at a workspace-uploaded bundle, a
- *     `{vendor, skillId, version}` reference to a provider built-in, or
- *     a `{slot, name, contentHash}` reference to per-run bytes attached
- *     as a multipart part on the submitRun call (and torn down at run
- *     terminal). The three shapes are discriminated by `kind` so
- *     consumers branch mechanically and providers can never accidentally
- *     be looked up in `skill_bundles`. Transient refs do NOT round-trip
- *     through JSON (bytes can't be serialised back); `parseRunRequestConfig`
- *     therefore rejects them while the BFF multipart submission parser
- *     accepts them.
+ *   - `SkillRef` is the wire-level reference to a skill. Public run
+ *     configs use storage-neutral `kind:"asset"` refs produced by the SDK
+ *     upload path or by workspace catalog records. Provider skill refs remain
+ *     in the parser for wire compatibility, but the managed runtime rejects
+ *     them at submission time.
  *
  *   - `McpServerRef` is the non-secret part of an MCP server declaration:
  *     `name` and `url`. Bearer / cookie / per-request headers travel in
@@ -37,7 +31,9 @@
  * boundary.
  */
 import type { JsonValue, PlatformProxyEndpoint, PlatformEnvironment } from "./submission.js";
+import { type RunModel } from "./models.js";
 import type { RuntimeSize } from "./runtime-sizes.js";
+import { type PlatformPostHookInput } from "./post-hook.js";
 /**
  * Mirrors the server-side CHECK constraint
  * `skill_bundles_id_format_chk = check (id ~ '^skl_[A-Za-z0-9_-]{8,128}$')`
@@ -62,10 +58,9 @@ export declare const SKILL_BUNDLE_LIMITS: {
     /** Compressed (.zip) ceiling. */
     readonly maxCompressedBytes: number;
     /**
-     * Hard ceiling for the direct-to-storage (presigned PUT) upload path, where
-     * bytes never transit the hosted API so its memory/request-payload limits no
-     * longer cap the bundle. Kept well under the object store's 5 GiB single-PUT
-     * limit; objects above this would need S3 multipart, which is out of scope.
+     * Hard ceiling for the direct-to-storage upload path. Bytes never transit the
+     * hosted API, so its memory/request-payload limits do not cap accepted
+     * bundles; objects above this product cap are rejected before upload.
      */
     readonly maxBytes: number;
     /** Sum of uncompressed file sizes. */
@@ -259,7 +254,7 @@ export declare function rejectStdioMcpShape(record: Record<string, unknown>): vo
  * into the normal `submitRun` request.
  */
 export interface RunRequestConfig {
-    readonly model: string;
+    readonly model: RunModel;
     readonly system?: string;
     readonly prompt: string | readonly string[];
     readonly skills?: readonly SkillRef[];
@@ -269,6 +264,8 @@ export interface RunRequestConfig {
     readonly runtimeSize?: RuntimeSize;
     /** Run deadline as a duration string (`"1h"`, `"30m"`); bounded [1m, 6h] server-side. */
     readonly timeout?: string;
+    /** Post-agent-run verifier command. Empty command is treated as omitted. */
+    readonly postHook?: PlatformPostHookInput;
     readonly proxyEndpoints?: readonly PlatformProxyEndpoint[];
     readonly metadata?: Readonly<Record<string, JsonValue>>;
 }
@@ -290,7 +287,7 @@ export declare function parseRunRequestConfig(input: unknown): RunRequestConfig;
  * the audit log don't have to re-handle two shapes.
  */
 export interface NormalisedRunRequestConfig {
-    readonly model: string;
+    readonly model: RunModel;
     readonly system?: string;
     readonly prompt: readonly string[];
     readonly skills: readonly SkillRef[];
@@ -298,6 +295,7 @@ export interface NormalisedRunRequestConfig {
     readonly environment?: PlatformEnvironment;
     readonly proxyEndpoints?: readonly PlatformProxyEndpoint[];
     readonly metadata?: Readonly<Record<string, JsonValue>>;
+    readonly postHook?: PlatformPostHookInput;
     /**
      * MCP servers whose run-config entry carried `headers`. Keyed by the `name`
      * that appears in `mcpServers` so the BFF can pair them up.

package/dist/_contracts/run-config.js

@@ -3,17 +3,11 @@
  *
  * Public composition concepts:
  *
- *   - `SkillRef` is the wire-level reference to a skill — either an
- *     `skl_*` id pointing at a workspace-uploaded bundle, a
- *     `{vendor, skillId, version}` reference to a provider built-in, or
- *     a `{slot, name, contentHash}` reference to per-run bytes attached
- *     as a multipart part on the submitRun call (and torn down at run
- *     terminal). The three shapes are discriminated by `kind` so
- *     consumers branch mechanically and providers can never accidentally
- *     be looked up in `skill_bundles`. Transient refs do NOT round-trip
- *     through JSON (bytes can't be serialised back); `parseRunRequestConfig`
- *     therefore rejects them while the BFF multipart submission parser
- *     accepts them.
+ *   - `SkillRef` is the wire-level reference to a skill. Public run
+ *     configs use storage-neutral `kind:"asset"` refs produced by the SDK
+ *     upload path or by workspace catalog records. Provider skill refs remain
+ *     in the parser for wire compatibility, but the managed runtime rejects
+ *     them at submission time.
  *
  *   - `McpServerRef` is the non-secret part of an MCP server declaration:
  *     `name` and `url`. Bearer / cookie / per-request headers travel in
@@ -36,6 +30,8 @@
  * Keep this as the public source of truth for the SDK/CLI composition
  * boundary.
  */
+import { parseRunModel } from "./models.js";
+import { parsePostHook } from "./post-hook.js";
 // ---------------------------------------------------------------------------
 // Skill ID + name format
 // ---------------------------------------------------------------------------
@@ -66,10 +62,9 @@ export const SKILL_BUNDLE_LIMITS = {
     /** Compressed (.zip) ceiling. */
     maxCompressedBytes: 10 * 1024 * 1024,
     /**
-     * Hard ceiling for the direct-to-storage (presigned PUT) upload path, where
-     * bytes never transit the hosted API so its memory/request-payload limits no
-     * longer cap the bundle. Kept well under the object store's 5 GiB single-PUT
-     * limit; objects above this would need S3 multipart, which is out of scope.
+     * Hard ceiling for the direct-to-storage upload path. Bytes never transit the
+     * hosted API, so its memory/request-payload limits do not cap accepted
+     * bundles; objects above this product cap are rejected before upload.
      */
     maxBytes: 2 * 1024 * 1024 * 1024,
     /** Sum of uncompressed file sizes. */
@@ -609,6 +604,7 @@ export function parseRunRequestConfig(input) {
         "environment",
         "runtimeSize",
         "timeout",
+        "postHook",
         "proxyEndpoints",
         "metadata"
     ]);
@@ -617,10 +613,7 @@ export function parseRunRequestConfig(input) {
             throw new Error(`run request config contains unexpected field: ${key}`);
         }
     }
-    const model = record.model;
-    if (typeof model !== "string" || model.length === 0) {
-        throw new Error("run request config model must be a non-empty string");
-    }
+    const model = parseRunModel(record.model, "run request config model");
     const system = record.system;
     if (system !== undefined && typeof system !== "string") {
         throw new Error("run request config system, when provided, must be a string");
@@ -628,6 +621,7 @@ export function parseRunRequestConfig(input) {
     const prompt = parseRunRequestConfigPrompt(record.prompt);
     const skills = parseRunRequestConfigSkills(record.skills);
     const mcpServers = parseRunRequestConfigMcpServers(record.mcpServers);
+    const postHook = parsePostHook(record.postHook, "run request config postHook");
     return {
         model,
         ...(system !== undefined ? { system } : {}),
@@ -647,6 +641,9 @@ export function parseRunRequestConfig(input) {
         ...(record.timeout !== undefined
             ? { timeout: record.timeout }
             : {}),
+        ...(postHook !== undefined
+            ? { postHook: record.postHook }
+            : {}),
         ...(record.proxyEndpoints !== undefined
             ? { proxyEndpoints: record.proxyEndpoints }
             : {}),
@@ -724,6 +721,7 @@ export function normaliseRunRequestConfig(config) {
         ...(config.environment !== undefined ? { environment: config.environment } : {}),
         ...(config.proxyEndpoints !== undefined ? { proxyEndpoints: config.proxyEndpoints } : {}),
         ...(config.metadata !== undefined ? { metadata: config.metadata } : {}),
+        ...(config.postHook !== undefined ? { postHook: config.postHook } : {}),
         mcpServerSecrets
     };
 }

package/dist/_contracts/run-unit.d.ts

@@ -185,9 +185,9 @@ export interface RunUnit {
  * submission. Never throws on minor unknown keys so we can
  * forward-compat with worker-side enrichment.
  *
- * Returns a typed shape even for malformed snapshots — the worst case
- * is `{kind: "submission", submission: {model: "", ...}}` with empty
- * defaults — because the dashboard must still render *something* for a
- * buggy historical row rather than 500ing the whole detail page.
+ * Returns a typed shape even for malformed snapshots by falling back to the
+ * default public model and empty collection defaults, because the dashboard
+ * must still render *something* for a buggy historical row rather than 500ing
+ * the whole detail page.
  */
 export declare function parseRunUnitSubmission(input: unknown): RunUnitSubmission;