@aexhq/sdk 0.35.0 → 0.37.0

package/dist/_contracts/run-trace.js

@@ -1,185 +1,2 @@
-/**
- * Typed decoders for a `listEvents(runId)` stream.
- *
- * `listEvents` returns the loose {@link RunEvent} wire shape: `type` at the top
- * level, but the tool name at `data.name`, the call args at `data.arguments`,
- * assistant text at `data.text`, and — the awkward part — a `TOOL_CALL_RESULT`
- * carries no name, so a consumer must correlate each result back to its
- * `TOOL_CALL_START` by `data.id` (the tool-call id). Every consumer ended up
- * re-implementing that correlation; these helpers do it once, typed and pure.
- *
- * They are total and side-effect-free: pass the array `listEvents` returns and
- * get back structured traces. Unknown event types are ignored (forward-compat),
- * a result with no matching start surfaces as an orphan (never dropped silently),
- * and timing falls back gracefully when a `recordedAt` is absent.
- *
- * `summarizeRunUsage` remains tolerant of historical/internal `aex.usage`
- * CUSTOM records when a caller has them, but the normal public `listEvents`
- * stream is not the live usage-reporting surface. Settled provider/runtime
- * usage is exposed through the run's `costTelemetry`.
- */
-const CUSTOM_USAGE_NAME = "aex.usage";
-/** snake_case `aex.usage` field → the camelCase {@link UsageSummary} field. */
-const USAGE_FIELD_MAP = {
-    input_tokens: "inputTokens",
-    output_tokens: "outputTokens",
-    cache_read_input_tokens: "cacheReadInputTokens",
-    cache_creation_input_tokens: "cacheCreationInputTokens"
-};
-/**
- * Decode a `listEvents` stream into correlated tool-call traces, in start order.
- *
- * Each `TOOL_CALL_START` opens a trace keyed by `data.id`; the matching
- * `TOOL_CALL_RESULT` (same `data.id`) fills in `result` + `durationMs`. A result
- * whose id never had a start is surfaced as an orphan trace (empty `name`, no
- * `args`) rather than dropped, so a partial/mis-ordered stream never hides a
- * result. Pure — no I/O, input is not mutated.
- */
-export function decodeToolCalls(events) {
-    const order = [];
-    const byId = new Map();
-    for (const event of events) {
-        const data = asRecord(event.data);
-        if (event.type === "TOOL_CALL_START") {
-            const id = asString(data.id);
-            if (id === undefined)
-                continue;
-            const trace = {
-                id,
-                name: asString(data.name) ?? "",
-                args: asRecord(data.arguments)
-            };
-            const messageId = asString(data.messageId);
-            if (messageId !== undefined)
-                trace.messageId = messageId;
-            if (typeof event.seq === "number")
-                trace.startSeq = event.seq;
-            if (typeof event.recordedAt === "string")
-                trace.startedAt = event.recordedAt;
-            if (!byId.has(id))
-                order.push(id);
-            byId.set(id, trace);
-            continue;
-        }
-        if (event.type === "TOOL_CALL_RESULT") {
-            const id = asString(data.id);
-            if (id === undefined)
-                continue;
-            const result = {
-                isError: data.isError === true,
-                content: data.content ?? null
-            };
-            if (typeof event.seq === "number")
-                result.seq = event.seq;
-            if (typeof event.recordedAt === "string")
-                result.recordedAt = event.recordedAt;
-            let trace = byId.get(id);
-            if (trace === undefined) {
-                // Orphan result (no matching start) — surface it, never drop it.
-                trace = { id, name: "", args: {} };
-                order.push(id);
-                byId.set(id, trace);
-            }
-            trace.result = result;
-            const duration = durationMs(trace.startedAt, result.recordedAt);
-            if (duration !== undefined)
-                trace.durationMs = duration;
-            continue;
-        }
-    }
-    return order.map((id) => byId.get(id));
-}
-/**
- * Sum any `aex.usage` CUSTOM events present in the supplied stream into one
- * {@link UsageSummary}. This is mainly for historical/internal event arrays;
- * current public reads expose settled provider usage through cost telemetry.
- * `totalTokens` is the sum of input + output tokens. Pure.
- */
-export function summarizeRunUsage(events) {
-    const totals = { inputTokens: 0, outputTokens: 0, cacheReadInputTokens: 0, cacheCreationInputTokens: 0 };
-    let seen = false;
-    for (const event of events) {
-        if (event.type !== "CUSTOM")
-            continue;
-        const data = asRecord(event.data);
-        if (asString(data.name) !== CUSTOM_USAGE_NAME)
-            continue;
-        const value = asRecord(data.value);
-        for (const [snake, camel] of Object.entries(USAGE_FIELD_MAP)) {
-            const n = value[snake];
-            if (typeof n === "number" && Number.isFinite(n)) {
-                totals[camel] += n;
-                seen = true;
-            }
-        }
-    }
-    if (!seen)
-        return {};
-    return {
-        inputTokens: totals.inputTokens,
-        outputTokens: totals.outputTokens,
-        cacheReadInputTokens: totals.cacheReadInputTokens,
-        cacheCreationInputTokens: totals.cacheCreationInputTokens,
-        totalTokens: totals.inputTokens + totals.outputTokens
-    };
-}
-/**
- * The run's final assistant text: every `TEXT_MESSAGE_CONTENT` block in stream
- * order, concatenated. The one-line "what did the agent say" accessor over
- * {@link decodeAssistantText} (buffered mode yields whole messages, stream mode
- * yields token deltas — both concatenate correctly). Pure.
- */
-export function textOf(events) {
-    return decodeAssistantText(events).map((entry) => entry.text).join("");
-}
-/** Decode the assistant text blocks (`TEXT_MESSAGE_CONTENT`) in stream order. Pure. */
-export function decodeAssistantText(events) {
-    const out = [];
-    for (const event of events) {
-        if (event.type !== "TEXT_MESSAGE_CONTENT")
-            continue;
-        const data = asRecord(event.data);
-        const text = asString(data.text);
-        if (text === undefined)
-            continue;
-        const entry = { text };
-        const messageId = asString(data.messageId);
-        if (messageId !== undefined)
-            entry.messageId = messageId;
-        if (typeof event.seq === "number")
-            entry.seq = event.seq;
-        if (typeof event.recordedAt === "string")
-            entry.recordedAt = event.recordedAt;
-        out.push(entry);
-    }
-    return out;
-}
-/**
- * Decode a whole `listEvents` stream in one pass: correlated tool calls,
- * aggregate {@link UsageSummary}, and assistant text. Convenience over the three
- * focused decoders; pure.
- */
-export function summarizeRunTrace(events) {
-    return {
-        toolCalls: decodeToolCalls(events),
-        usage: summarizeRunUsage(events),
-        text: decodeAssistantText(events)
-    };
-}
-function asRecord(value) {
-    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
-}
-function asString(value) {
-    return typeof value === "string" ? value : undefined;
-}
-function durationMs(start, end) {
-    if (start === undefined || end === undefined)
-        return undefined;
-    const a = Date.parse(start);
-    const b = Date.parse(end);
-    if (!Number.isFinite(a) || !Number.isFinite(b))
-        return undefined;
-    const delta = b - a;
-    return delta >= 0 ? delta : undefined;
-}
+export {};
 //# sourceMappingURL=run-trace.js.map

