@aexhq/sdk 0.40.16 → 0.41.1

package/dist/_contracts/session-artifacts.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Single source of truth for a session's artifact namespaces.
+ *
+ * Every session stores public files and internal diagnostics under its
+ * workspace-scoped session prefix:
+ *
+ *   workspaces/<workspaceId>/sessions/<sessionId>/checkpoints/current.json
+ *   workspaces/<workspaceId>/sessions/<sessionId>/checkpoints/<checkpointId>/workspace/index.json
+ *   workspaces/<workspaceId>/sessions/<sessionId>/checkpoints/<checkpointId>/workspace/objects/<fileId>
+ *   workspaces/<workspaceId>/sessions/<sessionId>/internal/logs/<rel>
+ *
+ * The latest complete checkpoint is the recovery source and the public files
+ * source. Diagnostics reach storage as workspace dotdirs (`.runtime-logs/...`,
+ * `.host-logs/...`, etc.); the stored path uses canonical log namespaces.
+ */
+export declare const WORKSPACES_PREFIX = "workspaces";
+export declare const SESSIONS_PREFIX = "sessions";
+export declare const SESSION_CHECKPOINTS_PREFIX = "checkpoints";
+export declare const SESSION_INTERNAL_PREFIX = "internal";
+export declare const SESSION_INTERNAL_LOGS_PREFIX = "internal/logs";
+export declare const S3_RETENTION_TAG_KEY = "aex-retention";
+export declare const S3_RETENTION_TAG_VALUES: readonly ["session-file-current", "workspace-asset", "session-core", "checkpoint-pending", "checkpoint-superseded", "upload-staging", "internal-log", "internal-event", "internal-usage", "admin-archive"];
+export type S3ObjectRetentionTagValue = (typeof S3_RETENTION_TAG_VALUES)[number];
+/**
+ * Internal raw-usage export namespace (cost & usage metering). Lives under
+ * `internal/` so public downloads never include it by default. Holds
+ * `SessionUsageSample` ndjson — the durable system of record for raw usage, written
+ * by the coordinator event stream; the public-safe `session_cost` table holds the summary.
+ */
+export declare const SESSION_INTERNAL_USAGE_PREFIX = "internal/usage";
+/** Object-key prefix (trailing slash) every session-local object for a session lives under. */
+export declare function runSessionPrefix(workspaceId: string, sessionId: string): string;
+/** Object key for a session's raw-usage ndjson chunk (n = monotonic chunk index). */
+export declare function runInternalUsageKey(workspaceId: string, sessionId: string, chunk: number): string;
+/** Object-key prefix (trailing slash) for a session's current-file checkpoints. */
+export declare function runCheckpointPrefix(workspaceId: string, sessionId: string): string;
+/** Pointer to the latest complete checkpoint. Written last during checkpoint commit. */
+export declare function runCheckpointCurrentKey(workspaceId: string, sessionId: string): string;
+/** Optional compact list of available checkpoints for admin/debug views. */
+export declare function runCheckpointIndexKey(workspaceId: string, sessionId: string): string;
+export declare function runCheckpointManifestKey(workspaceId: string, sessionId: string, checkpointId: string): string;
+export declare function runCheckpointWorkspaceIndexKey(workspaceId: string, sessionId: string, checkpointId: string): string;
+export declare function runCheckpointWorkspaceObjectKey(workspaceId: string, sessionId: string, checkpointId: string, fileId: string): string;
+export declare function runCheckpointBrainJournalKey(workspaceId: string, sessionId: string, checkpointId: string): string;
+export declare function runCheckpointBrainStateKey(workspaceId: string, sessionId: string, checkpointId: string): string;
+/** Object-key prefix (trailing slash) for operator-built archive zips for a session. */
+export declare function runAdminArchivePrefix(workspaceId: string, sessionId: string): string;
+/** Object-key prefix (trailing slash) for generated event archive files for a session. */
+export declare function runEventArchivePrefix(workspaceId: string, sessionId: string): string;
+/**
+ * Relative-path prefixes that mark a stored artifact as a platform diagnostic
+ * rather than a session deliverable. Dotted forms are upload-time paths.
+ */
+export declare const SESSION_LOG_REL_PREFIXES: readonly [".runtime-logs/", ".host-logs/", ".provider-proxy/", ".control-plane/", ".anthropic-debug/", "runtime/", "host/", "provider-proxy/", "control-plane/", "anthropic-debug/"];
+/** True when a workspace-relative artifact path belongs to the internal logs namespace. */
+export declare function isSessionLogRelPath(rel: string): boolean;
+/**
+ * The artifact's path relative to its namespace prefix as stored. Diagnostics
+ * are canonicalized (`.runtime-logs/x` -> `runtime/x`).
+ */
+export declare function sessionArtifactRel(rel: string): string;
+/**
+ * Storage key for a session artifact uploaded with relative path `rel`, routing
+ * diagnostics into `internal/logs/`. Workspace files are stored by checkpoint
+ * helpers, not by this function.
+ */
+export declare function sessionInternalArtifactKey(workspaceId: string, sessionId: string, rel: string): string;
+/**
+ * Opaque, non-reversible file id. Derived as SHA-256 hex of
+ * `sessionId:relPath` so a caller cannot construct an id by guessing a filename.
+ * It is the single id scheme for session files: the checkpoint index records it,
+ * the list route emits it, the download/link routes resolve it back to a path
+ * from the latest checkpoint index, and the object key uses it directly. Hex is
+ * URL-safe. WebCrypto, no new dep.
+ */
+export declare function opaqueSessionFileId(sessionId: string, relPath: string): Promise<string>;
+export interface SessionCheckpointCurrent {
+    readonly v: 1;
+    readonly workspaceId: string;
+    readonly sessionId: string;
+    readonly checkpointId: string;
+    readonly manifestKey: string;
+    readonly committedAt: string;
+    readonly throughSeq: number;
+}
+export interface SessionCheckpointIndex {
+    readonly v: 1;
+    readonly workspaceId: string;
+    readonly sessionId: string;
+    readonly currentCheckpointId: string;
+    readonly checkpoints: readonly SessionCheckpointIndexEntry[];
+}
+export interface SessionCheckpointIndexEntry {
+    readonly checkpointId: string;
+    readonly manifestKey: string;
+    readonly committedAt: string;
+    readonly throughSeq: number;
+    readonly fileCount: number;
+    readonly totalBytes: number;
+}
+export interface SessionCheckpointManifest {
+    readonly v: 1;
+    readonly workspaceId: string;
+    readonly sessionId: string;
+    readonly checkpointId: string;
+    readonly status: "complete";
+    readonly createdAt: string;
+    readonly committedAt: string;
+    readonly throughSeq: number;
+    readonly workspace: {
+        readonly indexKey: string;
+        readonly fileCount: number;
+        readonly totalBytes: number;
+    };
+    readonly brain?: {
+        readonly journalKey?: string;
+        readonly stateKey?: string;
+    };
+}
+export interface SessionWorkspaceFile {
+    readonly fileId: string;
+    readonly path: string;
+    readonly sizeBytes: number;
+    readonly contentType: string;
+    readonly objectKey: string;
+    readonly sha256?: string;
+    readonly createdAt: string;
+}
+export interface SessionCheckpointWorkspaceIndex {
+    readonly v: 1;
+    readonly workspaceId: string;
+    readonly sessionId: string;
+    readonly checkpointId: string;
+    readonly fileCount: number;
+    readonly totalBytes: number;
+    readonly files: readonly SessionWorkspaceFile[];
+}
+/**
+ * Storage key for a session's snapshotted asset, addressed by its content hash.
+ * This is used only for pre-checkpoint reusable workspace assets. Session boot
+ * should materialize those assets into an initial checkpoint before execution.
+ */
+export declare function workspaceAssetKey(workspaceId: string, hash: string): string;
+/**
+ * Retention class for an S3 key. Writers set this as the `aex-retention` object
+ * tag so bucket lifecycle rules can apply per logical namespace even though the
+ * useful category sits after dynamic workspace/session ids.
+ */
+export declare function s3ObjectRetentionTagValue(key: string): S3ObjectRetentionTagValue | undefined;
+/** S3 PutObject/CreateMultipartUpload/Upload `Tagging` header value for a key. */
+export declare function s3ObjectRetentionTaggingHeader(key: string): string | undefined;

