@aexhq/sdk 0.19.0 → 0.20.0

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;

package/dist/cli.mjs

@@ -126,6 +126,34 @@ var 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
+    }
   }
 };
 
@@ -144,7 +172,21 @@ var 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"
+  }
 };
 var RUN_MODELS = Object.keys(MODEL_PROVIDER_IDS);
 var PROVIDERS_BY_MODEL = (() => {
@@ -743,7 +785,9 @@ var RUN_PROVIDERS = [
   "openai",
   "gemini",
   "mistral",
-  "openrouter"
+  "openrouter",
+  "doubao",
+  "doubao-cn"
 ];
 var DEFAULT_RUN_PROVIDER = "anthropic";
 var RUNTIME_KINDS = ["managed"];
@@ -1246,11 +1290,13 @@ __export(operations_exports, {
   createAgentsMd: () => createAgentsMd,
   createFile: () => createFile,
   createOutputLink: () => createOutputLink,
+  createSecret: () => createSecret,
   createSkillBundle: () => createSkillBundle,
   createSkillBundleDirect: () => createSkillBundleDirect,
   deleteAgentsMd: () => deleteAgentsMd,
   deleteFile: () => deleteFile,
   deleteRun: () => deleteRun,
+  deleteSecret: () => deleteSecret,
   deleteSkill: () => deleteSkill,
   deleteWorkspaceAsset: () => deleteWorkspaceAsset,
   download: () => download,
@@ -1265,13 +1311,17 @@ __export(operations_exports, {
   getFile: () => getFile,
   getRun: () => getRun,
   getRunUnit: () => getRunUnit,
+  getSecret: () => getSecret,
   getSkill: () => getSkill,
   listAgentsMd: () => listAgentsMd,
   listFiles: () => listFiles,
   listOutputs: () => listOutputs,
   listRunEvents: () => listRunEvents,
+  listSecrets: () => listSecrets,
   listSkills: () => listSkills,
   resolveOutputFileSelector: () => resolveOutputFileSelector,
+  revealSecret: () => revealSecret,
+  rotateSecret: () => rotateSecret,
   submitRun: () => submitRun,
   submitRunMultipart: () => submitRunMultipart,
   uploadWorkspaceAsset: () => uploadWorkspaceAsset,
@@ -2380,6 +2430,44 @@ function unwrapFile(result) {
   }
   return result;
 }
+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);
+}
+async function listSecrets(http) {
+  const result = await http.request("/api/secrets");
+  if (Array.isArray(result)) {
+    return result;
+  }
+  return result.secrets;
+}
+async function getSecret(http, name) {
+  const result = await http.request(`/api/secrets/${encodeURIComponent(name)}`);
+  return unwrapSecret(result);
+}
+async function revealSecret(http, name) {
+  return http.request(`/api/secrets/${encodeURIComponent(name)}/reveal`, {
+    method: "POST"
+  });
+}
+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);
+}
+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/cli.mjs.sha256

@@ -1 +1 @@
-479aa815e56005b54f89791ddaac4e41b564ffc377e3077deb11258dba46aaf5  cli.mjs
+cbf31722f64f1ca909287456236e1e689291516e227dcdd69935300bbc0994c9  cli.mjs

package/dist/client.d.ts

@@ -1,9 +1,10 @@
-import { HttpClient, type AexEvent, type AgentsMdRecord, type CredentialMode, type DebugSink, type FetchLike, type FileRecord, type Output, type OutputMode, type PlatformEnvironmentInput, type PlatformSubmission, type PlatformInlineSecrets, type PlatformProxyEndpoint, type PlatformProxyEndpointAuth, type PlatformPostHookInput, type Run, type RunModel, type RunEvent, type RunProvider, type RunUnit, type Builtin, type RuntimeSize, type RuntimeKind, type SignedOutputLink, type Skill as SkillRecord, type WhoAmI } from "./_contracts/index.js";
+import { HttpClient, SecretString, type AexEvent, type AgentsMdRecord, type CredentialMode, type DebugSink, type FetchLike, type FileRecord, type Output, type OutputMode, type PlatformEnvironmentInput, type PlatformSubmission, type PlatformInlineSecrets, type PlatformProxyEndpoint, type PlatformProxyEndpointAuth, type PlatformPostHookInput, type Run, type RunModel, type RunEvent, type RunProvider, type SecretRecord, type SecretReveal, type RunUnit, type Builtin, type RuntimeSize, type RuntimeKind, type SignedOutputLink, type Skill as SkillRecord, type WhoAmI } from "./_contracts/index.js";
 import { AgentsMd } from "./agents-md.js";
 import { type UploadedAsset } from "./asset-upload.js";
 import { File } from "./file.js";
 import { McpServer } from "./mcp-server.js";
 import { ProxyEndpoint } from "./proxy-endpoint.js";
+import { Secret } from "./secret.js";
 import { Skill } from "./skill.js";
 export interface AgentExecutorOptions {
     /** Workspace-scoped SDK API token. */
@@ -85,6 +86,16 @@ export interface SubmitOptions {
     readonly agentsMd?: readonly AgentsMd[];
     readonly files?: readonly File[];
     readonly mcpServers?: readonly McpServer[];
+    /**
+     * Env-var secrets, keyed by env name. Each value is a {@link Secret}:
+     * `Secret.value(v)` (ephemeral per-run — vaulted at submit, deleted at the
+     * run's terminal) or `Secret.ref(handle)` (a persisted workspace secret,
+     * resolved server-side). The SDK splits these into value-free declarations on
+     * the hashed submission and ephemeral values into the vaulted secrets channel,
+     * so a value never enters the run snapshot or the idempotency hash. The
+     * runtime injects each as the named env var.
+     */
+    readonly secretEnv?: Readonly<Record<string, Secret>>;
     readonly environment?: PlatformEnvironmentInput;
     readonly metadata?: PlatformSubmission["metadata"];
     /**
@@ -148,6 +159,14 @@ export interface SubmitOptions {
     readonly outputMode?: OutputMode;
     readonly secrets: PlatformInlineSecrets;
     readonly idempotencyKey?: string;
+    /**
+     * Lineage parent (agent-session §9). When set, the server admits this run as
+     * a CHILD of `parentRunId` (same workspace required), enforcing the
+     * max-subagent-depth + per-root concurrency caps and persisting the lineage.
+     * The depth is always derived server-side from the parent row — clients name
+     * the parent, never the depth.
+     */
+    readonly parentRunId?: string;
     readonly signal?: AbortSignal;
 }
 /** @deprecated Renamed to {@link SubmitOptions}. Kept for one release. */
@@ -287,6 +306,52 @@ export declare class FilesClient {
         readonly bytes: Uint8Array;
     }): Promise<FileRecord>;
 }
