@aexhq/sdk 0.33.1 → 0.35.0

package/dist/retry.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Built-in transport resilience for the aex SDK.
+ *
+ * Every BFF-bound request the SDK makes goes through one {@link FetchLike}. This
+ * module wraps that fetch so a transient failure — an HTTP 429 (rate limited),
+ * a 500/502/503/504 (server hiccup), a 529 (upstream overloaded), or a network
+ * error — is retried with BOUNDED exponential backoff + full jitter, honoring
+ * the server's `Retry-After` header when present. Non-retryable 4xx responses
+ * (400/401/403/404/…) fail fast — retrying them only wastes the caller's time.
+ *
+ * Retries are SAFE to enable by default because the billable submits
+ * (`createSession` / `sendSessionMessage`) carry a stable `Idempotency-Key`
+ * header: re-sending the identical request de-duplicates server-side, so a retry
+ * never creates a duplicate billable turn.
+ *
+ * When retries are exhausted on a rate-limit / overloaded status the wrapper
+ * surfaces an {@link AexRateLimitError} — a structured, non-leaky throttle error
+ * carrying the parsed `retryAfterMs`, the attempt count, and (when the runtime
+ * supplies it) an upstream {@link ProviderFault}. All other exhausted retries
+ * fall through to the transport's usual `AexApiError` / network rejection.
+ */
+import { AexApiError, type FetchLike } from "./_contracts/index.js";
+/**
+ * HTTP statuses that are transient and worth retrying. The billable submits
+ * carry an idempotency key, so re-issuing them is safe. Everything not in this
+ * set (400/401/403/404/409/422/…) is a definitive client error and fails fast.
+ */
+export declare const RETRYABLE_STATUS: readonly number[];
+/**
+ * The subset of {@link RETRYABLE_STATUS} the platform / upstream provider uses to
+ * say "slow down": 429 rate-limit, 503 unavailable, 529 overloaded. When retries
+ * for one of these run out, the wrapper raises an {@link AexRateLimitError}.
+ */
+export declare const RATE_LIMIT_STATUS: readonly number[];
+/**
+ * Tunes the built-in retry loop. All fields are optional; omit the whole
+ * `retry` option (or pass `retry: false` on the client) to accept the defaults
+ * or turn the loop off entirely.
+ */
+export interface RetryOptions {
+    /**
+     * Maximum attempts INCLUDING the first try. Default `4` (one try + three
+     * retries). `1` performs a single attempt with no retries (but still maps a
+     * final rate-limit status to {@link AexRateLimitError}).
+     */
+    readonly maxAttempts?: number;
+    /**
+     * Base delay (ms) for the exponential backoff — the nominal wait before the
+     * first retry, doubling each subsequent retry. Default `500`.
+     */
+    readonly initialDelayMs?: number;
+    /** Upper bound (ms) on any single backoff wait. Default `20_000`. */
+    readonly maxDelayMs?: number;
+    /**
+     * Overall wall-clock budget (ms) across all attempts. Once the next backoff
+     * would push past this, the loop stops and surfaces the last error. Default
+     * `120_000`.
+     */
+    readonly maxElapsedMs?: number;
+}
+interface ResolvedRetryConfig {
+    readonly maxAttempts: number;
+    readonly initialDelayMs: number;
+    readonly maxDelayMs: number;
+    readonly maxElapsedMs: number;
+}
+/** Resolve caller options over the defaults, clamping to sane bounds. */
+export declare function resolveRetryConfig(options: RetryOptions | undefined): ResolvedRetryConfig;
+export declare function isRetryableStatus(status: number): boolean;
+export declare function isRateLimitStatus(status: number): boolean;
+/**
+ * Parse an HTTP `Retry-After` header into milliseconds. Per RFC 7231 the value
+ * is either a non-negative integer number of seconds or an HTTP-date; both are
+ * handled. Returns `undefined` for a missing or unparseable value.
+ */
+export declare function parseRetryAfterMs(headerValue: string | null | undefined, now?: number): number | undefined;
+/**
+ * Full-jitter exponential backoff (AWS-style): the nominal wait doubles per
+ * retry up to `maxDelayMs`, and the actual wait is a uniform sample in
+ * `[0, nominal]` to de-correlate concurrent clients. `attemptNumber` is the
+ * 1-based number of the attempt that just failed.
+ */
+export declare function computeBackoffDelayMs(config: ResolvedRetryConfig, attemptNumber: number, random: () => number): number;
+/**
+ * A structured, redaction-safe description of an UPSTREAM provider fault the aex
+ * runtime surfaces on a failed turn (a rate limit, an overloaded provider, a
+ * quota exhaustion, or a generic provider error). It is a sibling of the
+ * API-plane throttle: the container/runtime emits this shape on the terminal
+ * error and the SDK re-exposes it on {@link AexRateLimitError.providerFault} so
+ * callers get one place to read "the model provider throttled us".
+ */
+export interface ProviderFault {
+    /** Upstream provider id, e.g. `"anthropic"`, when the runtime reports one. */
+    readonly provider?: string;
+    /** Coarse fault class. */
+    readonly kind: "rate_limit" | "overloaded" | "quota_exceeded" | "provider_error";
+    /** Upstream HTTP status when the provider surfaced one (e.g. `429`, `529`). */
+    readonly status?: number;
+    /** Milliseconds the upstream asked the caller to wait, when it supplied one. */
+    readonly retryAfterMs?: number;
+    /** Short, already-redacted upstream message. */
+    readonly message?: string;
+}
+/** True when a {@link ProviderFault} represents a "back off and retry" signal. */
+export declare function isThrottleFault(fault: ProviderFault): boolean;
+/**
+ * Structured throttle error. Extends {@link AexApiError} so existing
+ * `catch (err instanceof AexApiError)` sites keep working, while callers that
+ * want the details narrow with {@link isRateLimited} and read `retryAfterMs`,
+ * `attempts`, `source`, and `providerFault`. The `message` is a fixed,
+ * non-leaky summary — it never echoes the raw error body (which is still
+ * available, redacted, on `.body`).
+ */
+export declare class AexRateLimitError extends AexApiError {
+    /** Milliseconds the server/provider asked us to wait, when known. */
+    readonly retryAfterMs?: number;
+    /** How many attempts were made before giving up. */
+    readonly attempts: number;
+    /** Whether the throttle came from the aex API plane or the upstream provider. */
+    readonly source: "api" | "provider";
+    /** The upstream provider fault, when the throttle originated there. */
+    readonly providerFault?: ProviderFault;
+    constructor(args: {
+        readonly status: number;
+        readonly attempts: number;
+        readonly retryAfterMs?: number;
+        readonly source?: "api" | "provider";
+        readonly providerFault?: ProviderFault;
+        readonly body?: unknown;
+        readonly message?: string;
+    });
+}
+/** Type guard for {@link AexRateLimitError}. */
+export declare function isRateLimited(err: unknown): err is AexRateLimitError;
+/**
+ * Best-effort parse of an unknown value into a {@link ProviderFault}. Tolerant
+ * of two shapes so the SDK consumes the runtime fault the moment it starts
+ * emitting one, without a contracts change:
+ *
+ *   1. The canonical `{ provider?, kind, status?, retryAfterMs?, message? }`
+ *      (optionally nested under a `providerFault` key), OR
+ *   2. A raw upstream error `{ type: "rate_limit_error" | "overloaded_error"
+ *      | ..., message?, retry_after? | retryAfter? }` — `type` maps to `kind`
+ *      and `retry_after` (seconds) maps to `retryAfterMs`.
+ *
+ * Returns `undefined` when the value carries no recognizable fault.
+ */
+export declare function parseProviderFault(value: unknown): ProviderFault | undefined;
+/** Hooks the retry loop needs, injectable so tests run without real timers. */
+export interface RetryDeps {
+    readonly sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    readonly random?: () => number;
+    readonly now?: () => number;
+}
+/**
+ * Wrap a {@link FetchLike} with the bounded-retry loop. `retry === false`
+ * disables the layer entirely (the input fetch is returned unchanged). Otherwise
+ * the returned fetch retries transient failures per {@link RetryOptions} and, on
+ * an exhausted rate-limit/overloaded status, throws {@link AexRateLimitError}.
+ */
+export declare function withRetry(fetchImpl: FetchLike, retry: RetryOptions | false | undefined, deps?: RetryDeps): FetchLike;
+export {};

