@aexhq/sdk 0.24.0 → 0.25.0

package/README.md

@@ -2,163 +2,74 @@
 title: aex
 ---
 
-# aex
+# @aexhq/sdk
 
-aex is a TypeScript-first SDK + CLI for running autonomous agent sessions across providers through the managed aex service. Everything an agent or human needs is reachable through **one** import and **one** binary.
+aex is an agent execution platform for launching autonomous agents from a simple TypeScript SDK and CLI.
 
-```ts
-import {
-  AgentExecutor,        // the only client class — submits durable runs to aex
-  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
-  File,                 // arbitrary workspace files mounted into the session
-  validateProxyAuth     // helper that fails fast on policy/auth mismatch
-} from "@aexhq/sdk";
-```
-
-```bash
-aex run     --config ./run.json --api-token ant_… \
-                --anthropic-api-key sk-ant-… --follow
-aex status  <run-id>             --api-token …
-aex wait    <run-id> [--timeout 8m] [--interval 2s] --api-token …
-aex events  <run-id> [--follow] [--timeout 8m]  --api-token …
-aex outputs <run-id>             --api-token …
-aex download <run-id> [--only outputs|events|metadata] [--out path] --api-token …
-aex cancel  <run-id>             --api-token …
-aex delete  <run-id>             --api-token …
-aex whoami                       --api-token …
-aex skills  <upload|list|get|delete> [flags] --api-token …
-aex delete-asset <assetId|hash>  --api-token …
-```
+The package ships:
 
-The SDK class and the CLI are backed by the same public `@aexhq/contracts` operations module — any read or write you can do through one, you can do through the other, against the same durable run records. The same npm package also ships the in-container `aex` CLI as its `bin` entry; managed runs mount that CLI inside the runner so skills can call `aex proxy …` against the per-run manifest. See [product capabilities and boundaries](docs/product-boundaries.md).
+- `AgentExecutor` for submit, run, wait, stream, inspect, download, cancel, and delete.
+- Typed run primitives: `Models`, `Providers`, `RuntimeSizes`, `Skill`, `AgentsMd`, `File`, `McpServer`, `ProxyEndpoint`, and `Secret`.
+- A bundled `aex` CLI with the same run, status, events, outputs, download, cancel, delete, whoami, and skills operations.
 
-The aex URL defaults to `https://api.aex.dev`. Set `--aex-url` on the CLI or `baseUrl` on `AgentExecutor` for local, staging, or hosted aex API planes. This is not a supported self-host deployment claim. The workspace is derived server-side from your API token (1:1 binding), so there is no `--workspace` flag and no `workspaceId` option.
+## Install
 
-## Product boundaries
-
-- Multi-provider via the managed runtime. The published surface is the same
-  regardless of provider:
-  - omit `runtime` or pass `runtime: "managed"`; every provider uses the
-    managed runtime and BYOK provider-proxy.
-  - `provider: "anthropic" | "deepseek" | "openai" | "gemini" | "mistral"`.
-  - See [provider/runtime capabilities](docs/provider-runtime-capabilities.md)
-    for the generated matrix.
-- BYO provider key + MCP credentials + skill references — passed inline on every submission and held in run-scoped custody, with cleanup/revocation attempted at terminal. Cross-provider keys are rejected loudly at submission time.
-- Workspace is the tenant boundary. Workspace identity is derived server-side from the API token (1:1 binding); the SDK / CLI never name it.
-- No SDK-side storage of provider keys, MCP credentials, or output file contents.
-- Cleanup runs by default for tracked runtime resources.
-- Product boundaries are explicit: see [product capabilities and boundaries](docs/product-boundaries.md) for what aex owns, inherits, and does not support.
+```bash
+npm install @aexhq/sdk
+```
 