package/dist/_contracts/run-unit.d.ts

@@ -3,8 +3,7 @@
  *
  * One canonical struct that captures every non-secret artifact persisted
  * for a single run: parsed submission inputs, status/lifecycle, attempts,
- * indexed events, raw-event Storage manifest, outputs (+ capture
- * failures), and the proxy-call audit log.
+ * indexed events, raw-event Storage manifest, outputs, and capture failures.
  *
  * Wire contract for `GET /api/runs/:runId`, the per-run archive's
  * `run.json`/`submission.json`/`caps.json`, and the SDK/CLI
@@ -19,7 +18,7 @@
  * detail response stays bounded). The archive zip carries the bytes.
  */
 import type { CleanupStatus } from "./status.js";
-import type { JsonValue, PlatformSubmission, PlatformProxyEndpoint } from "./submission.js";
+import type { JsonValue, PlatformSubmission } from "./submission.js";
 /**
  * Parsed view of the legacy run snapshot jsonb. Stored shape is
  * `{kind:"submission", submission}` written by the hosted API's
@@ -97,26 +96,6 @@ export interface RunUnitOutputCaptureFailure {
     readonly errorMessage?: string;
     readonly createdAt: string;
 }
-export interface RunUnitProxyCall {
-    readonly id: string;
-    readonly endpointName: string;
-    readonly method: string;
-    readonly requestPathRedacted: string | null;
-    readonly requestByteSize: number;
-    readonly responseStatus: number | null;
-    readonly responseByteSize: number;
-    readonly outcome: string;
-    readonly errorClass: string | null;
-    readonly startedAt: string;
-    readonly finishedAt: string | null;
-    readonly durationMs: number | null;
-}
-export interface RunUnitProxyCallPage {
-    readonly entries: readonly RunUnitProxyCall[];
-    readonly totalCount: number;
-    readonly truncated: boolean;
-    readonly nextCursor?: string;
-}
 export interface RunUnit {
     readonly id: string;
     readonly workspaceId: string;
@@ -131,14 +110,12 @@ export interface RunUnit {
     readonly attemptCount: number;
     readonly submission: RunUnitSubmission;
     readonly capsSnapshot?: Record<string, JsonValue>;
-    readonly proxyEndpointsSnapshot?: readonly PlatformProxyEndpoint[];
     readonly attempts: readonly RunUnitAttempt[];
     readonly events: RunUnitEventPage;
     readonly rawEventPages: readonly RunUnitRawEventPage[];
     readonly outputs: readonly RunUnitOutput[];
     readonly outputCaptureFailures: readonly RunUnitOutputCaptureFailure[];
     readonly costTelemetry?: import("./run-cost.js").RunCostTelemetry;
-    readonly proxyCalls: RunUnitProxyCallPage;
     /**
      * Per-run, per-provider runtime manifest — derived from the validated
      * submission + the chosen provider (`buildRuntimeManifest`). Tells
@@ -159,3 +136,15 @@ export interface RunUnit {
  * the whole detail page.
  */
 export declare function parseRunUnitSubmission(input: unknown): RunUnitSubmission;