package/dist/_contracts/session-artifacts.js

@@ -0,0 +1,234 @@
+/**
+ * Single source of truth for a session's artifact namespaces.
+ *
+ * Every session stores public files and internal diagnostics under its
+ * workspace-scoped session prefix:
+ *
+ *   workspaces/<workspaceId>/sessions/<sessionId>/checkpoints/current.json
+ *   workspaces/<workspaceId>/sessions/<sessionId>/checkpoints/<checkpointId>/workspace/index.json
+ *   workspaces/<workspaceId>/sessions/<sessionId>/checkpoints/<checkpointId>/workspace/objects/<fileId>
+ *   workspaces/<workspaceId>/sessions/<sessionId>/internal/logs/<rel>
+ *
+ * The latest complete checkpoint is the recovery source and the public files
+ * source. Diagnostics reach storage as workspace dotdirs (`.runtime-logs/...`,
+ * `.host-logs/...`, etc.); the stored path uses canonical log namespaces.
+ */
+export const WORKSPACES_PREFIX = "workspaces";
+export const SESSIONS_PREFIX = "sessions";
+export const SESSION_CHECKPOINTS_PREFIX = "checkpoints";
+export const SESSION_INTERNAL_PREFIX = "internal";
+export const SESSION_INTERNAL_LOGS_PREFIX = `${SESSION_INTERNAL_PREFIX}/logs`;
+export const S3_RETENTION_TAG_KEY = "aex-retention";
+export const S3_RETENTION_TAG_VALUES = [
+    "session-file-current",
+    "workspace-asset",
+    "session-core",
+    "checkpoint-pending",
+    "checkpoint-superseded",
+    "upload-staging",
+    "internal-log",
+    "internal-event",
+    "internal-usage",
+    "admin-archive"
+];
+/**
+ * Internal raw-usage export namespace (cost & usage metering). Lives under
+ * `internal/` so public downloads never include it by default. Holds
+ * `SessionUsageSample` ndjson — the durable system of record for raw usage, written
+ * by the coordinator event stream; the public-safe `session_cost` table holds the summary.
+ */
+export const SESSION_INTERNAL_USAGE_PREFIX = `${SESSION_INTERNAL_PREFIX}/usage`;
+/** Object-key prefix (trailing slash) every session-local object for a session lives under. */
+export function runSessionPrefix(workspaceId, sessionId) {
+    return `${WORKSPACES_PREFIX}/${workspaceId}/${SESSIONS_PREFIX}/${sessionId}/`;
+}
+/** Object key for a session's raw-usage ndjson chunk (n = monotonic chunk index). */
+export function runInternalUsageKey(workspaceId, sessionId, chunk) {
+    return `${runSessionPrefix(workspaceId, sessionId)}${SESSION_INTERNAL_USAGE_PREFIX}/${chunk}.ndjson`;
+}
+/** Object-key prefix (trailing slash) for a session's current-file checkpoints. */
+export function runCheckpointPrefix(workspaceId, sessionId) {
+    return `${runSessionPrefix(workspaceId, sessionId)}${SESSION_CHECKPOINTS_PREFIX}/`;
+}
+/** Pointer to the latest complete checkpoint. Written last during checkpoint commit. */
+export function runCheckpointCurrentKey(workspaceId, sessionId) {
+    return `${runCheckpointPrefix(workspaceId, sessionId)}current.json`;
+}
+/** Optional compact list of available checkpoints for admin/debug views. */
+export function runCheckpointIndexKey(workspaceId, sessionId) {
+    return `${runCheckpointPrefix(workspaceId, sessionId)}index.json`;
+}
+export function runCheckpointManifestKey(workspaceId, sessionId, checkpointId) {
+    return `${runCheckpointPrefix(workspaceId, sessionId)}${checkpointId}/manifest.json`;
+}
+export function runCheckpointWorkspaceIndexKey(workspaceId, sessionId, checkpointId) {
+    return `${runCheckpointPrefix(workspaceId, sessionId)}${checkpointId}/workspace/index.json`;
+}
+export function runCheckpointWorkspaceObjectKey(workspaceId, sessionId, checkpointId, fileId) {
+    return `${runCheckpointPrefix(workspaceId, sessionId)}${checkpointId}/workspace/objects/${fileId}`;
+}
+export function runCheckpointBrainJournalKey(workspaceId, sessionId, checkpointId) {
+    return `${runCheckpointPrefix(workspaceId, sessionId)}${checkpointId}/brain/journal.jsonl`;
+}
+export function runCheckpointBrainStateKey(workspaceId, sessionId, checkpointId) {
+    return `${runCheckpointPrefix(workspaceId, sessionId)}${checkpointId}/brain/state.json`;
+}
+/** Object-key prefix (trailing slash) for operator-built archive zips for a session. */
+export function runAdminArchivePrefix(workspaceId, sessionId) {
+    return `${runSessionPrefix(workspaceId, sessionId)}${SESSION_INTERNAL_PREFIX}/admin-archives/`;
+}
+/** Object-key prefix (trailing slash) for generated event archive files for a session. */
+export function runEventArchivePrefix(workspaceId, sessionId) {
+    return `${runSessionPrefix(workspaceId, sessionId)}${SESSION_INTERNAL_PREFIX}/events/`;
+}
+/**
+ * Relative-path prefixes that mark a stored artifact as a platform diagnostic
+ * rather than a session deliverable. Dotted forms are upload-time paths.
+ */
+export const SESSION_LOG_REL_PREFIXES = [
+    ".runtime-logs/",
+    ".host-logs/",
+    ".provider-proxy/",
+    ".control-plane/",
+    ".anthropic-debug/",
+    "runtime/",
+    "host/",
+    "provider-proxy/",
+    "control-plane/",
+    "anthropic-debug/"
+];
+/** True when a workspace-relative artifact path belongs to the internal logs namespace. */
+export function isSessionLogRelPath(rel) {
+    return SESSION_LOG_REL_PREFIXES.some((prefix) => matchesRelPrefix(rel, prefix));
+}
+/**
+ * The artifact's path relative to its namespace prefix as stored. Diagnostics
+ * are canonicalized (`.runtime-logs/x` -> `runtime/x`).
+ */
+export function sessionArtifactRel(rel) {
+    if (rel.startsWith(".runtime-logs/"))
+        return `runtime/${rel.slice(".runtime-logs/".length)}`;
+    if (rel.startsWith("runtime/"))
+        return rel;
+    if (rel.startsWith(".host-logs/"))
+        return `host/${rel.slice(".host-logs/".length)}`;
+    if (rel.startsWith("host/"))
+        return rel;
+    if (rel.startsWith(".provider-proxy/"))
+        return `provider-proxy/${rel.slice(".provider-proxy/".length)}`;
+    if (rel.startsWith("provider-proxy/"))
+        return rel;
+    if (rel.startsWith(".control-plane/"))
+        return `control-plane/${rel.slice(".control-plane/".length)}`;
+    if (rel.startsWith("control-plane/"))
+        return rel;
+    if (rel.startsWith(".anthropic-debug/"))
+        return `provider-proxy/${rel.slice(".anthropic-debug/".length)}`;
+    if (rel.startsWith("anthropic-debug/"))
+        return `provider-proxy/${rel.slice("anthropic-debug/".length)}`;
+    return rel;
+}
+/**
+ * Storage key for a session artifact uploaded with relative path `rel`, routing
+ * diagnostics into `internal/logs/`. Workspace files are stored by checkpoint
+ * helpers, not by this function.
+ */
+export function sessionInternalArtifactKey(workspaceId, sessionId, rel) {
+    return `${runSessionPrefix(workspaceId, sessionId)}${SESSION_INTERNAL_LOGS_PREFIX}/${sessionArtifactRel(rel)}`;
+}
+/**
+ * Opaque, non-reversible file id. Derived as SHA-256 hex of
+ * `sessionId:relPath` so a caller cannot construct an id by guessing a filename.
+ * It is the single id scheme for session files: the checkpoint index records it,
+ * the list route emits it, the download/link routes resolve it back to a path
+ * from the latest checkpoint index, and the object key uses it directly. Hex is
+ * URL-safe. WebCrypto, no new dep.
+ */
+export async function opaqueSessionFileId(sessionId, relPath) {
+    const data = new TextEncoder().encode(`${sessionId}:${relPath}`);
+    const digest = await crypto.subtle.digest("SHA-256", data);
+    return Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, "0")).join("");
+}
+function matchesRelPrefix(rel, prefix) {
+    if (prefix.endsWith("/"))
+        return rel.startsWith(prefix);
+    return rel === prefix || rel.startsWith(`${prefix}/`);
+}
+/**
+ * Storage key for a session's snapshotted asset, addressed by its content hash.
+ * This is used only for pre-checkpoint reusable workspace assets. Session boot
+ * should materialize those assets into an initial checkpoint before execution.
+ */
+export function workspaceAssetKey(workspaceId, hash) {
+    const hex = hash.startsWith("sha256:") ? hash.slice("sha256:".length) : hash;
+    return `${WORKSPACES_PREFIX}/${workspaceId}/assets/content/${hex}`;
+}
+/**
+ * Retention class for an S3 key. Writers set this as the `aex-retention` object
+ * tag so bucket lifecycle rules can apply per logical namespace even though the
+ * useful category sits after dynamic workspace/session ids.
+ */
+export function s3ObjectRetentionTagValue(key) {
+    const normalized = key.replace(/^\/+/, "");
+    if (normalized.startsWith(`${WORKSPACES_PREFIX}/`)) {
+        const parts = normalized.split("/");
+        if (parts[2] === "assets" && parts[3] === "content" && parts.length >= 5)
+            return "workspace-asset";
+        if (parts[2] === "uploads" && parts.length >= 4)
+            return "upload-staging";
+        if (parts[2] !== SESSIONS_PREFIX || parts.length < 5)
+            return undefined;
+        const rel = parts.slice(4).join("/");
+        if (rel.startsWith(`${SESSION_CHECKPOINTS_PREFIX}/`)) {
+            if (rel.includes("/workspace/objects/"))
+                return "session-file-current";
+            return "session-core";
+        }
+        if (rel.startsWith(`${SESSION_INTERNAL_PREFIX}/admin-archives/`))
+            return "admin-archive";
+        if (rel.startsWith(`${SESSION_INTERNAL_PREFIX}/events/`))
+            return "internal-event";
+        if (rel.startsWith(`${SESSION_INTERNAL_USAGE_PREFIX}/`))
+            return "internal-usage";
+        if (rel.startsWith(`${SESSION_INTERNAL_LOGS_PREFIX}/`))
+            return "internal-log";
+        if (rel.startsWith(`${SESSION_INTERNAL_PREFIX}/`))
+            return "internal-log";
+        return undefined;
+    }
+    // Current control-plane core is still read by the running container from the
+    // legacy control namespace. It is not a public files namespace and can be cut
+    // over independently after boot/journal consumers move to workspace-scoped keys.
+    if (normalized.startsWith(`${SESSIONS_PREFIX}/`)) {
+        const parts = normalized.split("/");
+        if (parts.length < 4 || parts[2] !== "session")
+            return undefined;
+        const rel = parts.slice(3).join("/");
+        if (rel.startsWith("logs/"))
+            return "internal-log";
+        if (rel.startsWith("internal/usage/"))
+            return "internal-usage";
+        if (rel.startsWith("internal/events/"))
+            return "internal-event";
+        if (rel.startsWith("admin-archives/") || rel.startsWith("internal/admin-archives/"))
+            return "admin-archive";
+        if (rel === "terminal-failure.json")
+            return "internal-log";
+        if (rel === "boot.json" ||
+            rel === "settle.json" ||
+            rel === "control.json" ||
+            rel === "secrets.sealed" ||
+            rel.startsWith("journal/") ||
+            rel.startsWith("turns/")) {
+            return "session-core";
+        }
+    }
+    return undefined;
+}
+/** S3 PutObject/CreateMultipartUpload/Upload `Tagging` header value for a key. */
+export function s3ObjectRetentionTaggingHeader(key) {
+    const value = s3ObjectRetentionTagValue(key);
+    if (value === undefined)
+        return undefined;
+    return `${encodeURIComponent(S3_RETENTION_TAG_KEY)}=${encodeURIComponent(value)}`;
+}

