@aexhq/sdk 0.33.1 → 0.35.0

package/dist/client.js

@@ -1,11 +1,12 @@
-import { AexError, DEFAULT_RUN_PROVIDER, HttpClient, RunConfigValidationError, RunStateError, SecretString, customName, isRunSettled, operations, providersForModel, streamCoordinatorEvents, summarizeRunTrace, textOf, parseRunLimits, BUILTIN_TOOL_NAMES, TERMINAL_RUN_STATUSES } from "./_contracts/index.js";
+import { AexError, DEFAULT_RUN_PROVIDER, HttpClient, RunConfigValidationError, RunStateError, SecretString, customName, isRunSettled, operations, providersForModel, streamCoordinatorEvents, decodeAssistantText, summarizeRunTrace, textOf, parseRunLimits, BUILTIN_TOOL_NAMES, TERMINAL_RUN_STATUSES } from "./_contracts/index.js";
 import { AgentsMd } from "./agents-md.js";
 import { uploadAsset } from "./asset-upload.js";
 import { File } from "./file.js";
 import { McpServer } from "./mcp-server.js";
 import { splitProxyEndpoints } from "./proxy-endpoint.js";
+import { AexRateLimitError, isThrottleFault, parseProviderFault, withRetry } from "./retry.js";
 import { splitSecretEnv } from "./secret.js";
-import { Skill } from "./skill.js";
+import { SkillTool } from "./skill-tool.js";
 import { Tool } from "./tool.js";
 export class SessionTurnStream {
     #run;
@@ -28,7 +29,6 @@ export class SessionTurnStream {
         return this.#done;
     }
 }
