@aexhq/sdk 0.39.0 → 0.40.1

package/dist/client.js

@@ -1,6 +1,6 @@
-import { AexApiError, AexError, CredentialValidationError, DEFAULT_RUN_PROVIDER, HttpClient, RunConfigValidationError, RunStateError, SecretString, customName, isRunSettled, operations, providersForModel, streamCoordinatorEvents, parseRunLimits, parseRuntimeSize, parseRunTimeout, parseRunWebhook, BUILTIN_TOOL_NAMES, SKILLS_MAX, TERMINAL_RUN_STATUSES } from "./_contracts/index.js";
+import { AexApiError, CredentialValidationError, HttpClient, PLANE_BASE_URLS, RunConfigValidationError, RunStateError, SecretString, asAexEventView, customName, isRunSettled, assertStreamableOutputMode, operations, parseApiKey, resolveModelProvider, streamCoordinatorEvents, usageFromProviderUsage, parseRunLimits, parseRuntimeSize, parseRunTimeout, parseRunWebhook, BUILTIN_TOOL_NAMES, SKILLS_MAX, TERMINAL_RUN_STATUSES } from "./_contracts/index.js";
 import { AgentsMd } from "./agents-md.js";
-import { uploadAsset } from "./asset-upload.js";
+import { uploadAsset, uploadAssetMultipart } from "./asset-upload.js";
 import { File } from "./file.js";
 import { McpServer } from "./mcp-server.js";
 import { AexRateLimitError, isThrottleFault, parseProviderFault, withRetry } from "./retry.js";
@@ -122,9 +122,9 @@ export class SessionHandle {
         });
     }
     async *#send(input, options) {
-        const idempotencyKey = options.idempotencyKey ?? generateIdempotencyKey();
+        const idempotencyKey = operations.resolveIdempotencyKey(options.idempotencyKey);
         this.#lastSend = { input, idempotencyKey };