package/dist/retry.js

@@ -0,0 +1,320 @@
+/**
+ * Built-in transport resilience for the aex SDK.
+ *
+ * Every BFF-bound request the SDK makes goes through one {@link FetchLike}. This
+ * module wraps that fetch so a transient failure — an HTTP 429 (rate limited),
+ * a 500/502/503/504 (server hiccup), a 529 (upstream overloaded), or a network
+ * error — is retried with BOUNDED exponential backoff + full jitter, honoring
+ * the server's `Retry-After` header when present. Non-retryable 4xx responses
+ * (400/401/403/404/…) fail fast — retrying them only wastes the caller's time.
+ *
+ * Retries are SAFE to enable by default because the billable submits
+ * (`createSession` / `sendSessionMessage`) carry a stable `Idempotency-Key`
+ * header: re-sending the identical request de-duplicates server-side, so a retry
+ * never creates a duplicate billable turn.
+ *
+ * When retries are exhausted on a rate-limit / overloaded status the wrapper
+ * surfaces an {@link AexRateLimitError} — a structured, non-leaky throttle error
+ * carrying the parsed `retryAfterMs`, the attempt count, and (when the runtime
+ * supplies it) an upstream {@link ProviderFault}. All other exhausted retries
+ * fall through to the transport's usual `AexApiError` / network rejection.
+ */
+import { AexApiError } from "./_contracts/index.js";
+/**
+ * HTTP statuses that are transient and worth retrying. The billable submits
+ * carry an idempotency key, so re-issuing them is safe. Everything not in this
+ * set (400/401/403/404/409/422/…) is a definitive client error and fails fast.
+ */
+export const RETRYABLE_STATUS = [429, 500, 502, 503, 504, 529];
+/**
+ * The subset of {@link RETRYABLE_STATUS} the platform / upstream provider uses to
+ * say "slow down": 429 rate-limit, 503 unavailable, 529 overloaded. When retries
+ * for one of these run out, the wrapper raises an {@link AexRateLimitError}.
+ */
+export const RATE_LIMIT_STATUS = [429, 503, 529];
+const DEFAULT_RETRY = {
+    maxAttempts: 4,
+    initialDelayMs: 500,
+    maxDelayMs: 20_000,
+    maxElapsedMs: 120_000
+};
+/** Resolve caller options over the defaults, clamping to sane bounds. */
+export function resolveRetryConfig(options) {
+    const maxAttempts = Math.max(1, Math.floor(options?.maxAttempts ?? DEFAULT_RETRY.maxAttempts));
+    const initialDelayMs = Math.max(0, options?.initialDelayMs ?? DEFAULT_RETRY.initialDelayMs);
+    const maxDelayMs = Math.max(initialDelayMs, options?.maxDelayMs ?? DEFAULT_RETRY.maxDelayMs);
+    const maxElapsedMs = Math.max(0, options?.maxElapsedMs ?? DEFAULT_RETRY.maxElapsedMs);
+    return { maxAttempts, initialDelayMs, maxDelayMs, maxElapsedMs };
+}
+export function isRetryableStatus(status) {
+    return RETRYABLE_STATUS.includes(status);
+}
+export function isRateLimitStatus(status) {
+    return RATE_LIMIT_STATUS.includes(status);
+}
+/**
+ * Parse an HTTP `Retry-After` header into milliseconds. Per RFC 7231 the value
+ * is either a non-negative integer number of seconds or an HTTP-date; both are
+ * handled. Returns `undefined` for a missing or unparseable value.
+ */
+export function parseRetryAfterMs(headerValue, now = Date.now()) {
+    if (headerValue === null || headerValue === undefined)
+        return undefined;
+    const trimmed = headerValue.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    if (/^\d+$/.test(trimmed)) {
+        return Number(trimmed) * 1000;
+    }
+    const dateMs = Date.parse(trimmed);
+    if (!Number.isNaN(dateMs)) {
+        return Math.max(0, dateMs - now);
+    }
+    return undefined;
+}
+/**
+ * Full-jitter exponential backoff (AWS-style): the nominal wait doubles per
+ * retry up to `maxDelayMs`, and the actual wait is a uniform sample in
+ * `[0, nominal]` to de-correlate concurrent clients. `attemptNumber` is the
+ * 1-based number of the attempt that just failed.
+ */
+export function computeBackoffDelayMs(config, attemptNumber, random) {
+    const exponent = Math.max(0, attemptNumber - 1);
+    const nominal = Math.min(config.maxDelayMs, config.initialDelayMs * 2 ** exponent);
+    return Math.round(random() * nominal);
+}
+/** Combine the server's `Retry-After` (a floor) with our jittered backoff. */
+function nextDelayMs(config, attemptNumber, random, retryAfterMs) {
+    const backoff = computeBackoffDelayMs(config, attemptNumber, random);
+    return retryAfterMs === undefined ? backoff : Math.max(retryAfterMs, backoff);
+}
+const THROTTLE_KINDS = new Set(["rate_limit", "overloaded", "quota_exceeded"]);
+/** True when a {@link ProviderFault} represents a "back off and retry" signal. */
+export function isThrottleFault(fault) {
+    return THROTTLE_KINDS.has(fault.kind);
+}
+/**
+ * Structured throttle error. Extends {@link AexApiError} so existing
+ * `catch (err instanceof AexApiError)` sites keep working, while callers that
+ * want the details narrow with {@link isRateLimited} and read `retryAfterMs`,
+ * `attempts`, `source`, and `providerFault`. The `message` is a fixed,
+ * non-leaky summary — it never echoes the raw error body (which is still
+ * available, redacted, on `.body`).
+ */
+export class AexRateLimitError extends AexApiError {
+    /** Milliseconds the server/provider asked us to wait, when known. */
+    retryAfterMs;
+    /** How many attempts were made before giving up. */
+    attempts;
+    /** Whether the throttle came from the aex API plane or the upstream provider. */
+    source;
+    /** The upstream provider fault, when the throttle originated there. */
+    providerFault;
+    constructor(args) {
+        super(args.status, args.message ?? defaultThrottleMessage(args), args.body);
+        this.attempts = args.attempts;
+        this.source = args.source ?? "api";
+        if (args.retryAfterMs !== undefined)
+            this.retryAfterMs = args.retryAfterMs;
+        if (args.providerFault !== undefined)
+            this.providerFault = args.providerFault;
+    }
+}
+/** Type guard for {@link AexRateLimitError}. */
+export function isRateLimited(err) {
+    return err instanceof AexRateLimitError;
+}
+function defaultThrottleMessage(args) {
+    const who = args.source === "provider" ? "upstream provider" : "aex API";
+    const label = args.status === 529 ? "overloaded" : "rate limit reached";
+    const attempts = `${args.attempts} attempt${args.attempts === 1 ? "" : "s"}`;
+    const wait = args.retryAfterMs !== undefined
+        ? `; retry after ~${Math.ceil(args.retryAfterMs / 1000)}s`
+        : "";
+    return `${who} ${label} (HTTP ${args.status}) after ${attempts}${wait}`;
+}
+/**
+ * Best-effort parse of an unknown value into a {@link ProviderFault}. Tolerant
+ * of two shapes so the SDK consumes the runtime fault the moment it starts
+ * emitting one, without a contracts change:
+ *
+ *   1. The canonical `{ provider?, kind, status?, retryAfterMs?, message? }`
+ *      (optionally nested under a `providerFault` key), OR
+ *   2. A raw upstream error `{ type: "rate_limit_error" | "overloaded_error"
+ *      | ..., message?, retry_after? | retryAfter? }` — `type` maps to `kind`
+ *      and `retry_after` (seconds) maps to `retryAfterMs`.
+ *
+ * Returns `undefined` when the value carries no recognizable fault.
+ */
+export function parseProviderFault(value) {
+    if (value === null || typeof value !== "object")
+        return undefined;
+    const record = value;
+    const nested = record.providerFault ?? record.provider_fault;
+    if (nested !== undefined && nested !== value) {
+        const fromNested = parseProviderFault(nested);
+        if (fromNested)
+            return fromNested;
+    }
+    const kind = coerceFaultKind(record.kind ?? record.type ?? record.code);
+    if (kind === undefined)
+        return undefined;
+    const provider = typeof record.provider === "string" ? record.provider : undefined;
+    const status = coerceStatus(record.status ?? record.statusCode ?? record.httpStatus);
+    const retryAfterMs = coerceRetryAfterMs(record.retryAfterMs ?? record.retry_after_ms ?? record.retryAfter ?? record.retry_after);
+    const message = typeof record.message === "string" ? record.message : undefined;
+    return {
+        kind,
+        ...(provider !== undefined ? { provider } : {}),
+        ...(status !== undefined ? { status } : {}),
+        ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
+        ...(message !== undefined ? { message } : {})
+    };
+}
+function coerceFaultKind(raw) {
+    if (typeof raw !== "string")
+        return undefined;
+    const value = raw.toLowerCase();
+    if (value.includes("rate_limit") || value.includes("rate limit") || value === "429")
+        return "rate_limit";
+    if (value.includes("overload") || value === "529")
+        return "overloaded";
+    if (value.includes("quota") || value.includes("insufficient"))
+        return "quota_exceeded";
+    if (value.includes("provider_error") || value.includes("provider error") || value.includes("api_error")) {
+        return "provider_error";
+    }
+    return undefined;
+}
+function coerceStatus(raw) {
+    if (typeof raw === "number" && Number.isFinite(raw))
+        return raw;
+    if (typeof raw === "string" && /^\d+$/.test(raw.trim()))
+        return Number(raw.trim());
+    return undefined;
+}
+/** Accept a ms number, a `<digits>` string, or seconds under a `retry_after` alias. */
+function coerceRetryAfterMs(raw) {
+    if (typeof raw === "number" && Number.isFinite(raw)) {
+        // Heuristic: small integers are seconds (the upstream convention), large
+        // ones are already milliseconds.
+        return raw > 0 && raw < 1000 ? raw * 1000 : raw;
+    }
+    if (typeof raw === "string" && /^\d+$/.test(raw.trim())) {
+        const n = Number(raw.trim());
+        return n > 0 && n < 1000 ? n * 1000 : n;
+    }
+    return undefined;
+}
+const defaultSleep = (ms, signal) => new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+        reject(signal.reason instanceof Error ? signal.reason : new DOMException("Aborted", "AbortError"));
+        return;
+    }
+    const timer = setTimeout(() => {
+        signal?.removeEventListener("abort", onAbort);
+        resolve();
+    }, ms);
+    const onAbort = () => {
+        clearTimeout(timer);
+        reject(signal?.reason instanceof Error ? signal.reason : new DOMException("Aborted", "AbortError"));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+});
+function isAbortError(err) {
+    return err instanceof Error && err.name === "AbortError";
+}
+async function drain(response) {
+    try {
+        if (response.body && typeof response.body.cancel === "function") {
+            await response.body.cancel();
+            return;
+        }
+        await response.text();
+    }
+    catch {
+        // Draining is best-effort; a discarded retryable response never surfaces.
+    }
+}
+async function readBodyForError(response) {
+    try {
+        const text = await response.text();
+        if (text.length === 0)
+            return {};
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return { raw: text };
+        }
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Wrap a {@link FetchLike} with the bounded-retry loop. `retry === false`
+ * disables the layer entirely (the input fetch is returned unchanged). Otherwise
+ * the returned fetch retries transient failures per {@link RetryOptions} and, on
+ * an exhausted rate-limit/overloaded status, throws {@link AexRateLimitError}.
+ */
+export function withRetry(fetchImpl, retry, deps = {}) {
+    if (retry === false)
+        return fetchImpl;
+    const config = resolveRetryConfig(retry);
+    const sleep = deps.sleep ?? defaultSleep;
+    const random = deps.random ?? Math.random;
+    const now = deps.now ?? Date.now;
+    return async (input, init) => {
+        const startedAt = now();
+        const signal = init?.signal ?? undefined;
+        let attempt = 0;
+        for (;;) {
+            attempt += 1;
+            let response;
+            try {
+                response = await fetchImpl(input, init);
+            }
+            catch (err) {
+                // A caller-initiated abort is terminal, never transient.
+                if (isAbortError(err))
+                    throw err;
+                if (attempt >= config.maxAttempts)
+                    throw err;
+                const delay = computeBackoffDelayMs(config, attempt, random);
+                if (now() - startedAt + delay > config.maxElapsedMs)
+                    throw err;
+                await sleep(delay, signal ?? undefined);
+                continue;
+            }
+            // Success or a definitive (non-retryable) response — hand straight back so
+            // the transport reads/throws exactly as it does without the retry layer.
+            if (!isRetryableStatus(response.status)) {
+                return response;
+            }
+            const retryAfterMs = parseRetryAfterMs(response.headers.get("retry-after"), now());
+            const willRetry = attempt < config.maxAttempts &&
+                now() - startedAt + nextDelayMs(config, attempt, random, retryAfterMs) <= config.maxElapsedMs;
+            if (willRetry) {
+                await drain(response);
+                await sleep(nextDelayMs(config, attempt, random, retryAfterMs), signal ?? undefined);
+                continue;
+            }
+            // Retries exhausted (or budget spent). A rate-limit/overloaded status
+            // becomes a structured throttle error; any other transient status falls
+            // through to the transport's normal AexApiError.
+            if (isRateLimitStatus(response.status)) {
+                const body = await readBodyForError(response);
+                throw new AexRateLimitError({
+                    status: response.status,
+                    attempts: attempt,
+                    source: "api",
+                    ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
+                    body
+                });
+            }
+            return response;
+        }
+    };
+}
+//# sourceMappingURL=retry.js.map

package/dist/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"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"}