-## Quickstart (SDK)
+## First Run
 
 ```ts
-import { AgentExecutor, RunModels } from "@aexhq/sdk";
+import { AgentExecutor, Models, Providers } from "@aexhq/sdk";
 
 const aex = new AgentExecutor({
-  apiToken: process.env.AEX_API_TOKEN!,
-  // baseUrl defaults to https://api.aex.dev - set it for local or staging planes.
+  apiToken: process.env.AEX_API_TOKEN!
 });
 
 const runId = await aex.submit({
-  model: RunModels.CLAUDE_HAIKU_4_5,
-  system: "You are a concise automation agent.",
-  prompt: "Write a short answer about agent-first SDK design.",
+  provider: Providers.ANTHROPIC,
+  model: Models.CLAUDE_HAIKU_4_5,
+  prompt: "Write the report and save outputs.",
   secrets: { apiKey: process.env.ANTHROPIC_API_KEY! }
 });
 
-const run = await aex.wait(runId);
-console.log(run.status);
-
-for (const output of await aex.outputs(runId)) {
-  console.log(output.id, output.filename);
-}
-
-const report = await aex.downloadOutput(runId, { path: "report.txt", match: "suffix" });
-console.log(new TextDecoder().decode(report));
-
-await aex.downloadOutputs(runId, { to: "./outputs.zip" });
-```
-
-Reusable, credential-free configs can be ordinary functions:
-
-```ts
-function summarise(topic: string) {
-  return {
-    model: RunModels.CLAUDE_HAIKU_4_5,
-    system: "You are a concise automation agent.",
-    prompt: `Write a short answer about ${topic}.`
-  };
+for await (const event of aex.stream(runId)) {
+  console.log(event.type);
 }
 
-const runId = await aex.submit({
-  ...summarise("agent-first SDK design"),
-  secrets: { apiKey: process.env.ANTHROPIC_API_KEY! }
-});
-```
-
-Stream events live with `aex.stream(runId)`:
+const run = await aex.wait(runId);
+console.log(run.status);
 
-```ts
-for await (const event of aex.stream(runId)) {
-  if (event.type === "TEXT_MESSAGE_CONTENT") {
-    // typed event helpers live under `aex`'s event guard exports.
-  }
-}
+await aex.download(runId, { to: "./run.zip" });
 ```
 
-The same flow from the CLI (two equivalent forms):
+The same request can run from the CLI:
 
 ```bash
 aex run \
   --api-token "$AEX_API_TOKEN" \
   --anthropic-api-key "$ANTHROPIC_API_KEY" \
   --model claude-haiku-4-5 \
-  --system "You are a concise automation agent." \
-  --prompt "Write a short answer about agent-first SDK design." \
-  --follow
-
-aex run \
-  --api-token "$AEX_API_TOKEN" \
-  --anthropic-api-key "$ANTHROPIC_API_KEY" \
-  --config ./run.json \
+  --prompt "Write the report and save outputs." \
   --follow
 ```
 
