@aexhq/sdk 0.34.0 → 0.36.0

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.

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

package/dist/_contracts/submission.d.ts

@@ -1,5 +1,3 @@
-import { PROXY_ENDPOINT_DEFAULTS, type ProxyAuthShape, type ProxyMethod, type ProxyRetryPolicy, type ProxyResponseMode } from "./proxy-protocol.js";
-export { PROXY_ENDPOINT_DEFAULTS };
 import type { AgentsMdRef, FileRef, McpServerRef, SkillToolRef, ToolRef } from "./run-config.js";
 import { type RuntimeSize } from "./runtime-sizes.js";
 import { type RunModel } from "./models.js";
@@ -141,43 +139,18 @@ export interface PlatformMcpServerSecret {
     readonly url: string;
     readonly headers?: Record<string, string>;
 }
-/**
- * Per-run auth value for a declared proxy endpoint. The `name` must
- * match a `proxyEndpoints[i].name` in the same submission, and `value`'s
- * shape must match that endpoint's `authShape.type`. The cross-validation
- * lives in `parseRunSubmissionRequest`.
- */
-export interface PlatformProxyEndpointAuth {
-    readonly name: string;
-    readonly value: PlatformProxyAuthValue;
-}
-export type PlatformProxyAuthValue = {
-    readonly type: "bearer";
-    readonly token: string;
-} | {
-    readonly type: "basic";
-    readonly username: string;
-    readonly password: string;
-} | {
-    readonly type: "header";
-    readonly value: string;
-} | {
-    readonly type: "query";
-    readonly value: string;
-};
 /**
  * Per-run inline secrets bundle. `apiKeys` holds the BYOK provider keys, keyed
  * by {@link RunProvider}. A run REQUIRES a key for its own `provider`; it MAY
  * carry keys for additional providers so a subagent spawned with a
  * different-family model inherits them server-side from the vault (the keys
- * never transit the container). `mcpServers` and `proxyEndpointAuth` are
- * cross-provider (an MCP credential is the same secret whichever model is
- * driving the MCP client).
+ * never transit the container). `mcpServers` credentials are cross-provider
+ * (an MCP credential is the same secret whichever model is driving the MCP
+ * client).
  */
 export interface PlatformInlineSecrets {
     readonly apiKeys?: Partial<Record<RunProvider, string>>;
     readonly mcpServers?: readonly PlatformMcpServerSecret[];
-    readonly proxyEndpointAuth?: readonly PlatformProxyEndpointAuth[];
     /**
      * Per-run env-var secret VALUES, keyed by env name. Each entry pairs with a
      * `submission.secretEnv[<envName>] = { ephemeral: true }` declaration. Lives
@@ -188,29 +161,6 @@ export interface PlatformInlineSecrets {
      */
     readonly envSecrets?: Readonly<Record<string, string>>;
 }
-/**
- * Per-run named HTTP proxy endpoint. The `authShape` describes how the
- * upstream expects auth; the actual value is supplied separately via
- * `secrets.proxyEndpointAuth`. The auth value never enters the
- * container — the BFF proxy injects it on outbound calls.
- *
- * Caps and allow-lists below are intentionally pessimistic by default
- * so a misconfigured endpoint can't accidentally permit a wide attack
- * surface; raise per endpoint if needed.
- */
-export interface PlatformProxyEndpoint {
-    readonly name: string;
-    readonly baseUrl: string;
-    readonly authShape: ProxyAuthShape;
-    readonly allowMethods: readonly ProxyMethod[];
-    readonly allowPathPrefixes: readonly string[];
-    readonly allowHeaders?: readonly string[];
-    readonly responseMode?: ProxyResponseMode;
-    readonly maxRequestBytes?: number;
-    readonly maxResponseBytes?: number;
-    readonly timeoutMs?: number;
-    readonly retry?: ProxyRetryPolicy;
-}
 export declare const SECRETS_KEY = "secrets";
 /** POSIX-style env var name a `secretEnv` entry binds to (e.g. `SERPER_API_KEY`). */
 export declare const SECRET_ENV_NAME_PATTERN: RegExp;
@@ -227,18 +177,10 @@ export type PlatformSecretEnvEntry = {
 } | {
     readonly ephemeral: true;
 };
-export declare const PROXY_ENDPOINT_NAME_PATTERN: RegExp;
-export declare const RESERVED_PROXY_ENDPOINT_NAMES: Set<string>;
 export declare const deniedSecretFields: Set<string>;