package/dist/secret.d.ts

@@ -26,19 +26,19 @@ export interface SecretUploader {
     }>;
 }
 /**
- * A secret with the SAME lifecycle semantic as `Skill` / `File` / `AgentsMd`:
+ * A secret with the SAME lifecycle semantic as `File` / `AgentsMd`:
  * EPHEMERAL per-run by default, PROMOTABLE to a persisted, name-searchable
  * workspace secret you can reference and reuse.
  *
- *   - `Secret.value(v)` — EPHEMERAL per-run: the value is vaulted at submit and
+ *   - `Secret.value(v)` — EPHEMERAL per-run: the value is vaulted when the session is created and
  *     excluded from the idempotency hash; only a `{ ephemeral: true }`
  *     placeholder rides the (hashed) submission. Deleted when the run finishes.
- *     Clean, no workspace dependency. ≙ `Skill.fromFiles(...)` (a draft).
+ *     Clean, no workspace dependency. ≙ `File.fromBytes(...)` (a draft).
  *   - `secret.upload(client, { name })` — PROMOTE that value into the workspace
- *     secret store under `name`; resolves to a `Secret.ref`. ≙ `skill.upload(client)`.
+ *     secret store under `name`; resolves to a `Secret.ref`.
  *   - `Secret.ref(handle)` — WORKSPACE: only the handle rides the submission;
  *     the value is resolved server-side from the workspace secret store. No
- *     value ever travels. ≙ `Skill.fromCatalog(record)`.
+ *     value ever travels.
  *
  * The SDK splits each `Secret` BEFORE the wire payload is built (exactly how
  * `McpServer` splits `headers` into `secrets.mcpServers`): the env-var name keys
@@ -58,9 +58,9 @@ export declare class Secret {
         readonly kind: "ref";
         readonly handle: string;
     });
-    /** Ephemeral per-run value. Vaulted at submit; never in the spec/hash; gone at terminal. */
+    /** Ephemeral per-run value. Vaulted when the session is created; never in the spec/hash; gone at terminal. */
     static value(value: string | SecretString): Secret;
