@aexhq/sdk 0.40.16 → 0.41.1

package/README.md

@@ -8,10 +8,10 @@ aex is an agent execution platform for launching autonomous agents from a simple
 
 The package ships:
 
-- `Aex` for sessions, one-shot runs, inspect, download, cancel, and delete.
+- `Aex` for sessions, one-shot sessions, inspect, download, cancel, and delete.
 - `sessions` / `openSession()` for durable, resumable agent sessions.
 - Typed run primitives: `Models`, `Providers`, `Sizes`, `Skill`, `Tool` / `Tools`, `AgentsMd`, `File`, `McpServer`, and `Secret`.
-- A bundled `aex` CLI with the same run, status, events, outputs, download, cancel, delete, and whoami operations.
+- A bundled `aex` CLI with the same run, status, events, files, download, cancel, delete, and whoami operations.
 
 ## Install
 
@@ -55,24 +55,24 @@ const resumed = await aex.openSession(session.id);
 await resumed.send("Continue with the follow-up validation.").done();
 ```
 
-Need a one-shot convenience? `run()` opens a session, sends `message` as one
-turn, and returns the collected result. The returned `runId` is the session id,
-so it can be resumed later with `openSession(runId)`.
+Need a one-shot convenience? `start()` opens a session, sends `message` as one
+turn, and returns the collected result. The returned `sessionId` is the session id,
+so it can be resumed later with `openSession(sessionId)`.
 
 ```ts