-export const ChatTurnStream = SessionTurnStream;
 const internalSessionSenders = new WeakMap();
 function sendSessionInternal(session, input, options = {}) {
     const sender = internalSessionSenders.get(session);
@@ -39,10 +39,14 @@ function sendSessionInternal(session, input, options = {}) {
 }
 export class SessionHandle {
     #http;
+    #fetch;
     #session;
-    constructor(http, session) {
+    /** The last message sent on this handle, for {@link SessionHandle.replayLast}. */
+    #lastSend;
+    constructor(http, session, fetch) {
         this.#http = http;
         this.#session = session;
+        this.#fetch = fetch;
         internalSessionSenders.set(this, (input, options = {}) => new SessionTurnStream(() => this.#send(input, options)));
     }
     get id() {
@@ -55,8 +59,28 @@ export class SessionHandle {
         assertNoSessionSendSignal(options, "SessionHandle.send");
         return sendSessionInternal(this, input, options);
     }
+    /**
+     * Re-send the last message on this session — the clean way to retry a turn a
+     * throttle or transient failure interrupted. By default it REUSES the previous
+     * message's idempotency key, so if the original turn actually landed
+     * server-side the replay de-duplicates instead of creating a second billable
+     * turn; pass a fresh `idempotencyKey` to force a brand-new turn.
+     */
+    replayLast(options = {}) {
+        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");
+        }
+        return sendSessionInternal(this, last.input, {
+            ...options,
+            idempotencyKey: options.idempotencyKey ?? last.idempotencyKey
+        });
+    }
     async *#send(input, options) {
-        const accepted = await operations.sendSessionMessage(this.#http, this.id, { input }, { idempotencyKey: options.idempotencyKey ?? generateIdempotencyKey() });
+        const idempotencyKey = options.idempotencyKey ?? generateIdempotencyKey();
+        this.#lastSend = { input, idempotencyKey };
+        const accepted = await operations.sendSessionMessage(this.#http, this.id, { input }, { idempotencyKey });
         this.#session = accepted.session;
         const turn = accepted.turn;
         const events = [];
@@ -102,28 +126,128 @@ export class SessionHandle {
             this.#session = accepted.session;
         }
     }
-    listEvents() {
-        return operations.listSessionEvents(this.#http, this.id);
+    /**
+     * Accessor for the session's decoded assistant messages (buffered output
+     * mode: one entry per assistant message). `list()` returns them oldest-first;
+     * `last()`/`first()` return a single entry or `undefined` when empty.
+     */
+    messages() {
+        const http = this.#http;
+        const id = this.id;
+        const list = async () => decodeAssistantText((await operations.listSessionEvents(http, id)));
+        return {
+            list,
+            last: async () => (await list()).at(-1),
+            first: async () => (await list())[0]
+        };
     }
-    listOutputs(query) {
-        return operations.listSessionOutputs(this.#http, this.id, query);
+    /**
+     * Accessor for the session's event stream: the buffered `SessionEvent`
+     * snapshots (`list`/`last`/`first`), the polling `RunEvent` 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);
+        return {
+            list,
+            last: async () => (await list()).at(-1),
+            first: async () => (await list())[0],
+            stream: (options) => streamSessionEventsPolling(http, id, options ?? {}),
+            streamEnvelopes: (options) => streamSessionEnvelopes(http, id, options ?? {}),
+            archiveLink: (options) => operations.eventArchiveLink(http, id, options),
+            download: async (options) => writeOptionalFile(await operations.downloadEvents(http, id), options?.to)
+        };
+    }
+    /**
+     * Accessor for the session's captured output 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
+     * zip (no selector) or one file's raw bytes (with selector).
+     */
+    outputs() {
+        return sessionOutputs(this.#http, this.id, this.#fetch);
+    }
+    /**
+     * Accessor for the session's webhook delivery ledger: `list()` returns the
+     * delivery attempts; `redeliver(id)` re-sends the frozen payload under the
+     * same `webhook-id` so the consumer dedupes.
+     */
+    webhooks() {
+        const http = this.#http;
+        const id = this.id;
+        return {
+            list: () => operations.getRunWebhookDeliveries(http, id),
+            redeliver: (deliveryId) => operations.redeliverRunWebhook(http, id, deliveryId)
+        };
+    }
+    /** Re-read the session record from the server and store it as the current record. */
+    async refresh() {
+        this.#session = await operations.getSession(this.#http, this.id);
+        return this.#session;
+    }
+    /**
+     * Poll the session record until it reaches a parked/terminal status (idle,
+     * suspended, error, or any terminal run status). Throws if `timeoutMs`
+     * elapses first. Updates the stored record.
+     */
+    async wait(options = {}) {
+        const intervalMs = options.intervalMs ?? 1_500;
+        const timeoutMs = options.timeoutMs;
+        const signal = options.signal;
+        const deadline = typeof timeoutMs === "number" ? Date.now() + timeoutMs : Number.POSITIVE_INFINITY;
+        while (!signal?.aborted) {
+            const session = await operations.getSession(this.#http, this.id);
+            this.#session = session;
+            if (isSessionParked(session.status))
+                return session;
+            if (Date.now() >= deadline) {
+                throw new Error(`SessionHandle.wait: timeout after ${timeoutMs}ms`);
+            }
+            await sleep(intervalMs, signal);
+        }
+        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
+     * resolved skills. Use this when you need fields beyond the session record.
+     */
+    unit() {
+        return operations.getRunUnit(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
+     * also write the bytes to a file path while still returning them.
+     */
+    async download(options) {
+        return writeOptionalFile(await operations.download(this.#http, this.id), options?.to);
+    }
+    /** Download only the session record (the `metadata` namespace) as a zip. */
+    async downloadMetadata(options) {
+        return writeOptionalFile(await operations.downloadMetadata(this.#http, this.id), options?.to);
     }
 }
-export const ChatSession = SessionHandle;
 export class SessionClient {
     #http;
+    #fetch;
     #buildCreateRequest;
-    constructor(http, buildCreateRequest) {
+    constructor(http, buildCreateRequest, fetch) {
         this.#http = http;
         this.#buildCreateRequest = buildCreateRequest;
+        this.#fetch = fetch;
     }
     async create(options) {
         const request = await this.#buildCreateRequest(options);
         const session = await operations.createSession(this.#http, request, { idempotencyKey: options.idempotencyKey ?? generateIdempotencyKey() });
-        return new SessionHandle(this.#http, session);
+        return new SessionHandle(this.#http, session, this.#fetch);
     }
     async open(sessionId) {
-        return new SessionHandle(this.#http, await operations.getSession(this.#http, sessionId));
+        return new SessionHandle(this.#http, await operations.getSession(this.#http, sessionId), this.#fetch);
     }
     get(sessionId) {
         return operations.getSession(this.#http, sessionId);
@@ -131,14 +255,86 @@ export class SessionClient {
     list(query) {
         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()` /
+     * `.read(selector)` / `.download()` / … — so the workspace client and the
+     * live handle share one accessor convention.
+     */
+    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 = {}) {
+        const sessionIds = query.runIds ?? (await this.#allSessionIds());
+        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) {
+            const outputs = hasFilter
+                ? await operations.listSessionOutputs(this.#http, sessionId, outputQuery)
+                : await operations.listSessionOutputs(this.#http, sessionId);
+            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 } : {})
+                });
+                if (hits.length >= limit)
+                    return { hits };
+            }
+        }
+        return { hits };
+    }
+    /** Enumerate every session id in the workspace by paging `listSessions`. */
+    async #allSessionIds() {
+        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");
+                }
+                seenCursors.add(cursor);
+            }
+            const page = await operations.listSessions(this.#http, cursor ? { cursor } : {});
+            for (const session of page.sessions)
+                ids.push(session.id);
+            cursor = page.nextCursor;
+        } 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");
-        const session = await this.create(createOptions);
+        // 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: messageIdempotencyKey ?? generateIdempotencyKey()
+            idempotencyKey: messageKey
         }).done();
         if (deleteAfter) {
             await session.delete();
@@ -146,7 +342,6 @@ export class SessionClient {
         return result;
     }
 }
-export const ChatClient = SessionClient;
 async function* streamSessionTurnEvents(http, sessionId, turn, options) {
     const first = await operations.getSessionCoordinatorTicket(http, sessionId);
     yield* streamCoordinatorEvents({
@@ -160,6 +355,98 @@ async function* streamSessionTurnEvents(http, sessionId, turn, options) {
         ...(options.pingIntervalMs !== undefined ? { pingIntervalMs: options.pingIntervalMs } : {})
     });
 }
+/**
+ * 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.
+ */
+async function* streamSessionEventsPolling(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 event;
+            }
+        }
+        const session = await operations.getSession(http, id);
+        if (isSessionParked(session.status))
+            return;
+        // `sleep` rejects on abort — treat that as a graceful stop.
+        try {
+            await sleep(intervalMs, signal);
+        }
+        catch {
+            return;
+        }
+    }
+}
+/**
+ * Stream the unified {@link AexEvent} envelope live over the session's
+ * coordinator WebSocket. The ticket is re-minted on each (re)connect so a long
+ * session never outlives it. Module-level so `SessionHandle.events()` can hand
+ * it to its accessor object literal.
+ */
+async function* streamSessionEnvelopes(http, id, options) {
+    const first = await operations.getSessionCoordinatorTicket(http, id);
+    yield* streamCoordinatorEvents({
+        wsUrl: first.wsUrl,
+        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.
+        ...(options.settleConsistent ? { isTerminal: isRunSettled } : {}),
+        ...(options.signal ? { signal: options.signal } : {})
+    });
+}
+/**
+ * Download captured deliverables. No selector → the full outputs namespace as a
+ * zip; a selector → one file's raw bytes. Module-level so
+ * `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());
+    }
+    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
+ * convention, one implementation.
+ */
+function sessionOutputs(http, id, fetchLike) {
+    const list = (query) => operations.listSessionOutputs(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),
+        link: (selectorOrQuery, options) => operations.outputLink(http, id, selectorOrQuery, options),
+        fetch: async (selectorOrQuery, options) => {
+            const link = await operations.outputLink(http, id, selectorOrQuery, options);
+            return (fetchLike ?? globalThis.fetch)(link.url);
+        },
+        download: (selector, options) => downloadSessionOutput(http, id, selector, options)
+    };
+}
 function isSessionTurnTerminalEvent(event, turnSeq) {
     const name = customName(event);
     if (name !== "aex.session.idle" &&
@@ -200,61 +487,12 @@ function withTerminalSessionStatus(session, terminalStatus) {
     }
     return { ...session, status: terminalStatus };
 }
-/**
- * Workspace skill admin operations exposed under `client.skills`.
- *
- * New run submissions usually use `Skill.fromFiles(...)` or
- * `Skill.fromPath(...)` directly inside `submit`; the SDK materializes
- * those bytes to the hosted asset store before the run lands. This namespace is the read/delete
- * surface for workspace skill records and the internal transport used by the
- * legacy CLI upload command.
- */
-export class SkillsClient {
-    #http;
-    constructor(http) {
-        this.#http = http;
-    }
-    list() {
-        return operations.listSkills(this.#http);
-    }
-    get(skillId) {
-        return operations.getSkill(this.#http, skillId);
-    }
-    delete(skillId) {
-        return operations.deleteSkill(this.#http, skillId);
-    }
-    /**
-     * Lookup a live workspace skill by `(name, contentHash)`.
-     *
-     * Returns the matching `Skill` record or `null` when no live row
-     * carries that hash. The `contentHash` is the wire format
-     * `sha256:<hex>` returned by `hashSkillBundle` (and stored verbatim
-     * on every skill row). The hash space is unique enough that one
-     * row at most can match, so this is a single keyed lookup.
-     *
-     * Consumers can call this directly when they already have a hash in hand
-     * and want to know whether the skill is already persisted.
-     */
-    findByHash(args) {
-        return operations.findSkillByHash(this.#http, args);
-    }
-    /**
-     * Lookup a live workspace skill by `name`. Returns the matching
-     * `Skill` record or `null` when no live row carries that name.
-     * Implemented as a list-and-filter against the existing `/api/skills`
-     * endpoint — typical workspace skill counts are small enough that
-     * the cost is negligible.
-     */
-    findByName(name) {
-        return operations.findSkillByName(this.#http, name);
-    }
-}
 /**
  * Workspace AgentsMd admin operations exposed under `client.agentsMd`.
  *
- * New run submissions usually use `AgentsMd.fromContent(...)` or
- * `AgentsMd.fromPath(...)` directly inside `submit`; the SDK
- * materializes those bytes to the hosted asset store before the run lands. This namespace is
+ * New sessions usually use `AgentsMd.fromContent(...)` or
+ * `AgentsMd.fromPath(...)` directly on `openSession` / `run`; the SDK
+ * materializes those bytes to the hosted asset store before the session starts. This namespace is
  * the read/delete surface for persisted AgentsMd records.
  */
 export class AgentsMdClient {
@@ -275,9 +513,9 @@ export class AgentsMdClient {
 /**
  * Workspace File admin operations exposed under `client.files`.
  *
- * New run submissions usually use `File.fromPath(...)` or
- * `File.fromBytes(...)` directly inside `submit`; the SDK materializes
- * those bytes to the hosted asset store before the run lands. This namespace is the read/delete
+ * New sessions usually use `File.fromPath(...)` or
+ * `File.fromBytes(...)` directly on `openSession` / `run`; the SDK materializes
+ * those bytes to the hosted asset store before the session starts. This namespace is the read/delete
  * surface for persisted file records.
  */
 export class FilesClient {
@@ -297,17 +535,16 @@ export class FilesClient {
 }
 /**
  * Workspace secret management exposed under `client.secrets`, mirroring
- * `client.skills` / `client.files`.
+ * `client.agentsMd` / `client.files`.
  *
- * Lifecycle parity with assets/skills: a `Secret.value(...)` is per-run and
+ * Lifecycle parity with assets: a `Secret.value(...)` is per-run and
  * gone at terminal; `set` (or promoting an ephemeral via `secret.upload`)
  * persists a named, searchable workspace secret you can `get` (metadata),
- * `get_value` (audited value), `rotate`, `list`, and `delete`. The identity is the
- * `name`; the value rotates under that stable name.
+ * `rotate`, `list`, and `delete`. The identity is the `name`; the value rotates
+ * under that stable name.
  *
- * Values are write-only: `set`/`rotate` send the value in the request BODY (never
- * the URL); `get`/`list` return metadata only; `get_value` is the explicit audited
- * value read.
+ * Values are write-only through the public SDK: `set`/`rotate` send the value in
+ * the request BODY (never the URL); `get`/`list` return metadata only.
  */
 export class SecretsClient {
     #http;
@@ -326,10 +563,6 @@ export class SecretsClient {
     get(name) {
         return operations.getSecret(this.#http, name);
     }
-    /** Audited value read — the preferred path that returns a workspace secret value. */
-    get_value(name) {
-        return operations.getSecretValue(this.#http, name);
-    }
     /** Replace the value of an existing workspace secret; bumps its version. */
     rotate(args) {
         return operations.rotateSecret(this.#http, { name: args.name, value: unwrapSecretValue(args.value) });
@@ -370,20 +603,24 @@ export class AgentExecutor {
     #http;
     /** The same fetch the HttpClient uses, threaded into `_uploadAsset`. */
     #fetch;
-    skills;
     agentsMd;
     files;
     secrets;
     sessions;
-    chat;
     constructor(options) {
         if (!options.apiToken) {
             throw new Error("AgentExecutor: apiToken is required");
         }
+        // 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
+        // and presigned output GETs, which target object storage, not the API plane.
+        const baseFetch = options.fetch ?? ((input, init) => fetch(input, init));
+        const retryingFetch = withRetry(baseFetch, options.retry);
         this.#http = new HttpClient({
             ...(options.baseUrl ? { baseUrl: options.baseUrl } : {}),
             apiToken: options.apiToken,
-            ...(options.fetch ? { fetch: options.fetch } : {}),
+            fetch: retryingFetch,
             // Opt-in local diagnostics: emit a redacted per-request trace to
             // stderr. Uploads nothing. A caller wanting a custom sink can pass
             // a function instead of `true`.
@@ -392,12 +629,10 @@ export class AgentExecutor {
                 : {})
         });
         this.#fetch = options.fetch;
-        this.skills = new SkillsClient(this.#http);
         this.agentsMd = new AgentsMdClient(this.#http);
         this.files = new FilesClient(this.#http);
         this.secrets = new SecretsClient(this.#http);
-        this.chat = new ChatClient(this.#http, (options) => this.#buildSessionCreateRequest(options));
-        this.sessions = this.chat;
+        this.sessions = new SessionClient(this.#http, (options) => this.#buildSessionCreateRequest(options), this.#fetch);
     }
     /**
      * Internal: satisfies the `SecretUploader` surface so a
@@ -410,9 +645,10 @@ export class AgentExecutor {
     }
     /**
      * Internal: materialize raw bytes to the content-addressable asset store
-     * (`/assets/presign` → PUT → `/assets/finalize`). Used by `Skill.upload(this)`
-     * to pre-upload a draft skill bundle so a later run carries only a plain
-     * `kind:"asset"` ref. NOT part of the public API.
+     * (`/assets/presign` → PUT → `/assets/finalize`). Used by the session-create
+     * prepare step to upload draft skill-tool / tool / agentsMd / file bundles so
+     * the wire submission carries only plain `kind:"asset"` / `kind:"skill"` refs.
+     * NOT part of the public API.
      */
     async _uploadAsset(args) {
         return uploadAsset({
@@ -444,10 +680,15 @@ export class AgentExecutor {
                 ...(opts.idleTimeoutMs !== undefined ? { idleTimeoutMs: opts.idleTimeoutMs } : {}),
                 ...(opts.pingIntervalMs !== undefined ? { pingIntervalMs: opts.pingIntervalMs } : {})
             };
-            const session = await this.sessions.create(createOptions);
+            // 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 session = await this.sessions.create({ ...createOptions, idempotencyKey: createKey });
             const turnResult = await sendSessionInternal(session, input, {
                 ...streamOptions,
-                idempotencyKey: messageIdempotencyKey ?? generateIdempotencyKey()
+                idempotencyKey: messageKey
             }).done();
             if (deleteAfter) {
                 await session.delete();
@@ -476,6 +717,19 @@ export class AgentExecutor {
                 ...(!ok && errorMessage ? { error: errorMessage } : {})
             };
             if (opts.throwOnFailure && !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.
+                const throttle = throttleFromSession(turnResult.session);
+                if (throttle) {
+                    throw new AexRateLimitError({
+                        status: throttle.status ?? 429,
+                        attempts: 1,
+                        source: "provider",
+                        providerFault: throttle,
+                        ...(throttle.retryAfterMs !== undefined ? { retryAfterMs: throttle.retryAfterMs } : {})
+                    });
+                }
                 throw new RunStateError(`AgentExecutor.run: session ${runId} ended ${turnResult.status}${errorMessage ? `: ${errorMessage}` : ""}`, { runId, status: turnResult.status });
             }
             return result;
@@ -484,183 +738,11 @@ export class AgentExecutor {
             scopedSignal?.clear();
         }
     }
-    /**
-     * Explicit, discoverable alias for {@link run}: open a one-shot session turn
-     * and collect the full {@link RunResult} in one call.
-     */
-    runAndCollect(options, opts) {
-        return this.run(options, opts);
-    }
     openSession(optionsOrId) {
         return typeof optionsOrId === "string"
             ? this.sessions.open(optionsOrId)
             : this.sessions.create(optionsOrId);
     }
-    /**
-     * Poll `listEvents` until the snapshot is settle-bracketed — both a
-     * RUN_STARTED and a terminal (RUN_FINISHED / RUN_ERROR) event present — then
-     * return it. The runner emits the terminal AG-UI event BEFORE the platform
-     * commits the record, and the `listEvents` snapshot can lag the terminal
-     * record by a beat; this closes that race so the decoded trace/text/outputs
-     * are complete. Bounded so an older runtime that never emits one of the
-     * brackets still returns the best snapshot available.
-     */
-    async #collectSettledEvents(runId, signal) {
-        const intervalMs = 500;
-        const maxAttempts = 20;
-        let latest = [];
-        for (let attempt = 0; attempt < maxAttempts; attempt++) {
-            if (signal?.aborted)
-                return latest;
-            latest = await this.listEvents(runId);
-            const hasStart = latest.some((event) => event.type === "RUN_STARTED");
-            const hasTerminal = latest.some((event) => event.type === "RUN_FINISHED" || event.type === "RUN_ERROR");
-            if (hasStart && hasTerminal)
-                return latest;
-            try {
-                await sleep(intervalMs, signal);
-            }
-            catch {
-                return latest;
-            }
-        }
-        return latest;
-    }
-    /**
-     * Submit a run and return its run id immediately. Use that id with
-     * `wait`, `stream`, `outputs`, `download`, `cancel`, or `delete`.
-     *
-     * The SDK splits `mcpServers[i].headers` into `secrets.mcpServers`
-     * and `proxyEndpoints[i]` auth values into `secrets.proxyEndpointAuth`
-     * before sending so credentials never enter the hashed submission or
-     * the run snapshot.
-     *
-     * Unstaged inline skills / agentsMd / files (`Skill.fromFiles` /
-     * `Skill.fromPath` / `AgentsMd.fromContent` / `File.fromBytes` without a
-     * prior `.upload`) are auto-uploaded to the content-addressable asset
-     * store (`/assets/presign` → PUT → `/assets/finalize`) before `POST /runs`,
-     * deduped by content hash, and referenced in the submission as plain
-     * `{ kind:"asset" }` refs — identical to a pre-staged `.upload(client)`.
-     */
-    async submit(options) {
-        if (!options || typeof options !== "object") {
-            throw new RunConfigValidationError("AgentExecutor.submit: options is required");
-        }
-        assertNoRemovedSubmitFields(options, "AgentExecutor.submit");
-        // A model maps to one or more upstream providers (see MODEL_PROVIDER_IDS).
-        // `providersForModel` returns the supported providers in priority order, or
-        // `[]` for an unknown model string (the model check below then rejects it).
-        // An explicit provider is allowed but must be one that serves the model;
-        // when omitted the model's default (first-listed) provider is used.
-        const supportedProviders = providersForModel(options.model);
-        if (options.provider &&
-            supportedProviders.length > 0 &&
-            !supportedProviders.includes(options.provider)) {
-            throw new RunConfigValidationError(`AgentExecutor.submit: provider ${JSON.stringify(options.provider)} is not available for ` +
-                `model ${JSON.stringify(options.model)} (supported: ${supportedProviders.join(", ")})`);
-        }
-        const provider = options.provider ?? supportedProviders[0] ?? DEFAULT_RUN_PROVIDER;
-        validateSubmitCredentials(options, provider, "AgentExecutor.submit");
-        if (typeof options.model !== "string" || !options.model) {
-            throw new RunConfigValidationError("AgentExecutor.submit: model is required");
-        }
-        const prompt = normalisePrompt(options.prompt, "AgentExecutor.submit", "prompt");
-        const { endpoints: proxyEndpointDeclarations, auth: proxyEndpointAuthFromInstances } = splitProxyEndpoints(options.proxyEndpoints ?? []);
-        const mergedProxyAuth = mergeProxyEndpointAuth(proxyEndpointAuthFromInstances, options.secrets?.proxyEndpointAuth ?? []);
-        // Split secretEnv into value-free declarations (hashed submission) and
-        // ephemeral values (vaulted secrets channel), mirroring the proxy split.
-        const { declarations: secretEnvDeclarations, values: envSecretValues } = splitSecretEnv(options.secretEnv);
-        // Validate the per-run limits override with the SAME parser the server runs
-        // (shape + positivity + allow-list), failing fast before any asset upload.
-        // Normalizes an all-absent override (e.g. `{}`) away.
-        let limits;
-        try {
-            limits = parseRunLimits(options.limits);
-        }
-        catch (err) {
-            throw new AexError("RUN_CONFIG_INVALID", `AgentExecutor.submit: ${err instanceof Error ? err.message : String(err)}`);
-        }
-        // Walk Skill / Tool / AgentsMd / File instances. Inline drafts are eagerly
-        // uploaded to the content-addressable asset store here (before POST /runs)
-        // and referenced as plain `kind:"asset"` refs. Already-materialized asset
-        // refs pass through unchanged.
-        const uploader = (args) => this._uploadAsset(args);
-        const preparedSkills = await prepareSkills(options.skills ?? [], uploader);
-        const preparedTools = await prepareTools(options.tools ?? [], uploader);
-        const preparedAgentsMd = await prepareAgentsMd(options.agentsMd ?? [], uploader);
-        const preparedFiles = await prepareFiles(options.files ?? [], uploader);
-        const { submissionMcpServers, mergedMcpSecrets } = mergeMcpServers(options.mcpServers ?? [], options.secrets?.mcpServers ?? []);
-        const outputCapture = outputsForWire(options.outputs);
-        const submission = {
-            model: options.model,
-            ...(options.system ? { system: options.system } : {}),
-            prompt,
-            skills: preparedSkills,
-            // The wire `tools` is the union: builtin name strings (cherry-picks)
-            // followed by the custom tool bundle refs. The shared parser splits them
-            // back into `tools` (custom) + `builtinTools` (names). The cast
-            // acknowledges the SDK is producing pre-parse wire input here, same as
-            // `mcpServers` / `environment` below.
-            tools: [...preparedTools.builtinNames, ...preparedTools.refs],
-            agentsMd: preparedAgentsMd,
-            files: preparedFiles,
-            // submissionMcpServers may contain workspace refs of the shape
-            // {kind:"workspace", id:"mcp_..."}. The BFF runs
-            // `resolveWorkspaceMcpRefsInSubmission` BEFORE the shared parser
-            // and replaces them with the resolved {name, url}, so by the
-            // time anything reads PlatformSubmission post-parse the
-            // shape matches McpServerRef. The cast acknowledges that the
-            // SDK is producing pre-resolution wire input here.
-            mcpServers: submissionMcpServers,
-            ...(Object.keys(secretEnvDeclarations).length > 0 ? { secretEnv: secretEnvDeclarations } : {}),
-            // `options.environment.packages` carry the customer wire shape
-            // (`{name:"pip:pandas"}`); the shared parser resolves the ecosystem
-            // prefix into PlatformPackage. The cast acknowledges the SDK is
-            // producing pre-parse wire input here, same as `mcpServers` above.
-            ...(options.environment
-                ? { environment: options.environment }
-                : {}),
-            ...(options.metadata ? { metadata: options.metadata } : {}),
-            ...(outputCapture ? { outputs: outputCapture } : {}),
-            // Pass-through the builtin-tool toggle verbatim (omitted ⇒ default ON).
-            ...(options.includeBuiltinTools !== undefined
-                ? { includeBuiltinTools: options.includeBuiltinTools }
-                : {}),
-            ...(options.outputMode !== undefined ? { outputMode: options.outputMode } : {})
-        };
-        const secrets = {
-            ...options.secrets,
-            ...(mergedMcpSecrets.length > 0 ? { mcpServers: mergedMcpSecrets } : {}),
-            ...(mergedProxyAuth.length > 0 ? { proxyEndpointAuth: mergedProxyAuth } : {}),
-            ...(Object.keys(envSecretValues).length > 0 ? { envSecrets: envSecretValues } : {})
-        };
-        const request = {
-            idempotencyKey: options.idempotencyKey ?? generateIdempotencyKey(),
-            // Always include `provider` on the wire so dashboard / proxy
-            // tooling never has to second-guess what the runtime saw. The
-            // shared parser still defaults to `anthropic` when callers omit
-            // the field entirely, but the SDK has resolved it by here.
-            provider,
-            submission,
-            ...(options.runtimeSize ? { runtimeSize: options.runtimeSize } : {}),
-            ...(options.timeout ? { timeout: options.timeout } : {}),
-            ...(options.parentRunId ? { parentRunId: options.parentRunId } : {}),
-            // Operational/delivery concern — sibling of idempotencyKey, NOT part of
-            // the hashed brief. The idempotency key here is randomly generated, so
-            // including the field has no effect on dedup.
-            ...(options.webhook ? { webhook: options.webhook } : {}),
-            // Per-run lineage-limit override — a top-level operational dial (sibling
-            // of parentRunId), NOT part of the hashed submission. Validated + normalized
-            // above; the server re-clamps against the workspace + platform ceilings.
-            ...(limits ? { limits } : {}),
-            secrets,
-            ...(proxyEndpointDeclarations.length > 0
-                ? { proxyEndpoints: proxyEndpointDeclarations }
-                : {})
-        };
-        const run = await operations.submitRun(this.#http, request);
-        return getSubmittedRunId(run);
-    }
     async #buildSessionCreateRequest(options) {
         if (!options || typeof options !== "object") {
             throw new RunConfigValidationError("Aex.openSession: options is required");
@@ -691,7 +773,6 @@ export class AgentExecutor {
             throw new AexError("RUN_CONFIG_INVALID", `Aex.openSession: ${err instanceof Error ? err.message : String(err)}`);
         }
         const uploader = (args) => this._uploadAsset(args);
-        const preparedSkills = await prepareSkills(options.skills ?? [], uploader);
         const preparedTools = await prepareTools(options.tools ?? [], uploader);
         const preparedAgentsMd = await prepareAgentsMd(options.agentsMd ?? [], uploader);
         const preparedFiles = await prepareFiles(options.files ?? [], uploader);
@@ -701,8 +782,13 @@ export class AgentExecutor {
         const submission = {
             model: options.model,
             ...(options.system ? { system: options.system } : {}),
-            skills: preparedSkills,
-            tools: [...preparedTools.builtinNames, ...preparedTools.refs],
+            // Builtin name strings + custom tool refs + skill-tool refs all ride the
+            // one `tools` union; the BFF parser splits them back apart by kind.
+            tools: [
+                ...preparedTools.builtinNames,
+                ...preparedTools.refs,
+                ...preparedTools.skillToolRefs
+            ],
             agentsMd: preparedAgentsMd,
             files: preparedFiles,
             mcpServers: submissionMcpServers,
@@ -729,275 +815,15 @@ export class AgentExecutor {
             ...(options.overrides?.timeout ? { timeout: options.overrides.timeout } : {}),
             ...(limits ? { limits } : {}),
             retention,
+            // Operational/delivery concern — sibling of secrets, NOT part of the
+            // hashed submission. Delivered at the settle-consistent barrier.
+            ...(options.webhook ? { webhook: options.webhook } : {}),
             secrets,
             ...(proxyEndpointDeclarations.length > 0
                 ? { proxyEndpoints: proxyEndpointDeclarations }
                 : {})
         };
     }
-    getRun(runId) {
-        return operations.getRun(this.#http, runId);
-    }
-    /** Short alias for `getRun`. */
-    get(runId) {
-        return this.getRun(runId);
-    }
-    /**
-     * List the runs in this workspace, most-recent first, one page at a time.
-     * The workspace is derived server-side from the API token, so this only ever
-     * enumerates your own runs. Pass `query.cursor` (from a prior page's
-     * `nextCursor`) to page; omit it for the first page. Returns public-safe
-     * {@link RunSummary} rows — the full submission stays behind `getRunUnit`.
-     *
-     * This is the workspace-wide discovery entry point: combine it with
-     * `listOutputs` / `readOutputText` to reach any run's deliverables.
-     */
-    listRuns(query) {
-        return operations.listRuns(this.#http, query);
-    }
-    /**
-     * Find output files across runs by filename / extension / content type.
-     * Returns lean REFERENCE hits (runId, outputId, filename, size, content type)
-     * — never bytes; fetch content with {@link readOutputText}. Scope the search
-     * to a corpus with `query.runIds`; omit it to scan the whole workspace (needs
-     * the owner-gated `listRuns`). Composed client-side for the MVP (per-run
-     * `listOutputs` + the contracts output filter), so it works against any
-     * already-terminal run with no new server endpoint. Bounded by
-     * `query.limit` (default 100) — for very large corpora prefer the deferred
-     * server-side index.
-     */
-    async searchOutputs(query = {}) {
-        const runIds = query.runIds ?? (await this.#allWorkspaceRunIds());
-        const limit = query.limit ?? 100;
-        // Translate the search query to an OutputQuery so the contracts output
-        // filter (classifyOutput / basename match / contentType wildcard) 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 runId of runIds) {
-            const outputs = hasFilter
-                ? await this.listOutputs(runId, outputQuery)
-                : await this.listOutputs(runId);
-            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)
-                    return { hits };
-            }
-        }
-        return { hits };
-    }
-    /** Enumerate every run id in the workspace by paging `listRuns`. */
-    async #allWorkspaceRunIds() {
-        const ids = [];
-        let cursor;
-        do {
-            const page = await this.listRuns(cursor ? { cursor } : {});
-            for (const run of page.runs)
-                ids.push(run.id);
-            cursor = page.nextCursor;
-        } while (cursor);
-        return ids;
-    }
-    /**
-     * Fetch the self-contained `RunUnit`: parsed submission inputs,
-     * attempts, indexed events (inline + cursor for the tail), raw
-     * provider-event Storage manifest, outputs, capture failures,
-     * proxy-call audit, pinned workspace skills, provider skills,
-     * inline skills. Backed by the same endpoint as `getRun` but
-     * typed against the full wire shape — use this when you need
-     * fields beyond `{id, status, timestamps, usage}`.
-     */
-    getRunUnit(runId) {
-        return operations.getRunUnit(this.#http, runId);
-    }
-    /** Short alias for `getRunUnit`. */
-    getUnit(runId) {
-        return this.getRunUnit(runId);
-    }
-    listEvents(runId) {
-        return operations.listRunEvents(this.#http, runId);
-    }
-    /** Short alias for `listEvents`. */
-    events(runId) {
-        return this.listEvents(runId);
-    }
-    /**
-     * Yield run events (the `RunEvent` snapshot shape) as they arrive, by
-     * polling the coordinator-backed `/events` endpoint until the run reaches
-     * a terminal state, the signal aborts, or the caller breaks the iterator.
-     *
-     * For the live, low-latency envelope stream prefer {@link streamEnvelopes}
-     * (coordinator WebSocket). This polling form stays for consumers that want
-     * the loose `RunEvent` shape without a WS.
-     */
-    async *streamEvents(runId, options = {}) {
-        if (options.signal?.aborted)
-            return;
-        yield* this.#streamEventsPolling(runId, { ...options, seenIds: new Set() });
-    }
-    /** Short alias for `streamEvents`. */
-    stream(runId, options) {
-        return this.streamEvents(runId, options);
-    }
-    /**
-     * Stream the unified {@link AexEvent} envelope live over the coordinator
-     * WebSocket. The hosted API's ticket broker authorizes the connection (workspace
-     * token → short-lived coordinator ticket); the shared client replays from
-     * the cursor, tails live, and resumes exactly-once across reconnects. The
-     * ticket is re-minted on each (re)connect so a long run never outlives it.
-     */
-    async *streamEnvelopes(runId, options = {}) {
-        const first = await operations.getCoordinatorTicket(this.#http, runId);
-        yield* streamCoordinatorEvents({
-            wsUrl: first.wsUrl,
-            from: options.from ?? 0,
-            fetchTicket: async () => (await operations.getCoordinatorTicket(this.#http, runId)).ticket,
-            // settleConsistent ends the stream on the post-mirror barrier instead of the
-            // earlier RUN_FINISHED UX signal, so "stream ended" ⇒ getRun is terminal.
-            ...(options.settleConsistent ? { isTerminal: isRunSettled } : {}),
-            ...(options.signal ? { signal: options.signal } : {})
-        });
-    }
-    async *#streamEventsPolling(runId, options) {
-        const intervalMs = options.intervalMs ?? 1_000;
-        const signal = options.signal;
-        while (!signal?.aborted) {
-            const events = await this.listEvents(runId);
-            for (const event of events) {
-                if (!options.seenIds.has(event.id)) {
-                    options.seenIds.add(event.id);
-                    yield event;
-                }
-            }
-            const run = await this.getRun(runId);
-            if (isTerminal(run.status))
-                return;
-            // `sleep` rejects on abort — treat that as a graceful stop.
-            try {
-                await sleep(intervalMs, signal);
-            }
-            catch {
-                return;
-            }
-        }
-    }
-    /**
-     * Poll the run record until it reaches a terminal status (succeeded,
-     * failed, terminated). Throws if `timeoutMs` elapses first.
-     */
-    async waitForRun(runId, options = {}) {
-        const intervalMs = options.intervalMs ?? 1_500;
-        const timeoutMs = options.timeoutMs;
-        const signal = options.signal;
-        const deadline = typeof timeoutMs === "number" ? Date.now() + timeoutMs : Number.POSITIVE_INFINITY;
-        while (!signal?.aborted) {
-            const run = await this.getRun(runId);
-            if (isTerminal(run.status))
-                return run;
-            if (Date.now() >= deadline) {
-                throw new Error(`AgentExecutor.waitForRun: timeout after ${timeoutMs}ms`);
-            }
-            await sleep(intervalMs, signal);
-        }
-        throw new Error("AgentExecutor.waitForRun: aborted");
-    }
-    /** Short alias for `waitForRun`. */
-    wait(runId, options) {
-        return this.waitForRun(runId, options);
-    }
-    listOutputs(runId, query) {
-        return operations.listOutputs(this.#http, runId, query);
-    }
-    /** Short alias for `listOutputs`. */
-    outputs(runId, query) {
-        return this.listOutputs(runId, query);
-    }
-    findOutputs(runId, query) {
-        return operations.findOutputs(this.#http, runId, query);
-    }
-    findOutput(runId, query) {
-        return operations.findOutput(this.#http, runId, query);
-    }
-    outputLink(runId, selectorOrQuery, options) {
-        return operations.outputLink(this.#http, runId, selectorOrQuery, options);
-    }
-    createOutputLink(runId, selectorOrQuery, options) {
-        return this.outputLink(runId, selectorOrQuery, options);
-    }
-    async fetchOutput(runId, selectorOrQuery, options) {
-        const link = await this.outputLink(runId, selectorOrQuery, options);
-        return (this.#fetch ?? fetch)(link.url);
-    }
-    /**
-     * Read ONE output file as byte-capped, decoded UTF-8 text. Streams the file and
-     * STOPS at `options.maxBytes` (default 50 KB, ceiling 10 MB), so a huge
-     * deliverable never fully buffers — ideal for handing a run's output to an LLM
-     * tool. Check `result.truncated` before treating the text as complete; pass
-     * `options.grep` to keep only matching lines. Select by `{ path }` or `{ id }`,
-     * same as `downloadOutput`.
-     */
-    readOutputText(runId, selector, options) {
-        return operations.readOutputText(this.#http, runId, selector, options);
-    }
-    eventArchiveLink(runId, options) {
-        return operations.eventArchiveLink(this.#http, runId, options);
-    }
-    async downloadOutput(runId, selectorOrOptions, options) {
-        const hasSelector = selectorOrOptions !== undefined && !isOutputDownloadOptionsOnly(selectorOrOptions);
-        const selector = hasSelector ? selectorOrOptions : undefined;
-        const to = hasSelector ? options?.to : selectorOrOptions?.to ?? options?.to;
-        let bytes;
-        if (selector === undefined) {
-            bytes = await operations.downloadOutputs(this.#http, runId);
-        }
-        else {
-            const output = isOutputPathSelector(selector)
-                ? resolveOutputFileSelector(await operations.listOutputs(this.#http, runId), selector, runId)
-                : resolveOutputFileSelector([], selector, runId);
-            const { response } = await this.#http.download(`/api/runs/${encodeURIComponent(runId)}/outputs/${encodeURIComponent(output.id)}/download`);
-            bytes = new Uint8Array(await response.arrayBuffer());
-        }
-        return writeOptionalFile(bytes, to);
-    }
-    cancelRun(runId) {
-        return operations.cancelRun(this.#http, runId);
-    }
-    /** Short alias for `cancelRun`. */
-    cancel(runId) {
-        return this.cancelRun(runId);
-    }
-    deleteRun(runId) {
-        return operations.deleteRun(this.#http, runId);
-    }
-    /** Short alias for `deleteRun`. */
-    delete(runId) {
-        return this.deleteRun(runId);
-    }
-    /**
-     * List a run's webhook delivery attempts (the per-run delivery ledger).
-     * Empty when the run carried no `webhook` or has not yet terminated.
-     */
-    getRunWebhookDeliveries(runId) {
-        return operations.getRunWebhookDeliveries(this.#http, runId);
-    }
-    /**
-     * Manually re-trigger a run's webhook delivery: re-sends the frozen payload
-     * with the SAME `webhook-id` so the consumer dedupes.
-     */
-    redeliverRunWebhook(runId, deliveryId) {
-        return operations.redeliverRunWebhook(this.#http, runId, deliveryId);
-    }
     /**
      * Delete a workspace asset blob from the shared content-addressed store
      * (`assets/<workspaceId>/<hash>`). Accepts `sha256:<hex>` or a bare
@@ -1009,29 +835,6 @@ export class AgentExecutor {
     whoami() {
         return operations.whoami(this.#http);
     }
-    /**
-     * Download EVERYTHING public about a run as one zip, assembled client-side
-     * from the public read endpoints (`getRun` + `listEvents` +
-     * `listOutputs` + per-output `/download`). Organised into the namespace
-     * folders `metadata/`, `events/`, and `outputs/`, plus a `manifest.json`.
-     * Pass `to` to also write the
-     * bytes to a file path while still returning the bytes.
-     */
-    async download(runId, options) {
-        return writeOptionalFile(await operations.download(this.#http, runId), options?.to);
-    }
-    /** Download only the run's deliverables (the `outputs` namespace) as a zip. */
-    async downloadOutputs(runId, options) {
-        return writeOptionalFile(await operations.downloadOutputs(this.#http, runId), options?.to);
-    }
-    /** Download only the indexed event archive (the `events` namespace) as a zip. */
-    async downloadEvents(runId, options) {
-        return writeOptionalFile(await operations.downloadEvents(this.#http, runId), options?.to);
-    }
-    /** Download only the run record (the `metadata` namespace) as a zip. */
-    async downloadMetadata(runId, options) {
-        return writeOptionalFile(await operations.downloadMetadata(this.#http, runId), options?.to);
-    }
 }
 /** Canonical SDK client name. `AgentExecutor` remains as a compatibility alias. */
 export class Aex extends AgentExecutor {
@@ -1043,6 +846,19 @@ const TERMINAL_STATUSES = new Set(TERMINAL_RUN_STATUSES);
 function isTerminal(status) {
     return typeof status === "string" && TERMINAL_STATUSES.has(status);
 }
+/**
+ * A session is "parked" once it stops making progress: it reached one of the
+ * turn-terminal statuses (`idle` / `suspended` / `error`) or a terminal run
+ * status. `SessionHandle.wait` / `streamEvents` stop here.
+ */
+function isSessionParked(status) {
+    return (status === "idle" ||
+        status === "suspended" ||
+        status === "error" ||
+        status === "deleted" ||
+        status === "expired" ||
+        isTerminal(status));
+}
 function sessionToRun(session) {
     const id = session.sessionId ?? session.id;
     return {
@@ -1075,13 +891,6 @@ function escapeRegExp(input) {
 function isOutputPathSelector(selector) {
     return Boolean(selector && typeof selector === "object" && "path" in selector);
 }
-function isOutputDownloadOptionsOnly(value) {
-    return Boolean(value &&
-        typeof value === "object" &&
-        "to" in value &&
-        !("id" in value) &&
-        !("path" in value));
-}
 function resolveOutputFileSelector(outputs, selector, runId) {
     if (isOutputPathSelector(selector)) {
         const target = normalizeOutputLookupPath(selector.path);
@@ -1148,22 +957,39 @@ function generateIdempotencyKey() {
         return cryptoObj.randomUUID();
     return `idem-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
 }
-function normalisePrompt(input, surface = "AgentExecutor.submit", field = "prompt") {
-    if (typeof input === "string") {
-        if (!input) {
-            throw new RunConfigValidationError(`${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`);
+/**
+ * Derive the message idempotency key from the session-create key. Mirrors the
+ * CLI (`<createKey>:message`) so a retried `run` / `sessions.run` that reuses
+ * one `idempotencyKey` de-duplicates BOTH the create and the billable turn.
+ */
+function deriveMessageKey(createKey) {
+    return `${createKey}:message`;
+}
+/**
+ * Extract a throttle-class {@link ProviderFault} from a failed session record.
+ * Reads a structured `providerFault` / `error` field first (the shape the
+ * runtime is expected to emit on a throttled turn), then falls back to a
+ * heuristic scan of `errorMessage`. Returns `undefined` when the failure is not
+ * a throttle.
+ */
+function throttleFromSession(session) {
+    const fault = parseProviderFault(session.providerFault) ??
+        parseProviderFault(session.error) ??
+        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. */
+function faultFromErrorMessage(message) {
+    if (message === undefined || message.length === 0)
+        return undefined;
+    const lower = message.toLowerCase();
+    if (/\b429\b|rate.?limit|too many requests/.test(lower)) {
+        return { kind: "rate_limit", message };
     }
-    for (const segment of input) {
-        if (typeof segment !== "string" || !segment) {
-            throw new RunConfigValidationError(`${surface}: ${field} segments must be non-empty strings`);
-        }
+    if (/\b529\b|overloaded/.test(lower)) {
+        return { kind: "overloaded", message };
     }
-    return [...input];
+    return undefined;
 }
 function normaliseSessionInput(input, surface, field) {
     if (typeof input === "string") {
@@ -1182,18 +1008,6 @@ function normaliseSessionInput(input, surface, field) {
     }
     return [...input];
 }
-function assertNoRemovedSubmitFields(options, surface, extraFields = []) {
-    const record = options;
-    for (const field of ["credentialMode", "runtime", "region", "apiKey", "credentials", "postHook", ...extraFields]) {
-        if (Object.prototype.hasOwnProperty.call(record, field)) {
-            throw new RunConfigValidationError(`${surface}: ${field} is not a supported option; use the managed path with secrets.apiKeys[provider].`);
-        }
-    }
-    const secrets = record.secrets;
-    if (secrets && typeof secrets === "object" && !Array.isArray(secrets) && Object.prototype.hasOwnProperty.call(secrets, "apiKey")) {
-        throw new RunConfigValidationError(`${surface}: secrets.apiKey is not supported; use secrets.apiKeys[provider].`);
-    }
-}
 function assertNoLegacySessionFields(options, surface) {
     const record = options;
     const messages = {
@@ -1204,14 +1018,14 @@ function assertNoLegacySessionFields(options, surface) {
         idleTtl: "use overrides.idleTtl.",
         retention: "use overrides.idleTtl.",
         secretEnv: "use environment.secrets.",
+        skills: "skills are now tools; build one with Tools.fromSkillDir/fromSkillUrl and pass it in tools.",
         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.",
         signal: "use session.cancel() / session.suspend() for remote control.",
-        postHook: "send a follow-up validation message when the session returns idle.",
-        webhook: "send a follow-up validation message instead of a submit webhook."
+        postHook: "send a follow-up validation message when the session returns idle."
     };
     for (const [field, message] of Object.entries(messages)) {
         if (Object.prototype.hasOwnProperty.call(record, field)) {
@@ -1232,15 +1046,6 @@ function assertNoSessionSendSignal(options, surface) {
         throw new RunConfigValidationError(`${surface}: signal is not a supported option; use session.cancel() / session.suspend() for remote control.`);
     }
 }
-function validateSubmitCredentials(options, provider, surface) {
-    if (options.parentRunId) {
-        return;
-    }
-    const key = options.secrets?.apiKeys?.[provider];
-    if (typeof key !== "string" || key.length === 0) {
-        throw new RunConfigValidationError(`${surface}: a provider API key is required — pass secrets.apiKeys[${JSON.stringify(provider)}].`);
-    }
-}
 function validateApiKeys(apiKeys, provider, surface) {
     const key = apiKeys?.[provider];
     if (typeof key !== "string" || key.length === 0) {
@@ -1304,42 +1109,17 @@ async function resolveAssetId(entry, bundle, uploader) {
     entry._rememberAsset(uploaded.assetId);
     return uploaded.assetId;
 }
-/** Walk Skill[], eagerly upload drafts as assets, and return plain asset refs. */
-async function prepareSkills(skills, uploader) {
-    const refs = [];
-    for (let i = 0; i < skills.length; i++) {
-        const entry = skills[i];
-        if (!(entry instanceof Skill)) {
-            throw new RunConfigValidationError(`AgentExecutor.submit: skills[${i}] must be a Skill instance`);
-        }
-        const ref = entry.ref;
-        if (ref.kind === "draft") {
-            const bundle = entry._takeDraftBundle();
-            if (!bundle) {
-                throw new RunConfigValidationError(`AgentExecutor.submit: skills[${i}] is draft but has no bytes`);
-            }
-            const assetId = await resolveAssetId(entry, bundle, uploader);
-            refs.push({
-                kind: "asset",
-                assetId,
-                name: bundle.name
-            });
-            continue;
-        }
-        // Already-materialized asset ref.
-        refs.push(ref);
-    }
-    return refs;
-}
 /**
  * Split the `tools` union into custom tool refs (drafts eagerly uploaded as
- * assets) and builtin tool-name references (bare strings, validated against the
- * closed {@link BUILTIN_TOOL_NAMES} set). Builtin names are deduped, in input
- * order; the two groups are recombined on the wire (builtins first) by the
- * caller.
+ * assets), skill-tool refs (skill bundles eagerly uploaded as assets), and
+ * builtin tool-name references (bare strings, validated against the closed
+ * {@link BUILTIN_TOOL_NAMES} set). Builtin names are deduped, in input order;
+ * the three groups are recombined on the wire by the caller (the BFF parser
+ * splits them back apart by kind).
  */
 async function prepareTools(tools, uploader) {
     const refs = [];
+    const skillToolRefs = [];
     const seenBuiltins = new Set();
     const builtinNames = [];
     for (let i = 0; i < tools.length; i++) {
@@ -1347,8 +1127,8 @@ 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(`AgentExecutor.submit: tools[${i}] (${JSON.stringify(entry)}) is not a builtin tool name; ` +
-                    `expected a Tool instance or one of: ${BUILTIN_TOOL_NAMES.join(", ")}`);
+                throw new RunConfigValidationError(`aex: tools[${i}] (${JSON.stringify(entry)}) is not a builtin tool name; ` +
+                    `expected a Tool, a SkillTool, or one of: ${BUILTIN_TOOL_NAMES.join(", ")}`);
             }
             if (!seenBuiltins.has(entry)) {
                 seenBuiltins.add(entry);
@@ -1356,14 +1136,29 @@ async function prepareTools(tools, uploader) {
             }
             continue;
         }
+        // A skill-tool: upload its bundle (if a draft) and emit a `kind:"skill"` ref.
+        if (entry instanceof SkillTool) {
+            const ref = entry.ref;
+            if (ref.kind === "draft") {
+                const bundle = entry._takeDraftBundle();
+                if (!bundle) {
+                    throw new RunConfigValidationError(`aex: tools[${i}] is a draft skill-tool but has no bytes`);
+                }
+                const assetId = await resolveAssetId(entry, bundle, uploader);
+                skillToolRefs.push({ kind: "skill", assetId, name: bundle.name, description: bundle.description });
+                continue;
+            }
+            skillToolRefs.push(ref);
+            continue;
+        }
         if (!(entry instanceof Tool)) {
-            throw new RunConfigValidationError(`AgentExecutor.submit: tools[${i}] must be a Tool instance or a builtin tool name`);
+            throw new RunConfigValidationError(`aex: tools[${i}] must be a Tool, a SkillTool, or a builtin tool name`);
         }
         const ref = entry.ref;
         if (ref.kind === "draft") {
             const bundle = entry._takeDraftBundle();
             if (!bundle) {
-                throw new RunConfigValidationError(`AgentExecutor.submit: tools[${i}] is draft but has no bytes`);
+                throw new RunConfigValidationError(`aex: tools[${i}] is draft but has no bytes`);
             }
             const assetId = await resolveAssetId(entry, bundle, uploader);
             refs.push({ ...bundle.ref, assetId });
@@ -1371,7 +1166,7 @@ async function prepareTools(tools, uploader) {
         }
         refs.push(ref);
     }
-    return { refs, builtinNames };
+    return { refs, skillToolRefs, builtinNames };
 }
 /** Walk AgentsMd[], eagerly upload drafts as assets, and return plain asset refs. */
 async function prepareAgentsMd(agentsMds, uploader) {
@@ -1379,13 +1174,13 @@ async function prepareAgentsMd(agentsMds, uploader) {
     for (let i = 0; i < agentsMds.length; i++) {
         const entry = agentsMds[i];
         if (!(entry instanceof AgentsMd)) {
-            throw new RunConfigValidationError(`AgentExecutor.submit: agentsMd[${i}] must be an AgentsMd instance`);
+            throw new RunConfigValidationError(`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(`AgentExecutor.submit: agentsMd[${i}] is draft but has no bytes`);
+                throw new RunConfigValidationError(`aex: agentsMd[${i}] is draft but has no bytes`);
             }
             const assetId = await resolveAssetId(entry, bundle, uploader);
             refs.push({
@@ -1405,13 +1200,13 @@ async function prepareFiles(files, uploader) {
     for (let i = 0; i < files.length; i++) {
         const entry = files[i];
         if (!(entry instanceof File)) {
-            throw new RunConfigValidationError(`AgentExecutor.submit: files[${i}] must be a File instance`);
+            throw new RunConfigValidationError(`aex: files[${i}] must be a File instance`);
         }
         const ref = entry.ref;
         if (ref.kind === "draft") {
             const bundle = entry._takeDraftBundle();
             if (!bundle) {
-                throw new RunConfigValidationError(`AgentExecutor.submit: files[${i}] is draft but has no bytes`);
+                throw new RunConfigValidationError(`aex: files[${i}] is draft but has no bytes`);
             }
             const assetId = await resolveAssetId(entry, bundle, uploader);
             refs.push({
@@ -1426,13 +1221,6 @@ async function prepareFiles(files, uploader) {
     }
     return refs;
 }
-function getSubmittedRunId(response) {
-    const id = response.id ?? response.runId;
-    if (typeof id !== "string" || id.length === 0) {
-        throw new RunStateError("AgentExecutor.submit: submit response did not include a run id");
-    }
-    return id;
-}
 function mergeMcpServers(inputs, explicitSecrets) {
     const submissionMcpServers = [];
     const secretByName = new Map();
@@ -1442,14 +1230,14 @@ function mergeMcpServers(inputs, explicitSecrets) {
     for (let i = 0; i < inputs.length; i++) {
         const entry = inputs[i];
         if (!(entry instanceof McpServer)) {
-            throw new RunConfigValidationError(`AgentExecutor.submit: mcpServers[${i}] must be an McpServer instance`);
+            throw new RunConfigValidationError(`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(`AgentExecutor.submit: mcpServers[${i}].url conflicts with secrets.mcpServers["${secret.name}"]`);
+                throw new RunConfigValidationError(`aex: mcpServers[${i}].url conflicts with secrets.mcpServers["${secret.name}"]`);
             }
             secretByName.set(secret.name, secret);
         }
@@ -1477,7 +1265,7 @@ function mergeProxyEndpointAuth(fromInstances, fromExplicitSecrets) {
     for (const entry of fromInstances) {
         const existing = byName.get(entry.name);
         if (existing && existing.value.type !== entry.value.type) {
-            throw new RunConfigValidationError(`AgentExecutor.submit: proxyEndpoint "${entry.name}" auth type conflicts ` +
+            throw new RunConfigValidationError(`aex: proxyEndpoint "${entry.name}" auth type conflicts ` +
                 `with secrets.proxyEndpointAuth (instance=${entry.value.type}, secrets=${existing.value.type})`);
         }
         byName.set(entry.name, entry);