-    /** Reference a workspace secret by handle; resolved server-side at submit. */
+    /** Reference a workspace secret by handle; resolved server-side when the session is created. */
     static ref(handle: string): Secret;
     /** True once this ephemeral secret has been promoted via `upload`. */
     get isConsumed(): boolean;
@@ -68,7 +68,7 @@ export declare class Secret {
      * Promote this EPHEMERAL secret into the workspace secret store under `name`
      * and return a `Secret.ref(name)` for reuse across runs. Blocking: the store
      * write completes before this resolves. Consumes this instance (an ephemeral
-     * value is promoted exactly once), mirroring `Skill.upload`.
+     * value is promoted exactly once).
      *
      * Only valid on a `Secret.value(...)`; a `Secret.ref(...)` is already
      * persisted.

package/dist/secret.js

@@ -1,18 +1,18 @@
 import { SECRET_ENV_NAME_PATTERN, SECRET_HANDLE_PATTERN, SecretString } from "./_contracts/index.js";
 /**
- * A secret with the SAME lifecycle semantic as `Skill` / `File` / `AgentsMd`:
+ * A secret with the SAME lifecycle semantic as `File` / `AgentsMd`:
  * EPHEMERAL per-run by default, PROMOTABLE to a persisted, name-searchable
  * workspace secret you can reference and reuse.
  *
- *   - `Secret.value(v)` — EPHEMERAL per-run: the value is vaulted at submit and
+ *   - `Secret.value(v)` — EPHEMERAL per-run: the value is vaulted when the session is created and
  *     excluded from the idempotency hash; only a `{ ephemeral: true }`
  *     placeholder rides the (hashed) submission. Deleted when the run finishes.
- *     Clean, no workspace dependency. ≙ `Skill.fromFiles(...)` (a draft).
+ *     Clean, no workspace dependency. ≙ `File.fromBytes(...)` (a draft).
  *   - `secret.upload(client, { name })` — PROMOTE that value into the workspace
- *     secret store under `name`; resolves to a `Secret.ref`. ≙ `skill.upload(client)`.
+ *     secret store under `name`; resolves to a `Secret.ref`.
  *   - `Secret.ref(handle)` — WORKSPACE: only the handle rides the submission;
  *     the value is resolved server-side from the workspace secret store. No
- *     value ever travels. ≙ `Skill.fromCatalog(record)`.
+ *     value ever travels.
  *
  * The SDK splits each `Secret` BEFORE the wire payload is built (exactly how
  * `McpServer` splits `headers` into `secrets.mcpServers`): the env-var name keys
@@ -44,7 +44,7 @@ export class Secret {
         this.handle = undefined;
         this.#value = args.value;
     }
-    /** Ephemeral per-run value. Vaulted at submit; never in the spec/hash; gone at terminal. */
+    /** Ephemeral per-run value. Vaulted when the session is created; never in the spec/hash; gone at terminal. */
     static value(value) {
         const wrapped = value instanceof SecretString ? value : new SecretString(value, "secret");
         if (!wrapped.unwrap()) {
@@ -52,7 +52,7 @@ export class Secret {
         }
         return new Secret({ kind: "value", value: wrapped });
     }
-    /** Reference a workspace secret by handle; resolved server-side at submit. */
+    /** Reference a workspace secret by handle; resolved server-side when the session is created. */
     static ref(handle) {
         return new Secret({ kind: "ref", handle });
     }
@@ -64,7 +64,7 @@ export class Secret {
      * Promote this EPHEMERAL secret into the workspace secret store under `name`
      * and return a `Secret.ref(name)` for reuse across runs. Blocking: the store
      * write completes before this resolves. Consumes this instance (an ephemeral
-     * value is promoted exactly once), mirroring `Skill.upload`.
+     * value is promoted exactly once).
      *
      * Only valid on a `Secret.value(...)`; a `Secret.ref(...)` is already
      * persisted.

package/dist/secret.js.map

@@ -1 +1 @@
-{"version":3,"file":"secret.js","sourceRoot":"","sources":["../src/secret.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"secret.js","sourceRoot":"","sources":["../src/secret.ts"],"names":[],"mappings":"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"}