@aexhq/sdk 0.33.1 → 0.35.0

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, ToolRef } from "./run-config.js";
+import type { AgentsMdRef, FileRef, McpServerRef, SkillToolRef, ToolRef } from "./run-config.js";
 import { type RuntimeSize } from "./runtime-sizes.js";
 import { type RunModel } from "./models.js";
 import { type RuntimeSecurityProfileName } from "./runtime-security-profile.js";
@@ -274,16 +274,24 @@ export declare function optionalPositiveNumber(input: unknown, field: string): n
  * only the non-secret half; bearer headers travel in
  * `secrets.mcpServers` keyed by `name`.
  *
- * `skills` is a list of `SkillRef`s. Launch workspace skills use
- * content-addressed asset refs; run submission snapshots the bytes into the
- * run-owned prefix before dispatch.
+ * `tools` is the union of builtin tool names, custom `ToolRef` bundles, and
+ * skill-tools (`{ kind:"skill", … }`); parsing splits them into `tools`,
+ * `builtinTools`, and `skillTools`. Skill bundles are content-addressed asset
+ * refs snapshotted into the run-owned prefix before dispatch.
  */
 export interface PlatformSubmission {
     readonly model: RunModel;
     readonly system?: string;
     readonly prompt: readonly string[];
-    readonly skills: readonly SkillRef[];
     readonly tools?: readonly ToolRef[];
+    /**
+     * Skill-tools: skills re-expressed as synthetic no-arg load-tools. Derived
+     * from the `tools` union at parse time (the `{ kind:"skill", … }` members),
+     * like {@link builtinTools}. Each becomes a model-visible tool whose call
+     * returns the skill's `SKILL.md` body; the bundle is eagerly staged to
+     * `/workspace/skills/<name>/`.
+     */
+    readonly skillTools?: readonly SkillToolRef[];
     readonly agentsMd: readonly AgentsMdRef[];
     readonly files: readonly FileRef[];
     readonly mcpServers: readonly McpServerRef[];
@@ -311,9 +319,9 @@ export interface PlatformSubmission {
      *   - omitted / `true` (default): inject the standard builtins.
      *   - `false`: inject NO builtins — useful for a pure-MCP / pure-custom run.
      *
-     * Cherry-pick individual builtins (e.g. opt the notebook in, or pick a narrow
-     * subset alongside `includeBuiltinTools: false`) by listing their names in
-     * `tools` (a bare-string builtin reference, prefer `BuiltinTools.<name>`).
+     * Pick a narrow subset alongside `includeBuiltinTools: false` by listing
+     * builtin names in `tools` (a bare-string builtin reference; prefer
+     * `BuiltinTools.<name>`).
      */
     readonly includeBuiltinTools?: boolean;
     /**
@@ -394,33 +402,31 @@ export interface PlatformRunSubmissionRequest {
      * terminal wait window and self-kill deadline.
      */
     readonly timeoutMs?: number;
-    /**
-     * Lineage parent (agent-session §9). When present the server admits this
-     * run as a CHILD of `parentRunId`: it walks the parent's lineage, enforces
-     * the max-subagent-depth + per-root concurrency caps, and persists
-     * `parent_run_id` + a server-derived `depth`. The client may name a parent
-     * but NEVER the depth — depth is computed server-side from the parent row,
-     * so a forged value cannot bypass the cap.
-     */
-    readonly parentRunId?: string;
     /**
      * Optional per-run callback URL. The platform delivers exactly the terminal
      * `run.finished` event to this URL at the settle-consistent barrier, signed
-     * Standard-Webhooks style. It is a sibling of {@link idempotencyKey} /
-     * {@link parentRunId} — an operational/delivery concern, NOT part of the
-     * hashed submission brief, so the same idempotency key with a different
-     * callback URL never 409s and the field never enters `request_hash`.
+     * Standard-Webhooks style. It is a sibling of {@link idempotencyKey} — an
+     * operational/delivery concern, NOT part of the hashed submission brief, so
+     * the same idempotency key with a different callback URL never 409s and the
+     * field never enters `request_hash`.
      */
     readonly webhook?: RunWebhookSpec;
     /**
      * Optional per-run override of the lineage limits (max concurrent child runs,
-     * max subagent depth). A sibling of {@link parentRunId} — these are dials the
-     * client may *request*; the server resolves them against the per-workspace
-     * ceiling and the hard platform ceiling (clamping happens in the resolver, NOT
-     * this parser). Absent fields fall back to the platform defaults. Only shape +
+     * max subagent depth, per-run spend cap). These are dials the client may
+     * *request*; the server resolves them against the per-workspace ceiling and
+     * the hard platform ceiling (clamping happens in the resolver, NOT this
+     * parser). Absent fields fall back to the platform defaults. Only shape +
      * positivity are validated here.
      */
     readonly limits?: RunLimits;
+    /**
+     * Optional capacity intent for the run's managed machine. `spot: true` opts
+     * the run into interruptible capacity; absent / `spot: false` requests
+     * standard capacity (the default). Intent only — the managed runtime selects
+     * capacity from it.
+     */
+    readonly machine?: RunMachine;
 }
 /** Per-run webhook callback. v1: terminal-only; the URL must be https. */
 export interface RunWebhookSpec {
@@ -436,15 +442,26 @@ export interface RunLimits {
     readonly maxConcurrentChildRuns?: number;
     readonly maxSubagentDepth?: number;
     /**
-     * Per-run spend cap in USD (defense-in-depth). The platform converts it to a
-     * wall-clock budget (priced compute is wall-time; BYOK provider tokens cost the
-     * platform nothing) and kills the run once it would out-spend the cap. A
-     * positive number; omitted ⇒ unbounded per-run (only the run's wall-clock
-     * `timeout` + the per-workspace spend cap apply). Only shape/positivity are
-     * validated here.
+     * Per-run spend cap in USD (defense-in-depth). The platform kills the run once
+     * it would out-spend the cap. A positive number; omitted ⇒ unbounded per-run
+     * (only the run's wall-clock `timeout` + the per-workspace spend cap apply).
+     * Only shape/positivity are validated here.
+     *
+     * The frozen boot session config the managed runtime folds the loop against
+     * names this same USD value `budgetUsd`; {@link sessionBudgetLimits} is the
+     * single source of truth for that wire→boot name mapping.
      */
     readonly maxSpendUsd?: number;
 }
+/**
+ * Per-run machine/capacity intent. v1 exposes only `spot`: opt the run into
+ * interruptible capacity (`spot: true`) vs standard capacity (absent /
+ * `spot: false`, the default). Only the boolean intent is public — capacity
+ * selection is a runtime concern.
+ */
+export interface RunMachine {
+    readonly spot?: boolean;
+}
 /**
  * Wire shape posted by the SDK and CLI. `workspaceId` is **omitted by
  * design** — token-authenticated clients never name the workspace
@@ -492,6 +509,32 @@ export declare function parseRunWebhook(input: unknown): RunWebhookSpec | undefi
  * collapses to `undefined` so it carries no signal onto the request.
  */
 export declare function parseRunLimits(input: unknown): RunLimits | undefined;
+/**
+ * Boot-session budget fragment. The public submit surface names a run's spend
+ * cap `limits.maxSpendUsd`; the frozen boot session config the managed runtime
+ * folds the loop against names the SAME USD value `budgetUsd` — the field the
+ * session planner reads to enforce/terminate a run that would out-spend its cap.
+ * This is the single source of truth for that wire→boot name mapping so the two
+ * layers can never drift.
+ *
+ * Returns a fragment safe to spread into `sessionConfig.limits`: `{ budgetUsd }`
+ * when a cap is set, `{}` when none is (an absent cap stays absent — the run is
+ * unbounded per-run, subject only to the run timeout + the per-workspace cap).
+ * Pure: same input ⇒ same output.
+ */
+export declare function sessionBudgetLimits(limits: RunLimits | undefined): {
+    budgetUsd?: number;
+};
+/**
+ * Parse the optional per-run `machine` capacity intent. Mirrors
+ * {@link parseRunWebhook}: absent ⇒ `undefined`; a non-object or any unknown
+ * subfield is rejected so the strict top-level allow-list extends to the nested
+ * object. `spot` must be a boolean when present. A no-signal object (e.g.
+ * `machine: {}`) collapses to `undefined` so it never lands an empty object on
+ * the request. An explicit `spot` (true or false) is preserved verbatim. Only
+ * shape is validated here — capacity selection is a runtime concern.
+ */
+export declare function parseRunMachine(input: unknown): RunMachine | undefined;
 export declare function parseRunProvider(input: unknown): RunProvider;
 /**
  * Cross-check the supplied secrets bundle against the credential mode. BYOK
@@ -524,12 +567,12 @@ export declare const DEFAULT_OUTPUT_MODE: OutputMode;
  * Order mirrors `HANDS_TOOLS`. A builtin tool reference (a bare string in
  * `submission.tools`) must be a member of this set.
  */
-export declare const BUILTIN_TOOL_NAMES: readonly ["bash", "read_file", "write_file", "edit_file", "grep", "glob", "head", "tail", "todo_write", "subagent", "subagent_result", "web_fetch", "web_search", "notebook_edit", "bash_output", "bash_kill", "code_execution", "wait", "git"];
+export declare const BUILTIN_TOOL_NAMES: readonly ["bash", "read_file", "write_file", "edit_file", "grep", "glob", "head", "tail", "todo_write", "subagent", "subagent_result", "web_fetch", "web_search", "bash_output", "bash_kill", "code_execution", "wait", "git"];
 export type BuiltinToolName = (typeof BUILTIN_TOOL_NAMES)[number];
 /**
  * Typo-safe accessors for the closed builtin tool set: each key maps to the
  * real tool NAME string. Reference a builtin in `submission.tools` via
- * `BuiltinTools.notebook_edit` rather than the bare string so a rename is a
+ * `BuiltinTools.web_search` rather than the bare string so a rename is a
  * compile error, not a runtime 400.
  *
  * Keys are the real tool names; a unit test asserts `Object.values(BuiltinTools)`
@@ -549,7 +592,6 @@ export declare const BuiltinTools: {
     readonly subagent_result: "subagent_result";
     readonly web_fetch: "web_fetch";
     readonly web_search: "web_search";
-    readonly notebook_edit: "notebook_edit";
     readonly bash_output: "bash_output";
     readonly bash_kill: "bash_kill";
     readonly code_execution: "code_execution";
@@ -557,11 +599,8 @@ export declare const BuiltinTools: {
     readonly git: "git";
 };
 /**
- * The default builtin tool set injected when `includeBuiltinTools !== false`:
- * every builtin tool EXCEPT `notebook_edit` (notebook editing stays opt-in —
- * add `BuiltinTools.notebook_edit` to `tools` to enable it). Derived by
- * filtering {@link BUILTIN_TOOL_NAMES} so it can never drift from the closed
- * set.
+ * The default builtin tool set injected when `includeBuiltinTools !== false`.
+ * It is the complete closed builtin set.
  */
 export declare const DEFAULT_BUILTIN_TOOLS: readonly BuiltinToolName[];
 /**
@@ -570,8 +609,8 @@ export declare const DEFAULT_BUILTIN_TOOLS: readonly BuiltinToolName[];
  *
  *   - `includeBuiltinTools !== false` ⇒ start from {@link DEFAULT_BUILTIN_TOOLS}
  *     (the standard set); `false` ⇒ start from none (pure-MCP / pure-custom).
- *   - union in every builtin-name string the caller listed in `tools` (a
- *     cherry-pick, e.g. `BuiltinTools.notebook_edit` to opt the notebook in).
+ *   - union in every builtin-name string the caller listed in `tools` (used to
+ *     cherry-pick a narrow subset when `includeBuiltinTools` is false).
  *
  * Every `toolRefs` string MUST be a member of {@link BUILTIN_TOOL_NAMES}; the
  * union is validated ⊆ the closed set so an invalid name can never leak through.

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 { TOOL_NAME_PATTERN, normaliseSkillBundlePath, parseAssetRefFields, parseMcpServerRef, parseSkillRef } from "./run-config.js";
+import { TOOL_NAME_PATTERN, normaliseSkillBundlePath, parseAssetRefFields, parseMcpServerRef } from "./run-config.js";
 import { parseRunTimeout, parseRuntimeSize } from "./runtime-sizes.js";
 import { assertRunModelMatchesProvider, parseRunModel } from "./models.js";
 import { parseRuntimeSecurityProfile } from "./runtime-security-profile.js";
@@ -658,8 +658,9 @@ export function crossValidateSecretEnvAndValues(secretEnv, envSecrets) {
     }
 }
 export function parseInlineSecrets(input) {
-    // A child run (parentRunId set) inherits its provider keys server-side from
-    // the parent's vault, so it may omit `secrets` entirely.
+    // Absent/null secrets collapse to an empty bundle; the credential-policy gate
+    // (enforceCredentialSecretPolicy) decides whether that is admissible for the
+    // run's mode (a run inheriting keys server-side may legitimately omit them).
     if (input === undefined || input === null)
         return {};
     const value = requireRecord(input, "secrets");
@@ -994,9 +995,9 @@ export function parseRunSubmissionRequest(input, options = {}) {
         "runtimeSize",
         "timeout",
         "proxyEndpoints",
-        "parentRunId",
         "webhook",
         "limits",
+        "machine",
         SECRETS_KEY
     ]);
     for (const key of Object.keys(value)) {
@@ -1020,16 +1021,12 @@ export function parseRunSubmissionRequest(input, options = {}) {
     void options;
     const runtimeSize = parseRuntimeSize(value.runtimeSize);
     const timeoutMs = parseRunTimeout(value.timeout);
-    // Lineage parent only. `depth` is NEVER accepted from the wire — the server
-    // derives it from the parent row (a forged depth must not bypass the cap).
-    const parentRunId = optionalString(value.parentRunId, "submission.parentRunId");
     const webhook = parseRunWebhook(value.webhook);
     const limits = parseRunLimits(value.limits);
+    const machine = parseRunMachine(value.machine);
     const proxyEndpoints = parseProxyEndpoints(value.proxyEndpoints);
     const secrets = parseInlineSecrets(value.secrets);
-    enforceCredentialSecretPolicy(secrets, provider, {
-        inheritsFromParent: parentRunId !== undefined
-    });
+    enforceCredentialSecretPolicy(secrets, provider);
     crossValidateProxyEndpointsAndAuth(proxyEndpoints, secrets.proxyEndpointAuth);
     const submission = parseSubmission(value.submission);
     assertRunModelMatchesProvider(provider, submission.model);
@@ -1060,9 +1057,9 @@ export function parseRunSubmissionRequest(input, options = {}) {
         ...(runtimeSize ? { runtimeSize } : {}),
         ...(timeoutMs !== undefined ? { timeoutMs } : {}),
         ...(proxyEndpoints ? { proxyEndpoints } : {}),
-        ...(parentRunId !== undefined ? { parentRunId } : {}),
         ...(webhook !== undefined ? { webhook } : {}),
         ...(limits !== undefined ? { limits } : {}),
+        ...(machine !== undefined ? { machine } : {}),
         secrets
     };
 }
@@ -1141,6 +1138,53 @@ export function parseRunLimits(input) {
         ...(maxSpendUsd !== undefined ? { maxSpendUsd } : {})
     };
 }
+/**
+ * Boot-session budget fragment. The public submit surface names a run's spend
+ * cap `limits.maxSpendUsd`; the frozen boot session config the managed runtime
+ * folds the loop against names the SAME USD value `budgetUsd` — the field the
+ * session planner reads to enforce/terminate a run that would out-spend its cap.
+ * This is the single source of truth for that wire→boot name mapping so the two
+ * layers can never drift.
+ *
+ * Returns a fragment safe to spread into `sessionConfig.limits`: `{ budgetUsd }`
+ * when a cap is set, `{}` when none is (an absent cap stays absent — the run is
+ * unbounded per-run, subject only to the run timeout + the per-workspace cap).
+ * Pure: same input ⇒ same output.
+ */
+export function sessionBudgetLimits(limits) {
+    if (limits?.maxSpendUsd === undefined) {
+        return {};
+    }
+    return { budgetUsd: limits.maxSpendUsd };
+}
+/**
+ * Parse the optional per-run `machine` capacity intent. Mirrors
+ * {@link parseRunWebhook}: absent ⇒ `undefined`; a non-object or any unknown
+ * subfield is rejected so the strict top-level allow-list extends to the nested
+ * object. `spot` must be a boolean when present. A no-signal object (e.g.
+ * `machine: {}`) collapses to `undefined` so it never lands an empty object on
+ * the request. An explicit `spot` (true or false) is preserved verbatim. Only
+ * shape is validated here — capacity selection is a runtime concern.
+ */
+export function parseRunMachine(input) {
+    if (input === undefined) {
+        return undefined;
+    }
+    const value = requireRecord(input, "machine");
+    const allowed = new Set(["spot"]);
+    for (const key of Object.keys(value)) {
+        if (!allowed.has(key)) {
+            throw new Error(`machine.${key} is not an allowed field; permitted: ${[...allowed].join(", ")}`);
+        }
+    }
+    if (value.spot !== undefined && typeof value.spot !== "boolean") {
+        throw new Error("machine.spot must be a boolean");
+    }
+    if (value.spot === undefined) {
+        return undefined;
+    }
+    return { spot: value.spot };
+}
 export function parseRunProvider(input) {
     if (input === undefined) {
         return DEFAULT_RUN_PROVIDER;
@@ -1175,7 +1219,6 @@ export function parseSubmission(input) {
         "model",
         "system",
         "prompt",
-        "skills",
         "tools",
         "agentsMd",
         "files",
@@ -1197,8 +1240,7 @@ export function parseSubmission(input) {
     const model = parseRunModel(value.model, "submission.model");
     const system = optionalString(value.system, "submission.system");
     const prompt = parsePrompt(value.prompt);
-    const skills = parseSkills(value.skills);
-    const { tools, builtinTools } = parseTools(value.tools);
+    const { tools, skillTools, builtinTools } = parseTools(value.tools);
     const agentsMd = parseAgentsMd(value.agentsMd);
     const files = parseFiles(value.files);
     const mcpServers = parseMcpServers(value.mcpServers);
@@ -1214,8 +1256,8 @@ export function parseSubmission(input) {
         model,
         ...(system ? { system } : {}),
         prompt,
-        skills,
         tools,
+        ...(skillTools.length > 0 ? { skillTools } : {}),
         agentsMd,
         files,
         mcpServers,
@@ -1313,7 +1355,6 @@ export const BUILTIN_TOOL_NAMES = [
     "subagent_result",
     "web_fetch",
     "web_search",
-    "notebook_edit",
     "bash_output",
     "bash_kill",
     "code_execution",
@@ -1323,7 +1364,7 @@ export const BUILTIN_TOOL_NAMES = [
 /**
  * Typo-safe accessors for the closed builtin tool set: each key maps to the
  * real tool NAME string. Reference a builtin in `submission.tools` via
- * `BuiltinTools.notebook_edit` rather than the bare string so a rename is a
+ * `BuiltinTools.web_search` rather than the bare string so a rename is a
  * compile error, not a runtime 400.
  *
  * Keys are the real tool names; a unit test asserts `Object.values(BuiltinTools)`
@@ -1343,7 +1384,6 @@ export const BuiltinTools = {
     subagent_result: "subagent_result",
     web_fetch: "web_fetch",
     web_search: "web_search",
-    notebook_edit: "notebook_edit",
     bash_output: "bash_output",
     bash_kill: "bash_kill",
     code_execution: "code_execution",
@@ -1351,21 +1391,18 @@ export const BuiltinTools = {
     git: "git"
 };
 /**
- * The default builtin tool set injected when `includeBuiltinTools !== false`:
- * every builtin tool EXCEPT `notebook_edit` (notebook editing stays opt-in —
- * add `BuiltinTools.notebook_edit` to `tools` to enable it). Derived by
- * filtering {@link BUILTIN_TOOL_NAMES} so it can never drift from the closed
- * set.
+ * The default builtin tool set injected when `includeBuiltinTools !== false`.
+ * It is the complete closed builtin set.
  */
-export const DEFAULT_BUILTIN_TOOLS = BUILTIN_TOOL_NAMES.filter((name) => name !== "notebook_edit");
+export const DEFAULT_BUILTIN_TOOLS = BUILTIN_TOOL_NAMES;
 /**
  * Resolve the set of builtin tool NAMES a submission injects, deduplicated and
  * in {@link BUILTIN_TOOL_NAMES} order.
  *
  *   - `includeBuiltinTools !== false` ⇒ start from {@link DEFAULT_BUILTIN_TOOLS}
  *     (the standard set); `false` ⇒ start from none (pure-MCP / pure-custom).
- *   - union in every builtin-name string the caller listed in `tools` (a
- *     cherry-pick, e.g. `BuiltinTools.notebook_edit` to opt the notebook in).
+ *   - union in every builtin-name string the caller listed in `tools` (used to
+ *     cherry-pick a narrow subset when `includeBuiltinTools` is false).
  *
  * Every `toolRefs` string MUST be a member of {@link BUILTIN_TOOL_NAMES}; the
  * union is validated ⊆ the closed set so an invalid name can never leak through.
@@ -1588,33 +1625,21 @@ function parsePrompt(input) {
     }
     return parts;
 }
-function parseSkills(input) {
-    if (input === undefined) {
-        return [];
-    }
-    if (!Array.isArray(input)) {
-        throw new Error("submission.skills must be an array of SkillRef objects");
-    }
-    const seenAssetId = new Set();
-    return input.map((item, index) => {
-        const ref = parseSkillRef(item, `submission.skills[${index}]`);
-        if (seenAssetId.has(ref.assetId)) {
-            throw new Error(`submission.skills duplicate assetId: ${ref.assetId}`);
-        }
-        seenAssetId.add(ref.assetId);
-        return ref;
-    });
-}
 /**
- * Parse the `submission.tools` union: each entry is either a BARE STRING (a
- * builtin tool reference, validated against {@link BUILTIN_TOOL_NAMES}) or a
- * custom tool bundle OBJECT ({@link ToolRef}). Returns the two groups split:
- * `tools` (custom bundles, the existing downstream shape) and `builtinTools`
- * (the deduped builtin-name references, in {@link BUILTIN_TOOL_NAMES} order).
+ * Parse the `submission.tools` union: each entry is one of THREE shapes —
+ *   (a) a BARE STRING: a builtin tool reference (validated against
+ *       {@link BUILTIN_TOOL_NAMES}).
+ *   (b) `{ kind:"asset", … }`: a custom tool bundle ({@link ToolRef}).
+ *   (c) `{ kind:"skill", assetId, name, description }`: a skill re-expressed as
+ *       a synthetic no-arg load-tool ({@link SkillToolRef}).
+ * Returns the three groups split: `tools` (custom bundles), `skillTools`
+ * (skill-tools), and `builtinTools` (the deduped builtin-name references, in
+ * {@link BUILTIN_TOOL_NAMES} order). Tool `name`s and `assetId`s are deduped
+ * across ALL object kinds so a name/asset names at most one tool.
  */
 function parseTools(input) {
     if (input === undefined) {
-        return { tools: [], builtinTools: [] };
+        return { tools: [], skillTools: [], builtinTools: [] };
     }
     if (!Array.isArray(input)) {
         throw new Error("submission.tools must be an array of builtin tool names or ToolRef objects");
@@ -1623,9 +1648,10 @@ function parseTools(input) {
     const seenAssetIds = new Set();
     const seenBuiltins = new Set();
     const tools = [];
+    const skillTools = [];
     input.forEach((item, index) => {
         const path = `submission.tools[${index}]`;
-        // A bare string is a builtin tool reference (e.g. BuiltinTools.notebook_edit).
+        // A bare string is a builtin tool reference (e.g. BuiltinTools.web_search).
         if (typeof item === "string") {
             if (!BUILTIN_TOOL_NAMES.includes(item)) {
                 throw new Error(`${path} (${JSON.stringify(item)}) is not a builtin tool name; ` +
@@ -1635,6 +1661,42 @@ function parseTools(input) {
             return;
         }
         const raw = requireRecord(item, path);
+        // A skill-tool is a synthetic no-arg load-tool: { kind:"skill", assetId,
+        // name, description }. Its call returns the skill's SKILL.md body; it carries
+        // no input_schema / entry (unlike a custom ToolRef).
+        if (raw.kind === "skill") {
+            for (const key of Object.keys(raw)) {
+                if (key !== "kind" && key !== "assetId" && key !== "name" && key !== "description") {
+                    throw new Error(`${path}.${key} is not an allowed field for a skill tool; permitted: kind, assetId, name, description`);
+                }
+            }
+            const skillFields = parseAssetRefFields({ kind: "asset", assetId: raw.assetId, name: raw.name }, path);
+            if (!TOOL_NAME_PATTERN.test(skillFields.name)) {
+                throw new Error(`${path}.name must match ${TOOL_NAME_PATTERN.source}`);
+            }
+            if (skillFields.name.includes("__")) {
+                throw new Error(`${path}.name must not contain "__"; that separator is reserved for MCP tools`);
+            }
+            if (seenNames.has(skillFields.name)) {
+                throw new Error(`submission.tools duplicate name: ${skillFields.name}`);
+            }
+            seenNames.add(skillFields.name);
+            if (seenAssetIds.has(skillFields.assetId)) {
+                throw new Error(`submission.tools duplicate assetId: ${skillFields.assetId}`);
+            }
+            seenAssetIds.add(skillFields.assetId);
+            const skillDescription = requireString(raw.description, `${path}.description`);
+            if (skillDescription.trim().length === 0 || skillDescription.length > 2048) {
+                throw new Error(`${path}.description must be non-empty and <= 2048 chars`);
+            }
+            skillTools.push({
+                kind: "skill",
+                assetId: skillFields.assetId,
+                name: skillFields.name,
+                description: skillDescription
+            });
+            return;
+        }
         for (const key of Object.keys(raw)) {
             if (key !== "kind" &&
                 key !== "assetId" &&
@@ -1646,7 +1708,7 @@ function parseTools(input) {
             }
         }
         if (raw.kind !== "asset") {
-            throw new Error(`${path}.kind must be 'asset' (got ${JSON.stringify(raw.kind)})`);
+            throw new Error(`${path}.kind must be 'asset' or 'skill' (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)) {
@@ -1685,7 +1747,7 @@ function parseTools(input) {
         });
     });
     const builtinTools = BUILTIN_TOOL_NAMES.filter((name) => seenBuiltins.has(name));
-    return { tools, builtinTools };
+    return { tools, skillTools, builtinTools };
 }
 function parseAgentsMd(input) {
     if (input === undefined)

package/dist/agents-md.d.ts

@@ -5,17 +5,17 @@ import type { AgentsMdRef } from "./_contracts/index.js";
  * behaviour).
  *
  *   const rules = await AgentsMd.fromContent("# Be helpful", { name: "rules" });
- *   await client.submit({ agentsMd: [rules], ... });
+ *   await client.run({ agentsMd: [rules], message: "..." });
  *
- * `client.submit` materializes the bytes to the hosted asset store before
- * the run lands. Asset deduplication handles repeated uploads automatically.
+ * `client.run` / `openSession` materializes the bytes to the hosted asset store
+ * before the run lands. Asset deduplication handles repeated uploads automatically.
  */
 export declare class AgentsMd {
     #private;
     constructor(ref: AgentsMdRef | DraftAgentsMdRef, zipBytes?: Uint8Array);
     get ref(): AgentsMdRef | DraftAgentsMdRef;
     get isDraft(): boolean;
-    /** Internal: the asset id resolved on a prior submit, or undefined. */
+    /** Internal: the asset id resolved on a prior use, or undefined. */
     get _cachedAssetId(): string | undefined;
     /** Internal: remember the asset id resolved for this draft's bytes. */
     _rememberAsset(assetId: string): void;
@@ -33,7 +33,7 @@ export declare class AgentsMd {
     }): Promise<AgentsMd>;
     /**
      * Internal: yield the draft's zipped bytes + metadata so
-     * `client.submit` can upload it as an asset.
+     * `client.run` / `openSession` can upload it as an asset.
      */
     _takeDraftBundle(): {
         name: string;

package/dist/agents-md.js

@@ -7,15 +7,15 @@ import { strToU8, zipSync } from "fflate";
  * behaviour).
  *
  *   const rules = await AgentsMd.fromContent("# Be helpful", { name: "rules" });
- *   await client.submit({ agentsMd: [rules], ... });
+ *   await client.run({ agentsMd: [rules], message: "..." });
  *
- * `client.submit` materializes the bytes to the hosted asset store before
- * the run lands. Asset deduplication handles repeated uploads automatically.
+ * `client.run` / `openSession` materializes the bytes to the hosted asset store
+ * before the run lands. Asset deduplication handles repeated uploads automatically.
  */
 export class AgentsMd {
     #ref;
     #zipBytes;
-    /** Asset id cached after the first submit, so reuse skips a re-upload. */
+    /** Asset id cached after the first use, so reuse skips a re-upload. */
     #assetId;
     constructor(ref, zipBytes) {
         this.#ref = ref;
@@ -27,7 +27,7 @@ export class AgentsMd {
     get isDraft() {
         return this.#ref.kind === "draft";
     }
-    /** Internal: the asset id resolved on a prior submit, or undefined. */
+    /** Internal: the asset id resolved on a prior use, or undefined. */
     get _cachedAssetId() {
         return this.#assetId;
     }
@@ -59,7 +59,7 @@ export class AgentsMd {
     }
     /**
      * Internal: yield the draft's zipped bytes + metadata so
-     * `client.submit` can upload it as an asset.
+     * `client.run` / `openSession` can upload it as an asset.
      */
     _takeDraftBundle() {
         if (this.#ref.kind !== "draft" || !this.#zipBytes) {
@@ -74,7 +74,7 @@ export class AgentsMd {
     toJSON() {
         if (this.#ref.kind === "draft") {
             throw new Error("AgentsMd: draft AgentsMd cannot be JSON-serialised — it only becomes a wire " +
-                "ref when client.submit uploads the bytes as an asset.");
+                "ref when aex.run / openSession uploads the bytes as an asset.");
         }
         return this.#ref;
     }

package/dist/agents-md.js.map

@@ -1 +1 @@
-{"version":3,"file":"agents-md.js","sourceRoot":"","sources":["../src/agents-md.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agents-md.js","sourceRoot":"","sources":["../src/agents-md.ts"],"names":[],"mappings":"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"}

package/dist/asset-upload.d.ts

@@ -1,9 +1,9 @@
 /**
- * Asset materialization for the SDK submit path.
+ * Asset materialization for the SDK run / session path.
  *
- * Every inline `Skill` / `AgentsMd` / `File` draft is materialized to the
- * hosted API's content-addressable asset store before the submit round-trip,
- * so the wire submission carries only storage-neutral `kind:"asset"` refs.
+ * Every inline skill-tool / `Tool` / `AgentsMd` / `File` draft is materialized
+ * to the hosted API's content-addressable asset store before the session
+ * starts, so the wire submission carries only storage-neutral refs.
  *
  * Upload is direct-to-storage (no bytes through the hosted API, so bundle size
  * is bounded by the object store rather than by the API's memory /

package/dist/asset-upload.js

@@ -1,9 +1,9 @@
 /**
- * Asset materialization for the SDK submit path.
+ * Asset materialization for the SDK run / session path.
  *
- * Every inline `Skill` / `AgentsMd` / `File` draft is materialized to the
- * hosted API's content-addressable asset store before the submit round-trip,
- * so the wire submission carries only storage-neutral `kind:"asset"` refs.
+ * Every inline skill-tool / `Tool` / `AgentsMd` / `File` draft is materialized
+ * to the hosted API's content-addressable asset store before the session
+ * starts, so the wire submission carries only storage-neutral refs.
  *
  * Upload is direct-to-storage (no bytes through the hosted API, so bundle size
  * is bounded by the object store rather than by the API's memory /