@aexhq/sdk 0.19.0 → 0.21.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/run-custody.js

@@ -397,7 +397,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,
@@ -406,11 +406,39 @@ function scanStringValue(value, path, findings) {
         }
     }
 }
+/**
+ * A pattern fires on a value if its `regex` matches AND — when the pattern
+ * carries an `accept` predicate — at least one matched run is accepted by it.
+ * The predicate lets a shape-matched run be VETOED per-match (the entropy
+ * catch-all uses it to skip content-addressed hashes and low-entropy slugs that
+ * its coarse regex would otherwise flag); shape-only patterns have no predicate.
+ */
+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;
+}
 const 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 },
@@ -419,8 +447,71 @@ const 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
+    }
 ]);
+/** A content-addressed hash (md5/sha1/sha256 hex digest) — the platform's own
+ * asset filenames and content references. Exempt from the entropy catch-all so
+ * a captured output named after its sha256 (or a hash echoed in tool-result
+ * text) is not misclassified as a leaked secret. */
+const CONTENT_HASH_RUN = /^(?:[0-9a-f]{32}|[0-9a-f]{40}|[0-9a-f]{64})$/i;
+/**
+ * Decide whether a coarse `[A-Za-z0-9-]{40,}` run is a genuine opaque secret.
+ * Rejects content-addressed hashes, then requires both character-class
+ * diversity (≥2 of lower/upper/digit) and high Shannon entropy — the property
+ * that separates an opaque key blob from a long dictionary-ish identifier. A
+ * real prefixless secret (base64url/alnum-mixed) clears both gates; a hash, a
+ * hyphenated slug, or a single-class run does not.
+ */
+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.0;
+}
+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 = 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);
 }

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;
+}