@aexhq/sdk 0.16.0 → 0.17.0

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,113 @@
+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-v4-flash", "deepseek-v4-pro", "deepseek-chat", "deepseek-reasoner", "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];
+/**
+ * Symbol-style accessors for the closed model set. Prefer these over raw
+ * strings so an invalid token is a compile error, not a runtime 400 — e.g.
+ * `Models.CLAUDE_HAIKU_4_5`. The upstream provider is a pure function of the
+ * model ({@link providerForModel}), so picking a model fully determines
+ * routing; callers never pass `provider` separately.
+ */
+export declare const Models: {
+    /** Claude Haiku 4.5 — Anthropic. */
+    readonly CLAUDE_HAIKU_4_5: "claude-haiku-4-5";
+    /** Claude 3.5 Haiku (latest) — Anthropic. */
+    readonly CLAUDE_3_5_HAIKU_LATEST: "claude-3-5-haiku-latest";
+    /** Claude 3.5 Sonnet (latest) — Anthropic. */
+    readonly CLAUDE_3_5_SONNET_LATEST: "claude-3-5-sonnet-latest";
+    /** DeepSeek V4 Flash — DeepSeek (non-thinking, fast). */
+    readonly DEEPSEEK_V4_FLASH: "deepseek-v4-flash";
+    /** DeepSeek V4 Pro — DeepSeek (reasoning-heavy). */
+    readonly DEEPSEEK_V4_PRO: "deepseek-v4-pro";
+    /**
+     * @deprecated Legacy alias DeepSeek routes to `deepseek-v4-flash` (non-thinking).
+     * DeepSeek removes this name on 2026-07-24 15:59 UTC — migrate to
+     * {@link Models.DEEPSEEK_V4_FLASH}.
+     */
+    readonly DEEPSEEK_CHAT: "deepseek-chat";
+    /**
+     * @deprecated Legacy alias DeepSeek routes to `deepseek-v4-flash` (thinking).
+     * DeepSeek removes this name on 2026-07-24 15:59 UTC — migrate to
+     * {@link Models.DEEPSEEK_V4_FLASH} (or {@link Models.DEEPSEEK_V4_PRO} for
+     * heavier reasoning).
+     */
+    readonly DEEPSEEK_REASONER: "deepseek-reasoner";
+    /** GPT-4.1 — OpenAI. */
+    readonly GPT_4_1: "gpt-4.1";
+    /** GPT-4o mini — OpenAI. */
+    readonly GPT_4O_MINI: "gpt-4o-mini";
+    /** Gemini 2.0 Flash — Gemini. */
+    readonly GEMINI_2_0_FLASH: "gemini-2.0-flash";
+    /** Gemini 2.5 Flash — Gemini. */
+    readonly GEMINI_2_5_FLASH: "gemini-2.5-flash";
+    /** Mistral Large (latest) — Mistral. */
+    readonly MISTRAL_LARGE_LATEST: "mistral-large-latest";
+    /** Mistral Small (latest) — Mistral. */
+    readonly MISTRAL_SMALL_LATEST: "mistral-small-latest";
+};
+/**
+ * Back-compat alias for {@link Models}. Existing imports of `RunModels`
+ * keep working; new code should prefer `Models`.
+ */
+export declare const RunModels: {
+    /** Claude Haiku 4.5 — Anthropic. */
+    readonly CLAUDE_HAIKU_4_5: "claude-haiku-4-5";
+    /** Claude 3.5 Haiku (latest) — Anthropic. */
+    readonly CLAUDE_3_5_HAIKU_LATEST: "claude-3-5-haiku-latest";
+    /** Claude 3.5 Sonnet (latest) — Anthropic. */
+    readonly CLAUDE_3_5_SONNET_LATEST: "claude-3-5-sonnet-latest";
+    /** DeepSeek V4 Flash — DeepSeek (non-thinking, fast). */
+    readonly DEEPSEEK_V4_FLASH: "deepseek-v4-flash";
+    /** DeepSeek V4 Pro — DeepSeek (reasoning-heavy). */
+    readonly DEEPSEEK_V4_PRO: "deepseek-v4-pro";
+    /**
+     * @deprecated Legacy alias DeepSeek routes to `deepseek-v4-flash` (non-thinking).
+     * DeepSeek removes this name on 2026-07-24 15:59 UTC — migrate to
+     * {@link Models.DEEPSEEK_V4_FLASH}.
+     */
+    readonly DEEPSEEK_CHAT: "deepseek-chat";
+    /**
+     * @deprecated Legacy alias DeepSeek routes to `deepseek-v4-flash` (thinking).
+     * DeepSeek removes this name on 2026-07-24 15:59 UTC — migrate to
+     * {@link Models.DEEPSEEK_V4_FLASH} (or {@link Models.DEEPSEEK_V4_PRO} for
+     * heavier reasoning).
+     */
+    readonly DEEPSEEK_REASONER: "deepseek-reasoner";
+    /** GPT-4.1 — OpenAI. */
+    readonly GPT_4_1: "gpt-4.1";
+    /** GPT-4o mini — OpenAI. */
+    readonly GPT_4O_MINI: "gpt-4o-mini";
+    /** Gemini 2.0 Flash — Gemini. */
+    readonly GEMINI_2_0_FLASH: "gemini-2.0-flash";
+    /** Gemini 2.5 Flash — Gemini. */
+    readonly GEMINI_2_5_FLASH: "gemini-2.5-flash";
+    /** Mistral Large (latest) — Mistral. */
+    readonly MISTRAL_LARGE_LATEST: "mistral-large-latest";
+    /** Mistral Small (latest) — Mistral. */
+    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-v4-flash", "deepseek-v4-pro", "deepseek-chat", "deepseek-reasoner"];
+    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"];
+};
+/**
+ * Resolve the upstream provider for a model id. Returns `undefined` when the
+ * input is not a known {@link RunModel} (so the SDK can fall back to the
+ * default and let the server reject the model). Total over the closed model
+ * set, so any `RunModel` resolves.
+ */
+export declare function providerForModel(model: string): RunProvider | undefined;
+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,127 @@
+/**
+ * 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-v4-flash",
+    "deepseek-v4-pro",
+    "deepseek-chat",
+    "deepseek-reasoner",
+    "gpt-4.1",
+    "gpt-4o-mini",
+    "gemini-2.0-flash",
+    "gemini-2.5-flash",
+    "mistral-large-latest",
+    "mistral-small-latest"
+];
+/**
+ * Symbol-style accessors for the closed model set. Prefer these over raw
+ * strings so an invalid token is a compile error, not a runtime 400 — e.g.
+ * `Models.CLAUDE_HAIKU_4_5`. The upstream provider is a pure function of the
+ * model ({@link providerForModel}), so picking a model fully determines
+ * routing; callers never pass `provider` separately.
+ */
+export const Models = {
+    /** Claude Haiku 4.5 — Anthropic. */
+    CLAUDE_HAIKU_4_5: "claude-haiku-4-5",
+    /** Claude 3.5 Haiku (latest) — Anthropic. */
+    CLAUDE_3_5_HAIKU_LATEST: "claude-3-5-haiku-latest",
+    /** Claude 3.5 Sonnet (latest) — Anthropic. */
+    CLAUDE_3_5_SONNET_LATEST: "claude-3-5-sonnet-latest",
+    /** DeepSeek V4 Flash — DeepSeek (non-thinking, fast). */
+    DEEPSEEK_V4_FLASH: "deepseek-v4-flash",
+    /** DeepSeek V4 Pro — DeepSeek (reasoning-heavy). */
+    DEEPSEEK_V4_PRO: "deepseek-v4-pro",
+    /**
+     * @deprecated Legacy alias DeepSeek routes to `deepseek-v4-flash` (non-thinking).
+     * DeepSeek removes this name on 2026-07-24 15:59 UTC — migrate to
+     * {@link Models.DEEPSEEK_V4_FLASH}.
+     */
+    DEEPSEEK_CHAT: "deepseek-chat",
+    /**
+     * @deprecated Legacy alias DeepSeek routes to `deepseek-v4-flash` (thinking).
+     * DeepSeek removes this name on 2026-07-24 15:59 UTC — migrate to
+     * {@link Models.DEEPSEEK_V4_FLASH} (or {@link Models.DEEPSEEK_V4_PRO} for
+     * heavier reasoning).
+     */
+    DEEPSEEK_REASONER: "deepseek-reasoner",
+    /** GPT-4.1 — OpenAI. */
+    GPT_4_1: "gpt-4.1",
+    /** GPT-4o mini — OpenAI. */
+    GPT_4O_MINI: "gpt-4o-mini",
+    /** Gemini 2.0 Flash — Gemini. */
+    GEMINI_2_0_FLASH: "gemini-2.0-flash",
+    /** Gemini 2.5 Flash — Gemini. */
+    GEMINI_2_5_FLASH: "gemini-2.5-flash",
+    /** Mistral Large (latest) — Mistral. */
+    MISTRAL_LARGE_LATEST: "mistral-large-latest",
+    /** Mistral Small (latest) — Mistral. */
+    MISTRAL_SMALL_LATEST: "mistral-small-latest"
+};
+/**
+ * Back-compat alias for {@link Models}. Existing imports of `RunModels`
+ * keep working; new code should prefer `Models`.
+ */
+export const RunModels = Models;
+export const RUN_MODELS_BY_PROVIDER = {
+    anthropic: [
+        Models.CLAUDE_HAIKU_4_5,
+        Models.CLAUDE_3_5_HAIKU_LATEST,
+        Models.CLAUDE_3_5_SONNET_LATEST
+    ],
+    deepseek: [
+        Models.DEEPSEEK_V4_FLASH,
+        Models.DEEPSEEK_V4_PRO,
+        Models.DEEPSEEK_CHAT,
+        Models.DEEPSEEK_REASONER
+    ],
+    openai: [Models.GPT_4_1, Models.GPT_4O_MINI],
+    gemini: [Models.GEMINI_2_0_FLASH, Models.GEMINI_2_5_FLASH],
+    mistral: [Models.MISTRAL_LARGE_LATEST, Models.MISTRAL_SMALL_LATEST]
+};
+/**
+ * Reverse index: every model id → its single upstream provider. Derived from
+ * {@link RUN_MODELS_BY_PROVIDER} so the two never drift; each model appears
+ * under exactly one provider.
+ */
+const PROVIDER_BY_MODEL = (() => {
+    const map = {};
+    for (const [provider, models] of Object.entries(RUN_MODELS_BY_PROVIDER)) {
+        for (const model of models) {
+            map[model] = provider;
+        }
+    }
+    return map;
+})();
+/**
+ * Resolve the upstream provider for a model id. Returns `undefined` when the
+ * input is not a known {@link RunModel} (so the SDK can fall back to the
+ * default and let the server reject the model). Total over the closed model
+ * set, so any `RunModel` resolves.
+ */
+export function providerForModel(model) {
+    return PROVIDER_BY_MODEL[model];
+}
+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/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;