-export declare function parseProxyRetryPolicy(input: unknown, field: string): ProxyRetryPolicy | undefined;
-export declare function parseProxyAuthShape(input: unknown, field: string): ProxyAuthShape;
-export declare function parseProxyMethods(input: unknown, field: string): readonly ProxyMethod[];
-export declare function parseProxyPathPrefixes(input: unknown, field: string): readonly string[];
-export declare function parseProxyAllowedHeaders(input: unknown, field: string, authShape: ProxyAuthShape): readonly string[] | undefined;
-export declare function crossValidateProxyEndpointsAndAuth(endpoints: readonly PlatformProxyEndpoint[] | undefined, auth: readonly PlatformProxyEndpointAuth[] | undefined): void;
 /**
  * Cross-check `submission.secretEnv` declarations against `secrets.envSecrets`
- * values. Mirrors {@link crossValidateProxyEndpointsAndAuth}:
+ * values:
  *
  *  - `{ ephemeral: true }` MUST have a matching `secrets.envSecrets` value.
  *  - `{ ref }` MUST NOT supply a value (the value lives in the workspace store).
@@ -247,15 +189,6 @@ export declare function crossValidateProxyEndpointsAndAuth(endpoints: readonly P
  */
 export declare function crossValidateSecretEnvAndValues(secretEnv: Readonly<Record<string, PlatformSecretEnvEntry>> | undefined, envSecrets: Readonly<Record<string, string>> | undefined): void;
 export declare function parseInlineSecrets(input: unknown): PlatformInlineSecrets;
-/**
- * The proxy body-redactor refuses to mask any derived target string shorter
- * than this many bytes — masking a 1-byte literal would corrupt the response
- * body. This is the floor for the *derived* redaction targets (e.g.
- * `Bearer <token>`, base64 fragments), used by
- * the hosted proxy redactor, which imports this constant so the two sides can
- * never silently diverge.
- */
-export declare const MIN_REDACTION_TARGET_BYTES = 4;
 export declare function assertNoSecretBearingFields(input: unknown, path: readonly string[]): void;
 export declare function requireRecord(input: unknown, field: string): Record<string, unknown>;
 export declare function requireString(input: unknown, field: string): string;