package/dist/_contracts/{run-config.d.ts → session-config.d.ts}

@@ -1,10 +1,10 @@
 /**
- * Run-request config and composition refs for the public SDK/CLI surface.
+ * SessionRecord-request config and composition refs for the public SDK/CLI surface.
  *
  * Public composition concepts:
  *
  *   - `SkillRef` is the PUBLIC wire-level reference to a workspace skill: just
- *     `{ kind:"skill", name }`. The binding is BY NAME and mutable — the run
+ *     `{ kind:"skill", name }`. The binding is BY NAME and mutable — the session
  *     resolves the name to the workspace skill's current bytes at submit time.
  *     It travels in `submission.skills` (NOT `submission.tools`).
  *
@@ -16,12 +16,12 @@
  *
  *   - `McpServerRef` is the non-secret part of an MCP server declaration:
  *     `name` and `url`. Bearer / cookie / per-request headers travel in
- *     the run's vaulted `secrets.mcpServers` block keyed by the same
+ *     the session's vaulted `secrets.mcpServers` block keyed by the same
  *     `name`, and never enter the hashed submission payload or the
- *     run snapshot.
+ *     session snapshot.
  *
- *   - `RunRequestConfig` is the credential-free set of run parameters that
- *     can be persisted to disk (e.g. `aex run --config run.json`) or
+ *   - `SessionRequestConfig` is the credential-free set of session parameters that
+ *     can be persisted to disk (e.g. `aex start --config session.json`) or
  *     returned from ordinary application helper functions. It excludes
  *     `secrets`/`idempotencyKey`/`signal`; strings are already resolved at
  *     the call site before submission.
@@ -36,7 +36,7 @@
  * boundary.
  */
 import { type JsonValue, type PlatformEnvironment } from "./submission.js";
