@aexhq/sdk 0.13.6

package/dist/client.js

@@ -0,0 +1,857 @@
+import { AexError, DEFAULT_CREDENTIAL_MODE, DEFAULT_RUN_PROVIDER, HttpClient, RUNTIME_KINDS, RunStateError, operations, parseCredentialMode, streamCoordinatorEvents, TERMINAL_RUN_STATUSES } from "./_contracts/index.js";
+import { uploadAsset } from "./asset-upload.js";
+import { AgentsMd } from "./agents-md.js";
+import { File } from "./file.js";
+import { McpServer } from "./mcp-server.js";
+import { splitProxyEndpoints } from "./proxy-endpoint.js";
+import { Skill } from "./skill.js";
+/**
+ * Workspace skill admin operations exposed under `client.skills`.
+ *
+ * New run submissions usually use `Skill.fromFiles(...)` or
+ * `Skill.fromPath(...)` directly inside `submitRun`; 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);
+    }
+    /**
+     * Internal: post a pre-bundled skill zip to the BFF. Only
+     * `Skill.upload` calls this. NOT part of the public API.
+     */
+    async _uploadSkillBundle(args) {
+        return operations.createSkillBundle(this.#http, {
+            name: args.name,
+            body: args.body,
+            contentType: "application/zip",
+            filename: `${args.name}.zip`
+        });
+    }
+}
+/**
+ * Workspace AgentsMd admin operations exposed under `client.agentsMd`.
+ *
+ * New run submissions usually use `AgentsMd.fromContent(...)` or
+ * `AgentsMd.fromPath(...)` directly inside `submitRun`; the SDK
+ * materializes those bytes to the hosted asset store before the run lands. This namespace is
+ * the read/delete surface for persisted AgentsMd records plus an internal
+ * upload transport retained for legacy callers.
+ */
+export class AgentsMdClient {
+    #http;
+    constructor(http) {
+        this.#http = http;
+    }
+    list() {
+        return operations.listAgentsMd(this.#http);
+    }
+    get(agentsMdId) {
+        return operations.getAgentsMd(this.#http, agentsMdId);
+    }
+    delete(agentsMdId) {
+        return operations.deleteAgentsMd(this.#http, agentsMdId);
+    }
+    /**
+     * Internal: post an AgentsMd markdown string to the BFF.
+     * NOT part of the public API.
+     */
+    async _uploadAgentsMd(args) {
+        return operations.createAgentsMd(this.#http, args);
+    }
+}
+/**
+ * Workspace File admin operations exposed under `client.files`.
+ *
+ * New run submissions usually use `File.fromPath(...)` or
+ * `File.fromBytes(...)` directly inside `submitRun`; the SDK materializes
+ * those bytes to the hosted asset store before the run lands. This namespace is the read/delete
+ * surface for persisted file records plus an internal upload transport
+ * retained for legacy callers.
+ */
+export class FilesClient {
+    #http;
+    constructor(http) {
+        this.#http = http;
+    }
+    list() {
+        return operations.listFiles(this.#http);
+    }
+    get(fileId) {
+        return operations.getFile(this.#http, fileId);
+    }
+    delete(fileId) {
+        return operations.deleteFile(this.#http, fileId);
+    }
+    /**
+     * Internal: post a pre-bundled file zip to the BFF.
+     * NOT part of the public API.
+     */
+    async _uploadFile(args) {
+        return operations.createFile(this.#http, args);
+    }
+}
+/**
+ * Unified user-facing client for the aex platform. The same class
+ * powers the published `@aexhq/sdk` SDK and (under the hood) every host-side
+ * subcommand of the in-container `aex` CLI. All operations talk to
+ * the dashboard BFF and operate on durable run records.
+ *
+ * The SDK never asks the caller for a workspace id — workspace identity
+ * is derived server-side from the API token on every request. Use
+ * `client.whoami()` if you want to introspect which workspace the
+ * token resolves to.
+ */
+export class AexClient {
+    #http;
+    /**
+     * The same fetch the HttpClient uses, kept so the asset materializer can
+     * PUT bytes DIRECTLY to the presigned upload URL (a non-aex origin) with the
+     * caller's fetch (tests inject one; prod uses the global).
+     */
+    #fetch;
+    skills;
+    agentsMd;
+    files;
+    constructor(options) {
+        if (!options.apiToken) {
+            throw new Error("AexClient: apiToken is required");
+        }
+        this.#http = new HttpClient({
+            ...(options.baseUrl ? { baseUrl: options.baseUrl } : {}),
+            apiToken: options.apiToken,
+            ...(options.fetch ? { fetch: options.fetch } : {}),
+            // 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`.
+            ...(options.debug
+                ? { debug: typeof options.debug === "function" ? options.debug : (line) => console.error(line) }
+                : {})
+        });
+        this.#fetch = options.fetch;
+        this.skills = new SkillsClient(this.#http);
+        this.agentsMd = new AgentsMdClient(this.#http);
+        this.files = new FilesClient(this.#http);
+    }
+    /**
+     * Internal: forwards to `SkillsClient._uploadSkillBundle`. NOT part of
+     * the public API.
+     *
+     * NOTE (tech-debt): this is part of the legacy workspace-skill upload
+     * surface (`SkillsClient` + `operations.createSkillBundle` + the TUS
+     * chunked path in asset-upload.ts). The live submit path materializes
+     * inline skills via `uploadAsset` instead; `Skill` no longer
+     * exposes `.upload()`/`.fromId()`. This surface is retained pending a
+     * deliberate deprecation pass (it still threads into the CLI host
+     * commands), tracked in the remediation plan as item 4a.
+     */
+    async _uploadSkillBundle(args) {
+        return this.skills._uploadSkillBundle(args);
+    }
+    /**
+     * Internal: an `AgentsMd.upload(this)` shortcut that bypasses
+     * `client.agentsMd` indirection. Forwarded to
+     * `AgentsMdClient._uploadAgentsMd`. NOT part of the public API.
+     */
+    async _uploadAgentsMd(args) {
+        return this.agentsMd._uploadAgentsMd(args);
+    }
+    /**
+     * Internal: a `File.upload(this)` shortcut that bypasses
+     * `client.files` indirection. Forwarded to
+     * `FilesClient._uploadFile`. NOT part of the public API.
+     */
+    async _uploadFile(args) {
+        return this.files._uploadFile(args);
+    }
+    /**
+     * Submit a run and wait for it to reach a terminal state. Returns the
+     * final `Run` record. For long-running flows, prefer `submitRun` +
+     * `stream(runId)` + `wait(runId)`.
+     */
+    async run(options) {
+        const runId = await this.submitRun(options);
+        return this.waitForRun(runId, options.signal ? { signal: options.signal } : {});
+    }
+    /**
+     * 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 (`Skill.fromFiles` / `Skill.fromPath`
+     * without a prior `.upload`) are accepted: the SDK switches to a
+     * multipart body that carries the canonical zip bytes alongside the
+     * JSON submission. The dashboard BFF ingests each one through the
+     * standard workspace-skill upload pipeline (dedup by content hash;
+     * upload via the existing two-phase pending → ready flow) and
+     * rewrites the run's `skills[]` to reference the resulting `skl_*`
+     * ids. The bytes persist on aex; the user can browse and
+     * download the resulting workspace skill from the dashboard.
+     */
+    async submitRun(options) {
+        if (!options || typeof options !== "object") {
+            throw new Error("AexClient.submitRun: options is required");
+        }
+        const provider = options.provider ?? DEFAULT_RUN_PROVIDER;
+        const credentialMode = parseCredentialMode(options.credentialMode);
+        if (credentialMode === "managed") {
+            throw new AexError("CREDENTIAL_INVALID", "AexClient.submitRun: credentialMode \"managed\" is not available without a private managed-key implementation");
+        }
+        if (!options.secrets) {
+            throw new Error("AexClient.submitRun: secrets is required");
+        }
+        // The matching provider's apiKey is required; every OTHER provider's
+        // secret block must be absent. The shared parser re-runs this check
+        // on the server; failing early here gives the caller a synchronous
+        // error before any network call.
+        const providerSecret = options.secrets[provider];
+        if (!providerSecret?.apiKey) {
+            throw new Error(`AexClient.submitRun: secrets.${provider}.apiKey is required`);
+        }
+        for (const other of ["anthropic", "deepseek", "openai", "gemini", "mistral"]) {
+            if (other === provider)
+                continue;
+            if (options.secrets[other] !== undefined) {
+                throw new Error(`AexClient.submitRun: secrets.${other} is not allowed when provider is ${provider}`);
+            }
+        }
+        if (typeof options.model !== "string" || !options.model) {
+            throw new Error("AexClient.submitRun: model is required");
+        }
+        const prompt = normalisePrompt(options.prompt);
+        const { endpoints: proxyEndpointDeclarations, auth: proxyEndpointAuthFromInstances } = splitProxyEndpoints(options.proxyEndpoints ?? []);
+        const mergedProxyAuth = mergeProxyEndpointAuth(proxyEndpointAuthFromInstances, options.secrets.proxyEndpointAuth ?? []);
+        // Walk Skill / AgentsMd / File instances and materialize every draft before
+        // the submit round-trip. The wire shape carries only kind:"asset" refs.
+        const assetSkills = await materializeSkills(this.#http, options.skills ?? [], this.#fetch);
+        const assetAgentsMd = await materializeAgentsMd(this.#http, options.agentsMd ?? [], this.#fetch);
+        const assetFiles = await materializeFiles(this.#http, options.files ?? [], this.#fetch);
+        const { submissionMcpServers, mergedMcpSecrets } = mergeMcpServers(options.mcpServers ?? [], options.secrets.mcpServers ?? []);
+        const submission = {
+            model: options.model,
+            ...(options.system ? { system: options.system } : {}),
+            prompt,
+            skills: assetSkills,
+            agentsMd: assetAgentsMd,
+            files: assetFiles,
+            // 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,
+            ...(options.environment ? { environment: options.environment } : {}),
+            ...(options.metadata ? { metadata: options.metadata } : {}),
+            ...(options.outputs &&
+                ((options.outputs.allowedDirs?.length ?? 0) > 0 || (options.outputs.deniedDirs?.length ?? 0) > 0)
+                ? { outputs: options.outputs }
+                : {}),
+            // Pass-through `builtins` verbatim — including an empty array,
+            // which is the "disable all builtins" signal. Distinguish from
+            // omitted (default applies) via `!== undefined`.
+            ...(options.builtins !== undefined ? { builtins: options.builtins } : {})
+        };
+        const secrets = {
+            ...options.secrets,
+            ...(mergedMcpSecrets.length > 0 ? { mcpServers: mergedMcpSecrets } : {}),
+            ...(mergedProxyAuth.length > 0 ? { proxyEndpointAuth: mergedProxyAuth } : {})
+        };
+        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,
+            ...(credentialMode !== DEFAULT_CREDENTIAL_MODE ? { credentialMode } : {}),
+            // `runtime` is optional on the wire — absent means let the
+            // dispatcher auto-route. Only emit it when the caller asked for
+            // a specific runtime so the wire shape stays minimal.
+            ...(options.runtime ? { runtime: options.runtime } : {}),
+            submission,
+            ...(options.runtimeSize ? { runtimeSize: options.runtimeSize } : {}),
+            ...(options.timeout ? { timeout: options.timeout } : {}),
+            secrets,
+            ...(proxyEndpointDeclarations.length > 0
+                ? { proxyEndpoints: proxyEndpointDeclarations }
+                : {})
+        };
+        if (options.runtime !== undefined &&
+            !RUNTIME_KINDS.includes(options.runtime)) {
+            throw new AexError("RUNTIME_UNSUPPORTED", `AexClient.submitRun: runtime must be one of: ${RUNTIME_KINDS.join(", ")} ` +
+                `(got ${JSON.stringify(options.runtime)})`);
+        }
+        // All inline refs were materialized above, so submitRun is
+        // always a plain JSON post. The multipart code path is gone.
+        const run = await operations.submitRun(this.#http, request);
+        return run.id;
+    }
+    getRun(runId) {
+        return operations.getRun(this.#http, runId);
+    }
+    /** Short alias for `getRun`. */
+    get(runId) {
+        return this.getRun(runId);
+    }
+    /**
+     * 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 Worker'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,
+            ...(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(`AexClient.waitForRun: timeout after ${timeoutMs}ms`);
+            }
+            await sleep(intervalMs, signal);
+        }
+        throw new Error("AexClient.waitForRun: aborted");
+    }
+    /** Short alias for `waitForRun`. */
+    wait(runId, options) {
+        return this.waitForRun(runId, options);
+    }
+    listOutputs(runId) {
+        return operations.listOutputs(this.#http, runId);
+    }
+    /** Short alias for `listOutputs`. */
+    outputs(runId) {
+        return this.listOutputs(runId);
+    }
+    createOutputLink(runId, outputId) {
+        return operations.createOutputLink(this.#http, runId, outputId);
+    }
+    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);
+    }
+    /**
+     * Bundle the per-run debug artifacts aex captures automatically:
+     *
+     *   - `runtime/{stdout,stderr,args}.log` — runtime process diagnostics.
+     *   - `host/...` — managed host logs when the platform includes them.
+     * These all live in the run's `logs` namespace (`runs/<id>/logs/`).
+     * Each is downloaded through the gated `/logs/:id/download` endpoint,
+     * decoded as UTF-8 text when the content type looks textual, and
+     * surfaced as raw bytes (base64) otherwise. The call is best-effort: a
+     * download failure for one file does not block the others; the failing
+     * entry lands in `errors` with the underlying message.
+     *
+     * Use this when a run failed or behaved oddly and you want all the
+     * post-mortem material in one round-trip — no need to wire
+     * `listOutputs` + `createOutputLink` by hand.
+     */
+    async getRunDebugLogs(runId) {
+        // The `logs` namespace IS the diagnostics surface — everything it
+        // lists is a debug artifact, so no client-side prefix filter.
+        const matches = await operations.listLogs(this.#http, runId);
+        const logs = [];
+        const errors = [];
+        for (const out of matches) {
+            const filename = out.filename ?? "(unnamed)";
+            try {
+                const { response } = await this.#http.download(`/api/runs/${runId}/logs/${out.id}/download`);
+                const buf = await response.arrayBuffer();
+                const bytes = new Uint8Array(buf);
+                const contentType = out.contentType ?? "application/octet-stream";
+                const isText = /^(text\/|application\/json)/.test(contentType);
+                const bytesBase64 = bytesToBase64(bytes);
+                logs.push({
+                    filename,
+                    sizeBytes: out.sizeBytes ?? bytes.byteLength,
+                    contentType,
+                    createdAt: out.createdAt ?? new Date(0).toISOString(),
+                    ...(isText ? { text: new TextDecoder().decode(bytes) } : {}),
+                    bytesBase64
+                });
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                errors.push({ filename, message });
+            }
+        }
+        return { runId, logs, errors };
+    }
+    /** Short alias for `getRunDebugLogs`. */
+    debugLogs(runId) {
+        return this.getRunDebugLogs(runId);
+    }
+    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);
+    }
+    /**
+     * Delete a workspace asset blob from the shared content-addressed store
+     * (`assets/<workspaceId>/<hash>`). Accepts `sha256:<hex>` or a bare
+     * 64-hex digest. Runs that already snapshotted the asset are unaffected.
+     */
+    deleteWorkspaceAsset(hash) {
+        return operations.deleteWorkspaceAsset(this.#http, hash);
+    }
+    whoami() {
+        return operations.whoami(this.#http);
+    }
+    /**
+     * Download EVERYTHING about a run as one zip, assembled client-side
+     * from the public read endpoints (`getRun` + `listEvents` +
+     * `listOutputs` + per-output `/download`). Organised into the four
+     * namespace folders: `metadata/`, `events/`, `outputs/` (deliverables),
+     * `logs/` (`runtime/`, `host/`, `provider-proxy/`, `control-plane/`
+     * diagnostics), 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 platform diagnostics (the `logs` namespace) as a zip. */
+    async downloadLogs(runId, options) {
+        return writeOptionalFile(await operations.downloadLogs(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);
+    }
+}
+// `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).
+const TERMINAL_STATUSES = new Set(TERMINAL_RUN_STATUSES);
+function isTerminal(status) {
+    return typeof status === "string" && TERMINAL_STATUSES.has(status);
+}
+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);
+        if (!target) {
+            throw new RunStateError("AexClient.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(`AexClient.downloadOutput: output path "${selector.path}" matched multiple files`, { runId, path: selector.path, matches: matches.map((output) => output.filename ?? output.id) });
+        }
+        throw new RunStateError(`AexClient.downloadOutput: output path "${selector.path}" was not found`, {
+            runId,
+            path: selector.path
+        });
+    }
+    if (typeof selector.id !== "string" || selector.id.length === 0) {
+        throw new RunStateError("AexClient.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");
+        await writeFile(to, bytes);
+    }
+    return bytes;
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(new Error("aborted"));
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(new Error("aborted"));
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/**
+ * Encode a byte array as base64. Uses Node's `Buffer` when available
+ * (the SDK ships as a Node tarball; this is the hot path), and falls
+ * back to `btoa` for browser or edge runtimes that pull the SDK in
+ * without Buffer.
+ */
+function bytesToBase64(bytes) {
+    const BufferCtor = globalThis.Buffer;
+    if (BufferCtor) {
+        return BufferCtor.from(bytes).toString("base64");
+    }
+    let binary = "";
+    for (let i = 0; i < bytes.length; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    return globalThis.btoa(binary);
+}
+function generateIdempotencyKey() {
+    const cryptoObj = globalThis.crypto;
+    if (cryptoObj?.randomUUID)
+        return cryptoObj.randomUUID();
+    return `idem-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+function normalisePrompt(input) {
+    if (typeof input === "string") {
+        if (!input) {
+            throw new Error("AexClient.submitRun: prompt must be a non-empty string");
+        }
+        return [input];
+    }
+    if (!Array.isArray(input) || input.length === 0) {
+        throw new Error("AexClient.submitRun: prompt must be a non-empty string or string array");
+    }
+    for (const segment of input) {
+        if (typeof segment !== "string" || !segment) {
+            throw new Error("AexClient.submitRun: prompt segments must be non-empty strings");
+        }
+    }
+    return [...input];
+}
+/**
+ * Walk the user-provided `Skill[]`, validating each instance and
+ * producing:
+ *   - `skillRefs[]` — the wire entries for `submission.skills[]`, with
+ *     inline refs assigned positional slot ids (`transient-0`, …).
+ *   - `inlineBundles[]` — the bytes for each inline skill,
+ *     parallel-indexed by slot.
+ *
+ * Throws on consumed Skills (the user reused a draft after a prior
+ * `submitRun` call) so that mistake is loud, not silent.
+ */
+/**
+ * Walk the user-provided Skill[], materialize every draft to assets, and return
+ * the wire-shape refs.
+ */
+async function materializeSkills(http, skills, fetch) {
+    const out = [];
+    for (let i = 0; i < skills.length; i++) {
+        const entry = skills[i];
+        if (!(entry instanceof Skill)) {
+            throw new Error(`AexClient.submitRun: skills[${i}] must be a Skill instance`);
+        }
+        if (entry.isConsumed) {
+            throw new Error(`AexClient.submitRun: skills[${i}] was already consumed by a prior submitRun`);
+        }
+        const ref = entry.ref;
+        if (ref.kind === "draft") {
+            const bundle = entry._takeDraftBundle();
+            if (!bundle) {
+                throw new Error(`AexClient.submitRun: skills[${i}] is draft but has no bytes`);
+            }
+            const uploaded = await uploadAsset({
+                http,
+                bytes: bundle.bytes,
+                hash: bundle.contentHash,
+                ...(fetch ? { fetch } : {})
+            });
+            out.push({
+                kind: "asset",
+                assetId: uploaded.assetId,
+                name: bundle.name
+            });
+            continue;
+        }
+        // Already-materialized asset ref.
+        out.push(ref);
+    }
+    return out;
+}
+/** Materialize draft AgentsMd[] to assets; pass-through any already-materialized refs. */
+async function materializeAgentsMd(http, agentsMds, fetch) {
+    const out = [];
+    for (let i = 0; i < agentsMds.length; i++) {
+        const entry = agentsMds[i];
+        if (!(entry instanceof AgentsMd)) {
+            throw new Error(`AexClient.submitRun: agentsMd[${i}] must be an AgentsMd instance`);
+        }
+        if (entry.isConsumed) {
+            throw new Error(`AexClient.submitRun: agentsMd[${i}] was already consumed by a prior submitRun`);
+        }
+        const ref = entry.ref;
+        if (ref.kind === "draft") {
+            const bundle = entry._takeDraftBundle();
+            if (!bundle) {
+                throw new Error(`AexClient.submitRun: agentsMd[${i}] is draft but has no bytes`);
+            }
+            const uploaded = await uploadAsset({ http, bytes: bundle.bytes, hash: bundle.contentHash, ...(fetch ? { fetch } : {}) });
+            out.push({
+                kind: "asset",
+                assetId: uploaded.assetId,
+                name: bundle.name
+            });
+            continue;
+        }
+        out.push(ref);
+    }
+    return out;
+}
+/** Materialize draft File[] to assets; pass-through any already-materialized refs. */
+async function materializeFiles(http, files, fetch) {
+    const out = [];
+    for (let i = 0; i < files.length; i++) {
+        const entry = files[i];
+        if (!(entry instanceof File)) {
+            throw new Error(`AexClient.submitRun: files[${i}] must be a File instance`);
+        }
+        if (entry.isConsumed) {
+            throw new Error(`AexClient.submitRun: files[${i}] was already consumed by a prior submitRun`);
+        }
+        const ref = entry.ref;
+        if (ref.kind === "draft") {
+            const bundle = entry._takeDraftBundle();
+            if (!bundle) {
+                throw new Error(`AexClient.submitRun: files[${i}] is draft but has no bytes`);
+            }
+            const uploaded = await uploadAsset({ http, bytes: bundle.bytes, hash: bundle.contentHash, ...(fetch ? { fetch } : {}) });
+            out.push(bundle.mountPath !== undefined
+                ? {
+                    kind: "asset",
+                    assetId: uploaded.assetId,
+                    name: bundle.name,
+                    mountPath: bundle.mountPath
+                }
+                : {
+                    kind: "asset",
+                    assetId: uploaded.assetId,
+                    name: bundle.name
+                });
+            continue;
+        }
+        out.push(ref);
+    }
+    return out;
+}
+function mergeMcpServers(inputs, explicitSecrets) {
+    const submissionMcpServers = [];
+    const secretByName = new Map();
+    for (const secret of explicitSecrets) {
+        secretByName.set(secret.name, secret);
+    }
+    for (let i = 0; i < inputs.length; i++) {
+        const entry = inputs[i];
+        if (!(entry instanceof McpServer)) {
+            throw new Error(`AexClient.submitRun: 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 Error(`AexClient.submitRun: mcpServers[${i}].url conflicts with secrets.mcpServers["${secret.name}"]`);
+            }
+            secretByName.set(secret.name, secret);
+        }
+    }
+    return {
+        submissionMcpServers,
+        mergedMcpSecrets: Array.from(secretByName.values())
+    };
+}
+/**
+ * Merge `ProxyEndpoint`-derived auth entries with any
+ * `secrets.proxyEndpointAuth` the caller passed explicitly. Per-instance
+ * auth values win on the same `name`; a type mismatch (e.g. instance
+ * declares `bearer` but secrets carry `header` for the same name) is a
+ * call-site error and we throw at the SDK boundary instead of letting
+ * the BFF reject the submission an HTTP request later.
+ */
+function mergeProxyEndpointAuth(fromInstances, fromExplicitSecrets) {
+    if (fromInstances.length === 0 && fromExplicitSecrets.length === 0)
+        return [];
+    const byName = new Map();
+    for (const entry of fromExplicitSecrets) {
+        byName.set(entry.name, entry);
+    }
+    for (const entry of fromInstances) {
+        const existing = byName.get(entry.name);
+        if (existing && existing.value.type !== entry.value.type) {
+            throw new Error(`AexClient.submitRun: proxyEndpoint "${entry.name}" auth type conflicts ` +
+                `with secrets.proxyEndpointAuth (instance=${entry.value.type}, secrets=${existing.value.type})`);
+        }
+        byName.set(entry.name, entry);
+    }
+    return Array.from(byName.values());
+}
+//# sourceMappingURL=client.js.map