+/**
+ * Normalize a `GET /api/runs/:runId` payload into a RunUnit whose type contract
+ * holds AT RUNTIME. The managed (AWS) plane returns a LEAN record (scalars +
+ * costTelemetry only) and omits the aggregate collections; the RunUnit type
+ * declares those non-optional, so a naive cast leaves `unit.outputs` /
+ * `unit.events.totalCount` `undefined` and a typed consumer crashes on
+ * `.map()` / `.totalCount` (pre-launch edge-sweep F25). We fill the aggregates
+ * with their empty defaults so array/page access is always safe. NOTE: on the
+ * managed plane these summaries are best-effort — read `outputs()` / `events()`
+ * / `messages()` for the authoritative per-run data.
+ */
+export declare function normalizeRunUnit(raw: unknown): RunUnit;

package/dist/_contracts/run-unit.js

@@ -3,8 +3,7 @@
  *
  * One canonical struct that captures every non-secret artifact persisted
  * for a single run: parsed submission inputs, status/lifecycle, attempts,
- * indexed events, raw-event Storage manifest, outputs (+ capture
- * failures), and the proxy-call audit log.
+ * indexed events, raw-event Storage manifest, outputs, and capture failures.
  *
  * Wire contract for `GET /api/runs/:runId`, the per-run archive's
  * `run.json`/`submission.json`/`caps.json`, and the SDK/CLI
@@ -19,6 +18,7 @@
  * detail response stays bounded). The archive zip carries the bytes.
  */
 import { parseMcpServerRef } from "./run-config.js";
+import { CLEANUP_STATUSES } from "./status.js";
 import { Models, parseRunModel } from "./models.js";
 import { PLATFORM_PACKAGE_ECOSYSTEMS } from "./submission.js";
 // ---------------------------------------------------------------------------