-import { type RunModel } from "./models.js";
+import { type ModelName } from "./models.js";
 import type { RuntimeSize } from "./runtime-sizes.js";
 /**
  * Mirrors the server-side CHECK constraint
@@ -96,8 +96,8 @@ export declare const SKILL_BUNDLE_LIMITS: {
 /**
  * The PUBLIC wire reference to a workspace skill — by NAME, no bytes, no hash.
  * This is what the SDK sends in `submission.skills` and what the idempotency
- * hash covers. The run resolves the name to the workspace skill's CURRENT bytes
- * at submit time (a re-upload under the same name changes what later runs see).
+ * hash covers. The session resolves the name to the workspace skill's CURRENT bytes
+ * at submit time (a re-upload under the same name changes what later sessions see).
  */
 export interface SkillRef {
     readonly kind: "skill";
@@ -185,7 +185,7 @@ export declare function assertValidMountPath(value: string, field: string): void
  */
 export declare function parseAssetRefFields(record: Record<string, unknown>, path: string): AssetRef;
 /**
- * Manifest entry persisted in `skill_bundles.manifest` and in run-owned
+ * Manifest entry persisted in `skill_bundles.manifest` and in session-owned
  * snapshots. `path` is forward-slash, relative, normalised. `mode` is the
  * stored POSIX mode (sanitised, NOT the user's filesystem mode) — see
  * `SKILL_BUNDLE_LIMITS.defaultFileMode`.
@@ -285,7 +285,7 @@ export type RemoteMcpTransport = (typeof REMOTE_MCP_TRANSPORTS)[number];
 export declare const REMOTE_MCP_STDIO_REJECTED_MESSAGE = "stdio MCP servers are not supported by Aex. Aex supports remote MCP servers over HTTP/SSE only.";
 /**
  * The non-secret half of an MCP server declaration. This is what enters
- * the hashed submission, the run snapshot, and any audit log. `name`
+ * the hashed submission, the session snapshot, and any audit log. `name`
  * keys into `secrets.mcpServers` for the per-request headers.
  *
  * `transport` is optional on the wire — when omitted, the runtime is
@@ -300,11 +300,11 @@ export interface McpServerRef {
 }
 export declare const MCP_SERVER_NAME_PATTERN: RegExp;
 /**
- * A run-config MCP entry. The user is free to supply headers inline; the SDK
+ * A session-config MCP entry. The user is free to supply headers inline; the SDK
  * splits the call site cleanly at submission time so the Authorization (or
  * other auth-bearing) header never enters the non-secret wire payload.
  */
-export interface RunConfigMcpServer extends McpServerRef {
+export interface SessionConfigMcpServer extends McpServerRef {
     readonly headers?: Readonly<Record<string, string>>;
 }
 export declare function parseMcpServerRef(input: unknown, path: string): McpServerRef;
@@ -316,48 +316,48 @@ export declare function parseMcpServerRef(input: unknown, path: string): McpServ
  */
 export declare function rejectStdioMcpShape(record: Record<string, unknown>): void;
 /**
- * Plain JSON accepted by `aex run --config <path>`. This is not a
- * platform object; it is only the non-secret run parameters that the CLI folds
+ * Plain JSON accepted by `aex start --config <path>`. This is not a
+ * platform object; it is only the non-secret session parameters that the CLI folds
  * into the normal `submit` request.
  */
-export interface RunRequestConfig {
-    readonly model: RunModel;
+export interface SessionRequestConfig {
+    readonly model: ModelName;
     readonly system?: string;
     readonly prompt: string | readonly string[];
-    readonly mcpServers?: readonly RunConfigMcpServer[];
+    readonly mcpServers?: readonly SessionConfigMcpServer[];
     readonly environment?: PlatformEnvironment;
     /** Managed runtime size preset (see {@link RuntimeSize}). */
     readonly runtimeSize?: RuntimeSize;
-    /** Run deadline as a duration string (`"1h"`, `"30m"`); bounded [1m, 8h] server-side. */
+    /** SessionRecord deadline as a duration string (`"1h"`, `"30m"`); bounded [1m, 8h] server-side. */
     readonly timeout?: string;
     readonly metadata?: Readonly<Record<string, JsonValue>>;
 }
 /**
- * Parse a run request config from JSON. Defensive — used by the host CLI to
- * load `--config run.json`. Throws with the JSON path that failed so
+ * Parse a session request config from JSON. Defensive — used by the host CLI to
+ * load `--config session.json`. Throws with the JSON path that failed so
  * a user can fix their file. Headers are preserved here and split out
  * later by the SDK normalisation step.
  */
-export declare function parseRunRequestConfig(input: unknown): RunRequestConfig;
+export declare function parseSessionRequestConfig(input: unknown): SessionRequestConfig;
 /**
- * Result of splitting a run config into the non-secret submission and the
+ * Result of splitting a session config into the non-secret submission and the
  * secret MCP-headers bundle. The SDK calls this just before posting to
- * /api/runs: the `submission` half is what the BFF hashes for idempotency, the
- * `mcpServerSecrets` half is what enters run-scoped custody.
+ * /api/sessions: the `submission` half is what the BFF hashes for idempotency, the
+ * `mcpServerSecrets` half is what enters session-scoped custody.
  *
  * `prompt` is normalised to `readonly string[]` (single-string callers
  * get wrapped in a length-1 array) so the wire payload, the hosted API,
  * and the audit log don't have to re-handle two shapes.
  */
-export interface NormalisedRunRequestConfig {
-    readonly model: RunModel;
+export interface NormalisedSessionRequestConfig {
+    readonly model: ModelName;
     readonly system?: string;
     readonly prompt: readonly string[];
     readonly mcpServers: readonly McpServerRef[];
     readonly environment?: PlatformEnvironment;
     readonly metadata?: Readonly<Record<string, JsonValue>>;
     /**
-     * MCP servers whose run-config entry carried `headers`. Keyed by the `name`
+     * MCP servers whose session-config entry carried `headers`. Keyed by the `name`
      * that appears in `mcpServers` so the BFF can pair them up.
      */
     readonly mcpServerSecrets: ReadonlyArray<{
@@ -366,5 +366,5 @@ export interface NormalisedRunRequestConfig {
         readonly headers: Readonly<Record<string, string>>;
     }>;
 }
-export declare function normaliseRunRequestConfig(config: RunRequestConfig): NormalisedRunRequestConfig;
+export declare function normaliseSessionRequestConfig(config: SessionRequestConfig): NormalisedSessionRequestConfig;
 export {};