@aexhq/sdk 0.18.1 → 0.20.0

package/dist/_contracts/provider-support.js

@@ -109,6 +109,34 @@ export const PROVIDER_PUBLIC_SUPPORT = {
         runtimeEvidence: {
             managed: COMMON_EVIDENCE
         }
+    },
+    // 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",
+        docsAnchor: "doubao",
+        docs: COMMON_DOCS,
+        evidence: COMMON_EVIDENCE,
+        runtimeEvidence: {
+            managed: COMMON_EVIDENCE
+        }
+    },
+    // 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",
+        docsAnchor: "doubao-cn",
+        docs: COMMON_DOCS,
+        evidence: COMMON_EVIDENCE,
+        runtimeEvidence: {
+            managed: COMMON_EVIDENCE
+        }
     }
 };
 export function providerPublicSupport(provider) {

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

@@ -251,7 +251,7 @@ export declare function rejectStdioMcpShape(record: Record<string, unknown>): vo
 /**
  * Plain JSON accepted by `aex run --config <path>`. This is not a
  * platform object; it is only the non-secret run parameters that the CLI folds
- * into the normal `submitRun` request.
+ * into the normal `submit` request.
  */
 export interface RunRequestConfig {
     readonly model: RunModel;

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

@@ -92,6 +92,21 @@ export interface RunCostManagedKeyBudgetTelemetry {
     readonly chargedCreditUnits?: number;
     readonly releasedCreditUnits?: number;
 }
+/**
+ * The basis for a {@link RunCostTelemetry.billedCostUsd}: an honest marker of
+ * whether the figure is a settle-time ESTIMATE or has been RECONCILED against
+ * authoritative actuals. Deliberately carries NO rate-card version or unit
+ * rates — the platform's public-safe convention treats `rateCard`/`margin` as
+ * private tokens (run-cost.test.ts privateCostFieldPattern), so the version the
+ * figure was derived under stays internal (recorded only in the platform's
+ * internal raw-usage export).
+ */
+export declare const RUN_COST_BASIS_STATUSES: readonly ["estimated", "reconciled"];
+export type RunCostBasisStatus = (typeof RUN_COST_BASIS_STATUSES)[number];
+export interface RunCostBasis {
+    readonly currency: "USD";
+    readonly status: RunCostBasisStatus;
+}
 export interface RunCostTelemetry {
     readonly schemaVersion: typeof RUN_COST_TELEMETRY_SCHEMA_VERSION;
     readonly runId?: string;
@@ -108,6 +123,18 @@ export interface RunCostTelemetry {
     readonly storage?: RunCostStorageTelemetry;
     readonly proxy?: RunCostProxyTelemetry;
     readonly managedKey?: RunCostManagedKeyBudgetTelemetry;
+    /**
+     * Customer-facing AEX cost of serving this run, USD — a REPORTED ESTIMATE,
+     * not a charge (telemetry/showback only; no invoicing or credit deduction).
+     * = rawCostUsd × marginMultiplier (margin currently a global 1.0). EXCLUDES
+     * the customer's BYOK provider spend. The raw (pre-margin) figure is kept
+     * internal and never appears on this public-safe shape. A plain number, so it
+     * passes the run-record public-safe archive scan. Absent when the run incurred
+     * no priced AEX usage.
+     */
+    readonly billedCostUsd?: number;
+    /** Currency + estimate/reconciled basis for {@link billedCostUsd}. */
+    readonly costBasis?: RunCostBasis;
 }
 export type RunCostTelemetryInput = Omit<RunCostTelemetry, "schemaVersion">;
 export interface RunCostTelemetryFromUsageSamplesInput {

package/dist/_contracts/run-cost.js

@@ -96,6 +96,16 @@ const RUN_USAGE_SAMPLE_METRIC_UNITS = {
     "managed_key.charged_credit_units": "credit_unit",
     "managed_key.released_credit_units": "credit_unit"
 };
+/**
+ * The basis for a {@link RunCostTelemetry.billedCostUsd}: an honest marker of
+ * whether the figure is a settle-time ESTIMATE or has been RECONCILED against
+ * authoritative actuals. Deliberately carries NO rate-card version or unit
+ * rates — the platform's public-safe convention treats `rateCard`/`margin` as
+ * private tokens (run-cost.test.ts privateCostFieldPattern), so the version the
+ * figure was derived under stays internal (recorded only in the platform's
+ * internal raw-usage export).
+ */
+export const RUN_COST_BASIS_STATUSES = ["estimated", "reconciled"];
 export function buildRunUsageSample(input) {
     const metric = normalizeUsageSampleMetric(input.metric);
     const expectedUnit = RUN_USAGE_SAMPLE_METRIC_UNITS[metric];
@@ -134,7 +144,9 @@ export function buildRunCostTelemetry(input) {
         ...(input.providerUsage ? { providerUsage: input.providerUsage.map(normalizeProviderUsage) } : {}),
         ...(input.storage ? { storage: normalizeStorage(input.storage) } : {}),
         ...(input.proxy ? { proxy: normalizeProxy(input.proxy) } : {}),
-        ...(input.managedKey ? { managedKey: normalizeManagedKey(input.managedKey) } : {})
+        ...(input.managedKey ? { managedKey: normalizeManagedKey(input.managedKey) } : {}),
+        ...(input.billedCostUsd !== undefined ? { billedCostUsd: nonNegativeFinite(input.billedCostUsd, "billedCostUsd") } : {}),
+        ...(input.costBasis ? { costBasis: normalizeCostBasis(input.costBasis) } : {})
     });
 }
 export function buildRunCostTelemetryFromUsageSamples(input) {
@@ -318,6 +330,11 @@ export function mergeRunCostTelemetry(base, next) {
     const storage = sumStorage(base.storage, patch.storage);
     const proxy = sumProxy(base.proxy, patch.proxy);
     const managedKey = mergeManagedKey(base.managedKey, patch.managedKey);
+    // Derived cost fields are LAST-WRITER-WINS (a re-derivation supersedes the
+    // prior estimate), not summed — they are projections of the whole sample set,
+    // not additive metrics.
+    const billedCostUsd = patch.billedCostUsd ?? base.billedCostUsd;
+    const costBasis = patch.costBasis ?? base.costBasis;
     if (runId)
         merged.runId = runId;
     if (provider)
@@ -346,6 +363,10 @@ export function mergeRunCostTelemetry(base, next) {
         merged.proxy = proxy;
     if (managedKey)
         merged.managedKey = managedKey;
+    if (billedCostUsd !== undefined)
+        merged.billedCostUsd = billedCostUsd;
+    if (costBasis)
+        merged.costBasis = costBasis;
     return buildRunCostTelemetry(merged);
 }
 function normalizeDurations(input) {
@@ -470,6 +491,18 @@ function normalizeSummaryStatus(input) {
     }
     return input;
 }
+function normalizeCostBasis(input) {
+    if (!input || typeof input !== "object") {
+        throw new Error("run cost basis must be an object");
+    }
+    if (input.currency !== "USD") {
+        throw new Error(`run cost basis currency ${String(input.currency)} is not supported`);
+    }
+    if (!isStringIn(input.status, RUN_COST_BASIS_STATUSES)) {
+        throw new Error(`run cost basis status ${String(input.status)} is not supported`);
+    }
+    return Object.freeze({ currency: "USD", status: input.status });
+}
 function addProviderUsage(usageByKey, input, sample, field) {
     const provider = sample.provider ?? input.provider;
     if (!provider) {

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

@@ -210,3 +210,35 @@ export interface FileRecord {
     readonly deletedAt?: string | null;
     readonly [key: string]: unknown;
 }
+/**
+ * Wire-level record for a workspace secret as returned by the BFF.
+ *
+ * Workspace secrets share the lifecycle SEMANTIC of skills/files: a
+ * `Secret.value(...)` is per-run and gone at terminal; PROMOTING it (or
+ * `aex.secrets.set`) persists a named, searchable workspace secret. The
+ * identity is the `name` (the handle a `Secret.ref` points at); the value
+ * rotates under that stable name, bumping `version`.
+ *
+ * This record is METADATA ONLY — it never carries the secret value. The value
+ * is write-only on create/rotate and readable solely via the audited
+ * {@link SecretReveal} path.
+ */
+export interface SecretRecord {
+    readonly id: string;
+    readonly name: string;
+    readonly version: number;
+    readonly state: "ready";
+    readonly createdAt?: string;
+    readonly updatedAt?: string;
+    readonly deletedAt?: string | null;
+    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
+ * action (POST, not GET) so a value read is always attributable.
+ */
+export interface SecretReveal {
+    readonly name: string;
+    readonly value: string;
+}

package/dist/_contracts/submission.d.ts

@@ -105,7 +105,7 @@ export declare function packageInstallString(pkg: PlatformPackage): string;
  * runtime; provider selection only decides which upstream model route
  * the managed provider-proxy uses.
  */
-export declare const RUN_PROVIDERS: readonly ["anthropic", "deepseek", "openai", "gemini", "mistral", "openrouter"];
+export declare const RUN_PROVIDERS: readonly ["anthropic", "deepseek", "openai", "gemini", "mistral", "openrouter", "doubao", "doubao-cn"];
 export type RunProvider = (typeof RUN_PROVIDERS)[number];
 export declare const DEFAULT_RUN_PROVIDER: RunProvider;
 /**
@@ -133,6 +133,10 @@ export declare const Providers: {
     readonly MISTRAL: "mistral";
     /** OpenRouter — OpenAI-compatible aggregator routing to many upstream models. */
     readonly OPENROUTER: "openrouter";
+    /** Doubao (ByteDance) via the official international BytePlus ModelArk gateway. */
+    readonly DOUBAO: "doubao";
+    /** Doubao (ByteDance) via the official China Volcengine Ark gateway. */
+    readonly DOUBAO_CN: "doubao-cn";
 };
 /**
  * Customer-facing runtime selector. Optional on the wire; absent resolves
@@ -194,6 +198,15 @@ export interface PlatformInlineSecrets {
     readonly apiKey?: string;
     readonly mcpServers?: readonly PlatformMcpServerSecret[];
     readonly proxyEndpointAuth?: readonly PlatformProxyEndpointAuth[];
+    /**
+     * Per-run env-var secret VALUES, keyed by env name. Each entry pairs with a
+     * `submission.secretEnv[<envName>] = { ephemeral: true }` declaration. Lives
+     * in the secrets channel so it is vaulted and excluded from the idempotency
+     * hash; the runtime injects it as the named env var and it is deleted at the
+     * run's terminal. Workspace `{ ref }` bindings resolve server-side and never
+     * appear here.
+     */
+    readonly envSecrets?: Readonly<Record<string, string>>;
 }
 /**
  * Per-run named HTTP proxy endpoint. The `authShape` describes how the
@@ -219,6 +232,21 @@ export interface PlatformProxyEndpoint {
     readonly retry?: ProxyRetryPolicy;
 }
 export declare const SECRETS_KEY = "secrets";
+/** POSIX-style env var name a `secretEnv` entry binds to (e.g. `SERPER_API_KEY`). */
+export declare const SECRET_ENV_NAME_PATTERN: RegExp;
+/** Workspace secret handle a `secretEnv` ref points at (and the name `secret.upload` persists to). */
+export declare const SECRET_HANDLE_PATTERN: RegExp;
+/**
+ * One `submission.secretEnv` entry — VALUE-FREE, so it rides the (hashed)
+ * submission safely. `{ ref }` resolves a workspace secret server-side;
+ * `{ ephemeral: true }` pairs with a `secrets.envSecrets[<envName>]` value
+ * (per-run, vaulted, deleted at the run's terminal).
+ */
+export type PlatformSecretEnvEntry = {
+    readonly ref: string;
+} | {
+    readonly ephemeral: true;
+};
 export declare const PROXY_ENDPOINT_NAME_PATTERN: RegExp;
 export declare const RESERVED_PROXY_ENDPOINT_NAMES: Set<string>;
 export declare const deniedSecretFields: Set<string>;
@@ -228,6 +256,16 @@ export declare function parseProxyMethods(input: unknown, field: string): readon
 export declare function parseProxyPathPrefixes(input: unknown, field: string): readonly string[];
 export declare function parseProxyAllowedHeaders(input: unknown, field: string, authShape: ProxyAuthShape): readonly string[] | undefined;
 export declare function crossValidateProxyEndpointsAndAuth(endpoints: readonly PlatformProxyEndpoint[] | undefined, auth: readonly PlatformProxyEndpointAuth[] | undefined): void;
+/**
+ * Cross-check `submission.secretEnv` declarations against `secrets.envSecrets`
+ * values. Mirrors {@link crossValidateProxyEndpointsAndAuth}:
+ *
+ *  - `{ ephemeral: true }` MUST have a matching `secrets.envSecrets` value.
+ *  - `{ ref }` MUST NOT supply a value (the value lives in the workspace store).
+ *  - every `secrets.envSecrets` value MUST have a matching `{ ephemeral: true }`
+ *    declaration (no orphan values that would never be injected).
+ */
+export declare function crossValidateSecretEnvAndValues(secretEnv: Readonly<Record<string, PlatformSecretEnvEntry>> | undefined, envSecrets: Readonly<Record<string, string>> | undefined): void;
 export declare function parseInlineSecrets(input: unknown): PlatformInlineSecrets;
 /**
  * The proxy body-redactor refuses to mask any derived target string shorter
@@ -263,6 +301,15 @@ export interface PlatformSubmission {
     readonly agentsMd: readonly AgentsMdRef[];
     readonly files: readonly FileRef[];
     readonly mcpServers: readonly McpServerRef[];
+    /**
+     * Env-var secret bindings — VALUE-FREE declarations keyed by env name. Each
+     * value is `{ ref }` (resolve a workspace secret server-side) or
+     * `{ ephemeral: true }` (value supplied in `secrets.envSecrets`, vaulted and
+     * deleted at terminal). The runtime injects the resolved value as the named
+     * env var. Lifecycle parity with skills/files: per-run by default, persisted
+     * only when promoted to the workspace store.
+     */
+    readonly secretEnv?: Readonly<Record<string, PlatformSecretEnvEntry>>;
     readonly environment?: PlatformEnvironment;
     readonly securityProfile?: RuntimeSecurityProfileName;
     readonly metadata?: Record<string, JsonValue>;
@@ -369,6 +416,15 @@ export interface PlatformRunSubmissionRequest {
      * for repair until this budget is exhausted.
      */
     readonly postHook?: PlatformPostHook;
+    /**
+     * 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;
 }
 /**
  * Wire shape posted by the SDK and CLI. `workspaceId` is **omitted by
@@ -466,7 +522,7 @@ export declare class RuntimeValidationError extends Error {
 }
 /**
  * Walk the parsed submission and collect features that the active managed
- * runtime cannot serve. Provider-hosted skill refs (`Skill.provider(...)`) are
+ * runtime cannot serve. Provider-hosted skill refs (`kind:"provider"`) are
  * rejected now that new submissions only dispatch through managed runs.
  */
 export declare function collectManagedUnsupportedFeatures(req: PlatformRunSubmissionRequest): string[];

package/dist/_contracts/submission.js

@@ -80,7 +80,9 @@ export const RUN_PROVIDERS = [
     "openai",
     "gemini",
     "mistral",
-    "openrouter"
+    "openrouter",
+    "doubao",
+    "doubao-cn"
 ];
 export const DEFAULT_RUN_PROVIDER = "anthropic";
 /**
@@ -107,7 +109,11 @@ export const Providers = {
     /** Mistral. */
     MISTRAL: "mistral",
     /** OpenRouter — OpenAI-compatible aggregator routing to many upstream models. */
-    OPENROUTER: "openrouter"
+    OPENROUTER: "openrouter",
+    /** Doubao (ByteDance) via the official international BytePlus ModelArk gateway. */
+    DOUBAO: "doubao",
+    /** Doubao (ByteDance) via the official China Volcengine Ark gateway. */
+    DOUBAO_CN: "doubao-cn"
 };
 /**
  * Customer-facing runtime selector. Optional on the wire; absent resolves
@@ -126,6 +132,10 @@ export function checkRuntimeSupported(provider, runtime) {
     return { ok: true };
 }
 export const SECRETS_KEY = "secrets";
+/** POSIX-style env var name a `secretEnv` entry binds to (e.g. `SERPER_API_KEY`). */
+export const SECRET_ENV_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
+/** Workspace secret handle a `secretEnv` ref points at (and the name `secret.upload` persists to). */
+export const SECRET_HANDLE_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 export const PROXY_ENDPOINT_NAME_PATTERN = /^[a-z][a-z0-9_-]{0,62}$/;
 export const RESERVED_PROXY_ENDPOINT_NAMES = new Set(["proxy", "aex", "internal", "admin"]);
 /**
@@ -633,9 +643,40 @@ export function crossValidateProxyEndpointsAndAuth(endpoints, auth) {
         }
     }
 }
+/**
+ * Cross-check `submission.secretEnv` declarations against `secrets.envSecrets`
+ * values. Mirrors {@link crossValidateProxyEndpointsAndAuth}:
+ *
+ *  - `{ ephemeral: true }` MUST have a matching `secrets.envSecrets` value.
+ *  - `{ ref }` MUST NOT supply a value (the value lives in the workspace store).
+ *  - every `secrets.envSecrets` value MUST have a matching `{ ephemeral: true }`
+ *    declaration (no orphan values that would never be injected).
+ */
+export function crossValidateSecretEnvAndValues(secretEnv, envSecrets) {
+    const declarations = secretEnv ?? {};
+    const values = envSecrets ?? {};
+    for (const [envName, entry] of Object.entries(declarations)) {
+        const hasValue = Object.prototype.hasOwnProperty.call(values, envName);
+        if ("ref" in entry) {
+            if (hasValue) {
+                throw new Error(`submission.secretEnv[${envName}] is a workspace ref and must not supply a value in secrets.envSecrets[${envName}]; the value resolves server-side`);
+            }
+            continue;
+        }
+        if (!hasValue) {
+            throw new Error(`submission.secretEnv[${envName}] is ephemeral but has no matching secrets.envSecrets[${envName}] value`);
+        }
+    }
+    for (const envName of Object.keys(values)) {
+        const entry = declarations[envName];
+        if (!entry || !("ephemeral" in entry)) {
+            throw new Error(`secrets.envSecrets[${envName}] has no matching submission.secretEnv[${envName}] ephemeral declaration`);
+        }
+    }
+}
 export function parseInlineSecrets(input) {
     const value = requireRecord(input, "secrets");
-    const allowedTopLevel = new Set(["apiKey", "mcpServers", "proxyEndpointAuth"]);
+    const allowedTopLevel = new Set(["apiKey", "mcpServers", "proxyEndpointAuth", "envSecrets"]);
     for (const key of Object.keys(value)) {
         if (key.startsWith("__aex_")) {
             // Platform-internal namespace (e.g. __aex_proxy_token). The BFF
@@ -651,12 +692,30 @@ export function parseInlineSecrets(input) {
     const apiKey = value.apiKey !== undefined ? requireString(value.apiKey, "secrets.apiKey") : undefined;
     const mcpServers = parseMcpServerSecrets(value.mcpServers);
     const proxyEndpointAuth = parseProxyEndpointAuth(value.proxyEndpointAuth);
+    const envSecrets = parseEnvSecrets(value.envSecrets);
     return {
         ...(apiKey !== undefined ? { apiKey } : {}),
         ...(mcpServers ? { mcpServers } : {}),
-        ...(proxyEndpointAuth ? { proxyEndpointAuth } : {})
+        ...(proxyEndpointAuth ? { proxyEndpointAuth } : {}),
+        ...(envSecrets ? { envSecrets } : {})
     };
 }
+function parseEnvSecrets(input) {
+    if (input === undefined || input === null)
+        return undefined;
+    const value = requireRecord(input, "secrets.envSecrets");
+    const out = {};
+    for (const [envName, entry] of Object.entries(value)) {
+        if (!SECRET_ENV_NAME_PATTERN.test(envName)) {
+            throw new Error(`secrets.envSecrets key "${envName}" must be a valid env var name matching ${SECRET_ENV_NAME_PATTERN.source}`);
+        }
+        if (typeof entry !== "string" || entry.length === 0) {
+            throw new Error(`secrets.envSecrets.${envName} must be a non-empty string`);
+        }
+        out[envName] = entry;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
 function parseMcpServerSecrets(input) {
     if (input === undefined) {
         return undefined;
@@ -917,6 +976,7 @@ export function parseRunSubmissionRequest(input, options = {}) {
         "timeout",
         "postHook",
         "proxyEndpoints",
+        "parentRunId",
         SECRETS_KEY
     ]);
     for (const key of Object.keys(value)) {
@@ -949,6 +1009,9 @@ export function parseRunSubmissionRequest(input, 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 postHook = parsePostHook(value.postHook, "submission.postHook");
     const proxyEndpoints = parseProxyEndpoints(value.proxyEndpoints);
     const secrets = parseInlineSecrets(value.secrets);
@@ -956,6 +1019,7 @@ export function parseRunSubmissionRequest(input, options = {}) {
     crossValidateProxyEndpointsAndAuth(proxyEndpoints, secrets.proxyEndpointAuth);
     const submission = parseSubmission(value.submission);
     assertRunModelMatchesProvider(provider, submission.model);
+    crossValidateSecretEnvAndValues(submission.secretEnv, secrets.envSecrets);
     // mcpServers names must agree across the submission half and the
     // secrets half — every secrets.mcpServers[i].name MUST resolve to a
     // submission.mcpServers entry (no orphan secrets) AND the URL must
@@ -999,6 +1063,7 @@ export function parseRunSubmissionRequest(input, options = {}) {
         ...(timeoutMs !== undefined ? { timeoutMs } : {}),
         ...(postHook !== undefined ? { postHook } : {}),
         ...(proxyEndpoints ? { proxyEndpoints } : {}),
+        ...(parentRunId !== undefined ? { parentRunId } : {}),
         secrets
     };
 }
@@ -1051,6 +1116,7 @@ export function parseSubmission(input) {
         "agentsMd",
         "files",
         "mcpServers",
+        "secretEnv",
         "environment",
         "securityProfile",
         "metadata",
@@ -1071,6 +1137,7 @@ export function parseSubmission(input) {
     const agentsMd = parseAgentsMd(value.agentsMd);
     const files = parseFiles(value.files);
     const mcpServers = parseMcpServers(value.mcpServers);
+    const secretEnv = parseSecretEnv(value.secretEnv);
     const environment = parseEnvironment(value.environment);
     const securityProfile = parseRuntimeSecurityProfile(value.securityProfile);
     const metadata = optionalJsonRecord(value.metadata, "submission.metadata");
@@ -1086,6 +1153,7 @@ export function parseSubmission(input) {
         agentsMd,
         files,
         mcpServers,
+        ...(secretEnv ? { secretEnv } : {}),
         ...(environment ? { environment } : {}),
         ...(securityProfile ? { securityProfile } : {}),
         ...(metadata ? { metadata } : {}),
@@ -1095,6 +1163,37 @@ export function parseSubmission(input) {
         ...(platform ? { platform } : {})
     };
 }
+function parseSecretEnv(input) {
+    if (input === undefined || input === null)
+        return undefined;
+    const value = requireRecord(input, "submission.secretEnv");
+    const out = {};
+    for (const [envName, entry] of Object.entries(value)) {
+        if (!SECRET_ENV_NAME_PATTERN.test(envName)) {
+            throw new Error(`submission.secretEnv key "${envName}" must be a valid env var name matching ${SECRET_ENV_NAME_PATTERN.source}`);
+        }
+        const path = `submission.secretEnv.${envName}`;
+        const record = requireRecord(entry, path);
+        const keys = Object.keys(record);
+        if (keys.length !== 1 || (!("ref" in record) && !("ephemeral" in record))) {
+            throw new Error(`${path} must be exactly one of { ref } or { ephemeral: true }`);
+        }
+        if ("ref" in record) {
+            const handle = requireString(record.ref, `${path}.ref`);
+            if (!SECRET_HANDLE_PATTERN.test(handle)) {
+                throw new Error(`${path}.ref handle must match ${SECRET_HANDLE_PATTERN.source}`);
+            }
+            out[envName] = { ref: handle };
+        }
+        else {
+            if (record.ephemeral !== true) {
+                throw new Error(`${path}.ephemeral must be the literal true`);
+            }
+            out[envName] = { ephemeral: true };
+        }
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
 function parsePlatformConfig(input) {
     if (input === undefined || input === null)
         return undefined;
@@ -1478,15 +1577,15 @@ export class RuntimeValidationError extends Error {
 }
 /**
  * Walk the parsed submission and collect features that the active managed
- * runtime cannot serve. Provider-hosted skill refs (`Skill.provider(...)`) are
+ * runtime cannot serve. Provider-hosted skill refs (`kind:"provider"`) are
  * rejected now that new submissions only dispatch through managed runs.
  */
 export function collectManagedUnsupportedFeatures(req) {
     const features = [];
     for (const skill of req.submission.skills) {
         if (skill.kind === "provider") {
-            const versionSuffix = skill.version ? `, "${skill.version}"` : "";
-            features.push(`Skill.provider("${skill.vendor}", "${skill.skillId}"${versionSuffix})`);
+            const versionSuffix = skill.version ? `@${skill.version}` : "";
+            features.push(`provider skill "${skill.vendor}/${skill.skillId}${versionSuffix}" (kind:"provider")`);
         }
     }
     return features;

package/dist/agents-md.d.ts

@@ -5,9 +5,9 @@ import type { AgentsMdRef } from "./_contracts/index.js";
  * behaviour).
  *
  *   const rules = await AgentsMd.fromContent("# Be helpful", { name: "rules" });
- *   await client.submitRun({ agentsMd: [rules], ... });
+ *   await client.submit({ agentsMd: [rules], ... });
  *
- * `client.submitRun` materializes the bytes to the hosted asset store before
+ * `client.submit` materializes the bytes to the hosted asset store before
  * the run lands. Asset deduplication handles repeated uploads automatically.
  */
 export declare class AgentsMd {
@@ -30,7 +30,7 @@ export declare class AgentsMd {
     }): Promise<AgentsMd>;
     /**
      * Internal: yield the draft's zipped bytes + metadata so
-     * `client.submitRun` can upload it as an asset.
+     * `client.submit` can upload it as an asset.
      */
     _takeDraftBundle(): {
         name: string;

package/dist/agents-md.js

@@ -7,9 +7,9 @@ import { strToU8, zipSync } from "fflate";
  * behaviour).
  *
  *   const rules = await AgentsMd.fromContent("# Be helpful", { name: "rules" });
- *   await client.submitRun({ agentsMd: [rules], ... });
+ *   await client.submit({ agentsMd: [rules], ... });
  *
- * `client.submitRun` materializes the bytes to the hosted asset store before
+ * `client.submit` materializes the bytes to the hosted asset store before
  * the run lands. Asset deduplication handles repeated uploads automatically.
  */
 export class AgentsMd {
@@ -53,12 +53,12 @@ export class AgentsMd {
     }
     /**
      * Internal: yield the draft's zipped bytes + metadata so
-     * `client.submitRun` can upload it as an asset.
+     * `client.submit` can upload it as an asset.
      */
     _takeDraftBundle() {
         if (this.#consumed) {
-            throw new Error("AgentsMd: cannot reuse a consumed AgentsMd in submitRun. Build a fresh one " +
-                "via AgentsMd.fromContent(...) / AgentsMd.fromPath(...) per submitRun call.");
+            throw new Error("AgentsMd: cannot reuse a consumed AgentsMd in submit. Build a fresh one " +
+                "via AgentsMd.fromContent(...) / AgentsMd.fromPath(...) per submit call.");
         }
         if (this.#ref.kind !== "draft" || !this.#zipBytes) {
             return undefined;
@@ -73,7 +73,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.submitRun uploads the bytes as an asset.");
+                "ref when client.submit 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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"}