-`--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.
+## Feature Areas
 
-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.
+- **Agent runtime:** managed autonomous runs with shell, filesystem, editing, notebook, web fetch/search, background command, and post-hook repair tools.
+- **Durable infrastructure:** run records, status, wait/cancel/delete, idempotency, typed events, output capture, downloads, timeouts, and runtime sizes.
+- **Agent composition:** skills, files, AGENTS.md, remote MCP servers, proxy endpoints, environment variables, packages, and networking controls.
+- **Subagents:** typed parent/child lineage for async child runs, output handoff, and bounded agent delegation.
+- **Models and providers:** Anthropic, DeepSeek, OpenAI, Gemini, Mistral, OpenRouter, Doubao, and Doubao China behind one submission shape.
+- **Typed control surface:** strongly typed SDK inputs, CLI parity, BYOK secrets, scoped proxy auth, redaction, and output modes.
 
-## Test commands
-
-```text
-pnpm test                # unit (deterministic; uses fakes/snapshots)
-pnpm test:user:offline   # clean install of packed/published SDK, no live API
-pnpm test:user           # live hosted API user tests
-pnpm test:user:heavy     # explicit heavy live canary
-```
-
-User tests auto-pack the current SDK when no artifact env is set. CI can pin a
-specific artifact with exactly one of `AEX_USER_TEST_TARBALL` or
-`AEX_USER_TEST_VERSION`; live runs also need `AEX_API_URL`,
-`AEX_API_TOKEN`, and `DEEPSEEK_API_KEY`.
-
-## Guides
+## Docs
 
 - [Quickstart](docs/quickstart.md)
-- [Run config](docs/run-config.md)
-- [Run record](docs/run-record.md)
-- [Product capabilities and boundaries](docs/product-boundaries.md)
+- [Run configuration](docs/run-config.md)
+- [Agent tools](docs/concepts/agent-tools.md)
+- [Composition](docs/concepts/composition.md)
+- [Secrets](docs/secrets.md)
+- [Limits](docs/limits.md)
 - [Provider/runtime capabilities](docs/provider-runtime-capabilities.md)
-- [Credentials](docs/credentials.md)
-- [MCP](docs/mcp.md)
-- [Skills](docs/skills.md)
-- [Outputs](docs/outputs.md)
-- [Events](docs/events.md)
-- [Cleanup](docs/cleanup.md)
-- [Testing](docs/testing.md)
-- [Release](docs/release.md)
-

package/dist/_contracts/models.js

@@ -37,8 +37,7 @@ export const MODEL_PROVIDER_IDS = {
     // China Volcengine Ark gateway (`doubao-cn`). Ark accepts the API-format
     // model NAME directly in the chat-completions `model` field (no `ep-…`
     // inference-endpoint id). The native strings are the same Ark catalog ids on
-    // both gateways; BytePlus per-account availability is confirmed at live-verify
-    // (both providers ship `live-unverified` until then — provider-support.ts).
+    // both gateways.
     //   pro   — Doubao Seed 1.8 (flagship, 256K context).
     //   flash — Doubao Seed 1.6 Flash (fast/cheap, 256K context).
     "doubao-seed-pro": { doubao: "doubao-seed-1-8-251228", "doubao-cn": "doubao-seed-1-8-251228" },

package/dist/_contracts/operations.d.ts

@@ -215,8 +215,8 @@ export declare function createSecret(http: HttpClient, args: {
 export declare function listSecrets(http: HttpClient): Promise<readonly SecretRecord[]>;
 /** Metadata for one workspace secret by name. Never returns the value. */
 export declare function getSecret(http: HttpClient, name: string): Promise<SecretRecord>;
-/** Audited value read — the only path that returns a workspace secret value. */
-export declare function revealSecret(http: HttpClient, name: string): Promise<SecretReveal>;
+/** Audited value read — the preferred path that returns a workspace secret value. */
+export declare function getSecretValue(http: HttpClient, name: string): Promise<SecretReveal>;
 /** Replace the value of an existing workspace secret; bumps its version. */
 export declare function rotateSecret(http: HttpClient, args: {
     readonly name: string;

package/dist/_contracts/operations.js

@@ -547,7 +547,7 @@ function unwrapFile(result) {
 // Value-bearing requests (create/rotate) carry the value in the JSON BODY,
 // never the URL/query, so it never lands in logs or the request line. Reads
 // split by sensitivity: `getSecret`/`listSecrets` return METADATA only;
-// `revealSecret` is the audited value read (POST so it's a logged action).
+// `getSecretValue` is the audited value read (POST so it's a logged action).
 // ===========================================================================
 /** Create a named workspace secret. The value travels in the body. */
 export async function createSecret(http, args) {
@@ -569,9 +569,9 @@ export async function getSecret(http, name) {
     const result = await http.request(`/api/secrets/${encodeURIComponent(name)}`);
     return unwrapSecret(result);
 }
-/** Audited value read — the only path that returns a workspace secret value. */
-export async function revealSecret(http, name) {
-    return http.request(`/api/secrets/${encodeURIComponent(name)}/reveal`, {
+/** Audited value read — the preferred path that returns a workspace secret value. */
+export async function getSecretValue(http, name) {
+    return http.request(`/api/secrets/${encodeURIComponent(name)}/get_value`, {
         method: "POST"
     });
 }

package/dist/_contracts/provider-support.d.ts

@@ -1,5 +1,5 @@
 import type { RunProvider, RuntimeKind } from "./submission.js";
-export declare const PROVIDER_SUPPORT_STATUSES: readonly ["supported", "live-unverified", "rejected"];
+export declare const PROVIDER_SUPPORT_STATUSES: readonly ["supported", "rejected"];
 export type ProviderSupportStatus = (typeof PROVIDER_SUPPORT_STATUSES)[number];
 export interface SupportPointer {
     readonly label: string;
@@ -45,8 +45,8 @@ export declare const PROVIDER_PUBLIC_SUPPORT: {
         readonly status: "supported";
         readonly docsAnchor: "anthropic";
         readonly docs: readonly [{
-            readonly label: "Credentials";
-            readonly href: "credentials.md";
+            readonly label: "Secrets";
+            readonly href: "secrets.md";
         }, {
             readonly label: "Events";
             readonly href: "events.md";
@@ -82,8 +82,8 @@ export declare const PROVIDER_PUBLIC_SUPPORT: {
         readonly status: "supported";
         readonly docsAnchor: "deepseek";
         readonly docs: readonly [{
-            readonly label: "Credentials";
-            readonly href: "credentials.md";
+            readonly label: "Secrets";
+            readonly href: "secrets.md";
         }, {
             readonly label: "Events";
             readonly href: "events.md";
@@ -122,11 +122,11 @@ export declare const PROVIDER_PUBLIC_SUPPORT: {
     };
     readonly openai: {
         readonly displayName: "OpenAI";
-        readonly status: "live-unverified";
+        readonly status: "supported";
         readonly docsAnchor: "openai";
         readonly docs: readonly [{
-            readonly label: "Credentials";
-            readonly href: "credentials.md";
+            readonly label: "Secrets";
+            readonly href: "secrets.md";
         }, {
             readonly label: "Events";
             readonly href: "events.md";
@@ -156,11 +156,11 @@ export declare const PROVIDER_PUBLIC_SUPPORT: {
     };
     readonly gemini: {
         readonly displayName: "Gemini";
-        readonly status: "live-unverified";
+        readonly status: "supported";
         readonly docsAnchor: "gemini";
         readonly docs: readonly [{
-            readonly label: "Credentials";
-            readonly href: "credentials.md";
+            readonly label: "Secrets";
+            readonly href: "secrets.md";
         }, {
             readonly label: "Events";
             readonly href: "events.md";
@@ -190,11 +190,11 @@ export declare const PROVIDER_PUBLIC_SUPPORT: {
     };
     readonly mistral: {
         readonly displayName: "Mistral";
-        readonly status: "live-unverified";
+        readonly status: "supported";
         readonly docsAnchor: "mistral";
         readonly docs: readonly [{
-            readonly label: "Credentials";
-            readonly href: "credentials.md";
+            readonly label: "Secrets";
+            readonly href: "secrets.md";
         }, {
             readonly label: "Events";
             readonly href: "events.md";
@@ -224,11 +224,11 @@ export declare const PROVIDER_PUBLIC_SUPPORT: {
     };
     readonly openrouter: {
         readonly displayName: "OpenRouter";
-        readonly status: "live-unverified";
+        readonly status: "supported";
         readonly docsAnchor: "openrouter";
         readonly docs: readonly [{
-            readonly label: "Credentials";
-            readonly href: "credentials.md";
+            readonly label: "Secrets";
+            readonly href: "secrets.md";
         }, {
             readonly label: "Events";
             readonly href: "events.md";
@@ -258,11 +258,11 @@ export declare const PROVIDER_PUBLIC_SUPPORT: {
     };
     readonly doubao: {
         readonly displayName: "Doubao";
-        readonly status: "live-unverified";
+        readonly status: "supported";
         readonly docsAnchor: "doubao";
         readonly docs: readonly [{
-            readonly label: "Credentials";
-            readonly href: "credentials.md";
+            readonly label: "Secrets";
+            readonly href: "secrets.md";
         }, {
             readonly label: "Events";
             readonly href: "events.md";
@@ -292,11 +292,11 @@ export declare const PROVIDER_PUBLIC_SUPPORT: {
     };
     readonly "doubao-cn": {
         readonly displayName: "Doubao (China)";
-        readonly status: "live-unverified";
+        readonly status: "supported";
         readonly docsAnchor: "doubao-cn";
         readonly docs: readonly [{
-            readonly label: "Credentials";
-            readonly href: "credentials.md";
+            readonly label: "Secrets";
+            readonly href: "secrets.md";
         }, {
             readonly label: "Events";
             readonly href: "events.md";

package/dist/_contracts/provider-support.js

@@ -1,10 +1,9 @@
 export const PROVIDER_SUPPORT_STATUSES = [
     "supported",
-    "live-unverified",
     "rejected"
 ];
 const COMMON_DOCS = [
-    { label: "Credentials", href: "credentials.md" },
+    { label: "Secrets", href: "secrets.md" },
     { label: "Events", href: "events.md" }
 ];
 const COMMON_EVIDENCE = [
@@ -72,7 +71,7 @@ export const PROVIDER_PUBLIC_SUPPORT = {
     },
     openai: {
         displayName: "OpenAI",
-        status: "live-unverified",
+        status: "supported",
         docsAnchor: "openai",
         docs: COMMON_DOCS,
         evidence: COMMON_EVIDENCE,
@@ -82,7 +81,7 @@ export const PROVIDER_PUBLIC_SUPPORT = {
     },
     gemini: {
         displayName: "Gemini",
-        status: "live-unverified",
+        status: "supported",
         docsAnchor: "gemini",
         docs: COMMON_DOCS,
         evidence: COMMON_EVIDENCE,
@@ -92,7 +91,7 @@ export const PROVIDER_PUBLIC_SUPPORT = {
     },
     mistral: {
         displayName: "Mistral",
-        status: "live-unverified",
+        status: "supported",
         docsAnchor: "mistral",
         docs: COMMON_DOCS,
         evidence: COMMON_EVIDENCE,
@@ -102,7 +101,7 @@ export const PROVIDER_PUBLIC_SUPPORT = {
     },
     openrouter: {
         displayName: "OpenRouter",
-        status: "live-unverified",
+        status: "supported",
         docsAnchor: "openrouter",
         docs: COMMON_DOCS,
         evidence: COMMON_EVIDENCE,
@@ -111,13 +110,9 @@ export const PROVIDER_PUBLIC_SUPPORT = {
         }
     },
     // Doubao (ByteDance) via the official Ark API — international BytePlus gateway.
-    // Wired + parser/routing-verified but not yet proven against a live BytePlus
-    // account, so `live-unverified`. Promote to `supported` (and swap COMMON_EVIDENCE
-    // for a DOUBAO_MANAGED_EVIDENCE pointer to live-sdk-doubao.test.ts) once the
-    // live run passes.
     doubao: {
         displayName: "Doubao",
-        status: "live-unverified",
+        status: "supported",
         docsAnchor: "doubao",
         docs: COMMON_DOCS,
         evidence: COMMON_EVIDENCE,
@@ -126,11 +121,9 @@ export const PROVIDER_PUBLIC_SUPPORT = {
         }
     },
     // Doubao (ByteDance) via the official Ark API — China Volcengine gateway.
-    // Same wiring as `doubao`; additionally gated on CF Worker egress reaching the
-    // Beijing host (see apps/egress-probe). `live-unverified` until proven live.
     "doubao-cn": {
         displayName: "Doubao (China)",
-        status: "live-unverified",
+        status: "supported",
         docsAnchor: "doubao-cn",
         docs: COMMON_DOCS,
         evidence: COMMON_EVIDENCE,

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

@@ -47,6 +47,12 @@ export declare const SKILL_ID_PATTERN: RegExp;
  * surface so callers fail at the boundary rather than in the BFF.
  */
 export declare const SKILL_NAME_PATTERN: RegExp;
+/**
+ * Provider-safe submitted tool name. Tool names share the same lowercase
+ * kebab/underscore envelope as skills. Submission parsing rejects `__`
+ * because SessionDO reserves that separator for MCP namespace routing.
+ */
+export declare const TOOL_NAME_PATTERN: RegExp;
 /**
  * Hard caps applied at upload time. The SDK enforces these before
  * computing the zip hash so a clearly-too-big bundle never wastes
@@ -87,6 +93,23 @@ export interface AssetRef {
     readonly name: string;
     readonly mountPath?: string;
 }
+type ToolJsonPrimitive = string | number | boolean | null;
+type ToolJsonValue = ToolJsonPrimitive | ToolJsonValue[] | {
+    readonly [key: string]: ToolJsonValue;
+};
+export type ToolInputSchema = {
+    readonly [key: string]: ToolJsonValue;
+};
+/**
+ * User-supplied executable tool bundle. The bytes are addressed by the same
+ * content-addressed asset ref used by Skills/Files, while the provider-visible
+ * manifest rides as value-free metadata on the submission.
+ */
+export interface ToolRef extends AssetRef {
+    readonly description: string;
+    readonly input_schema: ToolInputSchema;
+    readonly entry: string;
+}
 export interface ProviderSkillRef {
     readonly kind: "provider";
     readonly vendor: "anthropic" | "custom";
@@ -330,3 +353,4 @@ export interface NormalisedRunRequestConfig {
     }>;
 }
 export declare function normaliseRunRequestConfig(config: RunRequestConfig): NormalisedRunRequestConfig;
+export {};

package/dist/_contracts/run-config.js

@@ -48,6 +48,12 @@ export const SKILL_ID_PATTERN = /^skl_[A-Za-z0-9_-]{8,128}$/;
  * surface so callers fail at the boundary rather than in the BFF.
  */
 export const SKILL_NAME_PATTERN = /^[a-z0-9][a-z0-9_-]{0,127}$/;
+/**
+ * Provider-safe submitted tool name. Tool names share the same lowercase
+ * kebab/underscore envelope as skills. Submission parsing rejects `__`
+ * because SessionDO reserves that separator for MCP namespace routing.
+ */
+export const TOOL_NAME_PATTERN = SKILL_NAME_PATTERN;
 // ---------------------------------------------------------------------------
 // Skill bundle limits (uploaded bundles)
 // ---------------------------------------------------------------------------

package/dist/_contracts/run-unit.js

@@ -64,6 +64,7 @@ function parseFlatProjection(value) {
         agentsMd: [],
         files: [],
         mcpServers: toMcpServerRefArray(submissionRaw.mcpServers),
+        tools: [],
         ...(parseEnvironment(submissionRaw.environment)
             ? { environment: parseEnvironment(submissionRaw.environment) }
             : {}),
@@ -109,7 +110,8 @@ function fallbackFlat() {
             skills: [],
             agentsMd: [],
             files: [],
-            mcpServers: []
+            mcpServers: [],
+            tools: []
         }
     };
 }

package/dist/_contracts/runtime-types.d.ts

@@ -250,8 +250,8 @@ export interface SecretRecord {
     readonly [key: string]: unknown;
 }
 /**
- * Value-bearing result of an audited `aex.secrets.reveal`. The ONLY wire shape
- * that carries a workspace secret value back to the caller. Reveal is a logged
+ * Value-bearing result of an audited `aex.secrets.get_value`. The ONLY wire shape
+ * that carries a workspace secret value back to the caller. Value read is a logged
  * action (POST, not GET) so a value read is always attributable.
  */
 export interface SecretReveal {

package/dist/_contracts/submission.d.ts

@@ -1,6 +1,6 @@
 import { PROXY_ENDPOINT_DEFAULTS, type ProxyAuthShape, type ProxyMethod, type ProxyRetryPolicy, type ProxyResponseMode } from "./proxy-protocol.js";
 export { PROXY_ENDPOINT_DEFAULTS };
-import type { AgentsMdRef, FileRef, McpServerRef, SkillRef } from "./run-config.js";
+import type { AgentsMdRef, FileRef, McpServerRef, SkillRef, ToolRef } from "./run-config.js";
 import { type RuntimeSize } from "./runtime-sizes.js";
 import { type PlatformPostHook, type PlatformPostHookInput } from "./post-hook.js";
 import { type RunModel } from "./models.js";
@@ -298,6 +298,7 @@ export interface PlatformSubmission {
     readonly system?: string;
     readonly prompt: readonly string[];
     readonly skills: readonly SkillRef[];
+    readonly tools?: readonly ToolRef[];
     readonly agentsMd: readonly AgentsMdRef[];
     readonly files: readonly FileRef[];
     readonly mcpServers: readonly McpServerRef[];

package/dist/_contracts/submission.js

@@ -4,7 +4,7 @@ import { authShapeHeaderName, PROXY_ALLOWED_METHODS, PROXY_ENDPOINT_DEFAULTS, PR
 // existing `@aexhq/contracts` consumers of `PROXY_ENDPOINT_DEFAULTS` are
 // unaffected by the move.
 export { PROXY_ENDPOINT_DEFAULTS };
-import { parseAssetRefFields, parseMcpServerRef, parseSkillRef } from "./run-config.js";
+import { TOOL_NAME_PATTERN, normaliseSkillBundlePath, parseAssetRefFields, parseMcpServerRef, parseSkillRef } from "./run-config.js";
 import { parseRunTimeout, parseRuntimeSize } from "./runtime-sizes.js";
 import { parsePostHook } from "./post-hook.js";
 import { assertRunModelMatchesProvider, parseRunModel } from "./models.js";
@@ -1113,6 +1113,7 @@ export function parseSubmission(input) {
         "system",
         "prompt",
         "skills",
+        "tools",
         "agentsMd",
         "files",
         "mcpServers",
@@ -1134,6 +1135,7 @@ export function parseSubmission(input) {
     const system = optionalString(value.system, "submission.system");
     const prompt = parsePrompt(value.prompt);
     const skills = parseSkills(value.skills);
+    const tools = parseTools(value.tools);
     const agentsMd = parseAgentsMd(value.agentsMd);
     const files = parseFiles(value.files);
     const mcpServers = parseMcpServers(value.mcpServers);
@@ -1150,6 +1152,7 @@ export function parseSubmission(input) {
         ...(system ? { system } : {}),
         prompt,
         skills,
+        tools,
         agentsMd,
         files,
         mcpServers,
@@ -1505,6 +1508,68 @@ function parseSkills(input) {
         return ref;
     });
 }
+function parseTools(input) {
+    if (input === undefined) {
+        return [];
+    }
+    if (!Array.isArray(input)) {
+        throw new Error("submission.tools must be an array of ToolRef objects");
+    }
+    const seenNames = new Set();
+    const seenAssetIds = new Set();
+    return input.map((item, index) => {
+        const path = `submission.tools[${index}]`;
+        const raw = requireRecord(item, path);
+        for (const key of Object.keys(raw)) {
+            if (key !== "kind" &&
+                key !== "assetId" &&
+                key !== "name" &&
+                key !== "description" &&
+                key !== "input_schema" &&
+                key !== "entry") {
+                throw new Error(`${path}.${key} is not an allowed field for ToolRef; permitted: kind, assetId, name, description, input_schema, entry`);
+            }
+        }
+        if (raw.kind !== "asset") {
+            throw new Error(`${path}.kind must be 'asset' (got ${JSON.stringify(raw.kind)})`);
+        }
+        const fields = parseAssetRefFields({ kind: raw.kind, assetId: raw.assetId, name: raw.name }, path);
+        if (!TOOL_NAME_PATTERN.test(fields.name)) {
+            throw new Error(`${path}.name must match ${TOOL_NAME_PATTERN.source}`);
+        }
+        if (fields.name.includes("__")) {
+            throw new Error(`${path}.name must not contain "__"; that separator is reserved for MCP tools`);
+        }
+        if (seenNames.has(fields.name)) {
+            throw new Error(`submission.tools duplicate name: ${fields.name}`);
+        }
+        seenNames.add(fields.name);
+        if (seenAssetIds.has(fields.assetId)) {
+            throw new Error(`submission.tools duplicate assetId: ${fields.assetId}`);
+        }
+        seenAssetIds.add(fields.assetId);
+        const description = requireString(raw.description, `${path}.description`);
+        if (description.trim().length === 0 || description.length > 2048) {
+            throw new Error(`${path}.description must be non-empty and <= 2048 chars`);
+        }
+        const inputSchema = requireRecord(raw.input_schema, `${path}.input_schema`);
+        if (!isJsonValue(inputSchema)) {
+            throw new Error(`${path}.input_schema must be JSON-serializable`);
+        }
+        if (inputSchema.type !== "object") {
+            throw new Error(`${path}.input_schema.type must be "object"`);
+        }
+        const entry = normaliseSkillBundlePath(requireString(raw.entry, `${path}.entry`));
+        return {
+            kind: "asset",
+            assetId: fields.assetId,
+            name: fields.name,
+            description,
+            input_schema: inputSchema,
+            entry
+        };
+    });
+}
 function parseAgentsMd(input) {
     if (input === undefined)
         return [];