@@ -389,7 +322,6 @@ export interface PlatformRunSubmissionRequest {
     readonly provider: RunProvider;
     readonly submission: PlatformSubmission;
     readonly secrets: PlatformInlineSecrets;
-    readonly proxyEndpoints?: readonly PlatformProxyEndpoint[];
     /**
      * Managed runtime size. One of the closed {@link RuntimeSize} preset tokens
      * or absent (downstream applies the default).
@@ -402,33 +334,31 @@ export interface PlatformRunSubmissionRequest {
      * terminal wait window and self-kill deadline.
      */
     readonly timeoutMs?: number;
-    /**
-     * Lineage parent (agent-session §9). When present the server admits this
-     * run as a CHILD of `parentRunId`: it walks the parent's lineage, enforces
-     * the max-subagent-depth + per-root concurrency caps, and persists
-     * `parent_run_id` + a server-derived `depth`. The client may name a parent
-     * but NEVER the depth — depth is computed server-side from the parent row,
-     * so a forged value cannot bypass the cap.
-     */
-    readonly parentRunId?: string;
     /**
      * Optional per-run callback URL. The platform delivers exactly the terminal
      * `run.finished` event to this URL at the settle-consistent barrier, signed
-     * Standard-Webhooks style. It is a sibling of {@link idempotencyKey} /
-     * {@link parentRunId} — an operational/delivery concern, NOT part of the
-     * hashed submission brief, so the same idempotency key with a different
-     * callback URL never 409s and the field never enters `request_hash`.
+     * Standard-Webhooks style. It is a sibling of {@link idempotencyKey} — an
+     * operational/delivery concern, NOT part of the hashed submission brief, so
+     * the same idempotency key with a different callback URL never 409s and the
+     * field never enters `request_hash`.
      */
     readonly webhook?: RunWebhookSpec;
     /**
      * Optional per-run override of the lineage limits (max concurrent child runs,
-     * max subagent depth). A sibling of {@link parentRunId} — these are dials the
-     * client may *request*; the server resolves them against the per-workspace
-     * ceiling and the hard platform ceiling (clamping happens in the resolver, NOT
-     * this parser). Absent fields fall back to the platform defaults. Only shape +
+     * max subagent depth, per-run spend cap). These are dials the client may
+     * *request*; the server resolves them against the per-workspace ceiling and
+     * the hard platform ceiling (clamping happens in the resolver, NOT this
+     * parser). Absent fields fall back to the platform defaults. Only shape +
      * positivity are validated here.
      */
     readonly limits?: RunLimits;
+    /**
+     * Optional capacity intent for the run's managed machine. `spot: true` opts
+     * the run into interruptible capacity; absent / `spot: false` requests
+     * standard capacity (the default). Intent only — the managed runtime selects
+     * capacity from it.
+     */
+    readonly machine?: RunMachine;
 }
 /** Per-run webhook callback. v1: terminal-only; the URL must be https. */
 export interface RunWebhookSpec {
@@ -444,15 +374,26 @@ export interface RunLimits {
     readonly maxConcurrentChildRuns?: number;
     readonly maxSubagentDepth?: number;
     /**
-     * Per-run spend cap in USD (defense-in-depth). The platform converts it to a
-     * wall-clock budget (priced compute is wall-time; BYOK provider tokens cost the
-     * platform nothing) and kills the run once it would out-spend the cap. A
-     * positive number; omitted ⇒ unbounded per-run (only the run's wall-clock
-     * `timeout` + the per-workspace spend cap apply). Only shape/positivity are
-     * validated here.
+     * Per-run spend cap in USD (defense-in-depth). The platform kills the run once
+     * it would out-spend the cap. A positive number; omitted ⇒ unbounded per-run
+     * (only the run's wall-clock `timeout` + the per-workspace spend cap apply).
+     * Only shape/positivity are validated here.
+     *
+     * The frozen boot session config the managed runtime folds the loop against
+     * names this same USD value `budgetUsd`; {@link sessionBudgetLimits} is the
+     * single source of truth for that wire→boot name mapping.
      */
     readonly maxSpendUsd?: number;
 }
+/**
+ * Per-run machine/capacity intent. v1 exposes only `spot`: opt the run into
+ * interruptible capacity (`spot: true`) vs standard capacity (absent /
+ * `spot: false`, the default). Only the boolean intent is public — capacity
+ * selection is a runtime concern.
+ */
+export interface RunMachine {
+    readonly spot?: boolean;
+}
 /**
  * Wire shape posted by the SDK and CLI. `workspaceId` is **omitted by
  * design** — token-authenticated clients never name the workspace
@@ -500,6 +441,32 @@ export declare function parseRunWebhook(input: unknown): RunWebhookSpec | undefi
  * collapses to `undefined` so it carries no signal onto the request.
  */
 export declare function parseRunLimits(input: unknown): RunLimits | undefined;
+/**
+ * Boot-session budget fragment. The public submit surface names a run's spend
+ * cap `limits.maxSpendUsd`; the frozen boot session config the managed runtime
+ * folds the loop against names the SAME USD value `budgetUsd` — the field the
+ * session planner reads to enforce/terminate a run that would out-spend its cap.
+ * This is the single source of truth for that wire→boot name mapping so the two
+ * layers can never drift.
+ *
+ * Returns a fragment safe to spread into `sessionConfig.limits`: `{ budgetUsd }`
+ * when a cap is set, `{}` when none is (an absent cap stays absent — the run is
+ * unbounded per-run, subject only to the run timeout + the per-workspace cap).
+ * Pure: same input ⇒ same output.
+ */
+export declare function sessionBudgetLimits(limits: RunLimits | undefined): {
+    budgetUsd?: number;
+};
+/**
+ * Parse the optional per-run `machine` capacity intent. Mirrors
+ * {@link parseRunWebhook}: absent ⇒ `undefined`; a non-object or any unknown
+ * subfield is rejected so the strict top-level allow-list extends to the nested
+ * object. `spot` must be a boolean when present. A no-signal object (e.g.
+ * `machine: {}`) collapses to `undefined` so it never lands an empty object on
+ * the request. An explicit `spot` (true or false) is preserved verbatim. Only
+ * shape is validated here — capacity selection is a runtime concern.
+ */
+export declare function parseRunMachine(input: unknown): RunMachine | undefined;
 export declare function parseRunProvider(input: unknown): RunProvider;
 /**
  * Cross-check the supplied secrets bundle against the credential mode. BYOK