@aexhq/sdk 0.40.16 → 0.41.1

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

@@ -1,8 +1,8 @@
 import type { SessionStatus, SessionTerminalOutcome } from "./status.js";
-import type { RunCostProviderUsage } from "./run-cost.js";
-import type { PlatformRunSubmissionInput, PlatformSubmission } from "./submission.js";
+import type { SessionCostProviderUsage } from "./session-cost.js";
+import type { PlatformSessionSubmissionInput, PlatformSubmission } from "./submission.js";
 /**
- * Loose record describing a run as the dashboard BFF returns it. Concrete
+ * Loose record describing a session as the dashboard BFF returns it. Concrete
  * dashboard-managed fields appear in the index signature; the SDK and CLI
  * may surface them without strong typing per-field.
  *
@@ -12,7 +12,7 @@ import type { PlatformRunSubmissionInput, PlatformSubmission } from "./submissio
  * rollout; SDK consumers MUST treat it as best-effort and not panic on
  * its absence.
  */
-export interface Run {
+export interface SessionRecord {
     readonly id: string;
     readonly status: string;
     readonly workspaceId?: string;
@@ -20,10 +20,10 @@ export interface Run {
     readonly updatedAt?: string;
     readonly terminalAt?: string | null;
     /**
-     * The run's EXECUTION start (ISO-8601) — when the agent actually began
+     * The session's EXECUTION start (ISO-8601) — when the agent actually began
      * running, distinct from {@link createdAt} (submission/accept time). Present
-     * from the moment the run starts executing and throughout its live duration;
-     * absent before it starts and after the run's live object is torn down (a
+     * from the moment the session starts executing and throughout its live duration;
+     * absent before it starts and after the session's live object is torn down (a
      * terminal run also carries {@link terminalAt} and {@link costTelemetry}
      * durations).
      */
@@ -36,18 +36,18 @@ export interface Run {
      */
     readonly failureClass?: string | null;
     /**
-     * Aggregate token usage when a deployment chooses to expose it on the run
+     * Aggregate token usage when a deployment chooses to expose it on the session
      * record. Mid-run this is not populated. Settled provider/runtime usage is
      * exposed through {@link costTelemetry}; per-turn usage breadcrumbs, when a
      * deployment records them internally, are not part of the normal public event
      * stream.
      */
     readonly usage?: UsageSummary;
-    readonly costTelemetry?: import("./run-cost.js").RunCostTelemetry;
+    readonly costTelemetry?: import("./session-cost.js").SessionCostTelemetry;
     /**
-     * The authoritative terminal OUTCOME of the run's last turn — the settle-
+     * 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}. Absent until the run settles.
+     * from the resumable lifecycle {@link status}. Absent until the session settles.
      */
     readonly lastTurnOutcome?: SessionTerminalOutcome;
     readonly runtimeManifest?: import("./runtime-manifest.js").RuntimeManifest;
@@ -131,7 +131,7 @@ export interface SessionRetentionPolicy {
 export type SessionSubmission = Omit<PlatformSubmission, "prompt"> & {
     readonly prompt?: readonly string[];
 };
-export type SessionCreateRequest = Omit<PlatformRunSubmissionInput, "idempotencyKey" | "submission"> & {
+export type SessionCreateRequest = Omit<PlatformSessionSubmissionInput, "idempotencyKey" | "submission"> & {
     readonly submission: SessionSubmission;
     readonly input?: string | readonly string[];
     readonly retention?: SessionRetentionPolicy;
@@ -181,20 +181,20 @@ export interface UsageSummary {
 }
 /**
  * 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
+ * {@link SessionCostProviderUsage} entries — the SINGLE server source of token
+ * usage ({@link SessionRecord.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;
+export declare function usageFromProviderUsage(providerUsage: readonly SessionCostProviderUsage[] | undefined): UsageSummary;
 /**
- * The unified SETTLED-RESULT contract shared by `run()` and `done()`. Because
+ * The unified SETTLED-RESULT contract shared by `start()` 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()`.
+ * `SessionResult`/`SessionTurnResult` extend this one shape so `done()` == `start()`.
  *
  * `costUsd` is the AEX showback estimate in USD (>= 0) and EXCLUDES the
  * customer's BYOK provider spend — price BYOK from `usage` tokens.
@@ -208,7 +208,7 @@ export interface SettledResult {
     readonly costUsd: number;
     /** Aggregate token usage, derived from `costTelemetry.providerUsage`. */
     readonly usage: UsageSummary;
-    /** Terminal failure message (from the terminal `RUN_ERROR` event) when `!ok`. */
+    /** Terminal failure message (from the terminal `TURN_ERROR` event) when `!ok`. */
     readonly error?: string;
 }
 /**
@@ -217,29 +217,29 @@ export interface SettledResult {
  *   - `uncertain` — the model signalled low confidence / declined to commit.
  *   - `refused` — the model refused the request.
  */
-export type RunRefusalReason = "schema_violation" | "uncertain" | "refused";
+export type TurnRefusalReason = "schema_violation" | "uncertain" | "refused";
 /**
- * The typed outcome of a `run<T>({ responseFormat })`: EITHER a schema-valid
+ * The typed outcome of a `start<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> = {
+export type TurnOutcome<T = unknown> = {
     readonly kind: "decoded";
     readonly value: T;
 } | {
     readonly kind: "refused";
-    readonly reason: RunRefusalReason;
+    readonly reason: TurnRefusalReason;
     readonly detail?: string;
 };
 /** One item's settled result inside a {@link BatchResult}. */
 export interface BatchItemResult<T = unknown> extends SettledResult {
-    readonly runId: string;
+    readonly sessionId: string;
     /** Present only for a `responseFormat`-decoded item. */
-    readonly outcome?: RunOutcome<T>;
+    readonly outcome?: TurnOutcome<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
+ * rollup. The rollup is honest because `start()` awaits settle, so every item's
  * `costUsd`/`usage` is populated — a missing cost is a typed absent, not a
  * silent `$0`.
  */
@@ -251,13 +251,13 @@ export interface BatchResult<T = unknown> {
     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
+ * Filters for {@link import("./operations.js").listSessionRecords} / the CLI's `aex sessions`.
+ * Every field is optional; omitting all of them lists the most recent sessions in the
  * token's workspace. Workspace identity is derived server-side from the API key,
- * so there is no `workspaceId` here — a token can only ever enumerate its own runs.
+ * so there is no `workspaceId` here — a token can only ever enumerate its own sessions.
  */
-export interface RunListQuery {
-    /** Restrict to a single run status, e.g. `"succeeded"`. */
+export interface SessionRecordListQuery {
+    /** Restrict to a single session status, e.g. `"succeeded"`. */
     readonly status?: string;
     /** ISO-8601 lower bound on `createdAt` (inclusive). */
     readonly since?: string;
@@ -267,46 +267,46 @@ export interface RunListQuery {
     readonly cursor?: string;
 }
 /**
- * A public-safe run summary as returned by `GET /api/runs` (the workspace run
+ * A public-safe run summary as returned by `GET /api/sessions` (the workspace run
  * list). DELIBERATELY omits the submission snapshot (model/prompt/env) — the full,
- * redaction-scanned submission is only reachable through `getRunUnit(runId)`.
+ * redaction-scanned submission is only reachable through `getSessionUnit(sessionId)`.
  */
-export interface RunSummary {
+export interface SessionRecordSummary {
     readonly id: string;
     readonly status: string;
     readonly createdAt: string;
     readonly updatedAt: string;
-    /** Settled showback estimate (USD), present once the run has cost telemetry. */
+    /** Settled showback estimate (USD), present once the session has cost telemetry. */
     readonly costUsd?: number;
 }
-/** One page of the workspace run list. `nextCursor` absent ⇒ last page. */
-export interface RunListPage {
-    readonly runs: readonly RunSummary[];
+/** One page of the workspace session list. `nextCursor` absent ⇒ last page. */
+export interface SessionRecordListPage {
+    readonly sessions: readonly SessionRecordSummary[];
     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`.
+ * The minimal capability a value must carry to be RESOLVABLE through the session
+ * facade — `getSessionRecord` / `listSessionRecordEvents` / `listSessionFiles` 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
+ * platform hands you as a session reference exposes a resolvable `id`, so a session can
  * never be surfaced as a bare unresolvable string.
  */
-export interface ResolvableRunRef {
+export interface ResolvableSessionRef {
     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.
+ * A subagent child session, enumerated under its parent via `GET /sessions/:id/children`.
+ * A first-class, lineage-discoverable run reference: it {@link ResolvableSessionRef}
+ * (its `id` resolves through the session record facade — events/files/getSessionRecord), carries the
+ * lineage (`parentSessionId`/`depth`) and the terminal outcome/cost, so a child is
+ * observable exactly like a top-level session.
  */
-export interface ChildRunRef extends ResolvableRunRef {
-    /** The parent run this child was spawned by. */
-    readonly parentRunId: string;
-    /** The child's run status. */
+export interface ChildSessionRef extends ResolvableSessionRef {
+    /** The parent session this child was spawned by. */
+    readonly parentSessionId: string;
+    /** The child's session status. */
     readonly status: string;
-    /** Subagent nesting depth (1 = direct child of the top-level run). */
+    /** Subagent nesting depth (1 = direct child of the top-level session). */
     readonly depth?: number;
     /** Settled AEX showback estimate (USD) for the child, when present. */
     readonly costUsd?: number;
@@ -316,18 +316,18 @@ export interface ChildRunRef extends ResolvableRunRef {
     readonly lastTurnOutcome?: SessionTerminalOutcome;
 }
 /**
- * Cross-run output search query (`Aex.sessions.searchOutputs`). 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
- * cross-run index, body-only swap.
+ * Cross-session session-file search query (`Aex.files.search`). Restrict to a
+ * corpus with `sessionIds`; filter by filename substring / extension / content type.
+ * The MVP composes this client-side (per-session `listSessionFiles` + filter) — a future
+ * server-side `GET /api/files/search` can back the same contract with a real
+ * cross-session index, body-only swap.
  */
-export interface OutputSearchQuery {
-    /** Restrict the search to these runs (the chat corpus allow-list). */
-    readonly runIds?: readonly string[];
+export interface SessionFileSearchQuery {
+    /** Restrict the search to these sessions (the chat corpus allow-list). */
+    readonly sessionIds?: readonly string[];
     /**
      * Filename match. A string is a case-insensitive SUBSTRING match; a RegExp is
-     * tested as given. Unified with {@link OutputQuery.filename} (`string | RegExp`)
+     * tested as given. Unified with {@link SessionFileQuery.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.
      */
@@ -339,30 +339,30 @@ export interface OutputSearchQuery {
     /** Cap the number of hits returned (default 100). */
     readonly limit?: number;
 }
-/** One output-search hit — a reference only (no bytes); read with `readOutputText`. */
-export interface OutputSearchHit {
-    readonly runId: string;
-    readonly outputId: string;
+/** One session-file search hit — a reference only (no bytes); read with `readSessionFileText`. */
+export interface SessionFileSearchHit {
+    readonly sessionId: string;
+    readonly fileId: string;
     readonly filename?: string;
     readonly sizeBytes?: number;
     readonly contentType?: string;
 }
-/** A page of output-search hits. */
-export interface OutputSearchPage {
-    readonly hits: readonly OutputSearchHit[];
+/** A page of session-file search hits. */
+export interface SessionFileSearchPage {
+    readonly hits: readonly SessionFileSearchHit[];
 }
-/** Status of a per-run webhook delivery. Terminal: delivered/exhausted/invalid. */
-export type RunWebhookDeliveryStatus = "pending" | "delivering" | "retrying" | "delivered" | "exhausted" | "invalid";
+/** Status of a per-session webhook delivery. Terminal: delivered/exhausted/invalid. */
+export type SessionWebhookDeliveryStatus = "pending" | "delivering" | "retrying" | "delivered" | "exhausted" | "invalid";
 /**
- * One row of a run's webhook delivery ledger, as returned by
- * `GET /api/runs/:id/webhook-deliveries`. `id` is the stable `webhook-id`
+ * One row of a session's webhook delivery ledger, as returned by
+ * `GET /api/sessions/:id/webhook-deliveries`. `id` is the stable `webhook-id`
  * header the consumer dedupes on across retries; the optional fields are
  * populated only once a delivery attempt has been made.
  */
-export interface RunWebhookDelivery {
+export interface SessionWebhookDelivery {
     readonly id: string;
     readonly eventType: string;
-    readonly status: RunWebhookDeliveryStatus;
+    readonly status: SessionWebhookDeliveryStatus;
     readonly attemptCount: number;
     readonly lastStatusCode?: number;
     readonly lastError?: string;
@@ -381,10 +381,10 @@ export interface ProviderEvent {
     readonly [key: string]: unknown;
 }
 /**
- * One captured output file as the dashboard reports it. Use
- * `outputLink` / `createOutputLink` to get a temporary direct URL for download.
+ * One captured session file as the dashboard reports it. Use
+ * `sessionFileLink` / `createSessionFileLink` to get a temporary direct URL for download.
  */
-export interface Output {
+export interface SessionFile {
     readonly id: string;
     readonly filename?: string;
     readonly sizeBytes?: number;
@@ -392,15 +392,15 @@ export interface Output {
     readonly createdAt?: string;
     readonly [key: string]: unknown;
 }
-export type OutputFilePathMatch = "exact" | "suffix";
-export type OutputFileType = "text" | "json" | "image" | "audio" | "video" | "pdf" | "archive" | "binary" | "unknown";
-export interface OutputQuery {
-    /** Exact normalized output path. Leading `/` and `outputs/` are ignored. */
+export type SessionFilePathMatch = "exact" | "suffix";
+export type SessionFileType = "text" | "json" | "image" | "audio" | "video" | "pdf" | "archive" | "binary" | "unknown";
+export interface SessionFileQuery {
+    /** Exact normalized file path. Leading `/` and `files/` are ignored. */
     readonly path?: string;
     /** Basename match. A RegExp is tested against the basename only. */
     readonly filename?: string | RegExp;
     /**
-     * Directory prefix. Leading `/` and `outputs/` are ignored.
+     * Directory prefix. Leading `/` and `files/` are ignored.
      * `recursive` defaults to true.
      */
     readonly dir?: string;
@@ -410,22 +410,22 @@ export interface OutputQuery {
     /** Exact content type or a prefix wildcard such as `image/*`. */
     readonly contentType?: string;
     /** High-level type inferred from content type first, then extension. */
-    readonly type?: OutputFileType;
+    readonly type?: SessionFileType;
 }
-export interface OutputFilePathSelector {
+export interface SessionFilePathSelector {
     readonly path: string;
-    readonly match?: OutputFilePathMatch;
+    readonly match?: SessionFilePathMatch;
 }
-export interface OutputFileIdSelector {
+export interface SessionFileIdSelector {
     readonly id: string;
 }
-export type OutputFileSelector = Output | OutputFileIdSelector | OutputFilePathSelector;
-export interface OutputFileDownload {
-    readonly output: Output;
+export type SessionFileSelector = SessionFile | SessionFileIdSelector | SessionFilePathSelector;
+export interface SessionFileDownload {
+    readonly file: SessionFile;
     readonly bytes: Uint8Array;
 }
-/** Options for `Aex.sessions.outputs(id).read` / {@link import("./operations.js").readOutputText}. */
-export interface ReadOutputTextOptions {
+/** Options for `Aex.sessions.files(id).read` / {@link import("./operations.js").readSessionFileText}. */
+export interface ReadSessionFileTextOptions {
     /**
      * Stop reading after this many bytes. Defaults to 50_000; clamped server-side
      * of the SDK to [1, 10_000_000]. The read streams and cancels once the cap is
@@ -433,8 +433,8 @@ export interface ReadOutputTextOptions {
      */
     readonly maxBytes?: number;
     /**
-     * Per-attempt timeout for fetching and reading the selected output body.
-     * Defaults to 30_000ms; idempotent output reads retry once on timeout before
+     * Per-attempt timeout for fetching and reading the selected file body.
+     * Defaults to 30_000ms; idempotent file reads retry once on timeout before
      * surfacing a structured NETWORK_ERROR.
      */
     readonly timeoutMs?: number;
@@ -445,14 +445,14 @@ export interface ReadOutputTextOptions {
     readonly grep?: string | RegExp;
 }
 /**
- * A byte-capped, decoded text read of one output file, as returned by
- * `Aex.sessions.outputs(id).read`. Built for feeding run deliverables to an LLM
+ * A byte-capped, decoded text read of one session file, as returned by
+ * `Aex.sessions.files(id).read`. Built for feeding session 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.
  */
-export interface OutputText {
-    readonly output: Output;
+export interface SessionFileText {
+    readonly file: SessionFile;
     /** Decoded UTF-8, capped to the requested `maxBytes`. */
     readonly text: string;
     /** True when the file is larger than `maxBytes` (so `text` is a prefix). */
@@ -463,16 +463,16 @@ export interface OutputText {
      */
     readonly totalBytes: number;
 }
-export type OutputLinkExpiresIn = number | "15m" | "1h" | "1d";
-export interface OutputLinkOptions {
+export type SessionFileLinkExpiresIn = number | "15m" | "1h" | "1d";
+export interface SessionFileLinkOptions {
     /** Seconds or one of the documented presets. Defaults to `"1h"`. */
-    readonly expiresIn?: OutputLinkExpiresIn;
+    readonly expiresIn?: SessionFileLinkExpiresIn;
 }
-export interface OutputLink {
+export interface SessionFileLink {
     readonly url: string;
     readonly expiresAt?: string;
     readonly expiresInSeconds?: number;
-    readonly output?: Output;
+    readonly file?: SessionFile;
     readonly [key: string]: unknown;
 }
 export interface WhoAmI {
@@ -496,21 +496,21 @@ export interface WhoAmI {
      * `null` means no app-visible cap is applied for that field.
      */
     readonly caps?: {
-        /** Token-bucket cap on POST /api/runs per minute, per workspace. */
-        readonly runSubmitPerMinute?: number;
-        /** Hard cap on concurrent non-terminal runs the workspace may hold. */
-        readonly maxConcurrentRuns?: number;
-        /** Storage cap (bytes) on captured output objects, workspace-wide. `null` means unlimited. */
+        /** Token-bucket cap on POST /api/sessions per minute, per workspace. */
+        readonly sessionSubmitPerMinute?: number;
+        /** Hard cap on concurrent non-terminal sessions the workspace may hold. */
+        readonly maxConcurrentSessions?: number;
+        /** Storage cap (bytes) on captured file objects, workspace-wide. `null` means unlimited. */
         readonly storageCapBytes?: number | null;
-        /** Current captured-output usage in bytes. */
+        /** Current captured-file usage in bytes. */
         readonly storageUsedBytes?: number;
         /**
          * Wall-clock ceiling on a single run before forced termination.
          * `null` means no aex-imposed cap, but this is **not unlimited
          * overall**: the managed runner, infrastructure, or upstream provider may
-         * still impose a ceiling, and a run that exceeds it terminates regardless.
+         * still impose a ceiling, and a session that exceeds it terminates regardless.
          */
-        readonly maxRunDurationMs?: number | null;
+        readonly maxSessionDurationMs?: number | null;
     };
     /**
      * ADDITIVE effective per-workspace limits returned by `GET /whoami` on
@@ -521,7 +521,7 @@ export interface WhoAmI {
      */
     readonly limits?: {
         /** Effective live-run concurrency cap. One more live run past it fails with `429 workspace_concurrency_exceeded`. */
-        readonly maxConcurrentRuns: number;
+        readonly maxConcurrentSessions: 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`. */
@@ -541,7 +541,7 @@ export interface WhoAmI {
  * Workspace skill bundle as the dashboard BFF returns it. Mirrors a row
  * of `skill_bundles` joined with its computed manifest. `state` is the
  * upload lifecycle (`pending` -> `ready`); only `ready` rows are
- * referenceable from a run. Delete is hard; historical runs keep their
+ * referenceable from a session. Delete is hard; historical sessions keep their
  * submit-time snapshots rather than depending on this row.
  *
  * See the public architecture notes and server-side persistence schema for
@@ -614,7 +614,7 @@ export interface FileRecord {
  * 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
+ * upserts one under a stable `name`; a session 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.
@@ -636,7 +636,7 @@ export interface SkillRecord {
  * Wire-level record for a workspace secret as returned by the BFF.
  *
  * Workspace secrets share the lifecycle SEMANTIC of skills/files: a
- * `Secret.value(...)` is per-run and gone at terminal; PROMOTING it (or
+ * `Secret.value(...)` is per-session and gone at terminal; PROMOTING it (or
  * `aex.secrets.set`) persists a named, searchable workspace secret. The
  * identity is the `name` (the handle a `Secret.ref` points at); the value
  * rotates under that stable name, bumping `version`.
@@ -675,7 +675,7 @@ export interface BillingSummary {
     readonly balanceUsd: number;
     /** Accrued spend for the current calendar month. */
     readonly monthSpendUsd: number;
-    /** Monthly spend cap enforced on new runs. */
+    /** Monthly spend cap enforced on new sessions. */
     readonly spendCapUsd: number;
     readonly planKey: string;
     readonly subscriptionStatus: string;
@@ -710,12 +710,12 @@ export interface BillingHostedSession {
  */
 export interface BillingLedgerEntry {
     readonly id: string;
-    /** e.g. `top_up`, `run_charge`. Open server vocabulary. */
+    /** e.g. `top_up`, `session_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;
+    /** The session this entry charges, `null` for non-run entries. */
+    readonly sessionId?: string | null;
     readonly description?: string | null;
     readonly createdBy?: string;
     readonly createdAt: string;

package/dist/_contracts/runtime-types.js

@@ -1,7 +1,7 @@
 /**
  * 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
+ * {@link SessionCostProviderUsage} entries — the SINGLE server source of token
+ * usage ({@link SessionRecord.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

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

@@ -1,5 +1,5 @@
 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 type AexErrorCode = "SESSION_CONFIG_INVALID" | "CREDENTIAL_INVALID" | "PROVIDER_ERROR" | "SESSION_STATE_ERROR" | "CLEANUP_ERROR" | "RUNTIME_UNSUPPORTED" | "API_ERROR" | "NETWORK_ERROR";
 export declare class AexError extends Error {
     readonly code: AexErrorCode;
     readonly details?: unknown;
@@ -7,7 +7,7 @@ export declare class AexError extends Error {
         readonly cause?: unknown;
     });
 }
-export declare class RunConfigValidationError extends AexError {
+export declare class SessionConfigValidationError extends AexError {
     constructor(message: string, details?: unknown);
 }
 export declare class CredentialValidationError extends AexError {
@@ -20,7 +20,7 @@ export declare class ProviderError extends AexError {
         details?: unknown;
     });
 }
-export declare class RunStateError extends AexError {
+export declare class SessionStateError extends AexError {
     /**
      * HTTP status from a wrapped API rejection, when this state error is a
      * bounded client-side interpretation of that rejection.

package/dist/_contracts/sdk-errors.js

@@ -10,9 +10,9 @@ export class AexError extends Error {
         this.details = details === undefined ? undefined : redactSecrets(details);
     }
 }
-export class RunConfigValidationError extends AexError {
+export class SessionConfigValidationError extends AexError {
     constructor(message, details) {
-        super("RUN_CONFIG_INVALID", message, details);
+        super("SESSION_CONFIG_INVALID", message, details);
     }
 }
 export class CredentialValidationError extends AexError {
@@ -27,7 +27,7 @@ export class ProviderError extends AexError {
         this.status = options.status;
     }
 }
-export class RunStateError extends AexError {
+export class SessionStateError extends AexError {
     /**
      * HTTP status from a wrapped API rejection, when this state error is a
      * bounded client-side interpretation of that rejection.
@@ -42,7 +42,7 @@ export class RunStateError extends AexError {
             ? details
             : undefined;
         const cause = options?.cause ?? detailRecord?.cause;
-        super("RUN_STATE_ERROR", message, details, cause === undefined ? undefined : { cause });
+        super("SESSION_STATE_ERROR", message, details, cause === undefined ? undefined : { cause });
         const status = detailRecord?.httpStatus ?? detailRecord?.status;
         const apiCode = detailRecord?.apiCode;
         this.status = typeof status === "number" ? status : undefined;

package/dist/_contracts/sdk-secrets.js

@@ -55,25 +55,25 @@ const MIN_CHAR_CLASSES = 2;
  * A mixed-case run with no digit and < this length is treated as a benign
  * identifier, not a secret. Real opaque secrets are alnum-mixed (carry a
  * digit) or very long; digit-free camelCase identifiers like
- * `asyncRunEntryPointWithESMLoader` / `getReadableStreamController` (which
+ * `asyncEntryPointWithESMLoader` / `getReadableStreamController` (which
  * appear in stack traces the diagnostic bundle captures) are 24–39 chars and
  * digit-free — eating them would gut debuggability. The length escape hatch
  * still catches the rare long digit-free secret.
  */
 const HIGH_ENTROPY_NO_DIGIT_MIN_LEN = 40;
 /**
- * Canonical aex run-id hex: exactly 32 lowercase hex chars directly preceded
- * by `run_`. The HIGH_ENTROPY_CANDIDATE class excludes `_`, so the candidate
- * run for a run id is the bare hex — dense enough to trip the entropy gate.
+ * Canonical aex session-id hex: exactly 32 lowercase hex chars directly preceded
+ * by `ses_`. The HIGH_ENTROPY_CANDIDATE class excludes `_`, so the candidate
+ * candidate for a session id is the bare hex — dense enough to trip the entropy gate.
  * Masking it destroys the ONE identifier every error message needs for
- * traceability (`cancel via openSession("run_[REDACTED]")` is useless
- * guidance). A run id is not a credential: it grants nothing without the
+ * traceability (`cancel via openSession("ses_[REDACTED]")` is useless
+ * guidance). A session id is not a credential: it grants nothing without the
  * bearer token. Mirrors the platform-side redactor's canonical-id exemption.
  */
-function isCanonicalRunIdHex(input, matchStart, match) {
+function isCanonicalSessionIdHex(input, matchStart, match) {
     if (!/^[0-9a-f]{32}$/.test(match))
         return false;
-    return input.slice(Math.max(0, matchStart - 4), matchStart) === "run_";
+    return input.slice(Math.max(0, matchStart - 4), matchStart) === "ses_";
 }
 export class SecretString {
     #value;
@@ -133,7 +133,7 @@ export function redactString(input, known = []) {
     // Patterns with a captured prefix (Authorization header) keep the
     // prefix; the rest replace the whole match.
     typeof captured === "string" ? `${captured} ${REDACTED}` : REDACTED), out);
-    return out.replace(HIGH_ENTROPY_CANDIDATE, (match, offset, whole) => !isCanonicalRunIdHex(whole, offset, match) && looksHighEntropySecret(match) ? REDACTED : match);
+    return out.replace(HIGH_ENTROPY_CANDIDATE, (match, offset, whole) => !isCanonicalSessionIdHex(whole, offset, match) && looksHighEntropySecret(match) ? REDACTED : match);
 }
 export function containsSecretLikeValue(input) {
     if (SECRET_PATTERNS.some((pattern) => {
@@ -145,7 +145,7 @@ export function containsSecretLikeValue(input) {
     HIGH_ENTROPY_CANDIDATE.lastIndex = 0;
     let candidate;
     while ((candidate = HIGH_ENTROPY_CANDIDATE.exec(input)) !== null) {
-        if (isCanonicalRunIdHex(input, candidate.index, candidate[0])) {
+        if (isCanonicalSessionIdHex(input, candidate.index, candidate[0])) {
             continue;
         }
         if (looksHighEntropySecret(candidate[0])) {