@aexhq/sdk 0.40.16 → 0.41.0

package/dist/client.js

@@ -1,4 +1,4 @@
-import { AexApiError, CredentialValidationError, HttpClient, PLANE_BASE_URLS, RunConfigValidationError, RunStateError, SecretString, asAexEventView, customName, isSessionParked as isSessionParkedEvent, isRunSettled, assertStreamableOutputMode, operations, parseApiKey, resolveModelProvider, streamCoordinatorEvents, usageFromProviderUsage, parseRunLimits, parseRuntimeSize, parseRunTimeout, parseRunWebhook, BUILTIN_TOOL_NAMES, SKILLS_MAX, TERMINAL_RUN_STATUSES } from "./_contracts/index.js";
+import { AexApiError, CredentialValidationError, HttpClient, PLANE_BASE_URLS, SessionConfigValidationError, SessionStateError, SecretString, asAexEventView, customName, isSessionParked as isSessionParkedEvent, isSessionSettled, assertStreamableOutputMode, operations, parseApiKey, resolveModelProvider, streamCoordinatorEvents, usageFromProviderUsage, parseSessionLimits, parseRuntimeSize, parseSessionTimeout, parseSessionWebhook, BUILTIN_TOOL_NAMES, SKILLS_MAX, TERMINAL_SESSION_CONTROL_STATUSES } from "./_contracts/index.js";
 import { AgentsMd } from "./agents-md.js";
 import { uploadAsset, uploadAssetMultipart } from "./asset-upload.js";
 import { File } from "./file.js";
