@aexhq/sdk 0.19.0 → 0.20.0

package/dist/_contracts/models.d.ts

@@ -62,6 +62,14 @@ export declare const MODEL_PROVIDER_IDS: {
     readonly "mistral-small-latest": {
         readonly mistral: "mistral-small-latest";
     };
+    readonly "doubao-seed-pro": {
+        readonly doubao: "doubao-seed-1-8-251228";
+        readonly "doubao-cn": "doubao-seed-1-8-251228";
+    };
+    readonly "doubao-seed-flash": {
+        readonly doubao: "doubao-seed-1-6-flash-250828";
+        readonly "doubao-cn": "doubao-seed-1-6-flash-250828";
+    };
 };
 /**
  * Closed set of canonical model ids accepted by the public run-submission
@@ -116,6 +124,18 @@ export declare const Models: {
     readonly MISTRAL_LARGE_LATEST: "mistral-large-latest";
     /** Mistral Small (latest) — Mistral. */
     readonly MISTRAL_SMALL_LATEST: "mistral-small-latest";
+    /**
+     * Doubao Seed 1.8 — ByteDance, via the official Ark API. Default routes
+     * through the international BytePlus gateway (`Providers.DOUBAO`); pair with
+     * `Providers.DOUBAO_CN` for the China Volcengine gateway.
+     */
+    readonly DOUBAO_SEED_PRO: "doubao-seed-pro";
+    /**
+     * Doubao Seed 1.6 Flash — ByteDance, via the official Ark API (fast/cheap).
+     * Default `Providers.DOUBAO` (international); pair with `Providers.DOUBAO_CN`
+     * for China.
+     */
+    readonly DOUBAO_SEED_FLASH: "doubao-seed-flash";
 };
 /**
  * Back-compat alias for {@link Models}. Existing imports of `RunModels`
@@ -159,6 +179,18 @@ export declare const RunModels: {
     readonly MISTRAL_LARGE_LATEST: "mistral-large-latest";
     /** Mistral Small (latest) — Mistral. */
     readonly MISTRAL_SMALL_LATEST: "mistral-small-latest";
+    /**
+     * Doubao Seed 1.8 — ByteDance, via the official Ark API. Default routes
+     * through the international BytePlus gateway (`Providers.DOUBAO`); pair with
+     * `Providers.DOUBAO_CN` for the China Volcengine gateway.
+     */
+    readonly DOUBAO_SEED_PRO: "doubao-seed-pro";
+    /**
+     * Doubao Seed 1.6 Flash — ByteDance, via the official Ark API (fast/cheap).
+     * Default `Providers.DOUBAO` (international); pair with `Providers.DOUBAO_CN`
+     * for China.
+     */
+    readonly DOUBAO_SEED_FLASH: "doubao-seed-flash";
 };
 /**
  * Provider → canonical models that provider can serve. Derived from

package/dist/_contracts/models.js

@@ -30,7 +30,21 @@ export const MODEL_PROVIDER_IDS = {
     "gemini-2.0-flash": { gemini: "gemini-2.0-flash", openrouter: "google/gemini-2.0-flash-001" },
     "gemini-2.5-flash": { gemini: "gemini-2.5-flash" },
     "mistral-large-latest": { mistral: "mistral-large-latest" },
-    "mistral-small-latest": { mistral: "mistral-small-latest" }
+    "mistral-small-latest": { mistral: "mistral-small-latest" },
+    // Doubao (ByteDance) via the official Ark API. Served by both the
+    // international BytePlus ModelArk gateway (`doubao`, the default) and the
+    // 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).
+    //   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" },
+    "doubao-seed-flash": {
+        doubao: "doubao-seed-1-6-flash-250828",
+        "doubao-cn": "doubao-seed-1-6-flash-250828"
+    }
 };
 export const RUN_MODELS = Object.keys(MODEL_PROVIDER_IDS);
 /**
@@ -79,7 +93,19 @@ export const Models = {
     /** Mistral Large (latest) — Mistral. */
     MISTRAL_LARGE_LATEST: "mistral-large-latest",
     /** Mistral Small (latest) — Mistral. */
-    MISTRAL_SMALL_LATEST: "mistral-small-latest"
+    MISTRAL_SMALL_LATEST: "mistral-small-latest",
+    /**
+     * Doubao Seed 1.8 — ByteDance, via the official Ark API. Default routes
+     * through the international BytePlus gateway (`Providers.DOUBAO`); pair with
+     * `Providers.DOUBAO_CN` for the China Volcengine gateway.
+     */
+    DOUBAO_SEED_PRO: "doubao-seed-pro",
+    /**
+     * Doubao Seed 1.6 Flash — ByteDance, via the official Ark API (fast/cheap).
+     * Default `Providers.DOUBAO` (international); pair with `Providers.DOUBAO_CN`
+     * for China.
+     */
+    DOUBAO_SEED_FLASH: "doubao-seed-flash"
 };
 /**
  * Back-compat alias for {@link Models}. Existing imports of `RunModels`

package/dist/_contracts/operations.d.ts

@@ -1,6 +1,6 @@
 import type { HttpClient } from "./http.js";
 import type { RunUnit } from "./run-unit.js";
-import type { AgentsMdRecord, FileRecord, Output, OutputFileDownload, OutputFileSelector, Run, RunEvent, SignedOutputLink, Skill, WhoAmI } from "./runtime-types.js";
+import type { AgentsMdRecord, FileRecord, Output, OutputFileDownload, OutputFileSelector, Run, RunEvent, SecretRecord, SecretReveal, SignedOutputLink, Skill, WhoAmI } from "./runtime-types.js";
 import type { PlatformRunSubmissionInput } from "./submission.js";
 /**
  * The single source of truth for SDK<->BFF transport. The SDK class
@@ -207,6 +207,22 @@ export declare function createFile(http: HttpClient, args: {
 export declare function listFiles(http: HttpClient): Promise<readonly FileRecord[]>;
 export declare function getFile(http: HttpClient, fileId: string): Promise<FileRecord>;
 export declare function deleteFile(http: HttpClient, fileId: string): Promise<void>;
+/** Create a named workspace secret. The value travels in the body. */
+export declare function createSecret(http: HttpClient, args: {
+    readonly name: string;
+    readonly value: string;
+}): Promise<SecretRecord>;
+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>;
+/** Replace the value of an existing workspace secret; bumps its version. */
+export declare function rotateSecret(http: HttpClient, args: {
+    readonly name: string;
+    readonly value: string;
+}): Promise<SecretRecord>;
+export declare function deleteSecret(http: HttpClient, name: string): Promise<void>;
 export interface AssetUploadResult {
     readonly assetId: string;
     readonly contentHash: string;

package/dist/_contracts/operations.js

@@ -541,6 +541,56 @@ function unwrapFile(result) {
     }
     return result;
 }