@@ -120,6 +120,60 @@ function fallbackFlat() {
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+/**
+ * Normalize a `GET /api/runs/:runId` payload into a RunUnit whose type contract
+ * holds AT RUNTIME. The managed (AWS) plane returns a LEAN record (scalars +
+ * costTelemetry only) and omits the aggregate collections; the RunUnit type
+ * declares those non-optional, so a naive cast leaves `unit.outputs` /
+ * `unit.events.totalCount` `undefined` and a typed consumer crashes on
+ * `.map()` / `.totalCount` (pre-launch edge-sweep F25). We fill the aggregates
+ * with their empty defaults so array/page access is always safe. NOTE: on the
+ * managed plane these summaries are best-effort — read `outputs()` / `events()`
+ * / `messages()` for the authoritative per-run data.
+ */
+export function normalizeRunUnit(raw) {
+    const r = isRecord(raw) ? raw : {};
+    const eventsRaw = isRecord(r.events) ? r.events : {};
+    const str = (v) => (typeof v === "string" ? v : undefined);
+    const arr = (v) => (Array.isArray(v) ? v : []);
+    return {
+        id: str(r.id) ?? "",
+        workspaceId: str(r.workspaceId) ?? "",
+        status: str(r.status) ?? "unknown",
+        ...(str(r.lifecyclePhase) ? { lifecyclePhase: r.lifecyclePhase } : {}),
+        cleanupStatus: CLEANUP_STATUSES.includes(r.cleanupStatus)
+            ? r.cleanupStatus
+            : "not_started",
+        createdAt: str(r.createdAt) ?? "",
+        updatedAt: str(r.updatedAt) ?? "",
+        ...(str(r.startedAt) ? { startedAt: r.startedAt } : {}),
+        ...(str(r.terminalAt) ? { terminalAt: r.terminalAt } : {}),
+        ...(str(r.deletedAt) ? { deletedAt: r.deletedAt } : {}),
+        attemptCount: typeof r.attemptCount === "number"
+            ? r.attemptCount
+            : Array.isArray(r.attempts)
+                ? r.attempts.length
+                : 0,
+        submission: parseRunUnitSubmission(r.submission),
+        ...(isRecord(r.capsSnapshot) ? { capsSnapshot: r.capsSnapshot } : {}),
+        attempts: arr(r.attempts),
+        events: {
+            entries: arr(eventsRaw.entries),
+            totalCount: typeof eventsRaw.totalCount === "number" ? eventsRaw.totalCount : 0,
+            truncated: eventsRaw.truncated === true,
+            ...(str(eventsRaw.nextCursor) ? { nextCursor: eventsRaw.nextCursor } : {})
+        },
+        rawEventPages: arr(r.rawEventPages),
+        outputs: arr(r.outputs),
+        outputCaptureFailures: arr(r.outputCaptureFailures),
+        ...(isRecord(r.costTelemetry)
+            ? { costTelemetry: r.costTelemetry }
+            : {}),
+        ...(isRecord(r.runtimeManifest)
+            ? { runtimeManifest: r.runtimeManifest }
+            : {})
+    };
+}
 function coerceRunUnitModel(value) {
     if (typeof value !== "string")
         return Models.CLAUDE_HAIKU_4_5;

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

@@ -39,7 +39,7 @@ export interface RuntimeManifest {
     readonly assetsRoot: string;
     /** Absolute path of the in-container aex runtime bridge (invoke via `bun`). */
     readonly aexCli: string;
-    /** Absolute path of the per-run proxy-endpoints manifest. */
+    /** Absolute path of the in-container aex runtime index. */
     readonly indexJson: string;
     /** Absolute path of the always-mounted aex runtime contract README. */
     readonly readme: string;

package/dist/_contracts/runtime-security-profile.d.ts

@@ -6,14 +6,12 @@ export interface RuntimeSecurityProfile {
     readonly allowOpenNetworking: boolean;
     readonly allowRuntimePackages: boolean;
     readonly allowCustomerEnvVars: boolean;
-    readonly allowProxyEndpoints: boolean;
     readonly allowMcpServers: boolean;
 }
 export interface RuntimeSecurityProfileEvaluationInput {
     readonly networkingMode?: "limited" | "open";
     readonly packageCount?: number;
     readonly customerEnvVarCount?: number;
-    readonly proxyEndpointCount?: number;
     readonly mcpServerCount?: number;
 }
 export interface RuntimeSecurityProfileViolation {

package/dist/_contracts/runtime-security-profile.js

@@ -6,7 +6,6 @@ export const RUNTIME_SECURITY_PROFILE_CONFIG = Object.freeze({
         allowOpenNetworking: false,
         allowRuntimePackages: false,
         allowCustomerEnvVars: true,
-        allowProxyEndpoints: true,
         allowMcpServers: true
     }),
     standard: Object.freeze({
@@ -15,7 +14,6 @@ export const RUNTIME_SECURITY_PROFILE_CONFIG = Object.freeze({
         allowOpenNetworking: true,
         allowRuntimePackages: true,
         allowCustomerEnvVars: true,
-        allowProxyEndpoints: true,
         allowMcpServers: true
     }),
     developer: Object.freeze({
@@ -24,7 +22,6 @@ export const RUNTIME_SECURITY_PROFILE_CONFIG = Object.freeze({
         allowOpenNetworking: true,
         allowRuntimePackages: true,
         allowCustomerEnvVars: true,
-        allowProxyEndpoints: true,
         allowMcpServers: true
     })
 });
@@ -65,12 +62,6 @@ export function evaluateRuntimeSecurityProfile(profileName, input) {
             reason: `${profile.name} does not allow customer runtime env vars`
         });
     }
-    if ((input.proxyEndpointCount ?? 0) > 0 && !profile.allowProxyEndpoints) {
-        violations.push({
-            field: "proxyEndpoints",
-            reason: `${profile.name} does not allow HTTP proxy endpoints`
-        });
-    }
     if ((input.mcpServerCount ?? 0) > 0 && !profile.allowMcpServers) {
         violations.push({
             field: "submission.mcpServers",

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

@@ -65,9 +65,9 @@ export declare function runtimeResources(size: RuntimeSize): RuntimeResources;
  * consumers apply {@link DEFAULT_RUNTIME_SIZE}.
  */
 export declare function parseRuntimeSize(input: unknown): RuntimeSize | undefined;
-/** Default run deadline when `timeout` is omitted (1 hour). */
+/** Default run deadline when `timeout` is omitted (8 hours). */
 export declare const DEFAULT_RUN_TIMEOUT_MS: number;
-/** Hard ceiling on a run deadline (6 hours). */
+/** Hard ceiling on a run deadline (8 hours). */
 export declare const MAX_RUN_TIMEOUT_MS: number;
 /** Floor on a run deadline (1 minute). */
 export declare const MIN_RUN_TIMEOUT_MS: number;

package/dist/_contracts/runtime-sizes.js

@@ -54,10 +54,10 @@ export function parseRuntimeSize(input) {
 // ===========================================================================
 // Run timeout
 // ===========================================================================
-/** Default run deadline when `timeout` is omitted (1 hour). */
-export const DEFAULT_RUN_TIMEOUT_MS = 60 * 60 * 1000;
-/** Hard ceiling on a run deadline (6 hours). */
-export const MAX_RUN_TIMEOUT_MS = 6 * 60 * 60 * 1000;
+/** Default run deadline when `timeout` is omitted (8 hours). */
+export const DEFAULT_RUN_TIMEOUT_MS = 8 * 60 * 60 * 1000;
+/** Hard ceiling on a run deadline (8 hours). */
+export const MAX_RUN_TIMEOUT_MS = 8 * 60 * 60 * 1000;
 /** Floor on a run deadline (1 minute). */
 export const MIN_RUN_TIMEOUT_MS = 60 * 1000;
 const DURATION_PATTERN = /^(\d+(?:\.\d+)?)(ms|s|m|h)?$/;
@@ -95,7 +95,7 @@ export function parseRunTimeout(input) {
         throw new Error(`timeout must be at least ${MIN_RUN_TIMEOUT_MS}ms (1m); got ${ms}ms`);
     }
     if (ms > MAX_RUN_TIMEOUT_MS) {
-        throw new Error(`timeout must be at most ${MAX_RUN_TIMEOUT_MS}ms (6h); got ${ms}ms`);
+        throw new Error(`timeout must be at most ${MAX_RUN_TIMEOUT_MS}ms (8h); got ${ms}ms`);
     }
     return ms;
 }

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

@@ -118,6 +118,27 @@ export interface SessionMessageAccepted {
     readonly turn: SessionTurn;
     readonly eventCursor?: number;
 }
+export type SessionMessageSender = "user" | "assistant" | "system" | "tool";
+export interface SessionMessage {
+    readonly id: string;
+    readonly sender: SessionMessageSender;
+    readonly text: string;
+    readonly timestamp?: string;
+    readonly turnSeq?: number;
+    readonly sequence?: number;
+    readonly messageId?: string;
+    readonly content?: unknown;
+    readonly [key: string]: unknown;
+}
+export interface SessionMessagesQuery {
+    readonly limit?: number;
+    readonly cursor?: string;
+    readonly since?: string;
+}
+export interface SessionMessagesPage {
+    readonly messages: readonly SessionMessage[];
+    readonly nextCursor?: string;
+}
 export interface SessionStateChangeAccepted {
     readonly session: Session;
     readonly turn?: SessionTurn;
@@ -132,7 +153,7 @@ export interface UsageSummary {
     readonly totalTokens?: number;
 }
 /**
- * Filters for {@link import("./operations.js").listRuns} / `AgentExecutor.listRuns`.
+ * Filters for {@link import("./operations.js").listRuns} / `Aex.runs.list`.
  * Every field is optional; omitting all of them lists the most recent runs in the
  * token's workspace. Workspace identity is derived server-side from the API token,
  * so there is no `workspaceId` here — a token can only ever enumerate its own runs.
@@ -166,7 +187,7 @@ export interface RunListPage {
     readonly nextCursor?: string;
 }
 /**
- * Cross-run output search query (`AgentExecutor.searchOutputs`). Restrict to a
+ * Cross-run output search query (`Aex.outputs.search`). Restrict to a
  * corpus with `runIds`; filter by filename substring / extension / content type.
  * The MVP composes this client-side (per-run `listOutputs` + filter) — a future
  * server-side `GET /api/outputs/search` can back the same contract with a real
@@ -301,7 +322,7 @@ export interface OutputFileDownload {
     readonly output: Output;
     readonly bytes: Uint8Array;
 }
-/** Options for `AgentExecutor.readOutputText` / {@link import("./operations.js").readOutputText}. */
+/** Options for `Aex.outputs.read` / {@link import("./operations.js").readOutputText}. */
 export interface ReadOutputTextOptions {
     /**
      * Stop reading after this many bytes. Defaults to 50_000; clamped server-side
@@ -317,7 +338,7 @@ export interface ReadOutputTextOptions {
 }
 /**
  * A byte-capped, decoded text read of one output file, as returned by
- * `AgentExecutor.readOutputText`. Built for feeding run deliverables to an LLM
+ * `Aex.outputs.read`. Built for feeding run deliverables to an LLM
  * without loading the whole (possibly very large) file into memory or context:
  * the read streams and stops at `maxBytes`, so `text` is at most that many bytes
  * decoded as UTF-8. Check {@link truncated} before treating `text` as complete.
@@ -377,6 +398,29 @@ export interface WhoAmI {
          */
         readonly maxRunDurationMs?: number | null;
     };
+    /**
+     * ADDITIVE effective per-workspace limits returned by `GET /whoami` on
+     * current platform deployments — everything a caller needs to anticipate a
+     * `429` / `402` submit rejection before hitting it. Every value is the same
+     * one the platform's admission gates enforce. Optional: older deployments
+     * omit the field entirely.
+     */
+    readonly limits?: {
+        /** Effective live-run concurrency cap. One more live run past it fails with `429 workspace_concurrency_exceeded`. */
+        readonly maxConcurrentRuns: number;
+        /** Effective submit-velocity cap per minute; `0` = unlimited (disabled). Past it: `429 workspace_submit_rate_exceeded`. */
+        readonly submitRatePerMinute: number;
+        /** Effective monthly spend cap in USD; `0` = unlimited. Once `monthSpendUsd` reaches it: `402 workspace_spend_cap_exceeded`. */
+        readonly spendCapUsd: number;
+        /** Accrued spend in the current UTC calendar month — the value the spend gate compares. */
+        readonly monthSpendUsd: number;
+        /** Prepaid balance read-model — the value the balance gate compares. */
+        readonly balanceUsd: number;
+        /** Effective (payment-method-aware) submit floor: submits fail with `402 insufficient_balance` once `balanceUsd` is at or below it. */
+        readonly balanceGraceFloorUsd: number;
+        /** `"active"` means a bounded card overdraft is already folded into `balanceGraceFloorUsd`. */
+        readonly paymentMethodStatus: "none" | "active";
+    };
     readonly [key: string]: unknown;
 }
 /**
@@ -484,3 +528,78 @@ export interface SecretReveal {
     readonly name: string;
     readonly value: string;
 }
+/**
+ * Customer-facing billing summary — `GET /api/billing` (scope `billing:read`).
+ * All money fields are USD numbers. The index signature keeps the shape tolerant
+ * of ADDITIVE server fields (e.g. a deployment newer than this SDK reporting
+ * extra plan attributes) — unknown keys are preserved, never rejected.
+ */
+export interface BillingSummary {
+    /** Prepaid balance (authoritative ledger sum). */
+    readonly balanceUsd: number;
+    /** Accrued spend for the current calendar month. */
+    readonly monthSpendUsd: number;
+    /** Monthly spend cap enforced on new runs. */
+    readonly spendCapUsd: number;
+    readonly planKey: string;
+    readonly subscriptionStatus: string;
+    /** `"active"` once a payment method is bound; older deployments omit it. */
+    readonly paymentMethodStatus?: string;
+    readonly [key: string]: unknown;
+}
+/** Self-serve paid plans exposed through hosted checkout. */
+export type BillingCheckoutPlanKey = "pro" | "team";
+export interface BillingCheckoutRequest {
+    readonly planKey: BillingCheckoutPlanKey;
+    /** Optional return URL after successful hosted checkout. */
+    readonly successUrl?: string;
+    /** Optional return URL after checkout cancellation. */
+    readonly cancelUrl?: string;
+    /** Optional caller-stable key so a retry does not create a second hosted session. */
+    readonly idempotencyKey?: string;
+}
+export interface BillingPortalRequest {
+    /** Optional return URL after leaving the hosted billing portal. */
+    readonly returnUrl?: string;
+}
+/** Hosted checkout/portal session. The client should open `url`. */
+export interface BillingHostedSession {
+    readonly url: string;
+    readonly [key: string]: unknown;
+}
+/**
+ * One row of the workspace credit ledger as returned by
+ * `GET /api/billing/ledger` (newest first). `amountUsd` is signed: top-ups are
+ * positive, run charges negative. Tolerant of additive server fields.
+ */
+export interface BillingLedgerEntry {
+    readonly id: string;
+    /** e.g. `top_up`, `run_charge`. Open server vocabulary. */
+    readonly entryType: string;
+    readonly amountUsd: number;
+    readonly currency: string;
+    /** The run this entry charges, `null` for non-run entries. */
+    readonly runId?: string | null;
+    readonly description?: string | null;
+    readonly createdBy?: string;
+    readonly createdAt: string;
+    readonly [key: string]: unknown;
+}
+/** Query for the billing ledger read. `limit` is clamped server-side to [1, 100] (default 25). */
+export interface BillingLedgerQuery {
+    readonly limit?: number;
+}
+/** One page of recent ledger rows (newest first). Not cursor-paged — `limit` bounds the read. */
+export interface BillingLedgerPage {
+    readonly entries: readonly BillingLedgerEntry[];
+}
+/**
+ * The workspace webhook signing secret reveal — `POST /api/webhook/signing-secret`.
+ * `whsec` is the Standard-Webhooks style `whsec_<base64>` string that
+ * `verifyAexWebhook` accepts as `secret`. The endpoint reveals the current
+ * secret, CREATING one on first use; it does not rotate (a repeat call returns
+ * the same value). POST (not GET) so every reveal is a logged action.
+ */
+export interface WebhookSigningSecret {
+    readonly whsec: string;
+}

package/dist/_contracts/stable.d.ts

@@ -1,6 +1,6 @@
 /**
  * Canonical hosted aex API plane URL. Used as the default `baseUrl`
- * for the SDK `AgentExecutor` and the host-side CLI `--aex-url`
+ * for the SDK `Aex` client and the host-side CLI `--aex-url`
  * flag.
  *
  * Pinned to `api.aex.dev` on purpose: the dashboard at

package/dist/_contracts/stable.js

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 /**
  * Canonical hosted aex API plane URL. Used as the default `baseUrl`
- * for the SDK `AgentExecutor` and the host-side CLI `--aex-url`
+ * for the SDK `Aex` client and the host-side CLI `--aex-url`
  * flag.
  *
  * Pinned to `api.aex.dev` on purpose: the dashboard at