+/**
+ * Workspace secret management exposed under `client.secrets`, mirroring
+ * `client.skills` / `client.files`.
+ *
+ * Lifecycle parity with assets/skills: a `Secret.value(...)` is per-run and
+ * gone at terminal; `set` (or promoting an ephemeral via `secret.upload`)
+ * persists a named, searchable workspace secret you can `get` (metadata),
+ * `reveal` (audited value), `rotate`, `list`, and `delete`. The identity is the
+ * `name`; the value rotates under that stable name.
+ *
+ * Values are write-only: `set`/`rotate` send the value in the request BODY (never
+ * the URL); `get`/`list` return metadata only; `reveal` is the explicit audited
+ * value read.
+ */
+export declare class SecretsClient {
+    #private;
+    constructor(http: HttpClient);
+    /** Create a named workspace secret. Accepts a raw string or a `SecretString`. */
+    set(args: {
+        readonly name: string;
+        readonly value: string | SecretString;
+    }): Promise<SecretRecord>;
+    /** List workspace secret metadata (searchable by name). Never returns values. */
+    list(): Promise<readonly SecretRecord[]>;
+    /** Metadata for one workspace secret by name. Never returns the value. */
+    get(name: string): Promise<SecretRecord>;
+    /** Audited value read — the only path that returns a workspace secret value. */
+    reveal(name: string): Promise<SecretReveal>;
+    /** Replace the value of an existing workspace secret; bumps its version. */
+    rotate(args: {
+        readonly name: string;
+        readonly value: string | SecretString;
+    }): Promise<SecretRecord>;
+    delete(name: string): Promise<void>;
+    /**
+     * Internal: create a workspace secret from an ephemeral `Secret.value(...)`
+     * being promoted via `secret.upload(client, { name })`. NOT part of the
+     * public API — callers use `set`.
+     */
+    _createWorkspaceSecret(args: {
+        readonly name: string;
+        readonly value: string;
+    }): Promise<{
+        readonly name: string;
+    }>;
+}
 /**
  * Unified user-facing client for the aex platform. The same class
  * powers the published `@aexhq/sdk` SDK and (under the hood) every host-side
@@ -303,6 +368,7 @@ export declare class AgentExecutor {
     readonly skills: SkillsClient;
     readonly agentsMd: AgentsMdClient;
     readonly files: FilesClient;
+    readonly secrets: SecretsClient;
     constructor(options: AgentExecutorOptions);
     /**
      * Internal: forwards to `SkillsClient._uploadSkillBundle`. NOT part of
@@ -338,6 +404,18 @@ export declare class AgentExecutor {
         readonly name: string;
         readonly bytes: Uint8Array;
     }): Promise<FileRecord>;
+    /**
+     * Internal: satisfies the `SecretUploader` surface so a
+     * `Secret.value(...).upload(client, { name })` promotes an ephemeral secret
+     * into the workspace store. Forwarded to `SecretsClient._createWorkspaceSecret`.
+     * NOT part of the public API.
+     */
+    _createWorkspaceSecret(args: {
+        readonly name: string;
+        readonly value: string;
+    }): Promise<{
+        readonly name: string;
+    }>;
     /**
      * Internal: materialize raw bytes to the content-addressable asset store
      * (`/assets/presign` → PUT → `/assets/finalize`). Used by `Skill.upload(this)`

package/dist/client.js

@@ -1,9 +1,10 @@
-import { AexError, DEFAULT_CREDENTIAL_MODE, DEFAULT_RUN_PROVIDER, HttpClient, RUNTIME_KINDS, RunStateError, isRunSettled, operations, parseCredentialMode, providersForModel, streamCoordinatorEvents, TERMINAL_RUN_STATUSES } from "./_contracts/index.js";
+import { AexError, DEFAULT_CREDENTIAL_MODE, DEFAULT_RUN_PROVIDER, HttpClient, RUNTIME_KINDS, RunStateError, SecretString, isRunSettled, operations, parseCredentialMode, providersForModel, streamCoordinatorEvents, TERMINAL_RUN_STATUSES } from "./_contracts/index.js";
 import { AgentsMd } from "./agents-md.js";
 import { uploadAsset } from "./asset-upload.js";
 import { File } from "./file.js";
 import { McpServer } from "./mcp-server.js";
 import { splitProxyEndpoints } from "./proxy-endpoint.js";
+import { splitSecretEnv } from "./secret.js";
 import { Skill } from "./skill.js";
 /**
  * Workspace skill admin operations exposed under `client.skills`.
@@ -128,6 +129,66 @@ export class FilesClient {
         return operations.createFile(this.#http, args);
     }
 }
+/**
+ * Workspace secret management exposed under `client.secrets`, mirroring
+ * `client.skills` / `client.files`.
+ *
+ * Lifecycle parity with assets/skills: a `Secret.value(...)` is per-run and
+ * gone at terminal; `set` (or promoting an ephemeral via `secret.upload`)
+ * persists a named, searchable workspace secret you can `get` (metadata),
+ * `reveal` (audited value), `rotate`, `list`, and `delete`. The identity is the
+ * `name`; the value rotates under that stable name.
+ *
+ * Values are write-only: `set`/`rotate` send the value in the request BODY (never
+ * the URL); `get`/`list` return metadata only; `reveal` is the explicit audited
+ * value read.
+ */
+export class SecretsClient {
+    #http;
+    constructor(http) {
+        this.#http = http;
+    }
+    /** Create a named workspace secret. Accepts a raw string or a `SecretString`. */
+    set(args) {
+        return operations.createSecret(this.#http, { name: args.name, value: unwrapSecretValue(args.value) });
+    }
+    /** List workspace secret metadata (searchable by name). Never returns values. */
+    list() {
+        return operations.listSecrets(this.#http);
+    }
+    /** Metadata for one workspace secret by name. Never returns the value. */
+    get(name) {
+        return operations.getSecret(this.#http, name);
+    }
+    /** Audited value read — the only path that returns a workspace secret value. */
+    reveal(name) {
+        return operations.revealSecret(this.#http, name);
+    }
+    /** Replace the value of an existing workspace secret; bumps its version. */
+    rotate(args) {
+        return operations.rotateSecret(this.#http, { name: args.name, value: unwrapSecretValue(args.value) });
+    }
+    delete(name) {
+        return operations.deleteSecret(this.#http, name);
+    }
+    /**
+     * Internal: create a workspace secret from an ephemeral `Secret.value(...)`
+     * being promoted via `secret.upload(client, { name })`. NOT part of the
+     * public API — callers use `set`.
+     */
+    async _createWorkspaceSecret(args) {
+        const record = await operations.createSecret(this.#http, args);
+        return { name: record.name };
+    }
+}
+/** Accept a raw string or a `SecretString`; return the raw value for the wire. */
+function unwrapSecretValue(value) {
+    const raw = value instanceof SecretString ? value.unwrap() : value;
+    if (typeof raw !== "string" || !raw) {
+        throw new Error("secrets: value must be a non-empty string");
+    }
+    return raw;
+}
 /**
  * Unified user-facing client for the aex platform. The same class
  * powers the published `@aexhq/sdk` SDK and (under the hood) every host-side
@@ -146,6 +207,7 @@ export class AgentExecutor {
     skills;
     agentsMd;
     files;
+    secrets;
     constructor(options) {
         if (!options.apiToken) {
             throw new Error("AgentExecutor: apiToken is required");
@@ -165,6 +227,7 @@ export class AgentExecutor {
         this.skills = new SkillsClient(this.#http);
         this.agentsMd = new AgentsMdClient(this.#http);
         this.files = new FilesClient(this.#http);
+        this.secrets = new SecretsClient(this.#http);
     }
     /**
      * Internal: forwards to `SkillsClient._uploadSkillBundle`. NOT part of
@@ -197,6 +260,15 @@ export class AgentExecutor {
     async _uploadFile(args) {
         return this.files._uploadFile(args);
     }
+    /**
+     * Internal: satisfies the `SecretUploader` surface so a
+     * `Secret.value(...).upload(client, { name })` promotes an ephemeral secret
+     * into the workspace store. Forwarded to `SecretsClient._createWorkspaceSecret`.
+     * NOT part of the public API.
+     */
+    async _createWorkspaceSecret(args) {
+        return this.secrets._createWorkspaceSecret(args);
+    }
     /**
      * Internal: materialize raw bytes to the content-addressable asset store
      * (`/assets/presign` → PUT → `/assets/finalize`). Used by `Skill.upload(this)`
@@ -277,6 +349,9 @@ export class AgentExecutor {
         const prompt = normalisePrompt(options.prompt);
         const { endpoints: proxyEndpointDeclarations, auth: proxyEndpointAuthFromInstances } = splitProxyEndpoints(options.proxyEndpoints ?? []);
         const mergedProxyAuth = mergeProxyEndpointAuth(proxyEndpointAuthFromInstances, options.secrets.proxyEndpointAuth ?? []);
+        // Split secretEnv into value-free declarations (hashed submission) and
+        // ephemeral values (vaulted secrets channel), mirroring the proxy split.
+        const { declarations: secretEnvDeclarations, values: envSecretValues } = splitSecretEnv(options.secretEnv);
         // Validate the runtime selector before any network I/O — inline drafts
         // are uploaded below, so an invalid runtime must reject first rather than
         // leak an asset upload.
@@ -309,6 +384,7 @@ export class AgentExecutor {
             // shape matches McpServerRef. The cast acknowledges that the
             // SDK is producing pre-resolution wire input here.
             mcpServers: submissionMcpServers,
+            ...(Object.keys(secretEnvDeclarations).length > 0 ? { secretEnv: secretEnvDeclarations } : {}),
             // `options.environment.packages` carry the customer wire shape
             // (`{name:"pip:pandas"}`); the shared parser resolves the ecosystem
             // prefix into PlatformPackage. The cast acknowledges the SDK is
@@ -330,7 +406,8 @@ export class AgentExecutor {
         const secrets = {
             ...options.secrets,
             ...(mergedMcpSecrets.length > 0 ? { mcpServers: mergedMcpSecrets } : {}),
-            ...(mergedProxyAuth.length > 0 ? { proxyEndpointAuth: mergedProxyAuth } : {})
+            ...(mergedProxyAuth.length > 0 ? { proxyEndpointAuth: mergedProxyAuth } : {}),
+            ...(Object.keys(envSecretValues).length > 0 ? { envSecrets: envSecretValues } : {})
         };
         const postHook = postHookForWire(options.postHook);
         const request = {
@@ -349,6 +426,7 @@ export class AgentExecutor {
             ...(options.runtimeSize ? { runtimeSize: options.runtimeSize } : {}),
             ...(options.timeout ? { timeout: options.timeout } : {}),
             ...(postHook ? { postHook } : {}),
+            ...(options.parentRunId ? { parentRunId: options.parentRunId } : {}),
             secrets,
             ...(proxyEndpointDeclarations.length > 0
                 ? { proxyEndpoints: proxyEndpointDeclarations }