+// ===========================================================================
+// Workspace secret operations
+//
+// 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).
+// ===========================================================================
+/** Create a named workspace secret. The value travels in the body. */
+export async function createSecret(http, args) {
+    const result = await http.request("/api/secrets", {
+        method: "POST",
+        body: JSON.stringify({ name: args.name, value: args.value })
+    });
+    return unwrapSecret(result);
+}
+export async function listSecrets(http) {
+    const result = await http.request("/api/secrets");
+    if (Array.isArray(result)) {
+        return result;
+    }
+    return result.secrets;
+}
+/** Metadata for one workspace secret by name. Never returns the value. */
+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`, {
+        method: "POST"
+    });
+}
+/** Replace the value of an existing workspace secret; bumps its version. */
+export async function rotateSecret(http, args) {
+    const result = await http.request(`/api/secrets/${encodeURIComponent(args.name)}/rotate`, { method: "POST", body: JSON.stringify({ value: args.value }) });
+    return unwrapSecret(result);
+}
+export async function deleteSecret(http, name) {
+    await http.request(`/api/secrets/${encodeURIComponent(name)}`, {
+        method: "DELETE"
+    });
+}
+function unwrapSecret(result) {
+    if (result && typeof result === "object" && "secret" in result) {
+        return result.secret;
+    }
+    return result;
+}
 function unwrapSkill(result) {
     if (result && typeof result === "object" && "skill" in result) {
         return result.skill;

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

@@ -256,5 +256,73 @@ export declare const PROVIDER_PUBLIC_SUPPORT: {
             }];
         };
     };
+    readonly doubao: {
+        readonly displayName: "Doubao";
+        readonly status: "live-unverified";
+        readonly docsAnchor: "doubao";
+        readonly docs: readonly [{
+            readonly label: "Credentials";
+            readonly href: "credentials.md";
+        }, {
+            readonly label: "Events";
+            readonly href: "events.md";
+        }];
+        readonly evidence: readonly [{
+            readonly label: "Submission parser and routing parity";
+            readonly href: "../../contracts/test/submission.test.ts";
+        }, {
+            readonly label: "Runtime support validator";
+            readonly href: "../../contracts/test/runtime-support.test.ts";
+        }, {
+            readonly label: "Generated matrix freshness";
+            readonly href: "../../../scripts/validate/capability-matrix.test.ts";
+        }];
+        readonly runtimeEvidence: {
+            readonly managed: readonly [{
+                readonly label: "Submission parser and routing parity";
+                readonly href: "../../contracts/test/submission.test.ts";
+            }, {
+                readonly label: "Runtime support validator";
+                readonly href: "../../contracts/test/runtime-support.test.ts";
+            }, {
+                readonly label: "Generated matrix freshness";
+                readonly href: "../../../scripts/validate/capability-matrix.test.ts";
+            }];
+        };
+    };
+    readonly "doubao-cn": {
+        readonly displayName: "Doubao (China)";
+        readonly status: "live-unverified";
+        readonly docsAnchor: "doubao-cn";
+        readonly docs: readonly [{
+            readonly label: "Credentials";
+            readonly href: "credentials.md";
+        }, {
+            readonly label: "Events";
+            readonly href: "events.md";
+        }];
+        readonly evidence: readonly [{
+            readonly label: "Submission parser and routing parity";
+            readonly href: "../../contracts/test/submission.test.ts";
+        }, {
+            readonly label: "Runtime support validator";
+            readonly href: "../../contracts/test/runtime-support.test.ts";
+        }, {
+            readonly label: "Generated matrix freshness";
+            readonly href: "../../../scripts/validate/capability-matrix.test.ts";
+        }];
+        readonly runtimeEvidence: {
+            readonly managed: readonly [{
+                readonly label: "Submission parser and routing parity";
+                readonly href: "../../contracts/test/submission.test.ts";
+            }, {
+                readonly label: "Runtime support validator";
+                readonly href: "../../contracts/test/runtime-support.test.ts";
+            }, {
+                readonly label: "Generated matrix freshness";
+                readonly href: "../../../scripts/validate/capability-matrix.test.ts";
+            }];
+        };
+    };
 };
 export declare function providerPublicSupport(provider: RunProvider): ProviderPublicSupport;

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-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