@aexhq/sdk 0.13.7 → 0.13.9

package/dist/client.js

@@ -1,5 +1,6 @@
 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 { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
 import { AgentsMd } from "./agents-md.js";
 import { File } from "./file.js";
 import { McpServer } from "./mcp-server.js";
@@ -139,20 +140,16 @@ export class FilesClient {
  * `client.whoami()` if you want to introspect which workspace the
  * token resolves to.
  */
-export class AexClient {
+export class AgentExecutor {
     #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).
-     */
+    /** The same fetch the HttpClient uses, kept for direct bootstrap uploads. */
     #fetch;
     skills;
     agentsMd;
     files;
     constructor(options) {
         if (!options.apiToken) {
-            throw new Error("AexClient: apiToken is required");
+            throw new Error("AgentExecutor: apiToken is required");
         }
         this.#http = new HttpClient({
             ...(options.baseUrl ? { baseUrl: options.baseUrl } : {}),
@@ -231,15 +228,15 @@ export class AexClient {
      */
     async submitRun(options) {
         if (!options || typeof options !== "object") {
-            throw new Error("AexClient.submitRun: options is required");
+            throw new Error("AgentExecutor.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");
+            throw new AexError("CREDENTIAL_INVALID", "AgentExecutor.submitRun: credentialMode \"managed\" is not available without a private managed-key implementation");
         }
         if (!options.secrets) {
-            throw new Error("AexClient.submitRun: secrets is required");
+            throw new Error("AgentExecutor.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
@@ -247,34 +244,41 @@ export class AexClient {
         // error before any network call.
         const providerSecret = options.secrets[provider];
         if (!providerSecret?.apiKey) {
-            throw new Error(`AexClient.submitRun: secrets.${provider}.apiKey is required`);
+            throw new Error(`AgentExecutor.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}`);
+                throw new Error(`AgentExecutor.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");
+            throw new Error("AgentExecutor.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);
+        // Walk Skill / AgentsMd / File instances. Drafts are declared as direct
+        // inputs on the submit request, then uploaded to the run bootstrap target
+        // after the control plane accepts the run. Already-materialized asset refs
+        // still pass through unchanged.
+        const preparedSkills = prepareSkills(options.skills ?? []);
+        const preparedAgentsMd = prepareAgentsMd(options.agentsMd ?? []);
+        const preparedFiles = prepareFiles(options.files ?? []);
+        const directInputs = [
+            ...preparedSkills.directInputs,
+            ...preparedAgentsMd.directInputs,
+            ...preparedFiles.directInputs
+        ];
         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,
+            skills: preparedSkills.refs,
+            agentsMd: preparedAgentsMd.refs,
+            files: preparedFiles.refs,
             // submissionMcpServers may contain workspace refs of the shape
             // {kind:"workspace", id:"mcp_..."}. The BFF runs
             // `resolveWorkspaceMcpRefsInSubmission` BEFORE the shared parser
@@ -322,13 +326,28 @@ export class AexClient {
         };
         if (options.runtime !== undefined &&
             !RUNTIME_KINDS.includes(options.runtime)) {
-            throw new AexError("RUNTIME_UNSUPPORTED", `AexClient.submitRun: runtime must be one of: ${RUNTIME_KINDS.join(", ")} ` +
+            throw new AexError("RUNTIME_UNSUPPORTED", `AgentExecutor.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;
+        const submitRequest = directInputs.length > 0
+            ? {
+                ...request,
+                bootstrapMode: "direct",
+                directInputs: directInputs.map(({ bytes: _bytes, ...descriptor }) => descriptor)
+            }
+            : request;
+        const run = await operations.submitRun(this.#http, submitRequest);
+        const runId = getSubmittedRunId(run);
+        if (directInputs.length > 0) {
+            await completeDirectBootstrap({
+                response: run,
+                directInputs,
+                hasRunAcceptedBootstrap: async () => hasRunAcceptedBootstrap(await operations.getRun(this.#http, runId)),
+                ...(options.signal ? { signal: options.signal } : {}),
+                ...(this.#fetch ? { fetch: this.#fetch } : {})
+            });
+        }
+        return runId;
     }
     getRun(runId) {
         return operations.getRun(this.#http, runId);
@@ -431,11 +450,11 @@ export class AexClient {
             if (isTerminal(run.status))
                 return run;
             if (Date.now() >= deadline) {
-                throw new Error(`AexClient.waitForRun: timeout after ${timeoutMs}ms`);
+                throw new Error(`AgentExecutor.waitForRun: timeout after ${timeoutMs}ms`);
             }
             await sleep(intervalMs, signal);
         }
-        throw new Error("AexClient.waitForRun: aborted");
+        throw new Error("AgentExecutor.waitForRun: aborted");
     }
     /** Short alias for `waitForRun`. */
     wait(runId, options) {
@@ -468,57 +487,6 @@ export class AexClient {
         }
         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);
     }
@@ -545,12 +513,11 @@ export class AexClient {
         return operations.whoami(this.#http);
     }
     /**
-     * Download EVERYTHING about a run as one zip, assembled client-side
+     * 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 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
+     * `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) {
@@ -560,10 +527,6 @@ export class AexClient {
     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);
@@ -577,6 +540,10 @@ export class AexClient {
 // against the canonical terminal set rather than re-deriving one (which is how
 // `timed_out` got dropped from the old hardcoded list).
 const TERMINAL_STATUSES = new Set(TERMINAL_RUN_STATUSES);
+const DIRECT_BOOTSTRAP_RETRY_STATUSES = new Set([408, 425, 429, 502, 503, 504]);
+const DIRECT_BOOTSTRAP_INITIAL_BACKOFF_MS = 100;
+const DIRECT_BOOTSTRAP_MAX_BACKOFF_MS = 1_000;
+const DIRECT_BOOTSTRAP_ATTEMPT_TIMEOUT_MS = 10_000;
 function isTerminal(status) {
     return typeof status === "string" && TERMINAL_STATUSES.has(status);
 }
@@ -594,7 +561,7 @@ 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", {
+            throw new RunStateError("AgentExecutor.downloadOutput: output path must be non-empty", {
                 runId,
                 path: selector.path
             });
@@ -611,15 +578,15 @@ function resolveOutputFileSelector(outputs, selector, runId) {
         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(`AgentExecutor.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`, {
+        throw new RunStateError(`AgentExecutor.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 });
+        throw new RunStateError("AgentExecutor.downloadOutput: selector must include an output id or path", { runId });
     }
     return { ...selector, id: selector.id };
 }
@@ -650,23 +617,6 @@ function sleep(ms, signal) {
         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)
@@ -676,133 +626,640 @@ function generateIdempotencyKey() {
 function normalisePrompt(input) {
     if (typeof input === "string") {
         if (!input) {
-            throw new Error("AexClient.submitRun: prompt must be a non-empty string");
+            throw new Error("AgentExecutor.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");
+        throw new Error("AgentExecutor.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");
+            throw new Error("AgentExecutor.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 = [];
+/** Walk Skill[] and turn drafts into direct-bootstrap descriptors. */
+function prepareSkills(skills) {
+    const refs = [];
+    const directInputs = [];
     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`);
+            throw new Error(`AgentExecutor.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`);
+            throw new Error(`AgentExecutor.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`);
+                throw new Error(`AgentExecutor.submitRun: skills[${i}] is draft but has no bytes`);
             }
-            const uploaded = await uploadAsset({
-                http,
+            const input = directInputFor({
+                role: "skill",
+                index: i,
+                name: bundle.name,
+                contentHash: bundle.contentHash,
                 bytes: bundle.bytes,
-                hash: bundle.contentHash,
-                ...(fetch ? { fetch } : {})
+                contentType: "application/zip"
             });
-            out.push({
+            directInputs.push(input);
+            refs.push({
                 kind: "asset",
-                assetId: uploaded.assetId,
+                assetId: input.assetId,
                 name: bundle.name
             });
             continue;
         }
         // Already-materialized asset ref.
-        out.push(ref);
+        refs.push(ref);
     }
-    return out;
+    return { refs, directInputs };
 }
-/** Materialize draft AgentsMd[] to assets; pass-through any already-materialized refs. */
-async function materializeAgentsMd(http, agentsMds, fetch) {
-    const out = [];
+/** Walk AgentsMd[] and turn drafts into direct-bootstrap descriptors. */
+function prepareAgentsMd(agentsMds) {
+    const refs = [];
+    const directInputs = [];
     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`);
+            throw new Error(`AgentExecutor.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`);
+            throw new Error(`AgentExecutor.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`);
+                throw new Error(`AgentExecutor.submitRun: agentsMd[${i}] is draft but has no bytes`);
             }
-            const uploaded = await uploadAsset({ http, bytes: bundle.bytes, hash: bundle.contentHash, ...(fetch ? { fetch } : {}) });
-            out.push({
+            const input = directInputFor({
+                role: "agentsMd",
+                index: i,
+                name: bundle.name,
+                contentHash: bundle.contentHash,
+                bytes: bundle.bytes,
+                contentType: "application/zip"
+            });
+            directInputs.push(input);
+            refs.push({
                 kind: "asset",
-                assetId: uploaded.assetId,
+                assetId: input.assetId,
                 name: bundle.name
             });
             continue;
         }
-        out.push(ref);
+        refs.push(ref);
     }
-    return out;
+    return { refs, directInputs };
 }
-/** Materialize draft File[] to assets; pass-through any already-materialized refs. */
-async function materializeFiles(http, files, fetch) {
-    const out = [];
+/** Walk File[] and turn drafts into direct-bootstrap descriptors. */
+function prepareFiles(files) {
+    const refs = [];
+    const directInputs = [];
     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`);
+            throw new Error(`AgentExecutor.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`);
+            throw new Error(`AgentExecutor.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`);
+                throw new Error(`AgentExecutor.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
+            const input = directInputFor({
+                role: "file",
+                index: i,
+                name: bundle.name,
+                contentHash: bundle.contentHash,
+                bytes: bundle.bytes,
+                contentType: "application/zip",
+                ...(bundle.mountPath ? { mountPath: bundle.mountPath } : {})
+            });
+            directInputs.push(input);
+            refs.push(bundle.mountPath !== undefined
                 ? {
                     kind: "asset",
-                    assetId: uploaded.assetId,
+                    assetId: input.assetId,
                     name: bundle.name,
                     mountPath: bundle.mountPath
                 }
                 : {
                     kind: "asset",
-                    assetId: uploaded.assetId,
+                    assetId: input.assetId,
                     name: bundle.name
                 });
             continue;
         }
-        out.push(ref);
+        refs.push(ref);
+    }
+    return { refs, directInputs };
+}
+function directInputFor(args) {
+    const sha256 = args.contentHash.startsWith("sha256:")
+        ? args.contentHash
+        : `sha256:${args.contentHash}`;
+    const hashHex = sha256.slice("sha256:".length);
+    if (!/^[0-9a-f]{64}$/.test(hashHex)) {
+        throw new Error(`AgentExecutor.submitRun: ${args.role}[${args.index}] content hash must be sha256:<64-hex>`);
+    }
+    return {
+        inputId: `input_${args.role}_${args.index}_${hashHex}`,
+        role: args.role,
+        assetId: `asset_${hashHex}`,
+        name: args.name,
+        sha256,
+        sizeBytes: args.bytes.byteLength,
+        contentType: args.contentType,
+        ...(args.mountPath ? { mountPath: args.mountPath } : {}),
+        bytes: args.bytes
+    };
+}
+function getSubmittedRunId(response) {
+    const id = response.id ?? response.runId;
+    if (typeof id !== "string" || id.length === 0) {
+        throw new Error("AgentExecutor.submitRun: submit response did not include a run id");
+    }
+    return id;
+}
+async function completeDirectBootstrap(args) {
+    const token = args.response.bootstrapToken;
+    const statusUrl = args.response.bootstrapStatusUrl;
+    if (typeof token !== "string" || token.length === 0 || typeof statusUrl !== "string" || statusUrl.length === 0) {
+        return;
+    }
+    const fetchImpl = args.fetch ?? globalThis.fetch.bind(globalThis);
+    const useNodeTransport = args.fetch === undefined;
+    const deadline = bootstrapDeadline(args.response.bootstrapExpiresAt);
+    let target;
+    try {
+        target = resolveBootstrapReady(args.response) ?? await pollBootstrapReady({
+            fetchImpl,
+            statusUrl,
+            token,
+            deadline,
+            ...(args.signal ? { signal: args.signal } : {})
+        });
+        for (const input of args.directInputs) {
+            await uploadDirectInput({
+                fetchImpl,
+                target,
+                token,
+                input,
+                deadline,
+                useNodeTransport,
+                ...(args.signal ? { signal: args.signal } : {})
+            });
+        }
+        await commitDirectInputs({
+            fetchImpl,
+            target,
+            token,
+            inputs: args.directInputs,
+            deadline,
+            useNodeTransport,
+            ...(args.hasRunAcceptedBootstrap ? { hasRunAcceptedBootstrap: args.hasRunAcceptedBootstrap } : {}),
+            ...(args.signal ? { signal: args.signal } : {})
+        });
+    }
+    catch (err) {
+        await abortDirectBootstrap({
+            fetchImpl,
+            token,
+            statusUrl,
+            ...(target ? { target } : {}),
+            ...(args.signal ? { signal: args.signal } : {})
+        }).catch(() => undefined);
+        throw err;
+    }
+}
+async function pollBootstrapReady(args) {
+    while (!args.signal?.aborted) {
+        if (Date.now() >= args.deadline) {
+            throw new Error("AgentExecutor.submitRun: bootstrap target did not become ready before it expired");
+        }
+        const res = await args.fetchImpl(args.statusUrl, {
+            method: "GET",
+            headers: { authorization: `Bearer ${args.token}`, accept: "application/json" },
+            ...(args.signal ? { signal: args.signal } : {})
+        });
+        if (res.ok) {
+            const body = await res.json();
+            const ready = resolveBootstrapReady(body);
+            if (ready)
+                return ready;
+        }
+        else if (![202, 404, 425].includes(res.status)) {
+            const detail = await res.text().catch(() => "");
+            throw new Error(`AgentExecutor.submitRun: bootstrap status failed with ${res.status}` +
+                (detail ? `: ${detail.slice(0, 300)}` : ""));
+        }
+        await sleep(250, args.signal);
+    }
+    throw new Error("AgentExecutor.submitRun: aborted");
+}
+function resolveBootstrapReady(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const record = value;
+    const base = typeof record.uploadBaseUrl === "string"
+        ? record.uploadBaseUrl
+        : typeof record.bootstrapUploadBaseUrl === "string"
+            ? record.bootstrapUploadBaseUrl
+            : undefined;
+    if (!base)
+        return undefined;
+    const routingHeaders = isStringRecord(record.routingHeaders) ? record.routingHeaders : undefined;
+    return {
+        uploadBaseUrl: stripTrailingSlash(base),
+        ...(routingHeaders ? { routingHeaders } : {}),
+        ...(typeof record.abortUrl === "string" ? { abortUrl: record.abortUrl } : {}),
+        ...(typeof record.commitUrl === "string" ? { commitUrl: record.commitUrl } : {})
+    };
+}
+async function uploadDirectInput(args) {
+    let backoffMs = DIRECT_BOOTSTRAP_INITIAL_BACKOFF_MS;
+    let lastError;
+    const uploadUrl = `${args.target.uploadBaseUrl}/inputs/${encodeURIComponent(args.input.inputId)}`;
+    while (!args.signal?.aborted) {
+        if (Date.now() >= args.deadline) {
+            throw lastError ?? new Error("AgentExecutor.submitRun: bootstrap input upload did not complete before it expired");
+        }
+        let res;
+        try {
+            res = await directBootstrapFetch({
+                fetchImpl: args.fetchImpl,
+                url: uploadUrl,
+                deadline: args.deadline,
+                operation: `input upload for ${args.input.inputId}`,
+                useNodeTransport: args.useNodeTransport,
+                ...(args.signal ? { signal: args.signal } : {}),
+                init: {
+                    method: "PUT",
+                    headers: {
+                        authorization: `Bearer ${args.token}`,
+                        "content-type": args.input.contentType,
+                        "x-aex-input-sha256": args.input.sha256,
+                        "x-aex-input-size": String(args.input.sizeBytes),
+                        ...(args.target.routingHeaders ?? {})
+                    },
+                    body: args.input.bytes
+                }
+            });
+        }
+        catch (err) {
+            if (args.signal?.aborted)
+                throw err;
+            lastError = bootstrapNetworkError(`input upload for ${args.input.inputId}`, err);
+            backoffMs = await waitForBootstrapRetry(backoffMs, args.deadline, args.signal, lastError);
+            continue;
+        }
+        if (res.ok)
+            return;
+        const detail = await res.text().catch(() => "");
+        const err = new Error(`AgentExecutor.submitRun: bootstrap input upload failed for ${args.input.inputId} ` +
+            `(status ${res.status})${detail ? `: ${detail.slice(0, 300)}` : ""}`);
+        if (!DIRECT_BOOTSTRAP_RETRY_STATUSES.has(res.status)) {
+            throw err;
+        }
+        lastError = err;
+        backoffMs = await waitForBootstrapRetry(backoffMs, args.deadline, args.signal, lastError);
     }
-    return out;
+    throw lastError ?? new Error("AgentExecutor.submitRun: aborted");
+}
+async function waitForBootstrapRetry(backoffMs, deadline, signal, lastError) {
+    const remainingMs = deadline - Date.now();
+    if (remainingMs <= 0)
+        throw lastError;
+    await sleep(Math.min(backoffMs, remainingMs), signal);
+    return Math.min(backoffMs * 2, DIRECT_BOOTSTRAP_MAX_BACKOFF_MS);
+}
+async function directBootstrapFetch(args) {
+    const remainingMs = args.deadline - Date.now();
+    if (remainingMs <= 0) {
+        throw new Error(`AgentExecutor.submitRun: bootstrap ${args.operation} did not complete before it expired`);
+    }
+    const timeoutMs = Math.min(DIRECT_BOOTSTRAP_ATTEMPT_TIMEOUT_MS, remainingMs);
+    if (args.useNodeTransport) {
+        return nodeDirectBootstrapFetch({
+            url: args.url,
+            init: args.init,
+            timeoutMs,
+            operation: args.operation,
+            ...(args.hasRunAcceptedBootstrap ? { hasRunAcceptedBootstrap: args.hasRunAcceptedBootstrap } : {}),
+            ...(args.signal ? { signal: args.signal } : {})
+        });
+    }
+    const controller = new AbortController();
+    const onAbort = () => controller.abort();
+    args.signal?.addEventListener("abort", onAbort, { once: true });
+    const fetchPromise = args.fetchImpl(args.url, { ...args.init, signal: controller.signal });
+    fetchPromise.catch(() => undefined);
+    let timer;
+    const timeoutPromise = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => {
+            controller.abort();
+            reject(new Error(`AgentExecutor.submitRun: bootstrap ${args.operation} timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+    });
+    try {
+        return await Promise.race([fetchPromise, timeoutPromise]);
+    }
+    catch (err) {
+        if (args.signal?.aborted)
+            throw err;
+        throw err;
+    }
+    finally {
+        clearTimeout(timer);
+        args.signal?.removeEventListener("abort", onAbort);
+    }
+}
+async function nodeDirectBootstrapFetch(args) {
+    const url = new URL(args.url);
+    const requestImpl = url.protocol === "http:" ? httpRequest : url.protocol === "https:" ? httpsRequest : undefined;
+    if (!requestImpl) {
+        throw new Error(`AgentExecutor.submitRun: bootstrap ${args.operation} URL must use http or https`);
+    }
+    return await new Promise((resolve, reject) => {
+        let settled = false;
+        let timer;
+        let activeResponse;
+        let acceptedPollStarted = false;
+        const requestHeaders = normalizeBootstrapRequestHeaders(args.init.headers);
+        if (!hasHeader(requestHeaders, "connection")) {
+            requestHeaders.connection = "close";
+        }
+        const request = requestImpl(url, {
+            method: args.init.method ?? "GET",
+            headers: requestHeaders,
+            agent: false
+        }, (res) => {
+            activeResponse = res;
+            const chunks = [];
+            res.on("data", (chunk) => {
+                chunks.push(typeof chunk === "string" ? new TextEncoder().encode(chunk) : new Uint8Array(chunk));
+            });
+            res.on("end", () => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                activeResponse = undefined;
+                request.destroy();
+                resolve(new Response(concatUint8Arrays(chunks), {
+                    status: res.statusCode ?? 599,
+                    statusText: res.statusMessage ?? "",
+                    headers: normalizeBootstrapResponseHeaders(res.headers)
+                }));
+            });
+            res.on("error", fail);
+        });
+        function cleanup() {
+            if (timer)
+                clearTimeout(timer);
+            args.signal?.removeEventListener("abort", onAbort);
+        }
+        function fail(err) {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            activeResponse?.destroy(err);
+            request.destroy(err);
+            reject(err);
+        }
+        function timeoutError() {
+            return new Error(`AgentExecutor.submitRun: bootstrap ${args.operation} timed out after ${args.timeoutMs}ms`);
+        }
+        function onAbort() {
+            fail(new Error(`AgentExecutor.submitRun: bootstrap ${args.operation} aborted`));
+        }
+        function startAcceptedPoll() {
+            if (!args.hasRunAcceptedBootstrap || acceptedPollStarted)
+                return;
+            acceptedPollStarted = true;
+            void pollAcceptedBootstrapAfterRequestFinish({
+                check: args.hasRunAcceptedBootstrap,
+                isSettled: () => settled,
+                ...(args.signal ? { signal: args.signal } : {})
+            })
+                .then((accepted) => {
+                if (!accepted || settled)
+                    return;
+                settled = true;
+                cleanup();
+                activeResponse?.destroy();
+                request.destroy();
+                resolve(new Response(JSON.stringify({ ok: true }), {
+                    status: 200,
+                    headers: { "content-type": "application/json" }
+                }));
+            })
+                .catch(fail);
+        }
+        timer = setTimeout(() => fail(timeoutError()), args.timeoutMs);
+        request.setTimeout(args.timeoutMs, () => fail(timeoutError()));
+        request.on("error", fail);
+        request.on("finish", startAcceptedPoll);
+        args.signal?.addEventListener("abort", onAbort, { once: true });
+        try {
+            const body = normalizeBootstrapRequestBody(args.init.body);
+            if (body !== undefined)
+                request.write(body);
+            request.end();
+            startAcceptedPoll();
+        }
+        catch (err) {
+            fail(err instanceof Error ? err : new Error(String(err)));
+        }
+    });
+}
+async function pollAcceptedBootstrapAfterRequestFinish(args) {
+    while (!args.isSettled()) {
+        if (await checkRunAcceptedBootstrap(args.check))
+            return true;
+        await sleep(250, args.signal);
+    }
+    return false;
+}
+function normalizeBootstrapRequestHeaders(headers) {
+    const result = {};
+    if (!headers)
+        return result;
+    if (headers instanceof Headers) {
+        headers.forEach((value, key) => {
+            result[key] = value;
+        });
+        return result;
+    }
+    if (Array.isArray(headers)) {
+        for (const [key, value] of headers)
+            result[key] = value;
+        return result;
+    }
+    for (const [key, value] of Object.entries(headers)) {
+        if (value !== undefined)
+            result[key] = String(value);
+    }
+    return result;
+}
+function hasHeader(headers, name) {
+    const normalized = name.toLowerCase();
+    return Object.keys(headers).some((key) => key.toLowerCase() === normalized);
+}
+function normalizeBootstrapResponseHeaders(headers) {
+    const result = new Headers();
+    for (const [key, value] of Object.entries(headers)) {
+        if (value === undefined)
+            continue;
+        if (Array.isArray(value)) {
+            for (const item of value)
+                result.append(key, item);
+        }
+        else {
+            result.set(key, value);
+        }
+    }
+    return result;
+}
+function normalizeBootstrapRequestBody(body) {
+    if (body === null || body === undefined)
+        return undefined;
+    if (typeof body === "string")
+        return body;
+    if (body instanceof Uint8Array)
+        return body;
+    if (body instanceof ArrayBuffer)
+        return new Uint8Array(body);
+    if (ArrayBuffer.isView(body))
+        return new Uint8Array(body.buffer, body.byteOffset, body.byteLength);
+    if (body instanceof URLSearchParams)
+        return body.toString();
+    throw new Error("AgentExecutor.submitRun: unsupported bootstrap request body type");
+}
+function concatUint8Arrays(chunks) {
+    const total = chunks.reduce((sum, chunk) => sum + chunk.byteLength, 0);
+    const result = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        result.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return result;
+}
+function bootstrapNetworkError(operation, value) {
+    const message = value instanceof Error ? value.message : String(value);
+    return new Error(`AgentExecutor.submitRun: bootstrap ${operation} failed: ${message}`);
+}
+async function commitDirectInputs(args) {
+    const commitUrl = args.target.commitUrl ?? `${args.target.uploadBaseUrl}/commit`;
+    let backoffMs = DIRECT_BOOTSTRAP_INITIAL_BACKOFF_MS;
+    let lastError;
+    while (!args.signal?.aborted) {
+        if (Date.now() >= args.deadline) {
+            throw lastError ?? new Error("AgentExecutor.submitRun: bootstrap commit did not complete before it expired");
+        }
+        let res;
+        try {
+            res = await directBootstrapFetch({
+                fetchImpl: args.fetchImpl,
+                url: commitUrl,
+                deadline: args.deadline,
+                operation: "commit",
+                useNodeTransport: args.useNodeTransport,
+                ...(args.hasRunAcceptedBootstrap ? { hasRunAcceptedBootstrap: args.hasRunAcceptedBootstrap } : {}),
+                ...(args.signal ? { signal: args.signal } : {}),
+                init: {
+                    method: "POST",
+                    headers: {
+                        authorization: `Bearer ${args.token}`,
+                        "content-type": "application/json",
+                        accept: "application/json",
+                        ...(args.target.routingHeaders ?? {})
+                    },
+                    body: JSON.stringify({
+                        inputs: args.inputs.map((input) => ({
+                            inputId: input.inputId,
+                            sha256: input.sha256,
+                            sizeBytes: input.sizeBytes
+                        }))
+                    })
+                }
+            });
+        }
+        catch (err) {
+            if (args.signal?.aborted)
+                throw err;
+            lastError = bootstrapNetworkError("commit", err);
+            if (await checkRunAcceptedBootstrap(args.hasRunAcceptedBootstrap))
+                return;
+            backoffMs = await waitForBootstrapRetry(backoffMs, args.deadline, args.signal, lastError);
+            continue;
+        }
+        if (res.ok)
+            return;
+        const detail = await res.text().catch(() => "");
+        const err = new Error(`AgentExecutor.submitRun: bootstrap commit failed with ${res.status}` +
+            (detail ? `: ${detail.slice(0, 300)}` : ""));
+        if (!DIRECT_BOOTSTRAP_RETRY_STATUSES.has(res.status)) {
+            throw err;
+        }
+        lastError = err;
+        if (await checkRunAcceptedBootstrap(args.hasRunAcceptedBootstrap))
+            return;
+        backoffMs = await waitForBootstrapRetry(backoffMs, args.deadline, args.signal, lastError);
+    }
+    throw lastError ?? new Error("AgentExecutor.submitRun: aborted");
+}
+async function checkRunAcceptedBootstrap(check) {
+    if (!check)
+        return false;
+    return await check().catch(() => false);
+}
+function hasRunAcceptedBootstrap(run) {
+    if (run.status === "succeeded" || run.status === "cancelled" || run.status === "timed_out")
+        return true;
+    if (run.status === "failed")
+        return run.terminalAt !== undefined && run.terminalAt !== null;
+    return run.status === "running" || run.status === "provider_running";
+}
+async function abortDirectBootstrap(args) {
+    const abortUrl = args.target?.abortUrl ?? `${args.statusUrl.replace(/\/status$/, "")}/abort`;
+    await args.fetchImpl(abortUrl, {
+        method: "POST",
+        headers: {
+            authorization: `Bearer ${args.token}`,
+            accept: "application/json",
+            ...(args.target?.routingHeaders ?? {})
+        },
+        ...(args.signal ? { signal: args.signal } : {})
+    });
+}
+function bootstrapDeadline(expiresAt) {
+    if (typeof expiresAt === "string") {
+        const parsed = Date.parse(expiresAt);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    return Date.now() + 60_000;
+}
+function isStringRecord(value) {
+    return Boolean(value &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        Object.values(value).every((entry) => typeof entry === "string"));
+}
+function stripTrailingSlash(s) {
+    return s.endsWith("/") ? s.slice(0, -1) : s;
 }
 function mergeMcpServers(inputs, explicitSecrets) {
     const submissionMcpServers = [];
@@ -813,14 +1270,14 @@ function mergeMcpServers(inputs, explicitSecrets) {
     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`);
+            throw new Error(`AgentExecutor.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}"]`);
+                throw new Error(`AgentExecutor.submitRun: mcpServers[${i}].url conflicts with secrets.mcpServers["${secret.name}"]`);
             }
             secretByName.set(secret.name, secret);
         }
@@ -848,7 +1305,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 Error(`AexClient.submitRun: proxyEndpoint "${entry.name}" auth type conflicts ` +
+            throw new Error(`AgentExecutor.submitRun: proxyEndpoint "${entry.name}" auth type conflicts ` +
                 `with secrets.proxyEndpointAuth (instance=${entry.value.type}, secrets=${existing.value.type})`);
         }
         byName.set(entry.name, entry);