-        const accepted = await operations.sendSessionMessage(this.#http, this.id, { input }, { idempotencyKey });
+        const accepted = await this.#acceptTurn(input, idempotencyKey, options.signal);
         this.#session = accepted.session;
         const turn = accepted.turn;
         const events = [];
@@ -135,21 +135,70 @@ export class SessionHandle {
             events.push(event);
             yield event;
         }
-        const terminalStatus = terminalSessionStatusFromEvents(events, turn.turnSeq);
+        // Read the CARRIED terminal outcome from the events (never re-derive a lossy idle).
+        const read = terminalSessionStatusFromEvents(events, turn.turnSeq);
+        // Await the settle commit by DEFAULT so cost/usage + the terminal outcome are
+        // always present; `await: 'park'` returns at the render-complete park event.
         const readSession = await operations.getSession(this.#http, this.id).catch(() => this.#session);
-        this.#session = withTerminalSessionStatus(readSession, terminalStatus);
+        const settled = (options.await ?? "settle") === "park"
+            ? 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 messages = projectAssistantMessages(events);
-        return {
-            sessionId: this.id,
-            session: this.#session,
-            turn,
-            status: this.#session.status,
-            text: assistantTextFromEvents(events),
-            events,
-            outputs,
-            messages
-        };
+        return settledTurnResult(this.id, this.#session, turn, events, outputs, messages, read);
+    }
+    /**
+     * POST the next turn, reconciling the settle-lag race. A turn stream ends on
+     * the idle park EVENT, but the session RECORD can lag at `running` for a short
+     * window before the platform commits it — so an immediate follow-up `send()`
+     * 409s `session_busy` even though, from the caller's view, the previous turn
+     * already parked. When that happens we poll the record until it leaves
+     * `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
+     * waiting forever. Any non-`running` busy status (suspended / cancelling /
+     * deleted) is a real rejection and passes straight through.
+     */
+    async #acceptTurn(input, idempotencyKey, signal) {
+        const deadline = Date.now() + SESSION_BUSY_RECONCILE_DEADLINE_MS;
+        for (;;) {
+            try {
+                return await operations.sendSessionMessage(this.#http, this.id, { input }, { idempotencyKey });
+            }
+            catch (err) {
+                if (!isSettlingSessionBusy(err) || signal?.aborted)
+                    throw err;
+                if (Date.now() >= deadline) {
+                    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`, { sessionId: this.id, status: "running", cause: err });
+                }
+                await this.#awaitLeftRunning(deadline, signal);
+            }
+        }
+    }
+    /**
+     * Poll the session record until it is no longer `running`/`creating`, or the
+     * reconcile deadline elapses. Updates the stored record so the eventual retry
+     * (or the terminal error) reflects the freshest status.
+     */
+    async #awaitLeftRunning(deadline, signal) {
+        for (;;) {
+            try {
+                await sleep(SESSION_BUSY_RECONCILE_INTERVAL_MS, signal);
+            }
+            catch {
+                return; // aborted — let the retry POST surface the real state
+            }
+            const record = await operations.getSession(this.#http, this.id).catch(() => undefined);
+            if (record !== undefined) {
+                this.#session = record;
+                if (record.status !== "running" && record.status !== "creating")
+                    return;
+            }
+            if (Date.now() >= deadline)
+                return;
+        }
     }
     async suspend(options = {}) {
         const accepted = await operations.suspendSession(this.#http, this.id, options);
@@ -172,6 +221,39 @@ export class SessionHandle {
             this.#session = accepted.session;
         }
     }
+    /**
+     * Request the HITL write-gate: park this session `awaiting_approval` before
+     * its next gated action. Imperative counterpart to the declarative
+     * `approvalGate` submission option. Resume with {@link approve} / reject with
+     * {@link deny}.
+     */
+    async requestApproval(options = {}) {
+        const accepted = await operations.requestApproval(this.#http, this.id, options);
+        this.#session = accepted.session;
+        return accepted;
+    }
+    /** Approve an `awaiting_approval` session so the held turn resumes (→ running). */
+    async approve(options = {}) {
+        const accepted = await operations.approveSession(this.#http, this.id, options);
+        this.#session = accepted.session;
+        return accepted;
+    }
+    /** Deny an `awaiting_approval` session so the held turn is cancelled (→ cancelled). */
+    async deny(options = {}) {
+        const accepted = await operations.denySession(this.#http, this.id, options);
+        this.#session = accepted.session;
+        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) —
+     * NOT `openSession` — so every child the platform hands you is resolvable, with
+     * its lineage (`parentRunId`/`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));
+    }
     /**
      * Accessor for the session's assistant messages. `all()` returns them
      * oldest-first; `last()`/`first()` return a single entry or `undefined` when
@@ -209,14 +291,14 @@ export class SessionHandle {
     }
     /**
      * Accessor for the session's event stream: the buffered `SessionEvent`
-     * snapshots (`list`/`last`/`first`), the polling `RunEvent` iterator
+     * snapshots (`list`/`last`/`first`), the polling `AexEventView` iterator
      * (`stream`), the live coordinator envelope iterator (`streamEnvelopes`), and
      * the events-namespace archive (`archiveLink`/`download`).
      */
     events() {
         const http = this.#http;
         const id = this.id;
-        const list = () => operations.listSessionEvents(http, id);
+        const list = async () => (await operations.listSessionEvents(http, id)).map(asAexEventView);
         return {
             list,
             last: async () => (await list()).at(-1),
@@ -315,7 +397,7 @@ export class SessionClient {
     }
     async create(options) {
         const request = await this.#buildCreateRequest(options);
-        const session = await operations.createSession(this.#http, request, { idempotencyKey: options.idempotencyKey ?? generateIdempotencyKey() });
+        const session = await operations.createSession(this.#http, request, { idempotencyKey: operations.resolveIdempotencyKey(options.idempotencyKey) });
         return new SessionHandle(this.#http, session, this.#fetch);
     }
     async open(sessionId) {
@@ -340,65 +422,73 @@ export class SessionClient {
     outputs(sessionId) {
         return sessionOutputs(this.#http, sessionId, this.#fetch);
     }
-    /**
-     * Find output files across sessions by filename / extension / content type.
-     * Returns lean REFERENCE hits (never bytes; fetch content with `readOutput`).
-     * Scope the search to a corpus with `query.runIds` (a session-id allow-list);
-     * omit it to scan every session in the workspace. Composed client-side (per-
-     * session `listSessionOutputs` + the contracts output filter), bounded by
-     * `query.limit` (default 100).
-     */
-    async searchOutputs(query = {}) {
-        // Dedup the caller-supplied allow-list so a run repeated in `runIds` (e.g. from
-        // concatenating corpora) isn't scanned twice and doesn't inflate the hit count
-        // with duplicates (pre-launch edge-sweep F27).
+    async run(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
+        // with the same `idempotencyKey` de-duplicates BOTH the create and the
+        // billable turn — never a duplicate billable run.
+        const createKey = operations.resolveIdempotencyKey(createOptions.idempotencyKey);
+        const messageKey = messageIdempotencyKey !== undefined ? operations.resolveIdempotencyKey(messageIdempotencyKey) : deriveMessageKey(createKey);
+        const session = await this.create({ ...createOptions, idempotencyKey: createKey });
+        const result = await session.send(input, {
+            ...(stream ?? {}),
+            idempotencyKey: messageKey
+        }).done();
+        if (deleteAfter) {
+            await session.delete();
+        }
+        return result;
+    }
+}
+/**
+ * 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
+ * (reference hits, no bytes); a content-shaped query throws a typed
+ * "content search unsupported".
+ */
+export class OutputsClient {
+    #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
+        // concatenating corpora) isn't scanned twice and doesn't inflate hit count.
         const unscoped = query.runIds === undefined;
-        const sessionIds = unscoped ? await this.#allSessionIds() : [...new Set(query.runIds)];
+        const runIds = unscoped ? await this.#allRunIds() : [...new Set(query.runIds)];
         const limit = query.limit ?? 100;
-        // Translate the search query to an OutputQuery so the contracts output
-        // filter does the matching — no re-derived filter logic here.
-        const outputQuery = {
-            ...(query.filename ? { filename: new RegExp(escapeRegExp(query.filename), "i") } : {}),
-            ...(query.extension ? { extension: query.extension } : {}),
-            ...(query.contentType ? { contentType: query.contentType } : {})
-        };
-        const hasFilter = Object.keys(outputQuery).length > 0;
         const hits = [];
-        for (const sessionId of sessionIds) {
+        for (const runId of runIds) {
             let outputs;
             try {
-                outputs = hasFilter
-                    ? await operations.listSessionOutputs(this.#http, sessionId, outputQuery)
-                    : await operations.listSessionOutputs(this.#http, sessionId);
+                outputs = await searchRunOutputs(this.#http, runId, query);
             }
             catch (err) {
                 if (unscoped && isMissingOutputsSession(err))
                     continue;
                 throw err;
             }
-            for (const o of outputs) {
-                hits.push({
-                    runId: sessionId,
-                    outputId: o.id,
-                    ...(o.filename !== undefined ? { filename: o.filename } : {}),
-                    ...(o.sizeBytes !== undefined ? { sizeBytes: o.sizeBytes } : {}),
-                    ...(o.contentType !== undefined ? { contentType: o.contentType } : {})
-                });
+            for (const hit of outputHits(runId, outputs, limit - hits.length)) {
+                hits.push(hit);
                 if (hits.length >= limit)
                     return { hits };
             }
         }
         return { hits };
     }
-    /** Enumerate every session id in the workspace by paging `listSessions`. */
-    async #allSessionIds() {
+    /** Enumerate every run id in the workspace by paging `listSessions`. */
+    async #allRunIds() {
         const ids = [];
         const seenCursors = new Set();
         let cursor;
         do {
             if (cursor !== undefined) {
                 if (seenCursors.has(cursor)) {
-                    throw new Error("Aex.sessions.searchOutputs: listSessions returned a repeated cursor");
+                    throw new Error("aex.outputs.search: listSessions returned a repeated cursor");
                 }
                 seenCursors.add(cursor);
             }
@@ -409,29 +499,152 @@ export class SessionClient {
         } while (cursor);
         return ids;
     }
-    async run(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
-        // with the same `idempotencyKey` de-duplicates BOTH the create and the
-        // billable turn — never a duplicate billable run.
-        const createKey = createOptions.idempotencyKey ?? generateIdempotencyKey();
-        const messageKey = messageIdempotencyKey ?? deriveMessageKey(createKey);
-        const session = await this.create({ ...createOptions, idempotencyKey: createKey });
-        const result = await session.send(input, {
-            ...(stream ?? {}),
-            idempotencyKey: messageKey
-        }).done();
-        if (deleteAfter) {
-            await session.delete();
+}
+/**
+ * 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
+ * terminal outcome (`status`) are first-class.
+ */
+export class ChildRunHandle {
+    #http;
+    #fetch;
+    #ref;
+    constructor(http, ref, fetch) {
+        this.#http = http;
+        this.#ref = ref;
+        this.#fetch = fetch;
+    }
+    get id() {
+        return this.#ref.id;
+    }
+    get parentRunId() {
+        return this.#ref.parentRunId;
+    }
+    get depth() {
+        return this.#ref.depth;
+    }
+    /** The child's run status (a real run terminal outcome once settled). */
+    get status() {
+        return this.#ref.status;
+    }
+    get ref() {
+        return this.#ref;
+    }
+    /** Re-read the child run record (status, lineage, costTelemetry). */
+    get() {
+        return operations.getRun(this.#http, this.id);
+    }
+    /** The child's events over the RUN facade (`/runs/:id/events`). */
+    events() {
+        return runEventsAccessor(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);
+    }
+    /** 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));
+    }
+    /** Cancel the child run (run facade `POST /runs/:id/cancel`). */
+    cancel() {
+        return operations.cancelRun(this.#http, this.id);
+    }
+}
+/** Run-facade events accessor (list + polling stream) — used by {@link ChildRunHandle}. */
+function runEventsAccessor(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)
+    };
+}
+/**
+ * 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.
+ */
+async function* streamRunEventsPolling(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);
+        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))
+            return;
+        try {
+            await sleep(intervalMs, signal);
+        }
+        catch {
+            return;
         }
-        return result;
     }
 }
+/** Default / max concurrent items for {@link Aex.batch} (bounded below the tier cap). */
+const DEFAULT_BATCH_CONCURRENCY = 4;
+const BATCH_MAX_CONCURRENCY = 10;
+/** Sum the per-item settled cost/usage into a real {@link BatchResult} rollup. */
+function rollupBatch(results) {
+    let totalCostUsd = 0;
+    let okCount = 0;
+    const failed = [];
+    for (const result of results) {
+        totalCostUsd += result.costUsd;
+        if (result.ok)
+            okCount += 1;
+        else
+            failed.push(result);
+    }
+    return {
+        results,
+        totalCostUsd,
+        totalUsage: sumUsageSummaries(results.map((result) => result.usage)),
+        okCount,
+        failed
+    };
+}
+/** Field-wise sum of {@link UsageSummary} objects; a field is present iff some item carried it. */
+function sumUsageSummaries(usages) {
+    const keys = ["inputTokens", "outputTokens", "cacheReadInputTokens", "cacheCreationInputTokens", "totalTokens"];
+    const out = {};
+    for (const key of keys) {
+        let sum;
+        for (const usage of usages) {
+            const value = usage[key];
+            if (typeof value === "number")
+                sum = (sum ?? 0) + value;
+        }
+        if (sum !== undefined)
+            out[key] = sum;
+    }
+    return out;
+}
 async function* streamSessionTurnEvents(http, sessionId, turn, options) {
     const first = await operations.getSessionCoordinatorTicket(http, sessionId);
-    yield* streamCoordinatorEvents({
+    for await (const event of streamCoordinatorEvents({
         wsUrl: first.wsUrl,
         from: options.from ?? 0,
         fetchTicket: async () => (await operations.getSessionCoordinatorTicket(http, sessionId)).ticket,
@@ -440,12 +653,16 @@ async function* streamSessionTurnEvents(http, sessionId, turn, options) {
         ...(options.webSocketFactory ? { webSocketFactory: options.webSocketFactory } : {}),
         ...(options.idleTimeoutMs !== undefined ? { idleTimeoutMs: options.idleTimeoutMs } : {}),
         ...(options.pingIntervalMs !== undefined ? { pingIntervalMs: options.pingIntervalMs } : {})
-    });
+    })) {
+        yield asAexEventView(event);
+    }
 }
 /**
- * Poll the session's `RunEvent` snapshots until the session parks, the signal
- * aborts, or the caller breaks the iterator, deduping by event id. Module-level
- * so `SessionHandle.events()` can hand it to its accessor object literal.
+ * Poll the session's event snapshots until the session parks, the signal
+ * aborts, or the caller breaks the iterator, deduping by event id. Yields the
+ * one canonical guard-bearing {@link AexEventView} (same shape as every other
+ * event surface). Module-level so `SessionHandle.events()` can hand it to its
+ * accessor object literal.
  */
 async function* streamSessionEventsPolling(http, id, options) {
     if (options.signal?.aborted)
@@ -458,7 +675,7 @@ async function* streamSessionEventsPolling(http, id, options) {
         for (const event of events) {
             if (!seenIds.has(event.id)) {
                 seenIds.add(event.id);
-                yield event;
+                yield asAexEventView(event);
             }
         }
         const session = await operations.getSession(http, id);
@@ -481,7 +698,7 @@ async function* streamSessionEventsPolling(http, id, options) {
  */
 async function* streamSessionEnvelopes(http, id, options) {
     const first = await operations.getSessionCoordinatorTicket(http, id);
-    yield* streamCoordinatorEvents({
+    for await (const event of streamCoordinatorEvents({
         wsUrl: first.wsUrl,
         from: options.from ?? 0,
         fetchTicket: async () => (await operations.getSessionCoordinatorTicket(http, id)).ticket,
@@ -489,7 +706,9 @@ async function* streamSessionEnvelopes(http, id, options) {
         // the earlier RUN_FINISHED UX signal.
         ...(options.settleConsistent ? { isTerminal: isRunSettled } : {}),
         ...(options.signal ? { signal: options.signal } : {})
-    });
+    })) {
+        yield asAexEventView(event);
+    }
 }
 /**
  * Download captured deliverables. No selector → the full outputs namespace as a
@@ -497,17 +716,11 @@ async function* streamSessionEnvelopes(http, id, options) {
  * `SessionHandle.outputs()` can hand it to its accessor object literal.
  */
 async function downloadSessionOutput(http, id, selector, options) {
-    let bytes;
-    if (selector === undefined) {
-        bytes = await operations.downloadOutputs(http, id);
-    }
-    else {
-        const output = isOutputPathSelector(selector)
-            ? resolveOutputFileSelector(await operations.listOutputs(http, id), selector, id)
-            : resolveOutputFileSelector([], selector, id);
-        const { response } = await http.download(`/api/runs/${encodeURIComponent(id)}/outputs/${encodeURIComponent(output.id)}/download`);
-        bytes = new Uint8Array(await response.arrayBuffer());
-    }
+    // One selector-resolution path: the contracts `downloadOutput` lists-if-path
+    // then downloads, throwing with PUBLIC verb names — no duplicated resolver.
+    const bytes = selector === undefined
+        ? await operations.downloadOutputs(http, id)
+        : (await operations.downloadOutput(http, id, selector)).bytes;
     return writeOptionalFile(bytes, options?.to);
 }
 /**
@@ -526,6 +739,11 @@ function sessionOutputs(http, id, fetchLike) {
         read: (selector, options) => operations.readOutputText(http, id, selector, options),
         find: (query) => operations.findOutputs(http, id, query),
         findOne: (query) => operations.findOutput(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) };
+        },
         link: (selectorOrQuery, options) => operations.outputLink(http, id, selectorOrQuery, options),
         fetch: async (selectorOrQuery, options) => {
             const link = await operations.outputLink(http, id, selectorOrQuery, options);
@@ -534,6 +752,51 @@ function sessionOutputs(http, id, fetchLike) {
         download: (selector, options) => downloadSessionOutput(http, id, selector, options)
     };
 }
+/**
+ * List one run's outputs 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) {
+    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);
+    if (query.filename === undefined)
+        return outputs;
+    const match = operations.toFilenameMatcher(query.filename);
+    return outputs.filter((output) => typeof output.filename === "string" && match(output.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).
+ */
+function assertMetadataOnlyOutputSearch(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 });
+        }
+    }
+}
+/** Project a run's output files to reference-only {@link OutputSearchHit}s, capped. */
+function outputHits(runId, outputs, limit) {
+    const hits = [];
+    for (const o of outputs) {
+        hits.push({
+            runId,
+            outputId: o.id,
+            ...(o.filename !== undefined ? { filename: o.filename } : {}),
+            ...(o.sizeBytes !== undefined ? { sizeBytes: o.sizeBytes } : {}),
+            ...(o.contentType !== undefined ? { contentType: o.contentType } : {})
+        });
+        if (hits.length >= limit)
+            break;
+    }
+    return hits;
+}
 function messageFromWire(message) {
     return {
         id: message.id,
@@ -603,8 +866,7 @@ function runTraceFromEvents(events) {
 }
 function assistantTextEntriesFromEvents(events) {
     const out = [];
-    for (const raw of events) {
-        const event = raw;
+    for (const event of events) {
         if (event.type !== "TEXT_MESSAGE_CONTENT")
             continue;
         const data = asRecord(event.data);
@@ -615,11 +877,10 @@ function assistantTextEntriesFromEvents(events) {
         const messageId = typeof data.messageId === "string" ? data.messageId : undefined;
         if (messageId !== undefined)
             entry.messageId = messageId;
-        if (typeof event.seq === "number")
-            entry.seq = event.seq;
-        const recordedAt = typeof event.recordedAt === "string" ? event.recordedAt : undefined;
-        if (recordedAt !== undefined)
-            entry.recordedAt = recordedAt;
+        if (typeof event.sequence === "number")
+            entry.seq = event.sequence;
+        if (typeof event.time === "string")
+            entry.recordedAt = event.time;
         out.push(entry);
     }
     return out;
@@ -641,10 +902,10 @@ function toolCallsFromEvents(events) {
             const messageId = typeof data.messageId === "string" ? data.messageId : undefined;
             if (messageId !== undefined)
                 trace.messageId = messageId;
-            if (typeof event.seq === "number")
-                trace.startSeq = event.seq;
-            if (typeof event.recordedAt === "string")
-                trace.startedAt = event.recordedAt;
+            if (typeof event.sequence === "number")
+                trace.startSeq = event.sequence;
+            if (typeof event.time === "string")
+                trace.startedAt = event.time;
             if (!byId.has(id))
                 order.push(id);
             byId.set(id, trace);
@@ -658,10 +919,10 @@ function toolCallsFromEvents(events) {
                 isError: data.isError === true,
                 content: data.content ?? null
             };
-            if (typeof event.seq === "number")
-                result.seq = event.seq;
-            if (typeof event.recordedAt === "string")
-                result.recordedAt = event.recordedAt;
+            if (typeof event.sequence === "number")
+                result.seq = event.sequence;
+            if (typeof event.time === "string")
+                result.recordedAt = event.time;
             let trace = byId.get(id);
             if (trace === undefined) {
                 trace = { id, name: "", args: {} };
@@ -676,10 +937,6 @@ function toolCallsFromEvents(events) {
     }
     return order.map((id) => byId.get(id));
 }
-/** True when a usage summary actually carries at least one token count. */
-function hasUsageCounts(usage) {
-    return !!usage && Object.values(usage).some((n) => typeof n === "number");
-}
 function usageFromEvents(events) {
     const totals = { inputTokens: 0, outputTokens: 0, cacheReadInputTokens: 0, cacheCreationInputTokens: 0 };
     let seen = false;
@@ -734,14 +991,43 @@ function durationMs(start, end) {
     const delta = b - a;
     return delta >= 0 ? delta : undefined;
 }
+const SESSION_TERMINAL_READS = new Set([
+    "succeeded",
+    "failed",
+    "timed_out",
+    "cancelled",
+    "idle",
+    "suspended",
+    "awaiting_approval"
+]);
+/** The CUSTOM `aex.session.<name>` terminal event names → the carried read. */
+const SESSION_TERMINAL_EVENT_READS = {
+    "aex.session.succeeded": "succeeded",
+    "aex.session.failed": "failed",
+    // Clean-cut: the bare `error` park is now `failed` (one terminal vocabulary).
+    "aex.session.error": "failed",
+    "aex.session.timed_out": "timed_out",
+    "aex.session.cancelled": "cancelled",
+    "aex.session.idle": "idle",
+    "aex.session.suspended": "suspended",
+    "aex.session.awaiting_approval": "awaiting_approval"
+};
+/** An explicit `data.value.outcome` a park/settle event may carry (the authoritative outcome). */
+function carriedOutcome(event) {
+    const value = event.data.value;
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const outcome = value.outcome;
+    return typeof outcome === "string" && SESSION_TERMINAL_READS.has(outcome)
+        ? outcome
+        : undefined;
+}
 function isSessionTurnTerminalEvent(event, turnSeq) {
     if (event.type === "RUN_FINISHED" || event.type === "RUN_ERROR") {
         return true;
     }
     const name = customName(event);
-    if (name !== "aex.session.idle" &&
-        name !== "aex.session.suspended" &&
-        name !== "aex.session.error") {
+    if (name === null || !(name in SESSION_TERMINAL_EVENT_READS)) {
         return false;
     }
     const value = event.data.value;
@@ -751,27 +1037,31 @@ function isSessionTurnTerminalEvent(event, turnSeq) {
     const eventTurnSeq = value.turnSeq;
     return typeof eventTurnSeq !== "number" || eventTurnSeq === 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.
+ */
 function terminalSessionStatusFromEvents(events, turnSeq) {
     for (let i = events.length - 1; i >= 0; i--) {
         const event = events[i];
         if (!isSessionTurnTerminalEvent(event, turnSeq))
             continue;
+        const carried = carriedOutcome(event);
+        if (carried !== undefined)
+            return carried;
         if (event.type === "RUN_ERROR")
-            return "error";
+            return "failed";
         if (event.type === "RUN_FINISHED")
-            return "idle";
+            return "succeeded";
         const name = customName(event);
-        if (name === "aex.session.idle")
-            return "idle";
-        if (name === "aex.session.suspended")
-            return "suspended";
-        if (name === "aex.session.error")
-            return "error";
+        if (name !== null && name in SESSION_TERMINAL_EVENT_READS)
+            return SESSION_TERMINAL_EVENT_READS[name];
     }
     return undefined;
 }
-function withTerminalSessionStatus(session, terminalStatus) {
-    if (terminalStatus === undefined || session.status === terminalStatus)
+function withTerminalSessionStatus(session, read) {
+    if (read === undefined || session.status === read)
         return session;
     if (session.status !== "creating" &&
         session.status !== "running" &&
@@ -779,7 +1069,108 @@ function withTerminalSessionStatus(session, terminalStatus) {
         session.status !== "cancelling") {
         return session;
     }
-    return { ...session, status: terminalStatus };
+    return { ...session, status: read };
+}
+/** Map a terminal READ to the 4-value {@link SessionTerminalOutcome} for the result `status`. */
+function readToOutcome(read) {
+    return read === "failed" || read === "timed_out" || read === "cancelled" ? read : "succeeded";
+}
+/** `true` for an OK terminal read (succeeded / resumable idle|suspended / held awaiting_approval). */
+function isTerminalReadOk(read) {
+    return read !== "failed" && read !== "timed_out" && read !== "cancelled";
+}
+/** Best-effort READ off a settled record when the events carried none. */
+function sessionRecordRead(session) {
+    const outcome = session.lastTurnOutcome;
+    if (outcome !== undefined && SESSION_TERMINAL_READS.has(outcome))
+        return outcome;
+    const status = session.status;
+    if (status === "idle" || status === "suspended" || status === "awaiting_approval")
+        return status;
+    if (status === "succeeded" || status === "failed" || status === "timed_out" || status === "cancelled")
+        return status;
+    if (status === "error")
+        return "failed";
+    return "succeeded";
+}
+/** The settle-written provider usage entries (the SINGLE token-usage source). */
+function providerUsageOf(record) {
+    const telemetry = record.costTelemetry;
+    return telemetry?.providerUsage;
+}
+/**
+ * The IMMEDIATE authoritative failure text — the terminal `RUN_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
+ * `sessionRecord.errorMessage` lands.
+ */
+function failureFromEvents(events) {
+    for (let i = events.length - 1; i >= 0; i--) {
+        const event = events[i];
+        if (event.type !== "RUN_ERROR")
+            continue;
+        const data = asRecord(event.data);
+        for (const key of ["failureMessage", "message", "error"]) {
+            const value = data[key];
+            if (typeof value === "string" && value.length > 0)
+                return value;
+        }
+    }
+    return undefined;
+}
+/** The typed schema-decode outcome from the terminal `aex.result.*` event, if any. */
+function outcomeFromEvents(events) {
+    for (let i = events.length - 1; i >= 0; i--) {
+        const event = events[i];
+        if (event.isResultDecoded()) {
+            const value = asRecord(event.data).value;
+            const decoded = value && typeof value === "object" && !Array.isArray(value) && "value" in value
+                ? value.value
+                : value;
+            return { kind: "decoded", value: decoded };
+        }
+        if (event.isResultRefused()) {
+            const payload = asRecord(asRecord(event.data).value);
+            const reason = payload.reason;
+            const detail = typeof payload.detail === "string" ? payload.detail : undefined;
+            return {
+                kind: "refused",
+                reason: reason === "schema_violation" || reason === "uncertain" || reason === "refused" ? reason : "refused",
+                ...(detail !== undefined ? { detail } : {})
+            };
+        }
+    }
+    return undefined;
+}
+/**
+ * Build the ONE unified settled turn result (shared by `session.send().done()`
+ * and `Aex.run`): the terminal outcome `status`, `ok`, `costUsd` (>= 0),
+ * `usage` (from `costTelemetry.providerUsage`), and event-first `error`.
+ */
+function settledTurnResult(sessionId, session, turn, events, outputs, messages, read) {
+    const effectiveRead = read ?? sessionRecordRead(session);
+    const status = readToOutcome(effectiveRead);
+    const ok = isTerminalReadOk(effectiveRead);
+    const usage = usageFromProviderUsage(providerUsageOf(session));
+    const costUsd = typeof session.costUsd === "number" ? session.costUsd : 0;
+    const error = failureFromEvents(events) ??
+        (!ok && typeof session.errorMessage === "string" && session.errorMessage ? session.errorMessage : undefined);
+    const outcome = outcomeFromEvents(events);
+    return {
+        sessionId,
+        session,
+        turn,
+        status,
+        ok,
+        costUsd,
+        usage,
+        ...(error !== undefined ? { error } : {}),
+        text: assistantTextFromEvents(events),
+        events,
+        outputs,
+        messages,
+        ...(outcome !== undefined ? { outcome } : {})
+    };
 }
 /**
  * Workspace AgentsMd admin operations exposed under `client.agentsMd`.
@@ -924,6 +1315,8 @@ 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;
@@ -932,6 +1325,12 @@ export class Aex {
             // missing credential too, instead of a bare Error slipping the taxonomy.
             throw new CredentialValidationError("Aex: apiKey is required");
         }
+        // Self-describing key ⇒ plane-aware routing, checked ZERO-network in the
+        // constructor: derive the baseUrl from the key's plane when omitted, and
+        // fail fast on a plane/baseUrl mismatch instead of a bare 401 after a full
+        // round-trip. An opaque/legacy key (no `aex_` shape) skips this and keeps
+        // the HttpClient default.
+        const baseUrl = resolveBaseUrlForKey(apiKey, resolved.baseUrl);
         // Wrap the transport fetch (the caller's override, or global `fetch`) with
         // the bounded-retry layer so every BFF request gets default resilience.
         // The raw `#fetch` below stays unwrapped for the direct-to-storage asset PUT
@@ -939,7 +1338,7 @@ export class Aex {
         const baseFetch = resolved.fetch ?? ((input, init) => fetch(input, init));
         const retryingFetch = withRetry(baseFetch, resolved.retry);
         this.#http = new HttpClient({
-            ...(resolved.baseUrl ? { baseUrl: resolved.baseUrl } : {}),
+            ...(baseUrl ? { baseUrl } : {}),
             apiKey,
             fetch: retryingFetch,
             // Opt-in local diagnostics: emit a redacted per-request trace to
@@ -955,6 +1354,7 @@ 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
@@ -982,6 +1382,21 @@ export class Aex {
             ...(this.#fetch ? { fetch: this.#fetch } : {})
         });
     }
+    /**
+     * Internal: materialize a LARGE draft (a `File.fromPath` over the streaming
+     * threshold) to the content store via the two-pass streaming multipart flow —
+     * hash the deterministic canonical-zip stream, presign by hash (dedup still
+     * short-circuits), then upload it in parts. Bounded memory (one entry + one
+     * part). NOT part of the public API.
+     */
+    async _uploadAssetStream(args) {
+        return uploadAssetMultipart({
+            http: this.#http,
+            drive: args.drive,
+            ...(args.contentType ? { contentType: args.contentType } : {}),
+            ...(this.#fetch ? { fetch: this.#fetch } : {})
+        });
+    }
     /**
      * Internal: upsert already-uploaded skill metadata into the workspace registry.
      * The bytes are staged through `_uploadAsset`; this call binds the content hash
@@ -1004,61 +1419,46 @@ export class Aex {
             assertNoLegacySessionFields(options, "Aex.run");
             const input = normaliseSessionInput(message, "Aex.run", "message");
             assertNoSessionSendSignal(stream, "Aex.run stream");
-            const streamOptions = {
+            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 } : {})
+                ...(opts.pingIntervalMs !== undefined ? { pingIntervalMs: opts.pingIntervalMs } : {}),
+                // run()/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).
-            const createKey = createOptions.idempotencyKey ?? generateIdempotencyKey();
-            const messageKey = messageIdempotencyKey ?? deriveMessageKey(createKey);
+            const createKey = operations.resolveIdempotencyKey(createOptions.idempotencyKey);
+            const messageKey = messageIdempotencyKey !== undefined ? operations.resolveIdempotencyKey(messageIdempotencyKey) : deriveMessageKey(createKey);
             const session = await this.sessions.create({ ...createOptions, idempotencyKey: createKey });
-            const turnResult = await sendSessionInternal(session, input, {
-                ...streamOptions,
-                idempotencyKey: messageKey
-            }).done();
+            // 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).
+            let turnResult;
+            try {
+                turnResult = await sendSessionInternal(session, input, { ...sendOptions, idempotencyKey: messageKey }).done();
+            }
+            catch (err) {
+                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 ` +
+                        `continues server-side — cancel via session.cancel() or resume with openSession(${JSON.stringify(session.id)})`);
+                }
+                throw err;
+            }
             const runId = turnResult.sessionId;
-            // Settle-consistent enrichment (opt-in): the park EVENT that ends the
-            // stream lands tens of seconds BEFORE the settle write that flips the
-            // record and stamps costTelemetry/costUsd, so an immediate read misses
-            // the showback on virtually every fresh run. `settleConsistent: true`
-            // polls for the parked RECORD (bounded; degrades to the immediate read).
-            const settledRecord = opts.settleConsistent === true
-                ? await settledSessionRecord(this.#http, runId, turnResult.session, scopedSignal?.signal)
-                : undefined;
-            const sessionRecord = settledRecord ?? turnResult.session;
             if (deleteAfter) {
                 await session.delete();
             }
+            const sessionRecord = turnResult.session;
             const run = sessionToRun(sessionRecord);
-            const events = turnResult.events;
-            const outputs = turnResult.outputs;
-            const ok = turnResult.status === "idle" || turnResult.status === "suspended";
-            if (!ok && scopedSignal?.signal.aborted) {
-                // The client-side wait budget (opts.timeoutMs) expired before the run
-                // reached a terminal park. Parity with SessionHandle.wait(): THROW rather
-                // than silently returning a misleading {ok:false,status:"running"} with no
-                // error (pre-launch edge-sweep F3). The run continues server-side.
-                throw new RunStateError(`Aex.run: timed out after ${opts.timeoutMs}ms waiting for run ${runId} to park (last status ` +
-                    `${JSON.stringify(turnResult.status)}); the run continues server-side — cancel via ` +
-                    `session.cancel() or resume with openSession(${JSON.stringify(runId)})`);
-            }
-            const trace = runTraceFromEvents(events);
-            // Surface the trace-derived usage at the top level when the run record does
-            // not carry its own usage (the managed plane doesn't populate session.usage);
-            // the per-event trace still yields token counts (pre-launch edge-sweep F5).
-            // When NEITHER source carries token counts (trace usage is `{}` — the
-            // managed plane emits no `aex.usage` events today), leave `usage` absent so
-            // `result.usage` honors its "when the deployment exposes it" contract
-            // instead of surfacing a truthy-but-empty object.
-            const recordUsage = hasUsageCounts(sessionRecord.usage) ? sessionRecord.usage : undefined;
-            const usage = recordUsage ?? (hasUsageCounts(trace.usage) ? trace.usage : undefined);
-            const costUsd = typeof sessionRecord.costUsd === "number" ? sessionRecord.costUsd : undefined;
-            const errorMessage = typeof sessionRecord.errorMessage === "string" && sessionRecord.errorMessage ? sessionRecord.errorMessage : undefined;
+            const trace = runTraceFromEvents(turnResult.events);
+            const outcome = turnResult.outcome;
             const result = {
                 runId,
                 run,
@@ -1066,17 +1466,18 @@ export class Aex {
                 session: sessionRecord,
                 turn: turnResult.turn,
                 status: turnResult.status,
-                ok,
+                ok: turnResult.ok,
+                costUsd: turnResult.costUsd,
+                usage: turnResult.usage,
                 text: turnResult.text,
                 messages: turnResult.messages,
-                events,
+                events: turnResult.events,
                 trace,
-                outputs,
-                ...(usage ? { usage } : {}),
-                ...(typeof costUsd === "number" ? { costUsd } : {}),
-                ...(!ok && errorMessage ? { error: errorMessage } : {})
+                outputs: turnResult.outputs,
+                ...(turnResult.error !== undefined ? { error: turnResult.error } : {}),
+                ...(outcome !== undefined ? { outcome } : {})
             };
-            if (opts.throwOnFailure && !ok) {
+            if (opts.throwOnFailure && !turnResult.ok) {
                 // A turn that failed because the upstream provider throttled us surfaces
                 // as a structured, non-leaky AexRateLimitError carrying the provider
                 // fault, so callers can branch on `isRateLimited(err)` and replay.
@@ -1090,7 +1491,7 @@ export class Aex {
                         ...(throttle.retryAfterMs !== undefined ? { retryAfterMs: throttle.retryAfterMs } : {})
                     });
                 }
-                throw new RunStateError(`Aex.run: session ${runId} ended ${turnResult.status}${errorMessage ? `: ${errorMessage}` : ""}`, { runId, status: turnResult.status });
+                throw new RunStateError(`Aex.run: session ${runId} ended ${turnResult.status}${turnResult.error ? `: ${turnResult.error}` : ""}`, { runId, status: turnResult.status });
             }
             return result;
         }
@@ -1098,6 +1499,49 @@ export class Aex {
             scopedSignal?.clear();
         }
     }
+    /**
+     * 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)`.
+     */
+    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 }, {
+            idempotencyKey: operations.resolveIdempotencyKey(createOptions.idempotencyKey),
+            ...(messageIdempotencyKey !== undefined ? { messageIdempotencyKey } : {})
+        });
+        return { runId, session: new SessionHandle(this.#http, session, this.#fetch) };
+    }
+    /**
+     * Run 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
+     * 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");
+        }
+        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);
+            return {
+                runId: result.runId,
+                status: result.status,
+                ok: result.ok,
+                costUsd: result.costUsd,
+                usage: result.usage,
+                ...(result.error !== undefined ? { error: result.error } : {}),
+                ...(result.outcome !== undefined ? { outcome: result.outcome } : {})
+            };
+        }));
+        return rollupBatch(results);
+    }
     openSession(optionsOrId) {
         return typeof optionsOrId === "string"
             ? this.sessions.open(optionsOrId)
@@ -1116,31 +1560,33 @@ export class Aex {
             throw new RunConfigValidationError("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.");
         }
-        const supportedProviders = providersForModel(options.model);
-        if (options.provider &&
-            supportedProviders.length > 0 &&
-            !supportedProviders.includes(options.provider)) {
-            throw new RunConfigValidationError(`Aex.openSession: provider ${JSON.stringify(options.provider)} is not available for ` +
-                `model ${JSON.stringify(options.model)} (supported: ${supportedProviders.join(", ")})`);
+        // Model is REQUIRED and checked BEFORE the provider key, so omitting `model`
+        // reports "model is required" rather than a misleading provider-key message.
+        if (typeof options.model !== "string" || !options.model) {
+            throw configError("Aex.openSession", "model", "model is required");
+        }
+        // One model→provider resolver (SSoT), shared with the CLI: it honors an
+        // explicit provider (forward-compat: an unknown model is allowed through so a
+        // slightly-old SDK can still run a newly-launched model), infers the default
+        // provider for a known model, and — for an UNKNOWN model with no provider —
+        // throws a shared `did you mean?` suggestion.
+        let provider;
+        try {
+            provider = resolveModelProvider(options.model, options.provider);
         }
-        const provider = options.provider ?? supportedProviders[0] ?? DEFAULT_RUN_PROVIDER;
-        if (options.provider === undefined &&
-            supportedProviders.length === 0 &&
-            typeof options.model === "string" &&
-            options.model.length > 0 &&
-            (typeof options.apiKeys?.[provider] !== "string" || options.apiKeys[provider].length === 0)) {
-            // Unknown model with no explicit provider: the DEFAULT_RUN_PROVIDER
-            // fallback exists for forward-compat with models added server-side, but
-            // without a key for that default the generic missing-key error below
-            // would point at the wrong problem (e.g. "pass apiKeys[\"anthropic\"]"
-            // when the caller mistyped a deepseek model id). Name the real issue.
-            throw new RunConfigValidationError(`Aex.openSession: model ${JSON.stringify(options.model)} is not a known model id, so its provider ` +
-                `cannot be inferred — pass provider explicitly (with a matching apiKeys entry) to run a model ` +
-                `this SDK version does not know about.`);
+        catch (err) {
+            throw configError("Aex.openSession", options.provider === undefined ? "model" : "provider", err instanceof Error ? err.message : String(err), options.provider ?? options.model);
         }
         validateApiKeys(options.apiKeys, provider, "Aex.openSession");
-        if (typeof options.model !== "string" || !options.model) {
-            throw new RunConfigValidationError("Aex.openSession: model is required");
+        // WS9 fail-closed: `outputMode:'stream'` on a NON-streamable provider is a
+        // hard reject at the earliest seam (no silent downgrade to buffered).
+        if (options.outputMode !== undefined) {
+            try {
+                assertStreamableOutputMode(options.outputMode, provider);
+            }
+            catch (err) {
+                throw configError("Aex.openSession", "outputMode", err instanceof Error ? err.message : String(err), options.outputMode);
+            }
         }
         // Fast client-side validation via the contract parsers (the SSoT). runtimeSize
         // and timeout are STABLE closed sets whose invalid values the create endpoint
@@ -1161,22 +1607,28 @@ export class Aex {
         }
         const { declarations: secretEnvDeclarations, values: envSecretValues } = splitSecretEnv(options.environment?.secrets);
         let limits;
+        const limitsInput = {};
+        if (options.overrides?.maxSpendUsd !== undefined)
+            limitsInput.maxSpendUsd = options.overrides.maxSpendUsd;
+        if (options.overrides?.maxTurns !== undefined)
+            limitsInput.maxTurns = options.overrides.maxTurns;
         try {
-            limits = parseRunLimits(options.overrides?.maxSpendUsd === undefined
-                ? undefined
-                : { maxSpendUsd: options.overrides.maxSpendUsd });
+            limits = parseRunLimits(Object.keys(limitsInput).length > 0 ? limitsInput : undefined);
         }
         catch (err) {
-            throw new AexError("RUN_CONFIG_INVALID", `Aex.openSession: ${err instanceof Error ? err.message : String(err)}`);
+            // One `configError` factory for every client-side validation throw, so
+            // maxSpendUsd/maxTurns are `RunConfigValidationError` (not a base AexError).
+            throw configError("Aex.openSession", "limits", err instanceof Error ? err.message : String(err));
         }
         const uploader = (args) => this._uploadAsset(args);
+        const streamUploader = (args) => this._uploadAssetStream(args);
         // The four prepare passes touch disjoint instance sets, so run them
         // concurrently; each internally uploads its drafts with bounded concurrency.
         const [preparedTools, preparedSkills, preparedAgentsMd, preparedFiles] = await Promise.all([
             prepareTools(options.tools ?? [], uploader),
             prepareSkills(options.skills ?? [], this),
             prepareAgentsMd(options.agentsMd ?? [], uploader),
-            prepareFiles(options.files ?? [], uploader)
+            prepareFiles(options.files ?? [], uploader, streamUploader)
         ]);
         const { submissionMcpServers, mergedMcpSecrets } = mergeMcpServers(options.mcpServers ?? [], []);
         const outputCapture = outputsForWire(options.outputs);
@@ -1201,7 +1653,9 @@ export class Aex {
             ...(options.includeBuiltinTools !== undefined
                 ? { includeBuiltinTools: options.includeBuiltinTools }
                 : {}),
-            ...(options.outputMode !== undefined ? { outputMode: options.outputMode } : {})
+            ...(options.outputMode !== undefined ? { outputMode: options.outputMode } : {}),
+            ...(options.responseFormat !== undefined ? { responseFormat: options.responseFormat } : {}),
+            ...(options.approvalGate !== undefined ? { approvalGate: options.approvalGate } : {})
         };
         const secrets = {
             ...(options.apiKeys ? { apiKeys: options.apiKeys } : {}),
@@ -1277,6 +1731,35 @@ export class Aex {
         return operations.getWebhookSigningSecret(this.#http);
     }
 }
+/**
+ * Resolve the effective `baseUrl` from a self-describing API key (ZERO-network):
+ *   - key omitted-of-shape (opaque/legacy): return the caller's `baseUrl`
+ *     unchanged (HttpClient falls back to the prd default).
+ *   - `baseUrl` omitted: DERIVE it from the key's plane; a plane with no default
+ *     host (dev) requires an explicit `baseUrl` — throw with that guidance.
+ *   - `baseUrl` supplied but its plane DISAGREES with the key's plane: throw
+ *     {@link CredentialValidationError} BEFORE any request (the exact `dev key
+ *     against the prd default → bare token_invalid` trap).
+ */
+function resolveBaseUrlForKey(apiKey, baseUrl) {
+    const parsed = parseApiKey(apiKey);
+    if (parsed === null)
+        return baseUrl;
+    const planeUrl = PLANE_BASE_URLS[parsed.plane];
+    if (baseUrl === undefined) {
+        if (planeUrl === null) {
+            throw new CredentialValidationError(`Aex: this API key is for the ${parsed.plane} plane, which has no default host — pass baseUrl explicitly.`, { plane: parsed.plane });
+        }
+        return planeUrl;
+    }
+    // The only client-detectable mismatch: a non-prd key pointed at the canonical
+    // prd host (dev has no canonical host to compare a prd key against).
+    if (baseUrl === PLANE_BASE_URLS.prd && parsed.plane !== "prd") {
+        throw new CredentialValidationError(`Aex: this API key is for the ${parsed.plane} plane but baseUrl targets the prd plane (${PLANE_BASE_URLS.prd}) — ` +
+            `pass the ${parsed.plane} plane baseUrl, or omit baseUrl to auto-route.`, { plane: parsed.plane, baseUrl });
+    }
+    return baseUrl;
+}
 // `Run.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).
@@ -1289,21 +1772,33 @@ const SETTLE_POLL_DEADLINE_MS = 60_000;
 /** Interval between settle-poll reads (ms). */
 const SETTLE_POLL_INTERVAL_MS = 750;
 /**
- * Poll for the session RECORD to reach a parked status — i.e. for the settle
- * write (which also stamps `costUsd`/`usage`/`errorMessage`) to land. Returns
- * the settled record, or `undefined` on timeout/abort/read-failure so the
- * caller can fall back to the record it already holds. The first read is
+ * A settle marker on a record: the settle commit stamps `settledAt` (and always
+ * `costUsd`, default 0) plus the terminal outcome / cost telemetry. The SAME
+ * predicate gates the early-return and the loop-return so a $0 turn (costUsd:0
+ * present) resolves as settled — never a hang, never an undefined cost.
+ */
+function isSettledRecord(record) {
+    if (!isSessionParked(record.status))
+        return false;
+    return (record.settledAt !== undefined ||
+        typeof record.costUsd === "number" ||
+        record.lastTurnOutcome !== undefined ||
+        providerUsageOf(record) !== undefined);
+}
+/**
+ * Poll for the session RECORD to reach a SETTLED state — i.e. for the settle
+ * write (which stamps `settledAt` + `costUsd` + the terminal outcome) to land.
+ * Returns the settled record, or `undefined` on timeout/abort/read-failure so
+ * the caller can fall back to the record it already holds. The first read is
  * immediate, so a fast settle costs one extra GET and no added latency.
  */
 async function settledSessionRecord(http, sessionId, lastSeen, signal) {
-    // `lastSeen.status` may be client-side patched (withTerminalSessionStatus), so
-    // only trust it when it is parked AND already carries the settle-stamped cost.
-    if (isSessionParked(lastSeen.status) && typeof lastSeen.costUsd === "number")
+    if (isSettledRecord(lastSeen))
         return lastSeen;
     const deadline = Date.now() + SETTLE_POLL_DEADLINE_MS;
     while (signal?.aborted !== true && Date.now() < deadline) {
         const record = await operations.getSession(http, sessionId).catch(() => undefined);
-        if (record !== undefined && isSessionParked(record.status))
+        if (record !== undefined && isSettledRecord(record))
             return record;
         try {
             await sleep(SETTLE_POLL_INTERVAL_MS, signal);
@@ -1314,6 +1809,28 @@ async function settledSessionRecord(http, sessionId, lastSeen, signal) {
     }
     return undefined;
 }
+/**
+ * How long a follow-up `send()` waits for the session RECORD to catch up after
+ * our own turn parked idle before treating the `session_busy` as a genuinely
+ * in-flight turn (ms). The idle park EVENT ends the turn stream, but the record
+ * commit lags briefly behind it.
+ */
+const SESSION_BUSY_RECONCILE_DEADLINE_MS = 30_000;
+/** Interval between record reads while reconciling a settle-lag `session_busy` (ms). */
+const SESSION_BUSY_RECONCILE_INTERVAL_MS = 500;
+/**
+ * A 409 `session_busy` whose CURRENT status is `running` — the one case that is
+ * transient: the platform is still catching up from our own just-parked turn.
+ * The 409 body carries `{ error:"session_busy", status:<current> }`; any other
+ * busy status (suspended / cancelling / deleted) is a real, non-retryable
+ * rejection that must surface immediately.
+ */
+function isSettlingSessionBusy(err) {
+    if (!(err instanceof AexApiError) || err.status !== 409)
+        return false;
+    const body = asRecord(err.body);
+    return body.error === "session_busy" && body.status === "running";
+}
 /**
  * A session is "parked" once it stops making progress: it reached one of the
  * turn-terminal statuses (`idle` / `suspended` / `error`) or a terminal run
@@ -1322,6 +1839,7 @@ async function settledSessionRecord(http, sessionId, lastSeen, signal) {
 function isSessionParked(status) {
     return (status === "idle" ||
         status === "suspended" ||
+        status === "awaiting_approval" ||
         status === "error" ||
         status === "deleted" ||
         status === "expired" ||
@@ -1352,49 +1870,6 @@ function scopedAbortSignal(timeoutMs) {
         }
     };
 }
-/** Escape a literal string for safe interpolation into a RegExp. */
-function escapeRegExp(input) {
-    return input.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-function isOutputPathSelector(selector) {
-    return Boolean(selector && typeof selector === "object" && "path" in selector);
-}
-function resolveOutputFileSelector(outputs, selector, runId) {
-    if (isOutputPathSelector(selector)) {
-        const target = normalizeOutputLookupPath(selector.path);
-        if (!target) {
-            throw new RunStateError("Aex.downloadOutput: output path must be non-empty", {
-                runId,
-                path: selector.path
-            });
-        }
-        const matches = outputs.filter((output) => {
-            if (typeof output.filename !== "string")
-                return false;
-            const filename = normalizeOutputLookupPath(output.filename);
-            if (selector.match === "suffix") {
-                return filename === target || filename.endsWith(`/${target}`);
-            }
-            return filename === target;
-        });
-        if (matches.length === 1)
-            return matches[0];
-        if (matches.length > 1) {
-            throw new RunStateError(`Aex.downloadOutput: output path "${selector.path}" matched multiple files`, { runId, path: selector.path, matches: matches.map((output) => output.filename ?? output.id) });
-        }
-        throw new RunStateError(`Aex.downloadOutput: output path "${selector.path}" was not found`, {
-            runId,
-            path: selector.path
-        });
-    }
-    if (typeof selector.id !== "string" || selector.id.length === 0) {
-        throw new RunStateError("Aex.downloadOutput: selector must include an output id or path", { runId });
-    }
-    return { ...selector, id: selector.id };
-}
-function normalizeOutputLookupPath(path) {
-    return path.replace(/\\/g, "/").replace(/^\/+/, "");
-}
 async function writeOptionalFile(bytes, to) {
     if (to !== undefined) {
         const { writeFile } = await import("node:fs/promises");
@@ -1419,11 +1894,13 @@ function sleep(ms, signal) {
         signal?.addEventListener("abort", onAbort, { once: true });
     });
 }
-function generateIdempotencyKey() {
-    const cryptoObj = globalThis.crypto;
-    if (cryptoObj?.randomUUID)
-        return cryptoObj.randomUUID();
-    return `idem-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+/**
+ * ONE factory for every client-side validation throw: a
+ * {@link RunConfigValidationError} 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 });
 }
 /**
  * Derive the message idempotency key from the session-create key. Mirrors the
@@ -1478,7 +1955,7 @@ function normaliseSessionInput(input, surface, field) {
 }
 function assertNoLegacySessionFields(options, surface) {
     const record = options;
-    const removedProxyField = "proxy" + "Endpoints";
+    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.",
@@ -1489,9 +1966,9 @@ function assertNoLegacySessionFields(options, surface) {
         secretEnv: "use environment.secrets.",
         secrets: "use top-level apiKeys for provider keys and environment.secrets for run secrets.",
         runtimeSize: "use runtime.",
-        parentRunId: "subagents are session-internal; parentRunId is not part of the session API.",
         limits: "use overrides.",
         timeout: "use overrides.timeout.",
+        parentRunId: "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."
@@ -1701,13 +2178,24 @@ async function prepareAgentsMd(agentsMds, uploader) {
     });
 }
 /** Walk File[], eagerly upload drafts as assets (bounded concurrency), and return plain asset refs. */
-async function prepareFiles(files, 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`);
         }
         const ref = entry.ref;
         if (ref.kind === "draft") {
+            // A large draft carries a streaming driver instead of in-memory bytes.
+            const stream = entry._takeDraftStream();
+            if (stream) {
+                const cached = entry._cachedAssetId;
+                if (cached !== undefined) {
+                    return { kind: "asset", assetId: cached, name: stream.name, mountPath: stream.mountPath };
+                }
+                const uploaded = await streamUploader({ drive: stream.drive, contentType: "application/zip" });
+                entry._rememberAsset(uploaded.assetId);
+                return { kind: "asset", assetId: uploaded.assetId, name: stream.name, mountPath: stream.mountPath };
+            }
             const bundle = entry._takeDraftBundle();
             if (!bundle) {
                 throw new RunConfigValidationError(`aex: files[${i}] is draft but has no bytes`);