@@ -8,12 +8,12 @@ import { splitSecretEnv } from "./secret.js";
 import { Skill } from "./skill.js";
 import { Tool } from "./tool.js";
 export class SessionTurnStream {
-    #run;
+    #stream;
     #generator;
     #outcome;
     #done;
-    constructor(run) {
-        this.#run = run;
+    constructor(stream) {
+        this.#stream = stream;
     }
     /**
      * ONE underlying send per turn: iterating the stream and calling `done()`
@@ -22,7 +22,7 @@ export class SessionTurnStream {
      * message as a second billable turn (or 409 `session_busy` mid-turn).
      */
     #shared() {
-        this.#generator ??= this.#capture(this.#run());
+        this.#generator ??= this.#capture(this.#stream());
         return this.#generator;
     }
     async *#capture(generator) {
@@ -114,7 +114,7 @@ export class SessionHandle {
         assertNoSessionSendSignal(options, "SessionHandle.replayLast");
         const last = this.#lastSend;
         if (last === undefined) {
-            throw new RunStateError("SessionHandle.replayLast: no message has been sent on this session yet");
+            throw new SessionStateError("SessionHandle.replayLast: no message has been sent on this session yet");
         }
         return sendSessionInternal(this, last.input, {
             ...options,
@@ -144,9 +144,9 @@ export class SessionHandle {
             ? readSession
             : (await settledSessionRecord(this.#http, this.id, readSession, options.signal)) ?? readSession;
         this.#session = withTerminalSessionStatus(settled, read);
-        const outputs = await operations.listSessionOutputs(this.#http, this.id).catch(() => []);
+        const files = await operations.listSessionFiles(this.#http, this.id).catch(() => []);
         const messages = projectAssistantMessages(events);
-        return settledTurnResult(this.id, this.#session, turn, events, outputs, messages, read);
+        return settledTurnResult(this.id, this.#session, turn, events, files, messages, read);
     }
     /**
      * POST the next turn, reconciling the settle-lag race. A turn stream ends on
@@ -157,7 +157,7 @@ export class SessionHandle {
      * `running`, then retry the SAME idempotent POST (a replay de-duplicates, so
      * this never creates a second billable turn). A session that stays busy past
      * {@link SESSION_BUSY_RECONCILE_DEADLINE_MS} is a genuinely in-flight turn: we
-     * surface a clear, bounded {@link RunStateError} rather than masking it or
+     * surface a clear, bounded {@link SessionStateError} rather than masking it or
      * waiting forever. Any non-`running` busy status (suspended / cancelling /
      * deleted) is a real rejection and passes straight through.
      */
@@ -172,7 +172,7 @@ export class SessionHandle {
                     throw err;
                 if (Date.now() >= deadline) {
                     const apiErr = err instanceof AexApiError ? err : undefined;
-                    throw new RunStateError(`SessionHandle.send: session ${this.id} was still running ${SESSION_BUSY_RECONCILE_DEADLINE_MS}ms after the previous turn parked — a turn is still in flight`, {
+                    throw new SessionStateError(`SessionHandle.send: session ${this.id} was still running ${SESSION_BUSY_RECONCILE_DEADLINE_MS}ms after the previous turn parked — a turn is still in flight`, {
                         sessionId: this.id,
                         sessionStatus: "running",
                         ...(apiErr !== undefined ? { httpStatus: apiErr.status, apiCode: apiErr.apiCode, requestId: apiErr.requestId } : {}),
@@ -251,14 +251,14 @@ export class SessionHandle {
         return accepted;
     }
     /**
-     * Enumerate this run's subagent CHILD runs (`GET /runs/:id/children`). Each is
-     * a {@link ChildRunHandle} backed by the RUN facade (getRun/events/outputs) —
+     * Enumerate this session's subagent CHILD sessions (`GET /sessions/:id/children`). Each is
+     * a {@link ChildSessionHandle} backed by the RUN facade (getSessionRecord/events/files) —
      * NOT `openSession` — so every child the platform hands you is resolvable, with
-     * its lineage (`parentRunId`/`depth`) and terminal outcome exposed.
+     * its lineage (`parentSessionId`/`depth`) and terminal outcome exposed.
      */
     async children() {
-        const refs = await operations.listRunChildren(this.#http, this.id);
-        return refs.map((ref) => new ChildRunHandle(this.#http, ref, this.#fetch));
+        const refs = await operations.listSessionChildren(this.#http, this.id);
+        return refs.map((ref) => new ChildSessionHandle(this.#http, ref, this.#fetch));
     }
     /**
      * Accessor for the session's assistant messages. `all()` returns them
@@ -316,13 +316,13 @@ export class SessionHandle {
         };
     }
     /**
-     * Accessor for the session's captured output files: `list`/`last`/`first`
+     * Accessor for the session's captured files: `list`/`last`/`first`
      * enumerate them; `read` streams one as capped text; `find`/`findOne`/`link`/
-     * `fetch` locate and resolve them; `download` fetches the outputs-namespace
+     * `fetch` locate and resolve them; `download` fetches the files-namespace
      * zip (no selector) or one file's raw bytes (with selector).
      */
-    outputs() {
-        return sessionOutputs(this.#http, this.id, this.#fetch);
+    files() {
+        return sessionFiles(this.#http, this.id, this.#fetch);
     }
     /**
      * Accessor for the session's webhook delivery ledger: `list()` returns the
@@ -333,8 +333,8 @@ export class SessionHandle {
         const http = this.#http;
         const id = this.id;
         return {
-            list: () => operations.getRunWebhookDeliveries(http, id),
-            redeliver: (deliveryId) => operations.redeliverRunWebhook(http, id, deliveryId)
+            list: () => operations.getSessionWebhookDeliveries(http, id),
+            redeliver: (deliveryId) => operations.redeliverSessionWebhook(http, id, deliveryId)
         };
     }
     /** Re-read the session record from the server and store it as the current record. */
@@ -344,7 +344,7 @@ export class SessionHandle {
     }
     /**
      * Poll the session record until it reaches a parked/terminal status (idle,
-     * suspended, error, or any terminal run status). Throws if `timeoutMs`
+     * suspended, error, or any terminal session status). Throws if `timeoutMs`
      * elapses first. Updates the stored record.
      */
     async wait(options = {}) {
@@ -365,23 +365,23 @@ export class SessionHandle {
         throw new Error("SessionHandle.wait: aborted");
     }
     /**
-     * Fetch the self-contained `RunUnit` for this session: parsed submission,
-     * attempts, indexed events, outputs, capture failures, proxy-call audit, and
+     * Fetch the self-contained `SessionUnit` for this session: parsed submission,
+     * attempts, indexed events, session files, capture failures, proxy-call audit, and
      * resolved skills. Use this when you need fields beyond the session record.
      *
      * On the managed plane this is a LEAN summary — the aggregate collections
-     * (`attempts` / `events.entries` / `outputs` / `rawEventPages`) default to
-     * empty. For authoritative per-run data use `outputs()` / `events()` /
+     * (`attempts` / `events.entries` / `sessionFiles` / `rawEventPages`) default to
+     * empty. For authoritative per-session data use `files()` / `events()` /
      * `messages()`. The returned shape is always type-valid (never `undefined`
      * where the type promises an array/page), so array/page access is safe.
      */
     unit() {
-        return operations.getRunUnit(this.#http, this.id);
+        return operations.getSessionUnit(this.#http, this.id);
     }
     /**
      * Download EVERYTHING public about this session as one zip, assembled
      * client-side from the public read endpoints. Organised into `metadata/`,
-     * `events/`, and `outputs/` folders, plus a `manifest.json`. Pass `to` to
+     * `events/`, and `files/` folders, plus a `manifest.json`. Pass `to` to
      * also write the bytes to a file path while still returning them.
      */
     async download(options) {
@@ -419,22 +419,22 @@ export class SessionClient {
         return operations.listSessions(this.#http, query);
     }
     /**
-     * Accessor over one session's captured output files, addressed by id without
-     * opening a handle. Returns the SAME rich {@link SessionOutputs} surface as
-     * `session.outputs()` — `aex.sessions.outputs(id).list()` /
+     * Accessor over one session's captured files, addressed by id without
+     * opening a handle. Returns the SAME rich {@link SessionFiles} surface as
+     * `session.files()` — `aex.sessions.files(id).list()` /
      * `.read(selector)` / `.download()` / … — so the workspace client and the
      * live handle share one accessor convention.
      */
-    outputs(sessionId) {
-        return sessionOutputs(this.#http, sessionId, this.#fetch);
+    files(sessionId) {
+        return sessionFiles(this.#http, sessionId, this.#fetch);
     }
-    async run(options) {
+    async start(options) {
         const { message, deleteAfter, messageIdempotencyKey, stream, ...createOptions } = options;
-        assertNoLegacySessionFields(options, "Aex.sessions.run");
-        const input = normaliseSessionInput(message, "Aex.sessions.run", "message");
-        // Derive the message key from the create key (like the CLI) so a retried run
+        assertNoLegacySessionFields(options, "Aex.sessions.start");
+        const input = normaliseSessionInput(message, "Aex.sessions.start", "message");
+        // Derive the message key from the create key (like the CLI) so a retried session
         // with the same `idempotencyKey` de-duplicates BOTH the create and the
-        // billable turn — never a duplicate billable run.
+        // billable turn — never a duplicate billable session turn.
         const createKey = operations.resolveIdempotencyKey(createOptions.idempotencyKey);
         const messageKey = messageIdempotencyKey !== undefined ? operations.resolveIdempotencyKey(messageIdempotencyKey) : deriveMessageKey(createKey);
         const session = await this.create({ ...createOptions, idempotencyKey: createKey });
@@ -449,38 +449,38 @@ export class SessionClient {
     }
 }
 /**
- * Cross-run output search (`aex.outputs`). Composed client-side (per-run
- * `listSessionOutputs` + the contracts output filter): scope a corpus with
- * `query.runIds`, or omit it to scan every run in the workspace. Metadata-only
+ * Cross-session captured-file search (`aex.files.search`). Composed client-side (per-session
+ * `listSessionFiles` + the contracts file filter): scope a corpus with
+ * `query.sessionIds`, or omit it to scan every session in the workspace. Metadata-only
  * (reference hits, no bytes); a content-shaped query throws a typed
  * "content search unsupported".
  */
-export class OutputsClient {
+class SessionFilesSearchClient {
     #http;
     constructor(http) {
         this.#http = http;
     }
     async search(query = {}) {
-        assertMetadataOnlyOutputSearch(query, "aex.outputs.search");
-        // Dedup the caller-supplied allow-list so a run repeated in `runIds` (from
+        assertMetadataOnlyFileSearch(query, "aex.files.search");
+        // Dedup the caller-supplied allow-list so a session repeated in `sessionIds` (from
         // concatenating corpora) isn't scanned twice and doesn't inflate hit count.
-        const unscoped = query.runIds === undefined;
+        const unscoped = query.sessionIds === undefined;
         const limit = query.limit ?? 100;
         if (unscoped)
             return this.#searchWorkspace(query, limit);
-        const runIds = [...new Set(query.runIds)];
+        const sessionIds = [...new Set(query.sessionIds)];
         const hits = [];
-        for (const runId of runIds) {
-            let outputs;
+        for (const sessionId of sessionIds) {
+            let files;
             try {
-                outputs = await searchRunOutputs(this.#http, runId, query);
+                files = await searchSessionFiles(this.#http, sessionId, query);
             }
             catch (err) {
-                if (unscoped && isMissingOutputsSession(err))
+                if (unscoped && isMissingFilesSession(err))
                     continue;
                 throw err;
             }
-            for (const hit of outputHits(runId, outputs, limit - hits.length)) {
+            for (const hit of fileHits(sessionId, files, limit - hits.length)) {
                 hits.push(hit);
                 if (hits.length >= limit)
                     return { hits };
@@ -496,7 +496,7 @@ export class OutputsClient {
         do {
             if (cursor !== undefined) {
                 if (seenCursors.has(cursor)) {
-                    throw new Error("aex.outputs.search: listSessions returned a repeated cursor");
+                    throw new Error("aex.files.search: listSessions returned a repeated cursor");
                 }
                 seenCursors.add(cursor);
             }
@@ -505,16 +505,16 @@ export class OutputsClient {
                 ...(cursor ? { cursor } : {})
             });
             for (const session of page.sessions) {
-                let outputs;
+                let files;
                 try {
-                    outputs = await searchRunOutputs(this.#http, session.id, query);
+                    files = await searchSessionFiles(this.#http, session.id, query);
                 }
                 catch (err) {
-                    if (isMissingOutputsSession(err))
+                    if (isMissingFilesSession(err))
                         continue;
                     throw err;
                 }
-                for (const hit of outputHits(session.id, outputs, limit - hits.length)) {
+                for (const hit of fileHits(session.id, files, limit - hits.length)) {
                     hits.push(hit);
                     if (hits.length >= limit)
                         return { hits };
@@ -526,13 +526,13 @@ export class OutputsClient {
     }
 }
 /**
- * A first-class, lineage-discoverable SUBAGENT CHILD run — handed out by
- * `session.children()` / `run.children()`, backed by the RUN facade
- * (getRun/events/outputs), NOT `openSession`. Every child the platform hands you
- * is resolvable through this handle; its lineage (`parentRunId`/`depth`) and
+ * A first-class, lineage-discoverable SUBAGENT child session — handed out by
+ * `session.children()`, backed by the session-record facade
+ * (getSessionRecord/events/files), NOT `openSession`. Every child the platform hands you
+ * is resolvable through this handle; its lineage (`parentSessionId`/`depth`) and
  * terminal outcome (`status`) are first-class.
  */
-export class ChildRunHandle {
+export class ChildSessionHandle {
     #http;
     #fetch;
     #ref;
@@ -544,81 +544,70 @@ export class ChildRunHandle {
     get id() {
         return this.#ref.id;
     }
-    get parentRunId() {
-        return this.#ref.parentRunId;
+    get parentSessionId() {
+        return this.#ref.parentSessionId;
     }
     get depth() {
         return this.#ref.depth;
     }
-    /** The child's run status (a real run terminal outcome once settled). */
+    /** The child's session status (a real session terminal outcome once settled). */
     get status() {
         return this.#ref.status;
     }
     get ref() {
         return this.#ref;
     }
-    /** Re-read the child run record (status, lineage, costTelemetry). */
+    /** Re-read the child session record (status, lineage, costTelemetry). */
     get() {
-        return operations.getRun(this.#http, this.id);
+        return operations.getSessionRecord(this.#http, this.id);
     }
-    /** The child's events over the RUN facade (`/runs/:id/events`). */
+    /** The child's events over the session-record facade (`/sessions/:id/events`). */
     events() {
-        return runEventsAccessor(this.#http, this.id);
+        return childSessionEventsAccessor(this.#http, this.id);
     }
-    /** The child's captured outputs over the RUN facade (`/runs/:id/outputs`). */
-    outputs() {
-        return runOutputsAccessor(this.#http, this.id, this.#fetch);
+    /** The child's captured files over the session-record facade (`/sessions/:id/files`). */
+    files() {
+        return sessionFiles(this.#http, this.id, this.#fetch);
     }
     /** This child's own subagent children (recursive lineage). */
     async children() {
-        const refs = await operations.listRunChildren(this.#http, this.id);
-        return refs.map((ref) => new ChildRunHandle(this.#http, ref, this.#fetch));
+        const refs = await operations.listSessionChildren(this.#http, this.id);
+        return refs.map((ref) => new ChildSessionHandle(this.#http, ref, this.#fetch));
     }
-    /** Cancel the child run (run facade `POST /runs/:id/cancel`). */
+    /** Cancel the child session (session record facade `POST /sessions/:id/cancel`). */
     cancel() {
-        return operations.cancelRun(this.#http, this.id);
+        return operations.cancelSession(this.#http, this.id).then(() => undefined);
     }
 }
-/** Run-facade events accessor (list + polling stream) — used by {@link ChildRunHandle}. */
-function runEventsAccessor(http, id) {
+/** SessionRecord-facade events accessor (list + polling stream) — used by {@link ChildSessionHandle}. */
+function childSessionEventsAccessor(http, id) {
     return {
-        list: async () => (await operations.listRunEvents(http, id)).map(asAexEventView),
-        stream: (options) => streamRunEventsPolling(http, id, options ?? {})
-    };
-}
-/** Run-facade outputs accessor — used by {@link ChildRunHandle}. */
-function runOutputsAccessor(http, id, fetchLike) {
-    void fetchLike;
-    return {
-        list: (query) => operations.listOutputs(http, id, query),
-        find: (query) => operations.findOutputs(http, id, query),
-        findOne: (query) => operations.findOutput(http, id, query),
-        read: (selector, options) => operations.readOutputText(http, id, selector, options),
-        link: (selectorOrQuery, options) => operations.outputLink(http, id, selectorOrQuery, options),
-        download: (selector, options) => downloadSessionOutput(http, id, selector, options)
+        list: async () => (await operations.listSessionRecordEvents(http, id)).map(asAexEventView),
+        stream: (options) => streamChildSessionEventsPolling(http, id, options ?? {})
     };
 }
+/** SessionRecord-facade files accessor — used by {@link ChildSessionHandle}. */
 /**
- * Poll a RUN's events (via the run facade) until it reaches a terminal status,
- * the signal aborts, or the caller breaks the iterator. Uses `getRun` (not
- * `getSession`) so it resolves for a child run that has no session facade.
+ * Poll a child session's events (via the session record facade) until it reaches a terminal status,
+ * the signal aborts, or the caller breaks the iterator. Uses `getSessionRecord` (not
+ * `getSession`) so it resolves for a child session that has no session facade.
  */
-async function* streamRunEventsPolling(http, id, options) {
+async function* streamChildSessionEventsPolling(http, id, options) {
     if (options.signal?.aborted)
         return;
     const seenIds = new Set();
     const intervalMs = options.intervalMs ?? 1_000;
     const signal = options.signal;
     while (!signal?.aborted) {
-        const events = await operations.listRunEvents(http, id);
+        const events = await operations.listSessionRecordEvents(http, id);
         for (const event of events) {
             if (!seenIds.has(event.id)) {
                 seenIds.add(event.id);
                 yield asAexEventView(event);
             }
         }
-        const run = await operations.getRun(http, id);
-        if (isSessionParked(run.status))
+        const session = await operations.getSessionRecord(http, id);
+        if (isSessionParked(session.status))
             return;
         try {
             await sleep(intervalMs, signal);
@@ -696,7 +685,7 @@ async function* streamSessionEventsPolling(http, id, options) {
     const intervalMs = options.intervalMs ?? 1_000;
     const signal = options.signal;
     while (!signal?.aborted) {
-        const events = await operations.listRunEvents(http, id);
+        const events = await operations.listSessionRecordEvents(http, id);
         for (const event of events) {
             if (!seenIds.has(event.id)) {
                 seenIds.add(event.id);
@@ -728,8 +717,8 @@ async function* streamSessionEnvelopes(http, id, options) {
         from: options.from ?? 0,
         fetchTicket: async () => (await operations.getSessionCoordinatorTicket(http, id)).ticket,
         // settleConsistent ends the stream on the post-mirror barrier instead of
-        // the earlier RUN_FINISHED UX signal.
-        isTerminal: options.settleConsistent ? isRunSettled : isSessionEnvelopeTerminal,
+        // the earlier TURN_FINISHED UX signal.
+        isTerminal: options.settleConsistent ? isSessionSettled : isSessionEnvelopeTerminal,
         ...(options.signal ? { signal: options.signal } : {}),
         ...(options.idleTimeoutMs !== undefined ? { idleTimeoutMs: options.idleTimeoutMs } : {}),
         ...(options.pingIntervalMs !== undefined ? { pingIntervalMs: options.pingIntervalMs } : {}),
@@ -740,93 +729,93 @@ async function* streamSessionEnvelopes(http, id, options) {
     }
 }
 function isSessionEnvelopeTerminal(event) {
-    return event.type === "RUN_FINISHED" || event.type === "RUN_ERROR" || isSessionParkedEvent(event);
+    return event.type === "TURN_FINISHED" || event.type === "TURN_ERROR" || isSessionParkedEvent(event);
 }
 /**
- * Download captured deliverables. No selector → the full outputs namespace as a
+ * Download captured files. No selector → the full files namespace as a
  * zip; a selector → one file's raw bytes. Module-level so
- * `SessionHandle.outputs()` can hand it to its accessor object literal.
+ * `SessionHandle.files()` can hand it to its accessor object literal.
  */
-async function downloadSessionOutput(http, id, selector, options) {
-    // One selector-resolution path: the contracts `downloadOutput` lists-if-path
+async function downloadSessionFile(http, id, selector, options) {
+    // One selector-resolution path: the contracts `downloadSessionFile` lists-if-path
     // then downloads, throwing with PUBLIC verb names — no duplicated resolver.
     const transferOptions = options?.timeoutMs === undefined ? undefined : { timeoutMs: options.timeoutMs };
     const bytes = selector === undefined
-        ? await operations.downloadOutputs(http, id, transferOptions)
-        : (await operations.downloadOutput(http, id, selector, transferOptions)).bytes;
+        ? await operations.downloadSessionFiles(http, id, transferOptions)
+        : (await operations.downloadSessionFile(http, id, selector, transferOptions)).bytes;
     return writeOptionalFile(bytes, options?.to);
 }
 /**
- * Build the outputs accessor for a session id. Shared by
- * `SessionHandle.outputs()` (bound to the live handle) and
- * `SessionClient.outputs(id)` (addressed by id without opening a handle), so both
- * expose the identical rich {@link SessionOutputs} surface — one accessor
+ * Build the files accessor for a session id. Shared by
+ * `SessionHandle.files()` (bound to the live handle) and
+ * `SessionClient.files(id)` (addressed by id without opening a handle), so both
+ * expose the identical rich {@link SessionFiles} surface — one accessor
  * convention, one implementation.
  */
-function sessionOutputs(http, id, fetchLike) {
-    const list = (query) => operations.listSessionOutputs(http, id, query);
+function sessionFiles(http, id, fetchLike) {
+    const list = (query) => operations.listSessionFiles(http, id, query);
     return {
         list,
         last: async () => (await list()).at(-1),
         first: async () => (await list())[0],
-        read: (selector, options) => operations.readOutputText(http, id, selector, options),
-        find: (query) => operations.findOutputs(http, id, query),
-        findOne: (query) => operations.findOutput(http, id, query),
+        read: (selector, options) => operations.readSessionFileText(http, id, selector, options),
+        find: (query) => operations.findSessionFiles(http, id, query),
+        findOne: (query) => operations.findSessionFile(http, id, query),
         search: async (query = {}) => {
-            assertMetadataOnlyOutputSearch(query, "outputs().search");
-            const outputs = await searchRunOutputs(http, id, query);
-            return { hits: outputHits(id, outputs, query.limit ?? 100) };
+            assertMetadataOnlyFileSearch(query, "files().search");
+            const files = await searchSessionFiles(http, id, query);
+            return { hits: fileHits(id, files, query.limit ?? 100) };
         },
-        link: (selectorOrQuery, options) => operations.outputLink(http, id, selectorOrQuery, options),
+        link: (selectorOrQuery, options) => operations.sessionFileLink(http, id, selectorOrQuery, options),
         fetch: async (selectorOrQuery, options) => {
-            const link = await operations.outputLink(http, id, selectorOrQuery, options);
+            const link = await operations.sessionFileLink(http, id, selectorOrQuery, options);
             return (fetchLike ?? globalThis.fetch)(link.url);
         },
-        download: (selector, options) => downloadSessionOutput(http, id, selector, options)
+        download: (selector, options) => downloadSessionFile(http, id, selector, options)
     };
 }
 /**
- * List one run's outputs matching a metadata search: `extension`/`contentType`
+ * List one session's files matching a metadata search: `extension`/`contentType`
  * via the contracts filter, and `filename` via {@link operations.toFilenameMatcher}
  * — a case-insensitive SUBSTRING for a string, `.test` for a RegExp (RegExp-safe;
  * no `escapeRegExp` footgun on a reused pattern).
  */
-async function searchRunOutputs(http, runId, query) {
+async function searchSessionFiles(http, sessionId, query) {
     const listQuery = {
         ...(query.extension !== undefined ? { extension: query.extension } : {}),
         ...(query.contentType !== undefined ? { contentType: query.contentType } : {})
     };
-    const outputs = await operations.listSessionOutputs(http, runId, Object.keys(listQuery).length > 0 ? listQuery : undefined);
+    const files = await operations.listSessionFiles(http, sessionId, Object.keys(listQuery).length > 0 ? listQuery : undefined);
     if (query.filename === undefined)
-        return outputs;
+        return files;
     const match = operations.toFilenameMatcher(query.filename);
-    return outputs.filter((output) => typeof output.filename === "string" && match(output.filename));
+    return files.filter((file) => typeof file.filename === "string" && match(file.filename));
 }
 /**
  * Fail-fast on a CONTENT-shaped search: the search surface is metadata-only, so
  * a `content`/`text`/`query` needle throws a typed error rather than silently
- * returning 0 hits (which reads as "no matches" for a query that was never run).
+ * returning 0 hits (which reads as "no matches" for a query that was never executed).
  */
-function assertMetadataOnlyOutputSearch(query, surface) {
+function assertMetadataOnlyFileSearch(query, surface) {
     for (const key of ["content", "text", "query", "grep", "body"]) {
         if (Object.prototype.hasOwnProperty.call(query, key)) {
-            throw new RunConfigValidationError(`${surface}: content search is not supported — search matches on filename/extension/contentType metadata only`, { field: key });
+            throw new SessionConfigValidationError(`${surface}: content search is not supported — search matches on filename/extension/contentType metadata only`, { field: key });
         }
     }
 }
-/** Project a run's output files to reference-only {@link OutputSearchHit}s, capped. */
-function outputHits(runId, outputs, limit) {
+/** Project a session's files to reference-only {@link SessionFileSearchHit}s, capped. */
+function fileHits(sessionId, files, limit) {
     const cap = Math.max(0, Math.floor(limit));
     if (cap === 0)
         return [];
     const hits = [];
-    for (const o of outputs) {
+    for (const file of files) {
         hits.push({
-            runId,
-            outputId: o.id,
-            ...(o.filename !== undefined ? { filename: o.filename } : {}),
-            ...(o.sizeBytes !== undefined ? { sizeBytes: o.sizeBytes } : {}),
-            ...(o.contentType !== undefined ? { contentType: o.contentType } : {})
+            sessionId,
+            fileId: file.id,
+            ...(file.filename !== undefined ? { filename: file.filename } : {}),
+            ...(file.sizeBytes !== undefined ? { sizeBytes: file.sizeBytes } : {}),
+            ...(file.contentType !== undefined ? { contentType: file.contentType } : {})
         });
         if (hits.length >= cap)
             break;
@@ -846,7 +835,7 @@ function messageFromWire(message) {
 function isMissingMessagesEndpoint(err) {
     return err instanceof AexApiError && (err.status === 404 || err.status === 405 || err.status === 501);
 }
-function isMissingOutputsSession(err) {
+function isMissingFilesSession(err) {
     return err instanceof AexApiError && err.status === 404;
 }
 function projectAssistantMessages(events) {
@@ -893,7 +882,7 @@ function projectAssistantMessages(events) {
 function assistantTextFromEvents(events) {
     return assistantTextEntriesFromEvents(events).map((entry) => entry.text).join("");
 }
-function runTraceFromEvents(events) {
+function turnTraceFromEvents(events) {
     return {
         toolCalls: toolCallsFromEvents(events),
         usage: usageFromEvents(events),
@@ -1059,7 +1048,7 @@ function carriedOutcome(event) {
         : undefined;
 }
 function isSessionTurnTerminalEvent(event, turnSeq) {
-    if (event.type === "RUN_FINISHED" || event.type === "RUN_ERROR") {
+    if (event.type === "TURN_FINISHED" || event.type === "TURN_ERROR") {
         return true;
     }
     const name = customName(event);
@@ -1076,7 +1065,7 @@ function isSessionTurnTerminalEvent(event, turnSeq) {
 /**
  * Read the CARRIED terminal outcome/park from the turn's terminal event — never
  * a lossy re-derivation. Prefers an explicit `data.value.outcome`, then the
- * `aex.session.<name>` name, then RUN_ERROR→failed / RUN_FINISHED→succeeded.
+ * `aex.session.<name>` name, then TURN_ERROR→failed / TURN_FINISHED→succeeded.
  */
 function terminalSessionStatusFromEvents(events, turnSeq) {
     for (let i = events.length - 1; i >= 0; i--) {
@@ -1086,9 +1075,9 @@ function terminalSessionStatusFromEvents(events, turnSeq) {
         const carried = carriedOutcome(event);
         if (carried !== undefined)
             return carried;
-        if (event.type === "RUN_ERROR")
+        if (event.type === "TURN_ERROR")
             return "failed";
-        if (event.type === "RUN_FINISHED")
+        if (event.type === "TURN_FINISHED")
             return "succeeded";
         const name = customName(event);
         if (name !== null && name in SESSION_TERMINAL_EVENT_READS)
@@ -1135,15 +1124,15 @@ function providerUsageOf(record) {
     return telemetry?.providerUsage;
 }
 /**
- * The IMMEDIATE authoritative failure text — the terminal `RUN_ERROR` event's
+ * The IMMEDIATE authoritative failure text — the terminal `TURN_ERROR` event's
  * `data.failureMessage`. `result.error` reads this FIRST so a failed (e.g.
- * bad-BYOK) run's error is never empty even before the settle-lagged
+ * bad-BYOK) session's error is never empty even before the settle-lagged
  * `sessionRecord.errorMessage` lands.
  */
 function failureFromEvents(events) {
     for (let i = events.length - 1; i >= 0; i--) {
         const event = events[i];
-        if (event.type !== "RUN_ERROR")
+        if (event.type !== "TURN_ERROR")
             continue;
         const data = asRecord(event.data);
         for (const key of ["failureMessage", "message", "error"]) {
@@ -1180,10 +1169,10 @@ function outcomeFromEvents(events) {
 }
 /**
  * Build the ONE unified settled turn result (shared by `session.send().done()`
- * and `Aex.run`): the terminal outcome `status`, `ok`, `costUsd` (>= 0),
+ * and `Aex.start`): the terminal outcome `status`, `ok`, `costUsd` (>= 0),
  * `usage` (from `costTelemetry.providerUsage`), and event-first `error`.
  */
-function settledTurnResult(sessionId, session, turn, events, outputs, messages, read) {
+function settledTurnResult(sessionId, session, turn, events, files, messages, read) {
     const effectiveRead = read ?? sessionRecordRead(session);
     const status = readToOutcome(effectiveRead);
     const ok = isTerminalReadOk(effectiveRead);
@@ -1203,7 +1192,7 @@ function settledTurnResult(sessionId, session, turn, events, outputs, messages,
         ...(error !== undefined ? { error } : {}),
         text: assistantTextFromEvents(events),
         events,
-        outputs,
+        files,
         messages,
         ...(outcome !== undefined ? { outcome } : {})
     };
@@ -1241,8 +1230,10 @@ export class AgentsMdClient {
  */
 export class FilesClient {
     #http;
+    #sessionSearch;
     constructor(http) {
         this.#http = http;
+        this.#sessionSearch = new SessionFilesSearchClient(http);
     }
     list() {
         return operations.listFiles(this.#http);
@@ -1253,6 +1244,10 @@ export class FilesClient {
     delete(fileId) {
         return operations.deleteFile(this.#http, fileId);
     }
+    /** Cross-session captured-file metadata search. */
+    search(query) {
+        return this.#sessionSearch.search(query);
+    }
 }
 /**
  * Workspace skill registry operations exposed under `client.skills`.
@@ -1280,7 +1275,7 @@ export class SkillsClient {
  * Workspace secret management exposed under `client.secrets`, mirroring
  * `client.agentsMd` / `client.files`.
  *
- * Lifecycle parity with assets: a `Secret.value(...)` is per-run and
+ * Lifecycle parity with assets: a `Secret.value(...)` is per-session and
  * gone at terminal; `set` (or promoting an ephemeral via `secret.upload`)
  * persists a named, searchable workspace secret you can `get` (metadata),
  * `rotate`, `list`, and `delete`. The identity is the `name`; the value rotates
@@ -1335,7 +1330,7 @@ function unwrapSecretValue(value) {
  * Unified user-facing client for the aex platform. The same class
  * powers the published `@aexhq/sdk` SDK and (under the hood) every host-side
  * subcommand of the in-container `aex` CLI. All operations talk to
- * the dashboard BFF and operate on durable run records.
+ * the dashboard BFF and operate on durable session records.
  *
  * The SDK never asks the caller for a workspace id — workspace identity
  * is derived server-side from the API key on every request. Use
@@ -1351,8 +1346,6 @@ export class Aex {
     skills;
     secrets;
     sessions;
-    /** Cross-run output search (`aex.outputs.search(...)`). */
-    outputs;
     constructor(options, overrides = {}) {
         const resolved = typeof options === "string" ? { ...overrides, apiKey: options } : options;
         const apiKey = resolved.apiKey;
@@ -1390,7 +1383,6 @@ export class Aex {
         this.skills = new SkillsClient(this.#http);
         this.secrets = new SecretsClient(this.#http);
         this.sessions = new SessionClient(this.#http, (options) => this.#buildSessionCreateRequest(options), this.#fetch);
-        this.outputs = new OutputsClient(this.#http);
     }
     /**
      * Internal: satisfies the `SecretUploader` surface so a
@@ -1436,7 +1428,7 @@ export class Aex {
     /**
      * Internal: upsert already-uploaded skill metadata into the workspace registry.
      * The bytes are staged through `_uploadAsset`; this call binds the content hash
-     * to a mutable workspace skill name before the run references that name.
+     * to a mutable workspace skill name before the session references that name.
      */
     async _upsertSkill(args) {
         return operations.upsertSkill(this.#http, args);
@@ -1445,34 +1437,34 @@ export class Aex {
      * Convenience one-shot on top of the canonical session API:
      * open a session, send `message` as the first turn, stream until the session
      * parks (`idle` / `suspended` / `error`), then return the collected text,
-     * events, outputs, and session record. The returned `runId` is the session id,
-     * so callers can resume later with `openSession(runId)`.
+     * events, files, and session record. The returned `sessionId` is the session id,
+     * so callers can resume later with `openSession(sessionId)`.
      */
-    async run(options, opts = {}) {
+    async start(options, opts = {}) {
         const scopedSignal = scopedAbortSignal(opts.timeoutMs);
         try {
             const { message, deleteAfter, messageIdempotencyKey, stream, ...createOptions } = options;
-            assertNoLegacySessionFields(options, "Aex.run");
-            const input = normaliseSessionInput(message, "Aex.run", "message");
-            assertNoSessionSendSignal(stream, "Aex.run stream");
+            assertNoLegacySessionFields(options, "Aex.start");
+            const input = normaliseSessionInput(message, "Aex.start", "message");
+            assertNoSessionSendSignal(stream, "Aex.start stream");
             const sendOptions = {
                 ...(stream ?? {}),
                 ...(scopedSignal?.signal ? { signal: scopedSignal.signal } : {}),
                 ...(opts.webSocketFactory ? { webSocketFactory: opts.webSocketFactory } : {}),
                 ...(opts.idleTimeoutMs !== undefined ? { idleTimeoutMs: opts.idleTimeoutMs } : {}),
                 ...(opts.pingIntervalMs !== undefined ? { pingIntervalMs: opts.pingIntervalMs } : {}),
-                // run()/done() await settle by DEFAULT; opt out with `await: 'park'`.
+                // start()/done() await settle by DEFAULT; opt out with `await: 'park'`.
                 ...(opts.await !== undefined ? { await: opts.await } : {})
             };
             // Derive the message key from the create key (like the CLI) so a retried
-            // run with the same `idempotencyKey` de-duplicates BOTH the create and the
-            // billable turn server-side — never a duplicate billable run (sdk-dx-3).
+            // session with the same `idempotencyKey` de-duplicates BOTH the create and the
+            // billable turn server-side — never a duplicate billable session turn (sdk-dx-3).
             const createKey = operations.resolveIdempotencyKey(createOptions.idempotencyKey);
             const messageKey = messageIdempotencyKey !== undefined ? operations.resolveIdempotencyKey(messageIdempotencyKey) : deriveMessageKey(createKey);
             const session = await this.sessions.create({ ...createOptions, idempotencyKey: createKey });
             // ONE terminal boundary: `done()` awaits settle by default, so the turn
-            // result already carries the terminal outcome + cost + usage. `run()` just
-            // reshapes it — `done()` == `run()` (WS3).
+            // result already carries the terminal outcome + cost + usage. `start()` just
+            // reshapes it — `done()` == `start()` (WS3).
             let turnResult;
             try {
                 turnResult = await sendSessionInternal(session, input, { ...sendOptions, idempotencyKey: messageKey }).done();
@@ -1481,24 +1473,23 @@ export class Aex {
                 if (scopedSignal?.signal.aborted) {
                     // The client-side wait budget (opts.timeoutMs) expired. Parity with
                     // SessionHandle.wait(): THROW rather than a misleading silent result;
-                    // the run continues server-side.
-                    throw new RunStateError(`Aex.run: timed out after ${opts.timeoutMs}ms waiting for run ${session.id} to park; the run ` +
+                    // the session continues server-side.
+                    throw new SessionStateError(`Aex.start: timed out after ${opts.timeoutMs}ms waiting for session ${session.id} to park; the session ` +
                         `continues server-side — cancel via session.cancel() or resume with openSession(${JSON.stringify(session.id)})`);
                 }
                 throw err;
             }
-            const runId = turnResult.sessionId;
+            const sessionId = turnResult.sessionId;
             if (deleteAfter) {
                 await session.delete();
             }
             const sessionRecord = turnResult.session;
-            const run = sessionToRun(sessionRecord);
-            const trace = runTraceFromEvents(turnResult.events);
+            const record = sessionToSessionRecord(sessionRecord);
+            const trace = turnTraceFromEvents(turnResult.events);
             const outcome = turnResult.outcome;
             const result = {
-                runId,
-                run,
-                sessionId: runId,
+                sessionId,
+                record,
                 session: sessionRecord,
                 turn: turnResult.turn,
                 status: turnResult.status,
@@ -1509,7 +1500,7 @@ export class Aex {
                 messages: turnResult.messages,
                 events: turnResult.events,
                 trace,
-                outputs: turnResult.outputs,
+                files: turnResult.files,
                 ...(turnResult.error !== undefined ? { error: turnResult.error } : {}),
                 ...(outcome !== undefined ? { outcome } : {})
             };
@@ -1527,7 +1518,7 @@ export class Aex {
                         ...(throttle.retryAfterMs !== undefined ? { retryAfterMs: throttle.retryAfterMs } : {})
                     });
                 }
-                throw new RunStateError(`Aex.run: session ${runId} ended ${turnResult.status}${turnResult.error ? `: ${turnResult.error}` : ""}`, { runId, status: turnResult.status });
+                throw new SessionStateError(`Aex.start: session ${sessionId} ended ${turnResult.status}${turnResult.error ? `: ${turnResult.error}` : ""}`, { sessionId, status: turnResult.status });
             }
             return result;
         }
@@ -1537,37 +1528,37 @@ export class Aex {
     }
     /**
      * Fire-and-forget: create the session and POST its first turn WITHOUT awaiting
-     * settle (the honest counterpart to await-settle `run()`). Resolves with the
-     * `runId` + a resumable {@link SessionHandle} immediately; observe the run via
-     * a `webhook`, the event stream, or `openSession(runId)`.
+     * settle (the honest counterpart to await-settle `start()`). Resolves with the
+     * `sessionId` + a resumable {@link SessionHandle} immediately; observe the session via
+     * a `webhook`, the event stream, or `openSession(sessionId)`.
      */
     async submit(options) {
         const { message, deleteAfter: _deleteAfter, messageIdempotencyKey, stream: _stream, ...createOptions } = options;
         assertNoLegacySessionFields(options, "Aex.submit");
         const input = normaliseSessionInput(message, "Aex.submit", "message");
         const request = await this.#buildSessionCreateRequest(createOptions);
-        const { runId, session } = await operations.submit(this.#http, { ...request, input }, {
+        const { sessionId, session } = await operations.submit(this.#http, { ...request, input }, {
             idempotencyKey: operations.resolveIdempotencyKey(createOptions.idempotencyKey),
             ...(messageIdempotencyKey !== undefined ? { messageIdempotencyKey } : {})
         });
-        return { runId, session: new SessionHandle(this.#http, session, this.#fetch) };
+        return { sessionId, session: new SessionHandle(this.#http, session, this.#fetch) };
     }
     /**
-     * Run a batch of one-shot items with a bounded worker pool, returning every
+     * SessionRecord a batch of one-shot items with a bounded worker pool, returning every
      * item's settled result PLUS a REAL cost/usage rollup. The rollup is honest
-     * because each `run()` awaits settle, so each item's `costUsd`/`usage` is
+     * because each `start()` awaits settle, so each item's `costUsd`/`usage` is
      * populated — a failed item lands in `failed[]`, never a silent `$0` success.
      * Concurrency is clamped below the workspace tier cap.
      */
     async batch(items, options = {}) {
         if (!Array.isArray(items)) {
-            throw new RunConfigValidationError("Aex.batch: items must be an array of run options");
+            throw new SessionConfigValidationError("Aex.batch: items must be an array of session options");
         }
         const concurrency = Math.min(Math.max(1, Math.floor(options.concurrency ?? DEFAULT_BATCH_CONCURRENCY)), BATCH_MAX_CONCURRENCY);
         const results = (await mapWithConcurrency(items, concurrency, async (item) => {
-            const result = await this.run(item);
+            const result = await this.start(item);
             return {
-                runId: result.runId,
+                sessionId: result.sessionId,
                 status: result.status,
                 ok: result.ok,
                 costUsd: result.costUsd,
@@ -1585,15 +1576,15 @@ export class Aex {
     }
     async #buildSessionCreateRequest(options) {
         if (!options || typeof options !== "object") {
-            throw new RunConfigValidationError("Aex.openSession: options is required");
+            throw new SessionConfigValidationError("Aex.openSession: options is required");
         }
         assertNoLegacySessionFields(options, "Aex.openSession");
-        // `message` belongs to the one-shot surfaces (`run` / `sessions.run`), which
+        // `message` belongs to the one-shot surfaces (`run` / `sessions.start`), which
         // strip it before creating the session. Passing it here used to be SILENTLY
         // dropped — the session was created empty, idled from birth, and auto-
         // suspended at the idle TTL without ever running a turn.
         if (Object.prototype.hasOwnProperty.call(options, "message")) {
-            throw new RunConfigValidationError("Aex.openSession: message is not a supported option; sessions are created without a first " +
+            throw new SessionConfigValidationError("Aex.openSession: message is not a supported option; sessions are created without a first " +
                 "message — send it with session.send(...), or use run({ message }) for a one-shot.");
         }
         // Model is REQUIRED and checked BEFORE the provider key, so omitting `model`
@@ -1634,12 +1625,12 @@ export class Aex {
         // server).
         try {
             parseRuntimeSize(options.runtime);
-            parseRunTimeout(options.overrides?.timeout);
+            parseSessionTimeout(options.overrides?.timeout);
             if (options.webhook !== undefined)
-                parseRunWebhook(options.webhook);
+                parseSessionWebhook(options.webhook);
         }
         catch (err) {
-            throw new RunConfigValidationError(`Aex.openSession: ${err instanceof Error ? err.message : String(err)}`);
+            throw new SessionConfigValidationError(`Aex.openSession: ${err instanceof Error ? err.message : String(err)}`);
         }
         const { declarations: secretEnvDeclarations, values: envSecretValues } = splitSecretEnv(options.environment?.secrets);
         let limits;
@@ -1649,11 +1640,11 @@ export class Aex {
         if (options.overrides?.maxTurns !== undefined)
             limitsInput.maxTurns = options.overrides.maxTurns;
         try {
-            limits = parseRunLimits(Object.keys(limitsInput).length > 0 ? limitsInput : undefined);
+            limits = parseSessionLimits(Object.keys(limitsInput).length > 0 ? limitsInput : undefined);
         }
         catch (err) {
             // One `configError` factory for every client-side validation throw, so
-            // maxSpendUsd/maxTurns are `RunConfigValidationError` (not a base AexError).
+            // maxSpendUsd/maxTurns are `SessionConfigValidationError` (not a base AexError).
             throw configError("Aex.openSession", "limits", err instanceof Error ? err.message : String(err));
         }
         const uploader = (args) => this._uploadAsset(args);
@@ -1667,7 +1658,7 @@ export class Aex {
             prepareFiles(options.files ?? [], uploader, streamUploader)
         ]);
         const { submissionMcpServers, mergedMcpSecrets } = mergeMcpServers(options.mcpServers ?? [], []);
-        const outputCapture = outputsForWire(options.outputs);
+        const fileCapture = fileCaptureForWire(options.fileCapture);
         const environment = sessionEnvironmentForWire(options.environment);
         const submission = {
             model: options.model,
@@ -1685,7 +1676,7 @@ export class Aex {
             ...(Object.keys(secretEnvDeclarations).length > 0 ? { secretEnv: secretEnvDeclarations } : {}),
             ...(environment ? { environment: environment } : {}),
             ...(options.metadata ? { metadata: options.metadata } : {}),
-            ...(outputCapture ? { outputs: outputCapture } : {}),
+            ...(fileCapture ? { fileCapture } : {}),
             ...(options.includeBuiltinTools !== undefined
                 ? { includeBuiltinTools: options.includeBuiltinTools }
                 : {}),
@@ -1715,7 +1706,7 @@ export class Aex {
     /**
      * Delete a workspace asset blob from the shared content-addressed store
      * (`assets/<workspaceId>/<hash>`). Accepts `sha256:<hex>` or a bare
-     * 64-hex digest. Runs that already snapshotted the asset are unaffected.
+     * 64-hex digest. Sessions that already snapshotted the asset are unaffected.
      */
     deleteWorkspaceAsset(hash) {
         return operations.deleteWorkspaceAsset(this.#http, hash);
@@ -1790,14 +1781,14 @@ function resolveBaseUrlForKey(apiKey, baseUrl) {
     }
     return baseUrl;
 }
-// `Run.status` is a loose `string` on the wire shape, so we membership-test
+// `SessionRecord.status` is a loose `string` on the wire shape, so we membership-test
 // against the canonical terminal set rather than re-deriving one (which is how
 // `timed_out` got dropped from the old hardcoded list).
-const TERMINAL_STATUSES = new Set(TERMINAL_RUN_STATUSES);
+const TERMINAL_STATUSES = new Set(TERMINAL_SESSION_CONTROL_STATUSES);
 function isTerminal(status) {
     return typeof status === "string" && TERMINAL_STATUSES.has(status);
 }
-/** How long `Aex.run` waits for the settle write after the park event (ms). */
+/** How long `Aex.start` waits for the settle write after the park event (ms). */
 const SETTLE_POLL_DEADLINE_MS = 60_000;
 /** Interval between settle-poll reads (ms). */
 const SETTLE_POLL_INTERVAL_MS = 750;
@@ -1875,7 +1866,7 @@ function isSessionParked(status) {
         status === "expired" ||
         isTerminal(status));
 }
-function sessionToRun(session) {
+function sessionToSessionRecord(session) {
     const id = session.sessionId ?? session.id;
     return {
         id,
@@ -1927,15 +1918,15 @@ function sleep(ms, signal) {
 }
 /**
  * ONE factory for every client-side validation throw: a
- * {@link RunConfigValidationError} carrying structured `details: { field, value? }`
+ * {@link SessionConfigValidationError} carrying structured `details: { field, value? }`
  * so callers branch on `err.details.field` instead of string-parsing the message.
  */
 function configError(surface, field, message, value) {
-    return new RunConfigValidationError(`${surface}: ${message}`, value === undefined ? { field } : { field, value });
+    return new SessionConfigValidationError(`${surface}: ${message}`, value === undefined ? { field } : { field, value });
 }
 /**
  * Derive the message idempotency key from the session-create key. Mirrors the
- * CLI (`<createKey>:message`) so a retried `run` / `sessions.run` that reuses
+ * CLI (`<createKey>:message`) so a retried `run` / `sessions.start` that reuses
  * one `idempotencyKey` de-duplicates BOTH the create and the billable turn.
  */
 function deriveMessageKey(createKey) {
@@ -1954,7 +1945,7 @@ function throttleFromSession(session) {
         faultFromErrorMessage(typeof session.errorMessage === "string" ? session.errorMessage : undefined);
     return fault && isThrottleFault(fault) ? fault : undefined;
 }
-/** Last-resort throttle detection from a free-text run error message. */
+/** Last-resort throttle detection from a free-text turn error message. */
 function faultFromErrorMessage(message) {
     if (message === undefined || message.length === 0)
         return undefined;
@@ -1970,16 +1961,16 @@ function faultFromErrorMessage(message) {
 function normaliseSessionInput(input, surface, field) {
     if (typeof input === "string") {
         if (!input) {
-            throw new RunConfigValidationError(`${surface}: ${field} must be a non-empty string`);
+            throw new SessionConfigValidationError(`${surface}: ${field} must be a non-empty string`);
         }
         return input;
     }
     if (!Array.isArray(input) || input.length === 0) {
-        throw new RunConfigValidationError(`${surface}: ${field} must be a non-empty string or string array`);
+        throw new SessionConfigValidationError(`${surface}: ${field} must be a non-empty string or string array`);
     }
     for (const segment of input) {
         if (typeof segment !== "string" || !segment) {
-            throw new RunConfigValidationError(`${surface}: ${field} segments must be non-empty strings`);
+            throw new SessionConfigValidationError(`${surface}: ${field} segments must be non-empty strings`);
         }
     }
     return [...input];
@@ -1989,66 +1980,66 @@ function assertNoLegacySessionFields(options, surface) {
     const removedProxyField = ["proxy", "Endpoints"].join("");
     const messages = {
         input: "send user messages with session.send(...) or use run({ message }).",
-        prompt: "use message for one-shot run input or session.send(...) for follow-up messages.",
+        prompt: "use message for one-shot session input or session.send(...) for follow-up messages.",
         instructions: "use system.",
         idleSuspendAfter: "use overrides.idleTtl.",
         idleTtl: "use overrides.idleTtl.",
         retention: "use overrides.idleTtl.",
         secretEnv: "use environment.secrets.",
-        secrets: "use top-level apiKeys for provider keys and environment.secrets for run secrets.",
+        secrets: "use top-level apiKeys for provider keys and environment.secrets for session secrets.",
         runtimeSize: "use runtime.",
         limits: "use overrides.",
         timeout: "use overrides.timeout.",
-        parentRunId: "subagent lineage is assigned by the platform.",
+        parentSessionId: "subagent lineage is assigned by the platform.",
         signal: "use session.cancel() / session.suspend() for remote control.",
         postHook: "send a follow-up validation message when the session returns idle.",
         [removedProxyField]: "proxy endpoints are not part of the public SDK session API."
     };
     for (const [field, message] of Object.entries(messages)) {
         if (Object.prototype.hasOwnProperty.call(record, field)) {
-            throw new RunConfigValidationError(`${surface}: ${field} is not a supported option; ${message}`);
+            throw new SessionConfigValidationError(`${surface}: ${field} is not a supported option; ${message}`);
         }
     }
     const overrides = record.overrides;
     if (overrides && typeof overrides === "object" && !Array.isArray(overrides)) {
         const overrideRecord = overrides;
         if (Object.prototype.hasOwnProperty.call(overrideRecord, "idleSuspendAfter")) {
-            throw new RunConfigValidationError(`${surface}: overrides.idleSuspendAfter is not a supported option; use overrides.idleTtl.`);
+            throw new SessionConfigValidationError(`${surface}: overrides.idleSuspendAfter is not a supported option; use overrides.idleTtl.`);
         }
     }
 }
 function assertNoSessionSendSignal(options, surface) {
     const record = options;
     if (record && typeof record === "object" && Object.prototype.hasOwnProperty.call(record, "signal")) {
-        throw new RunConfigValidationError(`${surface}: signal is not a supported option; use session.cancel() / session.suspend() for remote control.`);
+        throw new SessionConfigValidationError(`${surface}: signal is not a supported option; use session.cancel() / session.suspend() for remote control.`);
     }
 }
 function validateApiKeys(apiKeys, provider, surface) {
     const key = apiKeys?.[provider];
     if (typeof key !== "string" || key.length === 0) {
-        throw new RunConfigValidationError(`${surface}: a provider API key is required — pass apiKeys[${JSON.stringify(provider)}].`);
+        throw new SessionConfigValidationError(`${surface}: a provider API key is required — pass apiKeys[${JSON.stringify(provider)}].`);
     }
 }
-function outputsForWire(outputs) {
-    if (outputs === undefined) {
+function fileCaptureForWire(fileCapture) {
+    if (fileCapture === undefined) {
         return undefined;
     }
-    const allowedDirs = outputs.allowedDirs?.filter((dir) => dir.length > 0);
-    const deniedDirs = outputs.deniedDirs?.filter((dir) => dir.length > 0);
-    const hasNumericOverride = outputs.captureTimeoutMs !== undefined ||
-        outputs.maxFileBytes !== undefined ||
-        outputs.maxTotalBytes !== undefined ||
-        outputs.maxFiles !== undefined;
+    const allowedDirs = fileCapture.allowedDirs?.filter((dir) => dir.length > 0);
+    const deniedDirs = fileCapture.deniedDirs?.filter((dir) => dir.length > 0);
+    const hasNumericOverride = fileCapture.captureTimeoutMs !== undefined ||
+        fileCapture.maxFileBytes !== undefined ||
+        fileCapture.maxTotalBytes !== undefined ||
+        fileCapture.maxFiles !== undefined;
     if ((allowedDirs?.length ?? 0) === 0 && (deniedDirs?.length ?? 0) === 0 && !hasNumericOverride) {
         return undefined;
     }
     return {
         ...(allowedDirs && allowedDirs.length > 0 ? { allowedDirs } : {}),
         ...(deniedDirs && deniedDirs.length > 0 ? { deniedDirs } : {}),
-        ...(outputs.captureTimeoutMs !== undefined ? { captureTimeoutMs: outputs.captureTimeoutMs } : {}),
-        ...(outputs.maxFileBytes !== undefined ? { maxFileBytes: outputs.maxFileBytes } : {}),
-        ...(outputs.maxTotalBytes !== undefined ? { maxTotalBytes: outputs.maxTotalBytes } : {}),
-        ...(outputs.maxFiles !== undefined ? { maxFiles: outputs.maxFiles } : {})
+        ...(fileCapture.captureTimeoutMs !== undefined ? { captureTimeoutMs: fileCapture.captureTimeoutMs } : {}),
+        ...(fileCapture.maxFileBytes !== undefined ? { maxFileBytes: fileCapture.maxFileBytes } : {}),
+        ...(fileCapture.maxTotalBytes !== undefined ? { maxTotalBytes: fileCapture.maxTotalBytes } : {}),
+        ...(fileCapture.maxFiles !== undefined ? { maxFiles: fileCapture.maxFiles } : {})
     };
 }
 const DEFAULT_SESSION_IDLE_TTL = "3m";
@@ -2121,7 +2112,7 @@ async function prepareTools(tools, uploader) {
         // A bare string is a builtin tool reference.
         if (typeof entry === "string") {
             if (!BUILTIN_TOOL_NAMES.includes(entry)) {
-                throw new RunConfigValidationError(`aex: tools[${i}] (${JSON.stringify(entry)}) is not a builtin tool name; ` +
+                throw new SessionConfigValidationError(`aex: tools[${i}] (${JSON.stringify(entry)}) is not a builtin tool name; ` +
                     `expected a Tool or one of: ${BUILTIN_TOOL_NAMES.join(", ")}`);
             }
             return { kind: "builtin", name: entry };
@@ -2129,15 +2120,15 @@ async function prepareTools(tools, uploader) {
         if (!(entry instanceof Tool)) {
             const maybeEntry = entry;
             if (maybeEntry instanceof Skill) {
-                throw new RunConfigValidationError(`aex: tools[${i}] is a Skill; pass skills via the top-level skills option`);
+                throw new SessionConfigValidationError(`aex: tools[${i}] is a Skill; pass skills via the top-level skills option`);
             }
-            throw new RunConfigValidationError(`aex: tools[${i}] must be a Tool or a builtin tool name`);
+            throw new SessionConfigValidationError(`aex: tools[${i}] must be a Tool or a builtin tool name`);
         }
         const ref = entry.ref;
         if (ref.kind === "draft") {
             const bundle = entry._takeDraftBundle();
             if (!bundle) {
-                throw new RunConfigValidationError(`aex: tools[${i}] is draft but has no bytes`);
+                throw new SessionConfigValidationError(`aex: tools[${i}] is draft but has no bytes`);
             }
             const assetId = await resolveAssetId(entry, bundle, uploader);
             return { kind: "ref", ref: { ...bundle.ref, assetId } };
@@ -2163,21 +2154,21 @@ async function prepareTools(tools, uploader) {
 /**
  * Upload/upsert workspace skills and return public name-only refs. Draft skills
  * auto-upsert (bytes → asset store, then registry PUT) by name; already-uploaded
- * skills pass through. Duplicate names are pre-checked (uploads run in parallel,
- * so the dedup cannot be a running set inside the map).
+ * skills pass through. Duplicate names are pre-checked (uploads session in parallel,
+ * so the dedup cannot be a sessionning set inside the map).
  */
 async function prepareSkills(skills, uploader) {
     if (skills.length > SKILLS_MAX) {
-        throw new RunConfigValidationError(`aex: skills exceeds the ${SKILLS_MAX}-skill limit (got ${skills.length})`);
+        throw new SessionConfigValidationError(`aex: skills exceeds the ${SKILLS_MAX}-skill limit (got ${skills.length})`);
     }
     const seen = new Set();
     for (let i = 0; i < skills.length; i++) {
         const entry = skills[i];
         if (!(entry instanceof Skill)) {
-            throw new RunConfigValidationError(`aex: skills[${i}] must be a Skill (Skill.fromDir / fromUrl / fromFiles / fromContent / fromBytes)`);
+            throw new SessionConfigValidationError(`aex: skills[${i}] must be a Skill (Skill.fromDir / fromUrl / fromFiles / fromContent / fromBytes)`);
         }
         if (seen.has(entry.name)) {
-            throw new RunConfigValidationError(`aex: skills duplicate name: ${entry.name}`);
+            throw new SessionConfigValidationError(`aex: skills duplicate name: ${entry.name}`);
         }
         seen.add(entry.name);
     }
@@ -2185,7 +2176,7 @@ async function prepareSkills(skills, uploader) {
         const uploaded = entry.isDraft ? await entry.upload(uploader) : entry;
         const ref = uploaded.ref;
         if (ref.kind !== "skill") {
-            throw new RunConfigValidationError(`aex: skills[${i}] did not resolve to a workspace skill ref`);
+            throw new SessionConfigValidationError(`aex: skills[${i}] did not resolve to a workspace skill ref`);
         }
         return ref;
     });
@@ -2194,13 +2185,13 @@ async function prepareSkills(skills, uploader) {
 async function prepareAgentsMd(agentsMds, uploader) {
     return mapWithConcurrency(agentsMds, UPLOAD_CONCURRENCY, async (entry, i) => {
         if (!(entry instanceof AgentsMd)) {
-            throw new RunConfigValidationError(`aex: agentsMd[${i}] must be an AgentsMd instance`);
+            throw new SessionConfigValidationError(`aex: agentsMd[${i}] must be an AgentsMd instance`);
         }
         const ref = entry.ref;
         if (ref.kind === "draft") {
             const bundle = entry._takeDraftBundle();
             if (!bundle) {
-                throw new RunConfigValidationError(`aex: agentsMd[${i}] is draft but has no bytes`);
+                throw new SessionConfigValidationError(`aex: agentsMd[${i}] is draft but has no bytes`);
             }
             const assetId = await resolveAssetId(entry, bundle, uploader);
             return { kind: "asset", assetId, name: bundle.name };
@@ -2212,7 +2203,7 @@ async function prepareAgentsMd(agentsMds, uploader) {
 async function prepareFiles(files, uploader, streamUploader) {
     return mapWithConcurrency(files, UPLOAD_CONCURRENCY, async (entry, i) => {
         if (!(entry instanceof File)) {
-            throw new RunConfigValidationError(`aex: files[${i}] must be a File instance`);
+            throw new SessionConfigValidationError(`aex: files[${i}] must be a File instance`);
         }
         const ref = entry.ref;
         if (ref.kind === "draft") {
@@ -2229,7 +2220,7 @@ async function prepareFiles(files, uploader, streamUploader) {
             }
             const bundle = entry._takeDraftBundle();
             if (!bundle) {
-                throw new RunConfigValidationError(`aex: files[${i}] is draft but has no bytes`);
+                throw new SessionConfigValidationError(`aex: files[${i}] is draft but has no bytes`);
             }
             const assetId = await resolveAssetId(entry, bundle, uploader);
             return { kind: "asset", assetId, name: bundle.name, mountPath: bundle.mountPath };
@@ -2246,14 +2237,14 @@ function mergeMcpServers(inputs, explicitSecrets) {
     for (let i = 0; i < inputs.length; i++) {
         const entry = inputs[i];
         if (!(entry instanceof McpServer)) {
-            throw new RunConfigValidationError(`aex: mcpServers[${i}] must be an McpServer instance`);
+            throw new SessionConfigValidationError(`aex: mcpServers[${i}] must be an McpServer instance`);
         }
         submissionMcpServers.push(entry.toSubmissionEntry());
         const secret = entry.toSecretEntry();
         if (secret) {
             const existing = secretByName.get(secret.name);
             if (existing && existing.url !== secret.url) {
-                throw new RunConfigValidationError(`aex: mcpServers[${i}].url conflicts with secrets.mcpServers["${secret.name}"]`);
+                throw new SessionConfigValidationError(`aex: mcpServers[${i}].url conflicts with secrets.mcpServers["${secret.name}"]`);
             }
             secretByName.set(secret.name, secret);
         }