@aexhq/sdk 0.19.0 → 0.21.0

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

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"];
@@ -794,7 +838,7 @@ function visitCustodyValue(input, path, findings) {
 }
 function scanStringValue(value, path, findings) {
   for (const pattern of forbiddenStringPatterns) {
-    if (pattern.regex.test(value)) {
+    if (matchesForbiddenPattern(pattern, value)) {
       findings.push(Object.freeze({
         path,
         reason: pattern.reason,
@@ -803,11 +847,32 @@ function scanStringValue(value, path, findings) {
     }
   }
 }
+function matchesForbiddenPattern(pattern, value) {
+  if (!pattern.accept) {
+    return pattern.regex.test(value);
+  }
+  const scan = pattern.regex.global ? pattern.regex : new RegExp(pattern.regex.source, `${pattern.regex.flags}g`);
+  scan.lastIndex = 0;
+  let match;
+  while ((match = scan.exec(value)) !== null) {
+    if (pattern.accept(match[0])) {
+      return true;
+    }
+    if (match.index === scan.lastIndex) {
+      scan.lastIndex++;
+    }
+  }
+  return false;
+}
 var forbiddenStringPatterns = Object.freeze([
   { reason: "bearer_token", regex: /\bBearer\s+[A-Za-z0-9._~+/=-]{8,}/i },
   {
     reason: "provider_key",
-    regex: /\b(?:sk-(?:ant|proj|live|test|deepseek|openai)|xox[baprs]-|AIza)[A-Za-z0-9_-]{8,}/i
+    // Prefixed provider keys (`sk-…`, Slack `xox*-…`, Google `AIza…`). The bare
+    // `sk-` body is intentionally generic so an unrecognised vendor's `sk-` key
+    // (e.g. DeepSeek `sk-<hex>`, OpenRouter `sk-or-…`) is still caught by shape,
+    // not left to the narrowed entropy catch-all below.
+    regex: /\b(?:sk-[A-Za-z0-9_-]{16,}|xox[baprs]-[A-Za-z0-9-]{8,}|AIza[A-Za-z0-9_-]{8,})/i
   },
   { reason: "signed_url", regex: /[?&](?:X-Amz-Signature|X-Amz-Credential|X-Amz-Algorithm|AWSAccessKeyId)=/i },
   { reason: "object_store_key", regex: /(^|[\s"'`])(?:runs|assets)\/[^?<#\s"'`]+/i },
@@ -816,8 +881,59 @@ var forbiddenStringPatterns = Object.freeze([
     reason: "private_resource_handle",
     regex: /\b(?:machine|session|agent|file|skill|env|resource|handle|token_hash|bearer_hash)[_:-][A-Za-z0-9][A-Za-z0-9_-]{7,}\b/i
   },
-  { reason: "high_entropy_token", regex: /\b(?=[A-Za-z0-9_-]{40,}\b)(?=.*[A-Za-z])(?=.*\d)[A-Za-z0-9_-]{40,}\b/ }
+  {
+    reason: "high_entropy_token",
+    // Catch-all for an unrecognised opaque secret blob. The candidate run
+    // EXCLUDES `_` (so `SCREAMING_SNAKE` env names and `slug_with_words` URL
+    // segments split instead of fusing into a phantom 40-char run — the live
+    // false positive was `ted_season_2_peacock_official_discussion_thread` in
+    // web-search result text and a fetched URL), and the `accept` predicate
+    // vetoes content-addressed hashes (md5/sha1/sha256 digests — the platform's
+    // OWN asset filenames) and low-entropy / single-class runs so only genuine
+    // opaque secrets remain. Slash-bearing secrets (signed URLs, connection
+    // strings, `Bearer …`) are covered by the named patterns above.
+    regex: /\b[A-Za-z0-9-]{40,}\b/,
+    accept: isHighEntropySecretRun
+  }
 ]);
+var CONTENT_HASH_RUN = /^(?:[0-9a-f]{32}|[0-9a-f]{40}|[0-9a-f]{64})$/i;
+function isHighEntropySecretRun(run) {
+  if (CONTENT_HASH_RUN.test(run)) {
+    return false;
+  }
+  if (!/[A-Za-z]/.test(run) || !/\d/.test(run)) {
+    return false;
+  }
+  if (highEntropyCharClassCount(run) < 2) {
+    return false;
+  }
+  return highEntropyShannonBits(run) >= 3;
+}
+function highEntropyCharClassCount(value) {
+  let count = 0;
+  if (/[a-z]/.test(value))
+    count++;
+  if (/[A-Z]/.test(value))
+    count++;
+  if (/[0-9]/.test(value))
+    count++;
+  return count;
+}
+function highEntropyShannonBits(value) {
+  if (value.length === 0) {
+    return 0;
+  }
+  const counts = /* @__PURE__ */ new Map();
+  for (const char of value) {
+    counts.set(char, (counts.get(char) ?? 0) + 1);
+  }
+  let bits = 0;
+  for (const count of counts.values()) {
+    const p = count / value.length;
+    bits -= p * Math.log2(p);
+  }
+  return bits;
+}
 function isForbiddenCustodyFieldName(key) {
   return /^(apiKey|secretValue|bearerHash|signedUrl|objectStoreKey|objectKey|vaultId|providerResponseBody|responseBody|privateResourceHandle|resourceHandle|rawBody)$/i.test(key);
 }
@@ -1246,11 +1362,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 +1383,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 +2502,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
+d05e5e074b577553d20fa3680f834b7941fe0cb7692c0a743975fcf36c4ec9b5  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)`