@aexhq/sdk 0.38.1 → 0.40.0

package/dist/_contracts/runtime-types.d.ts

@@ -1,4 +1,5 @@
-import type { SessionStatus } from "./status.js";
+import type { SessionStatus, SessionTerminalOutcome } from "./status.js";
+import type { RunCostProviderUsage } from "./run-cost.js";
 import type { PlatformRunSubmissionInput, PlatformSubmission } from "./submission.js";
 /**
  * Loose record describing a run as the dashboard BFF returns it. Concrete
@@ -37,6 +38,12 @@ export interface Run {
      */
     readonly usage?: UsageSummary;
     readonly costTelemetry?: import("./run-cost.js").RunCostTelemetry;
+    /**
+     * The authoritative terminal OUTCOME of the run's last turn — the settle-
+     * written outcome (`succeeded`/`failed`/`timed_out`/`cancelled`), distinct
+     * from the resumable lifecycle {@link status}. Absent until the run settles.
+     */
+    readonly lastTurnOutcome?: SessionTerminalOutcome;
     readonly runtimeManifest?: import("./runtime-manifest.js").RuntimeManifest;
     readonly [key: string]: unknown;
 }
@@ -68,9 +75,17 @@ export interface Session {
     readonly retainedStorageBytes?: number;
     readonly usage?: UsageSummary;
     readonly costUsd?: number;
+    /**
+     * The authoritative terminal OUTCOME of the session's last turn — the
+     * settle-written outcome (`succeeded`/`failed`/`timed_out`/`cancelled`),
+     * distinct from the resumable lifecycle {@link status} (`idle`/`suspended`).
+     * A cancelled turn reads `cancelled` here even though the session may park
+     * `idle`; absent until the turn settles.
+     */
+    readonly lastTurnOutcome?: SessionTerminalOutcome;
     readonly errorMessage?: string | null;
     /**
-     * Settle-written failure taxonomy for an `error` session (e.g.
+     * Settle-written failure taxonomy for a `failed` session (e.g.
      * `provider-permanent`, `budget_exhausted`) — the class a caller can branch
      * on, complementing the human-readable `errorMessage`.
      */
@@ -158,6 +173,77 @@ export interface UsageSummary {
     readonly cacheCreationInputTokens?: number;
     readonly totalTokens?: number;
 }
+/**
+ * Project a {@link UsageSummary} from the settle-written
+ * {@link RunCostProviderUsage} entries — the SINGLE server source of token
+ * usage ({@link Run.costTelemetry}`.providerUsage`). Sums each field across all
+ * provider entries; a field is present only when at least one entry carried it.
+ * This retires the dead `session.usage` / `aex.usage`-event usage path: the SDK
+ * derives usage from cost telemetry, never re-reads a dual-written top-level
+ * `usage`. Pure.
+ */
+export declare function usageFromProviderUsage(providerUsage: readonly RunCostProviderUsage[] | undefined): UsageSummary;
+/**
+ * The unified SETTLED-RESULT contract shared by `run()` and `done()`. Because
+ * both await the settle commit by default, these fields are ALWAYS present at a
+ * terminal read — they are NON-optional, so a code path that forgets to
+ * populate `costUsd`/`usage`/the terminal `status` fails to typecheck. The SDK
+ * `RunResult`/`SessionTurnResult` extend this one shape so `done()` == `run()`.
+ *
+ * `costUsd` is the AEX showback estimate in USD (>= 0) and EXCLUDES the
+ * customer's BYOK provider spend — price BYOK from `usage` tokens.
+ */
+export interface SettledResult {
+    /** The terminal outcome (never a bare resumable `idle`). */
+    readonly status: SessionTerminalOutcome;
+    /** `succeeded` ⇒ true; `failed`/`timed_out`/`cancelled` ⇒ false. */
+    readonly ok: boolean;
+    /** AEX showback estimate (USD, >= 0). Excludes BYOK provider spend. */
+    readonly costUsd: number;
+    /** Aggregate token usage, derived from `costTelemetry.providerUsage`. */
+    readonly usage: UsageSummary;
+    /** Terminal failure message (from the terminal `RUN_ERROR` event) when `!ok`. */
+    readonly error?: string;
+}
+/**
+ * The reason a schema-constrained decode did not yield a value:
+ *   - `schema_violation` — the model output failed schema validation.
+ *   - `uncertain` — the model signalled low confidence / declined to commit.
+ *   - `refused` — the model refused the request.
+ */
+export type RunRefusalReason = "schema_violation" | "uncertain" | "refused";
+/**
+ * The typed outcome of a `run<T>({ responseFormat })`: EITHER a schema-valid
+ * decoded value OR a typed refusal — there is no untyped path that silently
+ * yields a hallucinated object. `T` is the decoded value type.
+ */
+export type RunOutcome<T = unknown> = {
+    readonly kind: "decoded";
+    readonly value: T;
+} | {
+    readonly kind: "refused";
+    readonly reason: RunRefusalReason;
+    readonly detail?: string;
+};
+/** One item's settled result inside a {@link BatchResult}. */
+export interface BatchItemResult<T = unknown> extends SettledResult {
+    readonly runId: string;
+    /** Present only for a `responseFormat`-decoded item. */
+    readonly outcome?: RunOutcome<T>;
+}
+/**
+ * The result of `aex.batch(items, …)`: every item's settled result PLUS a real
+ * rollup. The rollup is honest because `run()` awaits settle, so every item's
+ * `costUsd`/`usage` is populated — a missing cost is a typed absent, not a
+ * silent `$0`.
+ */
+export interface BatchResult<T = unknown> {
+    readonly results: readonly BatchItemResult<T>[];
+    readonly totalCostUsd: number;
+    readonly totalUsage: UsageSummary;
+    readonly okCount: number;
+    readonly failed: readonly BatchItemResult<T>[];
+}
 /**
  * Filters for {@link import("./operations.js").listRuns} / the CLI's `aex runs`.
  * Every field is optional; omitting all of them lists the most recent runs in the
@@ -192,6 +278,37 @@ export interface RunListPage {
     readonly runs: readonly RunSummary[];
     readonly nextCursor?: string;
 }
+/**
+ * The minimal capability a value must carry to be RESOLVABLE through the run
+ * facade — `getRun` / `listRunEvents` / `listOutputs` all key on this `id`.
+ * Encodes the "handed ⇒ resolvable" invariant at the type level: anything the
+ * platform hands you as a run reference exposes a resolvable `id`, so a run can
+ * never be surfaced as a bare unresolvable string.
+ */
+export interface ResolvableRunRef {
+    readonly id: string;
+}
+/**
+ * A subagent CHILD run, enumerated under its parent via `GET /runs/:id/children`.
+ * A first-class, lineage-discoverable run reference: it {@link ResolvableRunRef}
+ * (its `id` resolves through the run facade — events/outputs/getRun), carries the
+ * lineage (`parentRunId`/`depth`) and the terminal outcome/cost, so a child is
+ * observable exactly like a top-level run.
+ */
+export interface ChildRunRef extends ResolvableRunRef {
+    /** The parent run this child was spawned by. */
+    readonly parentRunId: string;
+    /** The child's run status. */
+    readonly status: string;
+    /** Subagent nesting depth (1 = direct child of the top-level run). */
+    readonly depth?: number;
+    /** Settled AEX showback estimate (USD) for the child, when present. */
+    readonly costUsd?: number;
+    readonly createdAt?: string;
+    readonly terminalAt?: string | null;
+    /** The child's terminal outcome once settled. */
+    readonly lastTurnOutcome?: SessionTerminalOutcome;
+}
 /**
  * Cross-run output search query (`Aex.sessions.searchOutputs`). Restrict to a
  * corpus with `runIds`; filter by filename substring / extension / content type.
@@ -202,8 +319,13 @@ export interface RunListPage {
 export interface OutputSearchQuery {
     /** Restrict the search to these runs (the chat corpus allow-list). */
     readonly runIds?: readonly string[];
-    /** Case-insensitive substring match on the output filename. */
-    readonly filename?: string;
+    /**
+     * Filename match. A string is a case-insensitive SUBSTRING match; a RegExp is
+     * tested as given. Unified with {@link OutputQuery.filename} (`string | RegExp`)
+     * so the same value works on `find()` and `search()` — feed it through
+     * {@link import("./operations.js").toFilenameMatcher} rather than assuming a string.
+     */
+    readonly filename?: string | RegExp;
     /** File extension, with or without a leading dot. Case-insensitive. */
     readonly extension?: string;
     /** Exact content type or a prefix wildcard such as `image/*`. */
@@ -223,38 +345,6 @@ export interface OutputSearchHit {
 export interface OutputSearchPage {
     readonly hits: readonly OutputSearchHit[];
 }
-/**
- * A run event as recorded by the dashboard. Includes the `type` field
- * that the `is*Event` type guards narrow on plus any provider payload.
- *
- * The unified-stream discriminators (`channel`, `source`, `sourceSeq`,
- * `emittedAt`, `receivedAt`, `level`) carry through from the coordinator
- * envelope (see `event-envelope.ts` —
- * {@link import("./event-envelope.js").AexEvent}) so SDK/CLI consumers can
- * split/filter the one stream by channel or source. All are OPTIONAL: archived
- * events from before the unification (and any producer that omits an ordering
- * attribute) lack them, an absent `channel` means `"event"` (see `channelOf`),
- * and `level` is present only on `log`-channel records.
- */
-export interface RunEvent {
-    readonly id: string;
-    readonly type: string;
-    readonly runId?: string;
-    readonly recordedAt?: string;
-    /** Which sub-stream this record rides — `"event"` (typed) or `"log"`. Absent ⇒ `"event"`. */
-    readonly channel?: import("./event-envelope.js").AexEventChannel;
-    /** Coarse origin classifier. See {@link AexEventSource}. */
-    readonly source?: import("./event-envelope.js").AexEventSource;
-    /** Per-source monotonic counter assigned at the source (carried, not re-ordered). */
-    readonly sourceSeq?: number;
-    /** Source wall-clock ms at emit (carried for a best-effort client time view). */
-    readonly emittedAt?: number;
-    /** The DO's authoritative receive-time (wall-clock ms) stamped at ingest, companion to `seq`. */
-    readonly receivedAt?: number;
-    /** Log severity, first-class on a `channel: "log"` record ("info" | "warn" | "error"). */
-    readonly level?: import("./event-envelope.js").AexLogLevel;
-    readonly [key: string]: unknown;
-}
 /** Status of a per-run webhook delivery. Terminal: delivered/exhausted/invalid. */
 export type RunWebhookDeliveryStatus = "pending" | "delivering" | "retrying" | "delivered" | "exhausted" | "invalid";
 /**
@@ -508,6 +598,28 @@ export interface FileRecord {
     readonly finalizedAt?: string | null;
     readonly [key: string]: unknown;
 }
+/**
+ * Wire-level metadata record for a workspace skill as returned by the BFF.
+ *
+ * Workspace skills are named, mutable, by-name-bound bundles: `skill.upload()`
+ * upserts one under a stable `name`; a run references it by that name and the
+ * platform resolves it to the CURRENT bytes at submit time. This record is
+ * METADATA ONLY — the bytes live in the content-addressed asset store keyed by
+ * `contentHash`. `version` bumps each time the bytes change under the name.
+ */
+export interface SkillRecord {
+    readonly id?: string;
+    readonly kind?: "skill";
+    readonly name: string;
+    readonly contentHash: string;
+    readonly description: string;
+    readonly sizeBytes?: number | null;
+    readonly version?: number;
+    readonly createdAt?: string;
+    readonly updatedAt?: string;
+    readonly deletedAt?: string | null;
+    readonly [key: string]: unknown;
+}
 /**
  * Wire-level record for a workspace secret as returned by the BFF.
  *

package/dist/_contracts/runtime-types.js

@@ -1,2 +1,34 @@
-export {};
+/**
+ * Project a {@link UsageSummary} from the settle-written
+ * {@link RunCostProviderUsage} entries — the SINGLE server source of token
+ * usage ({@link Run.costTelemetry}`.providerUsage`). Sums each field across all
+ * provider entries; a field is present only when at least one entry carried it.
+ * This retires the dead `session.usage` / `aex.usage`-event usage path: the SDK
+ * derives usage from cost telemetry, never re-reads a dual-written top-level
+ * `usage`. Pure.
+ */
+export function usageFromProviderUsage(providerUsage) {
+    if (!providerUsage || providerUsage.length === 0)
+        return {};
+    let inputTokens;
+    let outputTokens;
+    let cacheReadInputTokens;
+    let cacheCreationInputTokens;
+    let totalTokens;
+    const add = (acc, value) => value === undefined ? acc : (acc ?? 0) + value;
+    for (const entry of providerUsage) {
+        inputTokens = add(inputTokens, entry.inputTokens);
+        outputTokens = add(outputTokens, entry.outputTokens);
+        cacheReadInputTokens = add(cacheReadInputTokens, entry.cacheReadInputTokens);
+        cacheCreationInputTokens = add(cacheCreationInputTokens, entry.cacheCreationInputTokens);
+        totalTokens = add(totalTokens, entry.totalTokens);
+    }
+    return {
+        ...(inputTokens !== undefined ? { inputTokens } : {}),
+        ...(outputTokens !== undefined ? { outputTokens } : {}),
+        ...(cacheReadInputTokens !== undefined ? { cacheReadInputTokens } : {}),
+        ...(cacheCreationInputTokens !== undefined ? { cacheCreationInputTokens } : {}),
+        ...(totalTokens !== undefined ? { totalTokens } : {})
+    };
+}
 //# sourceMappingURL=runtime-types.js.map

package/dist/_contracts/sdk-errors.d.ts

@@ -1,3 +1,4 @@
+import type { AexApiErrorCode } from "./error-codes.js";
 export type AexErrorCode = "RUN_CONFIG_INVALID" | "CREDENTIAL_INVALID" | "PROVIDER_ERROR" | "RUN_STATE_ERROR" | "CLEANUP_ERROR" | "RUNTIME_UNSUPPORTED" | "API_ERROR" | "NETWORK_ERROR";
 export declare class AexError extends Error {
     readonly code: AexErrorCode;
@@ -27,13 +28,69 @@ export declare class CleanupError extends AexError {
 }
 /**
  * Thrown by SDK and CLI operations when the dashboard BFF returns a non-2xx
- * response. Carries the HTTP status and parsed body for the caller to inspect.
+ * response. Carries the HTTP status, the redacted parsed body, the server's
+ * STABLE {@link AexApiErrorCode} (when present), and a `requestId` for support.
+ * Construct via {@link import("./error-factory.js").apiErrorFromResponse} — the
+ * single wire→exception mapping — which dispatches to a typed subclass
+ * ({@link AexAuthError} / {@link AexIdempotencyConflictError} /
+ * {@link AexNotFoundError} / {@link AexRateLimitError}).
  */
 export declare class AexApiError extends AexError {
     readonly status: number;
     readonly body: unknown;
-    constructor(status: number, message: string, body: unknown);
+    /** The server's stable error code, when the body carried a known one. */
+    readonly apiCode: AexApiErrorCode | undefined;
+    /** Request id (body `requestId` or a response header) for support correlation. */
+    readonly requestId: string | undefined;
+    constructor(status: number, message: string, body: unknown, options?: {
+        readonly apiCode?: AexApiErrorCode | undefined;
+        readonly requestId?: string | undefined;
+        readonly cause?: unknown;
+    });
+}
+/** Shared construction shape for the typed {@link AexApiError} subclasses. */
+export interface AexApiErrorInit {
+    readonly status: number;
+    readonly message: string;
+    readonly body: unknown;
+    readonly apiCode?: AexApiErrorCode | undefined;
+    readonly requestId?: string | undefined;
+    readonly cause?: unknown;
+}
+/** 401/403 auth failure (token invalid/revoked/expired, forbidden, insufficient scope). */
+export declare class AexAuthError extends AexApiError {
+    /** The scope the endpoint required, when the server named it (insufficient_scope). */
+    readonly requiredScope: string | undefined;
+    constructor(init: AexApiErrorInit & {
+        readonly requiredScope?: string | undefined;
+    });
+}
+/** 409 — the idempotency key was reused with a different request body. */
+export declare class AexIdempotencyConflictError extends AexApiError {
+    constructor(init: AexApiErrorInit);
+}
+/** 404 — the requested resource was not found. */
+export declare class AexNotFoundError extends AexApiError {
+    constructor(init: AexApiErrorInit);
+}
+/** 429 — the workspace hit a rate/concurrency limit; retry after a backoff. */
+export declare class AexRateLimitError extends AexApiError {
+    /** Suggested backoff (ms), when the server advertised one (Retry-After). */
+    readonly retryAfterMs: number | undefined;
+    constructor(init: AexApiErrorInit & {
+        readonly retryAfterMs?: number | undefined;
+    });
 }
+/** True for a 401/403 authentication/authorization failure. */
+export declare function isAuthError(err: unknown): err is AexAuthError;
+/** True for a 403 whose cause is a missing scope (`insufficient_scope`). */
+export declare function isInsufficientScope(err: unknown): boolean;
+/** True for a 409 idempotency-key reuse conflict. */
+export declare function isIdempotencyConflict(err: unknown): err is AexIdempotencyConflictError;
+/** True for a 404 not-found error. */
+export declare function isNotFound(err: unknown): err is AexNotFoundError;
+/** True for a 429 rate/concurrency-limit error. */
+export declare function isRateLimited(err: unknown): err is AexRateLimitError;
 /**
  * Thrown when a BFF-bound request fails BEFORE any HTTP response exists — DNS
  * failure, connection refused, TLS error, socket reset. Wraps the raw fetch
@@ -52,6 +109,8 @@ export declare class AexNetworkError extends AexError {
     readonly causeCode: string | undefined;
     /** Attempts made when a retry layer exhausted its budget; `1` otherwise. */
     readonly attempts: number;
+    /** Total elapsed time (ms) across all attempts, when the retry layer set it. */
+    readonly elapsedMs: number | undefined;
     constructor(args: {
         readonly method: string;
         readonly host: string;

package/dist/_contracts/sdk-errors.js

@@ -38,17 +38,94 @@ export class CleanupError extends AexError {
 }
 /**
  * Thrown by SDK and CLI operations when the dashboard BFF returns a non-2xx
- * response. Carries the HTTP status and parsed body for the caller to inspect.
+ * response. Carries the HTTP status, the redacted parsed body, the server's
+ * STABLE {@link AexApiErrorCode} (when present), and a `requestId` for support.
+ * Construct via {@link import("./error-factory.js").apiErrorFromResponse} — the
+ * single wire→exception mapping — which dispatches to a typed subclass
+ * ({@link AexAuthError} / {@link AexIdempotencyConflictError} /
+ * {@link AexNotFoundError} / {@link AexRateLimitError}).
  */
 export class AexApiError extends AexError {
     status;
     body;
-    constructor(status, message, body) {
-        super("API_ERROR", message, body);
+    /** The server's stable error code, when the body carried a known one. */
+    apiCode;
+    /** Request id (body `requestId` or a response header) for support correlation. */
+    requestId;
+    constructor(status, message, body, options) {
+        super("API_ERROR", message, body, options?.cause === undefined ? undefined : { cause: options.cause });
         this.status = status;
         this.body = redactSecrets(body);
+        this.apiCode = options?.apiCode;
+        this.requestId = options?.requestId;
     }
 }
+/** 401/403 auth failure (token invalid/revoked/expired, forbidden, insufficient scope). */
+export class AexAuthError extends AexApiError {
+    /** The scope the endpoint required, when the server named it (insufficient_scope). */
+    requiredScope;
+    constructor(init) {
+        super(init.status, init.message, init.body, {
+            apiCode: init.apiCode,
+            requestId: init.requestId,
+            cause: init.cause
+        });
+        this.requiredScope = init.requiredScope;
+    }
+}
+/** 409 — the idempotency key was reused with a different request body. */
+export class AexIdempotencyConflictError extends AexApiError {
+    constructor(init) {
+        super(init.status, init.message, init.body, {
+            apiCode: init.apiCode,
+            requestId: init.requestId,
+            cause: init.cause
+        });
+    }
+}
+/** 404 — the requested resource was not found. */
+export class AexNotFoundError extends AexApiError {
+    constructor(init) {
+        super(init.status, init.message, init.body, {
+            apiCode: init.apiCode,
+            requestId: init.requestId,
+            cause: init.cause
+        });
+    }
+}
+/** 429 — the workspace hit a rate/concurrency limit; retry after a backoff. */
+export class AexRateLimitError extends AexApiError {
+    /** Suggested backoff (ms), when the server advertised one (Retry-After). */
+    retryAfterMs;
+    constructor(init) {
+        super(init.status, init.message, init.body, {
+            apiCode: init.apiCode,
+            requestId: init.requestId,
+            cause: init.cause
+        });
+        this.retryAfterMs = init.retryAfterMs;
+    }
+}
+/** True for a 401/403 authentication/authorization failure. */
+export function isAuthError(err) {
+    return err instanceof AexAuthError;
+}
+/** True for a 403 whose cause is a missing scope (`insufficient_scope`). */
+export function isInsufficientScope(err) {
+    return err instanceof AexAuthError && err.apiCode === "insufficient_scope";
+}
+/** True for a 409 idempotency-key reuse conflict. */
+export function isIdempotencyConflict(err) {
+    return err instanceof AexIdempotencyConflictError;
+}
+/** True for a 404 not-found error. */
+export function isNotFound(err) {
+    return err instanceof AexNotFoundError;
+}
+/** True for a 429 rate/concurrency-limit error. */
+export function isRateLimited(err) {
+    return err instanceof AexRateLimitError;
+}
 /**
  * Thrown when a BFF-bound request fails BEFORE any HTTP response exists — DNS
  * failure, connection refused, TLS error, socket reset. Wraps the raw fetch
@@ -67,6 +144,8 @@ export class AexNetworkError extends AexError {
     causeCode;
     /** Attempts made when a retry layer exhausted its budget; `1` otherwise. */
     attempts;
+    /** Total elapsed time (ms) across all attempts, when the retry layer set it. */
+    elapsedMs;
     constructor(args) {
         const causeCode = extractErrorCode(args.cause);
         super("NETWORK_ERROR", networkErrorMessage(args, causeCode), { method: args.method, host: args.host, path: args.path, ...(causeCode ? { code: causeCode } : {}) }, { cause: args.cause });
@@ -75,6 +154,7 @@ export class AexNetworkError extends AexError {
         this.path = args.path;
         this.causeCode = causeCode;
         this.attempts = args.attempts ?? 1;
+        this.elapsedMs = args.elapsedMs;
     }
 }
 function networkErrorMessage(args, causeCode) {

package/dist/_contracts/sdk-secrets.js

@@ -194,17 +194,42 @@ export function createRedactingStream(known = []) {
 function isSecretKey(key) {
     return /(?:api[_-]?key|authorization|token|secret|password|credential)/i.test(key);
 }
-/** A candidate run is a high-entropy secret if it is both information-dense
- * AND mixes character classes (the property that separates opaque secret blobs
- * from single-class identifiers/paths). */
+/**
+ * A candidate run is a high-entropy secret if it contains an opaque
+ * secret-shaped SEGMENT. The candidate class already excludes `_` so
+ * snake_case names split into sub-candidates; we ADDITIONALLY treat `-` as a
+ * segment boundary here, at the entropy layer, so a kebab-case human name or a
+ * timestamped slug is judged by its PARTS — dictionary words + a decimal number,
+ * each individually low-entropy — not by its (misleadingly high) whole-run
+ * entropy. Concretely a customer secret NAME like `spike17-race-1720000000000`
+ * (and its real-`Date.now()` variants, whose whole-run entropy is ~4.1) has no
+ * opaque segment and SURVIVES — a name is not a credential, and masking it makes
+ * `secret_not_found` unactionable.
+ *
+ * Splitting at the entropy layer (not in the candidate regex) is the precise,
+ * non-weakening choice: an OPAQUE base64url secret that merely CONTAINS a `-`
+ * still masks, because at least one of its `-`-segments is itself a dense,
+ * class-diverse run and trips the gate. A `-`-free candidate is a single
+ * segment, i.e. byte-identical to the pre-fix whole-run check.
+ */
 function looksHighEntropySecret(value) {
+    return value.split("-").some(isOpaqueSecretRun);
+}
+/**
+ * True when a delimiter-free run is a dense, character-class-diverse opaque
+ * secret: an entropy floor AND ≥2 character classes, and either a digit or an
+ * extreme length. The digit/length clause keeps digit-free mixed-case
+ * identifiers (stack-trace frames, API symbol names the diagnostic bundle
+ * captures) legible while real secret shapes still match. A segment below ~8
+ * chars cannot clear the entropy floor, so dictionary words and short slug parts
+ * fall out on entropy alone — no separate length gate needed here (the
+ * ≥24-char {@link HIGH_ENTROPY_CANDIDATE} bounds the whole candidate).
+ */
+function isOpaqueSecretRun(value) {
     if (charClassCount(value) < MIN_CHAR_CLASSES)
         return false;
     if (shannonEntropyBits(value) < ENTROPY_BITS_PER_CHAR)
         return false;
-    // Require a digit OR extreme length so digit-free mixed-case identifiers
-    // (stack-trace frames, API symbol names) are not destroyed in diagnostic
-    // output, while real secret shapes (alnum-mixed, or very long) still match.
     return /[0-9]/.test(value) || value.length >= HIGH_ENTROPY_NO_DIGIT_MIN_LEN;
 }
 /** How many of {lowercase, uppercase, digit} appear in `value` (0–3). */

package/dist/_contracts/stable.d.ts

@@ -22,5 +22,19 @@
  * exact default API plane.
  */
 export declare const AEX_DEFAULT_BASE_URL = "https://api.aex.dev";
+/**
+ * Plane → API base URL. When the SDK constructor is given no explicit `baseUrl`
+ * it DERIVES the target from the API key's embedded plane (see
+ * {@link import("./api-key.js").parseApiKey}) rather than blindly defaulting to
+ * prod — so a dev key never silently 401s against `api.aex.dev`.
+ *
+ * `prd` is {@link AEX_DEFAULT_BASE_URL}. `dev` is `null`: the dev plane has no
+ * stable public hostname yet, so a dev key still requires an explicit `baseUrl`
+ * — but the plane-mismatch guard (dev key + prd baseUrl) still fires.
+ */
+export declare const PLANE_BASE_URLS: {
+    readonly dev: null;
+    readonly prd: "https://api.aex.dev";
+};
 export declare function stableStringify(value: unknown): string;
 export declare function sha256(value: unknown): string;

package/dist/_contracts/stable.js

@@ -23,6 +23,20 @@ import { createHash } from "node:crypto";
  * exact default API plane.
  */
 export const AEX_DEFAULT_BASE_URL = "https://api.aex.dev";
+/**
+ * Plane → API base URL. When the SDK constructor is given no explicit `baseUrl`
+ * it DERIVES the target from the API key's embedded plane (see
+ * {@link import("./api-key.js").parseApiKey}) rather than blindly defaulting to
+ * prod — so a dev key never silently 401s against `api.aex.dev`.
+ *
+ * `prd` is {@link AEX_DEFAULT_BASE_URL}. `dev` is `null`: the dev plane has no
+ * stable public hostname yet, so a dev key still requires an explicit `baseUrl`
+ * — but the plane-mismatch guard (dev key + prd baseUrl) still fires.
+ */
+export const PLANE_BASE_URLS = {
+    dev: null,
+    prd: AEX_DEFAULT_BASE_URL
+};
 export function stableStringify(value) {
     return JSON.stringify(sortValue(value));
 }

package/dist/_contracts/status.d.ts

@@ -1,7 +1,34 @@
 export declare const RUN_STATUSES: readonly ["queued", "claiming", "provisioning", "session_created", "dispatched", "provider_running", "provider_idle", "provider_rescheduled", "idle", "suspending", "suspended", "deleting", "deleted", "expired", "cancelling", "capturing_outputs", "cleaning_up", "succeeded", "failed", "timed_out", "cancelled", "cleanup_failed"];
 export type RunStatus = typeof RUN_STATUSES[number];
-export declare const SESSION_STATUSES: readonly ["creating", "running", "idle", "suspending", "suspended", "cancelling", "deleting", "deleted", "expired", "error"];
+/**
+ * The RESUMABLE / in-flight lifecycle half of a session's status. A session
+ * whose status is one of these is either transitioning or parked resumable
+ * (`idle`/`suspended`) — it is NOT a terminal outcome. The terminal outcome
+ * half is {@link SESSION_TERMINAL_OUTCOMES}, derived from the run outcome SSoT.
+ */
+export declare const SESSION_LIFECYCLE_STATUSES: readonly ["creating", "running", "idle", "suspending", "suspended", "cancelling", "deleting", "deleted", "expired"];
+export type SessionLifecycleStatus = typeof SESSION_LIFECYCLE_STATUSES[number];
+/**
+ * The terminal OUTCOME half of a session's status — DERIVED from the run
+ * outcome SSoT via `satisfies readonly RunTerminalOutcome[]`, so a new run
+ * outcome fails to compile until it is accounted for here (and therefore in
+ * {@link SESSION_STATUSES}). This is the compile-time binding that stops the
+ * session and run terminal vocabularies from drifting: the bare session
+ * `error` is gone — a failed turn is `failed`, a wall-clock kill `timed_out`,
+ * a cancel `cancelled`, a clean finish `succeeded`.
+ */
+export declare const SESSION_TERMINAL_OUTCOMES: readonly ["succeeded", "failed", "timed_out", "cancelled"];
+export type SessionTerminalOutcome = typeof SESSION_TERMINAL_OUTCOMES[number];
+/**
+ * The full closed set of session statuses: the resumable lifecycle half, the
+ * terminal-outcome half (bound to {@link RUN_TERMINAL_OUTCOMES}), and the
+ * first-class HITL write-gate `awaiting_approval`. Composed — never
+ * hand-listed — so the outcome vocabulary can only be extended at the run SSoT.
+ */
+export declare const SESSION_STATUSES: readonly ["creating", "running", "idle", "suspending", "suspended", "cancelling", "deleting", "deleted", "expired", "succeeded", "failed", "timed_out", "cancelled", "awaiting_approval"];
 export type SessionStatus = typeof SESSION_STATUSES[number];
+/** True when a session status is terminal (an outcome, or deleted/expired). */
+export declare function isTerminalSessionStatus(status: SessionStatus): boolean;
 export type RunStatusKind = "active" | "terminal";
 export declare const TERMINAL_RUN_STATUSES: readonly ["succeeded", "failed", "timed_out", "cancelled", "deleted", "expired", "cleanup_failed"];
 export declare function isTerminalRunStatus(status: RunStatus): boolean;

package/dist/_contracts/status.js

@@ -22,7 +22,13 @@ export const RUN_STATUSES = [
     "cancelled",
     "cleanup_failed"
 ];
-export const SESSION_STATUSES = [
+/**
+ * The RESUMABLE / in-flight lifecycle half of a session's status. A session
+ * whose status is one of these is either transitioning or parked resumable
+ * (`idle`/`suspended`) — it is NOT a terminal outcome. The terminal outcome
+ * half is {@link SESSION_TERMINAL_OUTCOMES}, derived from the run outcome SSoT.
+ */
+export const SESSION_LIFECYCLE_STATUSES = [
     "creating",
     "running",
     "idle",
@@ -31,9 +37,48 @@ export const SESSION_STATUSES = [
     "cancelling",
     "deleting",
     "deleted",
-    "expired",
-    "error"
+    "expired"
 ];
+/**
+ * The terminal OUTCOME half of a session's status — DERIVED from the run
+ * outcome SSoT via `satisfies readonly RunTerminalOutcome[]`, so a new run
+ * outcome fails to compile until it is accounted for here (and therefore in
+ * {@link SESSION_STATUSES}). This is the compile-time binding that stops the
+ * session and run terminal vocabularies from drifting: the bare session
+ * `error` is gone — a failed turn is `failed`, a wall-clock kill `timed_out`,
+ * a cancel `cancelled`, a clean finish `succeeded`.
+ */
+export const SESSION_TERMINAL_OUTCOMES = [
+    "succeeded",
+    "failed",
+    "timed_out",
+    "cancelled"
+];
+/**
+ * The full closed set of session statuses: the resumable lifecycle half, the
+ * terminal-outcome half (bound to {@link RUN_TERMINAL_OUTCOMES}), and the
+ * first-class HITL write-gate `awaiting_approval`. Composed — never
+ * hand-listed — so the outcome vocabulary can only be extended at the run SSoT.
+ */
+export const SESSION_STATUSES = [
+    ...SESSION_LIFECYCLE_STATUSES,
+    ...SESSION_TERMINAL_OUTCOMES,
+    "awaiting_approval"
+];
+/**
+ * The terminal session statuses: the four outcomes plus the lifecycle-terminal
+ * `deleted`/`expired`. `idle`/`suspended` are resumable (NOT terminal) and
+ * `awaiting_approval` is a held gate (NOT terminal).
+ */
+const SESSION_TERMINAL_STATUSES = new Set([
+    ...SESSION_TERMINAL_OUTCOMES,
+    "deleted",
+    "expired"
+]);
+/** True when a session status is terminal (an outcome, or deleted/expired). */
+export function isTerminalSessionStatus(status) {
+    return SESSION_TERMINAL_STATUSES.has(status);
+}
 export const TERMINAL_RUN_STATUSES = [
     "succeeded",
     "failed",