-const result = await aex.run({
+const result = await aex.start({
   model: Models.CLAUDE_HAIKU_4_5,
   apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! },
-  message: "Write the report and save outputs."
+  message: "Write the report and save files."
 });
 
-console.log(result.runId, result.status, result.text);
+console.log(result.sessionId, result.status, result.text);
 ```
 
 For multiple providers, include each BYOK key in `apiKeys`:
 
 ```ts
-await aex.run({
+await aex.start({
   model: Models.CLAUDE_HAIKU_4_5,
   apiKeys: {
     anthropic: process.env.ANTHROPIC_API_KEY!,
@@ -85,11 +85,11 @@ await aex.run({
 The same request can run from the bundled CLI (`npx aex` on a local install):
 
 ```bash
-npx aex run \
+npx aex start \
   --api-key "$AEX_API_KEY" \
   --anthropic-api-key "$ANTHROPIC_API_KEY" \
   --model claude-haiku-4-5 \
-  --prompt "Write the report and save outputs." \
+  --prompt "Write the report and save files." \
   --follow
 ```
 
@@ -115,44 +115,44 @@ by default, machine JSON under `--json`). Per-verb `--help` is also key-free:
 npx aex models list           # canonical models + their default provider
 npx aex providers list        # providers + the models each serves
 npx aex tools list            # complete builtin tool set
-npx aex runtime-sizes list    # managed runtime presets (cpus / memory / default)
-npx aex run --help            # flags for one verb (no API key required)
+npx aex starttime-sizes list    # managed runtime presets (cpus / memory / default)
+npx aex start --help            # flags for one verb (no API key required)
 ```
 
-Errors are typed and actionable. Every `openSession()` / `run()` config-validation
-failure throws a `RunConfigValidationError` (`err.code === "RUN_CONFIG_INVALID"`)
+Errors are typed and actionable. Every `openSession()` / `start()` config-validation
+failure throws a `SessionConfigValidationError` (`err.code === "SESSION_CONFIG_INVALID"`)
 you can `catch` by code; CLI failures print a JSON envelope carrying the HTTP
-`status`, a one-line `remedy`, and the `runId` where known, and a wrong `--model`,
+`status`, a one-line `remedy`, and the `sessionId` where known, and a wrong `--model`,
 `--provider`, or `--runtime-size` gets a "did you mean?" suggestion.
 
 ## Continue with sessions
 
-Use sessions for conversational flows. `run()` is the one-shot convenience; a
+Use sessions for conversational flows. `start()` is the one-shot convenience; a
 `SessionHandle` is the lower-level surface when you want multiple turns,
-streaming, messages, events, outputs, or downloads.
+streaming, messages, events, files, or downloads.
 
 ```ts
-const session = await aex.openSession(result.runId);
+const session = await aex.openSession(result.sessionId);
 const next = await session.send("Turn this into a checklist.").done();
 console.log(next.text);
 
 const messages = await session.messages().list();
-const outputs = await aex.sessions.outputs(session.id).list();
+const files = await aex.sessions.files(session.id).list();
 ```
 
 ## Feature Areas
 
-- **Agent runtime:** managed autonomous runs with filesystem read/edit, grep/glob/head/tail, open web fetch/search, background commands, code execution, git, and subagents.
-- **Durable infrastructure:** run records, status, wait/cancel/delete, idempotency, typed events, output capture, downloads, timeouts, and runtime sizes.
+- **Agent runtime:** managed autonomous sessions with filesystem read/edit, grep/glob/head/tail, open web fetch/search, background commands, code execution, git, and subagents.
+- **Durable infrastructure:** session records, status, wait/cancel/delete, idempotency, typed events, file capture, downloads, timeouts, and runtime sizes.
 - **Agent composition:** skills, files, AGENTS.md, remote MCP servers, environment variables, packages, and networking controls.
-- **Subagents:** typed parent/child lineage for async child runs, output handoff, and bounded agent delegation.
+- **Subagents:** typed parent/child lineage for async child sessions, file handoff, and bounded agent delegation.
 - **Models and providers:** Anthropic, DeepSeek, OpenAI, Gemini, Mistral, OpenRouter, Doubao, and Doubao China behind one submission shape.
-- **Typed control surface:** strongly typed SDK inputs, CLI parity, BYOK provider keys, workspace secrets, redaction, and output modes.
+- **Typed control surface:** strongly typed SDK inputs, CLI parity, BYOK provider keys, workspace secrets, redaction, assistant text modes, and file capture policy.
 
 ## Docs
 
 - [Quickstart](docs/quickstart.md)
-- [Run configuration](docs/run-config.md)
+- [SessionRecord configuration](docs/session-config.md)
 - [Composition](docs/concepts/composition.md)
 - [Secrets](docs/secrets.md)
 - [Limits](docs/limits.md)

package/dist/_contracts/api-key.d.ts

@@ -24,9 +24,10 @@ export interface ParsedApiKey {
     readonly workspaceId: string;
 }
 /**
- * Canonical form of a workspaceId for EMBEDDING in a key: dashes stripped so the
- * whole key is a single double-click-selectable word (`_` is a word char, `-`
- * is not). Kept byte-for-byte in sync with the platform codec.
+ * Canonical form of a workspaceId for EMBEDDING in a key. Public workspace ids
+ * are `wsp_<uuidhex>`, while storage rows still use dashed UUIDs. Keys embed only
+ * the hex field so the token remains underscore-delimited and double-click
+ * selectable.
  */
 export declare function normalizeWorkspaceId(workspaceId: string): string;
 /**
@@ -39,7 +40,8 @@ export declare function parseApiKey(token: string): ParsedApiKey | null;
  * Assemble a valid API key from its parts (the inverse of {@link parseApiKey}).
  * Unlike the server's `mintApiKeyValue` this takes an EXPLICIT `secret` so it is
  * deterministic — used by codec round-trip / cross-repo parity tests. The
- * embedded workspace id is dash-normalized; `workspaceId` must not contain `_`.
+ * embedded workspace id is normalized; public `wsp_...` ids are accepted and
+ * embedded as their hex field.
  */
 export declare function formatApiKey(input: {
     readonly plane: ApiKeyPlane;

package/dist/_contracts/api-key.js

@@ -21,13 +21,24 @@ export const API_KEY_REGION_TO_CODE = {
 };
 const CODE_TO_REGION = Object.fromEntries(Object.entries(API_KEY_REGION_TO_CODE).map(([region, code]) => [code, region]));
 const API_KEY_PLANE_SET = new Set(API_KEY_PLANES);
+const PUBLIC_WORKSPACE_ID_RE = /^wsp_([0-9a-f]{32})$/i;
+const DASHLESS_UUID_RE = /^[0-9a-f]{32}$/i;
+const UUID_RE = /^([0-9a-f]{8})-([0-9a-f]{4})-([0-9a-f]{4})-([0-9a-f]{4})-([0-9a-f]{12})$/i;
 /**
- * Canonical form of a workspaceId for EMBEDDING in a key: dashes stripped so the
- * whole key is a single double-click-selectable word (`_` is a word char, `-`
- * is not). Kept byte-for-byte in sync with the platform codec.
+ * Canonical form of a workspaceId for EMBEDDING in a key. Public workspace ids
+ * are `wsp_<uuidhex>`, while storage rows still use dashed UUIDs. Keys embed only
+ * the hex field so the token remains underscore-delimited and double-click
+ * selectable.
  */
 export function normalizeWorkspaceId(workspaceId) {
-    return workspaceId.replace(/-/g, "");
+    const trimmed = workspaceId.trim();
+    const publicMatch = PUBLIC_WORKSPACE_ID_RE.exec(trimmed);
+    if (publicMatch)
+        return publicMatch[1].toLowerCase();
+    if (DASHLESS_UUID_RE.test(trimmed))
+        return trimmed.toLowerCase();
+    const uuidMatch = UUID_RE.exec(trimmed);
+    return uuidMatch ? uuidMatch.slice(1).join("").toLowerCase() : trimmed.replace(/-/g, "");
 }
 /**
  * Parse a self-describing API key, or `null` for any legacy/opaque/tampered
@@ -55,20 +66,22 @@ export function parseApiKey(token) {
  * Assemble a valid API key from its parts (the inverse of {@link parseApiKey}).
  * Unlike the server's `mintApiKeyValue` this takes an EXPLICIT `secret` so it is
  * deterministic — used by codec round-trip / cross-repo parity tests. The
- * embedded workspace id is dash-normalized; `workspaceId` must not contain `_`.
+ * embedded workspace id is normalized; public `wsp_...` ids are accepted and
+ * embedded as their hex field.
  */
 export function formatApiKey(input) {
     const code = API_KEY_REGION_TO_CODE[input.region];
     if (code === undefined) {
         throw new Error(`API key region is not supported: ${input.region}`);
     }
-    if (!input.workspaceId || input.workspaceId.includes("_")) {
+    const workspaceField = normalizeWorkspaceId(input.workspaceId);
+    if (!workspaceField || workspaceField.includes("_")) {
         throw new Error("workspaceId must be non-empty and contain no '_'");
     }
     if (!input.secret || input.secret.includes("_")) {
         throw new Error("secret must be non-empty and contain no '_'");
     }
-    const body = ["aex", input.plane, code, normalizeWorkspaceId(input.workspaceId), input.secret].join("_");
+    const body = ["aex", input.plane, code, workspaceField, input.secret].join("_");
     return `${body}_${crc32Base36(body)}`;
 }
 function crc32Base36(input) {

package/dist/_contracts/connection-ticket.d.ts

@@ -4,8 +4,8 @@
  * A browser/runtime WebSocket handshake cannot carry an Authorization header,
  * so a subscriber first obtains a short-lived ticket from an authenticated
  * HTTP endpoint, then presents it as a `?ticket=` query parameter on the WS
- * upgrade. The ticket is an HMAC over `${runId}.${channel}.${exp}` keyed by
- * the coordinator secret — it binds the grant to one run, one stream channel,
+ * upgrade. The ticket is an HMAC over `${sessionId}.${channel}.${exp}` keyed by
+ * the coordinator secret — it binds the grant to one session, one stream channel,
  * and one expiry and is verified without any per-ticket storage.
  *
  * This lives in shared so the coordinator (which verifies) and the API
@@ -14,9 +14,9 @@
  */
 export type ConnectionTicketChannel = "event" | "log" | "all";
 /** Mint a `${channel}.${exp}.${mac}` ticket valid for `ttlMs` from `nowMs`. */
-export declare function mintConnectionTicket(runId: string, secret: string, nowMs: number, ttlMs?: number, channel?: ConnectionTicketChannel): Promise<{
+export declare function mintConnectionTicket(sessionId: string, secret: string, nowMs: number, ttlMs?: number, channel?: ConnectionTicketChannel): Promise<{
     ticket: string;
     expiresAtMs: number;
 }>;
-/** Verify a ticket against `runId`, channel, and current time. Constant-time MAC compare. */
-export declare function verifyConnectionTicket(ticket: string, runId: string, secret: string, nowMs: number, channel?: ConnectionTicketChannel): Promise<boolean>;
+/** Verify a ticket against `sessionId`, channel, and current time. Constant-time MAC compare. */
+export declare function verifyConnectionTicket(ticket: string, sessionId: string, secret: string, nowMs: number, channel?: ConnectionTicketChannel): Promise<boolean>;

package/dist/_contracts/connection-ticket.js

@@ -4,8 +4,8 @@
  * A browser/runtime WebSocket handshake cannot carry an Authorization header,
  * so a subscriber first obtains a short-lived ticket from an authenticated
  * HTTP endpoint, then presents it as a `?ticket=` query parameter on the WS
- * upgrade. The ticket is an HMAC over `${runId}.${channel}.${exp}` keyed by
- * the coordinator secret — it binds the grant to one run, one stream channel,
+ * upgrade. The ticket is an HMAC over `${sessionId}.${channel}.${exp}` keyed by
+ * the coordinator secret — it binds the grant to one session, one stream channel,
  * and one expiry and is verified without any per-ticket storage.
  *
  * This lives in shared so the coordinator (which verifies) and the API
@@ -23,14 +23,14 @@ async function hmacHex(secret, message) {
     return [...new Uint8Array(sig)].map((b) => b.toString(16).padStart(2, "0")).join("");
 }
 /** Mint a `${channel}.${exp}.${mac}` ticket valid for `ttlMs` from `nowMs`. */
-export async function mintConnectionTicket(runId, secret, nowMs, ttlMs = DEFAULT_TICKET_TTL_MS, channel = "event") {
+export async function mintConnectionTicket(sessionId, secret, nowMs, ttlMs = DEFAULT_TICKET_TTL_MS, channel = "event") {
     const boundChannel = normalizeTicketChannel(channel);
     const exp = nowMs + ttlMs;
-    const mac = await hmacHex(secret, `${runId}.${boundChannel}.${exp}`);
+    const mac = await hmacHex(secret, `${sessionId}.${boundChannel}.${exp}`);
     return { ticket: `${boundChannel}.${exp}.${mac}`, expiresAtMs: exp };
 }
-/** Verify a ticket against `runId`, channel, and current time. Constant-time MAC compare. */
-export async function verifyConnectionTicket(ticket, runId, secret, nowMs, channel = "event") {
+/** Verify a ticket against `sessionId`, channel, and current time. Constant-time MAC compare. */
+export async function verifyConnectionTicket(ticket, sessionId, secret, nowMs, channel = "event") {
     const [ticketChannel, expRaw, mac, ...rest] = ticket.split(".");
     if (rest.length > 0 || !ticketChannel || !expRaw || !mac)
         return false;
@@ -40,7 +40,7 @@ export async function verifyConnectionTicket(ticket, runId, secret, nowMs, chann
     const exp = Number(expRaw);
     if (!Number.isFinite(exp) || exp < nowMs)
         return false;
-    const expected = await hmacHex(secret, `${runId}.${boundChannel}.${exp}`);
+    const expected = await hmacHex(secret, `${sessionId}.${boundChannel}.${exp}`);
     return timingSafeEqual(mac, expected);
 }
 /** Length-then-constant-time comparison of two hex strings. */

package/dist/_contracts/error-codes.d.ts

@@ -11,7 +11,7 @@
  * from the human `message`. `idempotency_conflict` and `insufficient_scope`
  * (previously message-less bare 409/403 bodies) are first-class here.
  */
-export declare const AEX_API_ERROR_CODES: readonly ["unauthorized", "forbidden", "insufficient_scope", "token_invalid", "token_revoked", "token_expired", "malformed_token", "not_found", "idempotency_conflict", "session_busy", "run_not_terminal", "unknown_workspace", "workspace_concurrency_exceeded", "workspace_submit_rate_exceeded", "workspace_spend_cap_exceeded", "insufficient_balance", "rate_limited", "upstream_error", "internal_error"];
+export declare const AEX_API_ERROR_CODES: readonly ["unauthorized", "forbidden", "insufficient_scope", "token_invalid", "token_revoked", "token_expired", "malformed_token", "not_found", "idempotency_conflict", "session_busy", "session_not_terminal", "unknown_workspace", "workspace_concurrency_exceeded", "workspace_submit_rate_exceeded", "workspace_spend_cap_exceeded", "insufficient_balance", "rate_limited", "upstream_error", "internal_error"];
 export type AexApiErrorCode = (typeof AEX_API_ERROR_CODES)[number];
 /**
  * Human message per stable code. A `Record` (not `Partial`) so a code added to

package/dist/_contracts/error-codes.js

@@ -22,7 +22,7 @@ export const AEX_API_ERROR_CODES = [
     "not_found",
     "idempotency_conflict",
     "session_busy",
-    "run_not_terminal",
+    "session_not_terminal",
     "unknown_workspace",
     "workspace_concurrency_exceeded",
     "workspace_submit_rate_exceeded",
@@ -49,12 +49,12 @@ export const AEX_API_ERROR_MESSAGES = {
     not_found: "The requested resource was not found.",
     idempotency_conflict: "This idempotency key was already used with a different request body.",
     session_busy: "The session is busy handling another turn.",
-    run_not_terminal: "The run has not reached a terminal state yet.",
+    session_not_terminal: "The session has not reached a terminal state yet.",
     unknown_workspace: "The workspace could not be resolved from the API key.",
     workspace_concurrency_exceeded: "The workspace has reached its concurrent-run limit.",
     workspace_submit_rate_exceeded: "The workspace submit-rate limit was exceeded.",
     workspace_spend_cap_exceeded: "The workspace monthly spend cap was reached.",
-    insufficient_balance: "The workspace prepaid balance is insufficient to submit this run.",
+    insufficient_balance: "The workspace prepaid balance is insufficient to submit this session.",
     rate_limited: "Too many requests — retry after a short backoff.",
     upstream_error: "An upstream provider returned an error.",
     internal_error: "The aex API encountered an internal error."
@@ -68,7 +68,7 @@ export const AEX_API_ERROR_REMEDIES = {
     token_revoked: "Mint a new API key.",
     workspace_spend_cap_exceeded: "Raise the workspace spend cap or wait for the next billing cycle.",
     insufficient_balance: "Top up the workspace balance or add a payment method.",
-    workspace_concurrency_exceeded: "Wait for in-flight runs to finish or raise the concurrency limit.",
+    workspace_concurrency_exceeded: "Wait for in-flight sessions to finish or raise the concurrency limit.",
     workspace_submit_rate_exceeded: "Slow the submit rate or raise the workspace submit-rate limit."
 };
 const API_ERROR_CODE_SET = new Set(AEX_API_ERROR_CODES);

package/dist/_contracts/error-factory.js

@@ -34,7 +34,7 @@ export function apiErrorKindForCode(code) {
         case "workspace_submit_rate_exceeded":
             return "rate_limit";
         case "session_busy":
-        case "run_not_terminal":
+        case "session_not_terminal":
         case "unknown_workspace":
         case "workspace_spend_cap_exceeded":
         case "insufficient_balance":

package/dist/_contracts/event-envelope.d.ts

@@ -7,17 +7,17 @@
  * the shape the coordinator (Phase 2) appends, broadcasts, and archives.
  *
  *   - **CloudEvents-shaped** self-describing envelope: a stable `id`, the
- *     coarse `source`, the AG-UI-aligned `type`, the `subject` (run), a
+ *     coarse `source`, the AG-UI-aligned `type`, the `subject` (session), a
  *     `time`, the `sequence` cursor, and the typed `data`.
  *   - **AG-UI vocabulary** for `type` where it maps; aex-specific events
  *     ride AG-UI's reserved `CUSTOM` carrier under an `aex.*` name, so an
- *     off-the-shelf AG-UI client reads an aex run with no glue.
+ *     off-the-shelf AG-UI client reads an aex start with no glue.
  *   - Two aex extensions: a coarse `source` (filter first by origin) and
  *     an optional human `message` (log / CLI / dashboard rendering).
  *
  * Unified observability spine:
  * the envelope additionally carries four ordering attributes so BOTH the typed
- * event stream and the high-volume hosted-platform log stream ride one per-run
+ * event stream and the high-volume hosted-platform log stream ride one per-session
  * coordinator:
  *   - `channel`   — "event" (the typed AG-UI stream) or "log" (a verbose log
  *                   line). The single axis a consumer splits the unified stream
@@ -62,7 +62,7 @@ export declare const AEX_EVENT_MAP_VERSION: 1;
 export declare const AEX_EVENT_SOURCES: readonly ["agent", "api", "runtime", "mcp", "aex", "workflow", "host"];
 export type AexEventSource = (typeof AEX_EVENT_SOURCES)[number];
 /**
- * The channel a record rides on the unified per-run stream:
+ * The channel a record rides on the unified per-session stream:
  *   - `event` — the typed, low-volume, fully-replayed AG-UI event stream.
  *   - `log`   — a high-volume verbose log line (level + message + fields). The
  *               coordinator prunes flushed log rows after evidence archival
@@ -84,7 +84,7 @@ export type AexLogLevel = (typeof AEX_LOG_LEVELS)[number];
  * full AG-UI protocol — the events aex actually produces today — plus
  * `CUSTOM`, AG-UI's reserved carrier for aex-native events.
  */
-export declare const AEX_EVENT_TYPES: readonly ["RUN_STARTED", "RUN_FINISHED", "RUN_ERROR", "TEXT_MESSAGE_CONTENT", "TOOL_CALL_START", "TOOL_CALL_RESULT", "CUSTOM", "LOG"];
+export declare const AEX_EVENT_TYPES: readonly ["TURN_STARTED", "TURN_FINISHED", "TURN_ERROR", "TEXT_MESSAGE_CONTENT", "TOOL_CALL_START", "TOOL_CALL_RESULT", "CUSTOM", "LOG"];
 export type AexEventType = (typeof AEX_EVENT_TYPES)[number];
 /**
  * One event on the unified log. CloudEvents core attributes (`specversion`,
@@ -94,18 +94,18 @@ export type AexEventType = (typeof AEX_EVENT_TYPES)[number];
 export interface AexEvent {
     /** CloudEvents specversion. Always {@link AEX_EVENT_SPECVERSION}. */
     readonly specversion: typeof AEX_EVENT_SPECVERSION;
-    /** Stable, globally-unique event id: `${runId}:${sequence}`. Dedupe key. */
+    /** Stable, globally-unique event id: `${sessionId}:${sequence}`. Dedupe key. */
     readonly id: string;
     /** Coarse origin classifier. */
     readonly source: AexEventSource;
     /** AG-UI-aligned event type. */
     readonly type: AexEventType;
-    /** The run this event belongs to (CloudEvents `subject`). */
+    /** The session this event belongs to (CloudEvents `subject`). */
     readonly subject: string;
-    /** ISO-8601 event time (run base + the RunnerEvent's relative `tMs`). */
+    /** ISO-8601 event time (session base + the RunnerEvent's relative `tMs`). */
     readonly time: string;
     /**
-     * Monotonic ordering cursor within the run — the GLOBAL `seq` the coordinator
+     * Monotonic ordering cursor within the session — the GLOBAL `seq` the coordinator
      * assigns on arrival. This is the canonical stream order and the dedupe key.
      */
     readonly sequence: number;
@@ -126,12 +126,12 @@ export interface AexEvent {
      * The DO's authoritative receive time (wall-clock ms), stamped at ingest
      * alongside the global {@link sequence}. This is the authoritative wall-clock
      * companion to `sequence` — distinct from `emittedAt` (the SOURCE's clock) and
-     * `time` (the LOGICAL time = run base + relative tMs).
+     * `time` (the LOGICAL time = session base + relative tMs).
      *
      * NOTE: some edge clocks are coarsened/frozen-at-I/O, so `receivedAt` is
      * precisely "the coordinator's last-I/O wall-clock at ingest" — that is fine
      * as the authoritative receive marker. It does NOT need to exceed `emittedAt`:
-     * the source runs on a different host with an independent clock, so cross-host
+     * the source sessions on a different host with an independent clock, so cross-host
      * drift can leave `receivedAt < emittedAt` and that is expected, not an error.
      */
     readonly receivedAt?: number;
@@ -152,10 +152,10 @@ export interface AexEvent {
 }
 /** Context the mapper needs to stamp absolute identity/time onto an event. */
 export interface AexEventContext {
-    readonly runId: string;
+    readonly sessionId: string;
     /**
-     * Run-start epoch ms. The RunnerEvent's `tMs` is relative to this, so
-     * `time = new Date(baseMs + tMs)`. Pass the run's `createdAtMs`.
+     * SessionRecord-start epoch ms. The RunnerEvent's `tMs` is relative to this, so
+     * `time = new Date(baseMs + tMs)`. Pass the session's `createdAtMs`.
      */
     readonly baseMs: number;
 }
@@ -190,22 +190,22 @@ export type AexInboundLog = Omit<AexEvent, "specversion" | "id" | "subject" | "s
  * and the `LOG` payload — is supplied here.
  */
 export declare function logToInbound(source: AexEventSource, line: AexLogLine): AexInboundLog;
-export declare function isRunStarted(e: AexEvent): boolean;
-export declare function isRunFinished(e: AexEvent): boolean;
-export declare function isRunError(e: AexEvent): boolean;
+export declare function isTurnStarted(e: AexEvent): boolean;
+export declare function isTurnFinished(e: AexEvent): boolean;
+export declare function isTurnError(e: AexEvent): boolean;
 /** A terminal event of either flavour (finished or error). */
-export declare function isRunTerminal(e: AexEvent): boolean;
+export declare function isTurnTerminal(e: AexEvent): boolean;
 /**
- * The CUSTOM `data.name`s the MANAGED runtime emits as a run/turn's SETTLED
- * terminal. A managed one-shot run PARKS (`session_parked.v1` → one of these)
- * rather than writing a `session_finished` → RUN_FINISHED, so these — not just
- * the AG-UI RUN_FINISHED/RUN_ERROR — are what actually end a managed run's event
+ * The CUSTOM `data.name`s the MANAGED runtime emits as a session/turn's SETTLED
+ * terminal. A managed one-shot session PARKS (`session_parked.v1` → one of these)
+ * rather than writing a `session_finished` → TURN_FINISHED, so these — not just
+ * the AG-UI TURN_FINISHED/TURN_ERROR — are what actually end a managed session's event
  * stream. Clean-cut (WS1): the bare `aex.session.error` park is retired in favour
  * of the terminal OUTCOME vocabulary — a failed turn is `failed`, a wall-clock
  * kill `timed_out`, a cancel `cancelled`, a clean finish `succeeded`; `idle`/
  * `suspended` remain the resumable parks. Held `awaiting_approval` is NOT here:
  * it ends the TURN stream (see `isSessionTurnTerminalEvent` in the SDK) but the
- * RUN is not settled. Kept byte-in-sync with `@aexhq/shared` `AEX_SESSION_PARKED_NAMES`
+ * session is not settled. Kept byte-in-sync with `@aexhq/shared` `AEX_SESSION_PARKED_NAMES`
  * and the platform journal projection (`journal-project.ts` session_parked.v1).
  */
 export declare const AEX_SESSION_PARKED_NAMES: readonly ["aex.session.idle", "aex.session.suspended", "aex.session.succeeded", "aex.session.failed", "aex.session.timed_out", "aex.session.cancelled"];
@@ -213,8 +213,8 @@ export declare const AEX_SESSION_PARKED_NAMES: readonly ["aex.session.idle", "ae
  * True for a managed-runtime session-park terminal (a resumable idle/suspended
  * park OR a terminal succeeded/failed/timed_out/cancelled outcome). The turn's
  * work is done and the record has reached its terminal status; a stream consumer
- * should stop here exactly as it would on RUN_FINISHED/RUN_ERROR. (Held
- * `awaiting_approval` is deliberately excluded — the run is paused, not settled.)
+ * should stop here exactly as it would on TURN_FINISHED/TURN_ERROR. (Held
+ * `awaiting_approval` is deliberately excluded — the session is paused, not settled.)
  */
 export declare function isSessionParked(e: AexEvent): boolean;
 export declare function isTextMessage(e: AexEvent): boolean;
@@ -225,25 +225,25 @@ export declare function isCustom(e: AexEvent): boolean;
 export declare function customName(e: AexEvent): string | null;
 /**
  * The `data.name` of the settle-consistency barrier event. The coordinator
- * broadcasts ONE such CUSTOM event as a run's LAST stream event, after the
- * Postgres mirror lands — so observing it ⇒ a subsequent `getRun` is terminal
- * and `listOutputs` is complete. It is intentionally a CUSTOM event (not a
- * typed RUN_* event): off-the-shelf AG-UI clients ignore it, while
- * `streamEnvelopes(runId, { settleConsistent: true })` ends the iterator on it.
- * Unlike RUN_FINISHED (the AG-UI render-complete UX signal, emitted by the
+ * broadcasts ONE such CUSTOM event as a session's LAST stream event, after the
+ * Postgres mirror lands — so observing it ⇒ a subsequent `getSessionRecord` is terminal
+ * and `listSessionFiles` is complete. It is intentionally a CUSTOM event (not a
+ * typed SESSION_* event): off-the-shelf AG-UI clients ignore it, while
+ * `streamEnvelopes(sessionId, { settleConsistent: true })` ends the iterator on it.
+ * Unlike TURN_FINISHED (the AG-UI render-complete UX signal, emitted by the
  * runner BEFORE the platform learns the outcome), this is settle-gated. The
  * platform mirrors this constant in `@aexhq/shared`.
  */
-export declare const AEX_RUN_SETTLED_NAME = "aex.run.settled";
+export declare const AEX_SESSION_SETTLED_NAME = "aex.session.settled";
 /**
  * True for the settle-consistency barrier event (post-mirror, read-consistent).
  * Also true for a managed-runtime session-park terminal: the current plane emits
- * an `aex.run.settled` barrier after settle, but a stream may still observe the
+ * an `aex.session.settled` barrier after settle, but a stream may still observe the
  * park as the terminal event when no later barrier is delivered.
  */
-export declare function isRunSettled(e: AexEvent): boolean;
+export declare function isSessionSettled(e: AexEvent): boolean;
 /**
- * The CUSTOM `data.name` of the HITL write-gate park: the run has reached the
+ * The CUSTOM `data.name` of the HITL write-gate park: the session has reached the
  * `awaiting_approval` state before a gated action and is holding for an
  * `approve()`/`deny()`. Structural (independent of model prose).
  */
@@ -285,17 +285,17 @@ export declare function exceedsRowBudget(e: AexEvent, max?: number): boolean;
  * that want it.
  */
 export type AguiEvent = {
-    type: "RUN_STARTED";
+    type: "TURN_STARTED";
     timestamp: number;
     threadId: string;
-    runId: string;
+    sessionId: string;
 } | {
-    type: "RUN_FINISHED";
+    type: "TURN_FINISHED";
     timestamp: number;
     threadId: string;
-    runId: string;
+    sessionId: string;
 } | {
-    type: "RUN_ERROR";
+    type: "TURN_ERROR";
     timestamp: number;
     message: string;
     code?: string;
@@ -323,7 +323,7 @@ export type AguiEvent = {
 };
 /**
  * Project an aex envelope to a strict AG-UI event so an off-the-shelf
- * AG-UI client can consume an aex run with no glue. This is the
+ * AG-UI client can consume an aex start with no glue. This is the
  * client-side projection the SDK exposes.
  */
 export declare function toAGUI(e: AexEvent): AguiEvent;