@aexhq/sdk 0.29.0 → 0.30.0

package/dist/cli.mjs.sha256

@@ -1 +1 @@
-03e2640ecfc2afaed33effd74cb0fb3cea62e049193e566c16eb3d80340ddfff  cli.mjs
+88682d1f64442fabb34e7f3645f950c2a109b192183b100cd75dbaf92fd8f385  cli.mjs

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { HttpClient, SecretString, type AexEvent, type AgentsMdRecord, type CredentialMode, type DebugSink, type FetchLike, type FileRecord, type Output, type OutputFileType, type OutputLink, type OutputLinkOptions, type OutputQuery, type OutputText, type OutputMode, type ReadOutputTextOptions, type RunListPage, type RunListQuery, type PlatformEnvironmentInput, type PlatformSubmission, type PlatformInlineSecrets, type PlatformProxyEndpoint, type PlatformProxyEndpointAuth, type PlatformPostHookInput, type Run, type RunModel, type RunEvent, type RunLimits, type RunWebhookDelivery, type RunProvider, type Region, type SecretRecord, type SecretReveal, type RunUnit, type BuiltinToolName, type RuntimeSize, type RuntimeKind, type Skill as SkillRecord, type WhoAmI } from "./_contracts/index.js";
+import { HttpClient, SecretString, type AexEvent, type AgentsMdRecord, type CredentialMode, type DebugSink, type FetchLike, type FileRecord, type Output, type OutputFileType, type OutputLink, type OutputLinkOptions, type OutputQuery, type OutputText, type OutputMode, type ReadOutputTextOptions, type RunListPage, type RunListQuery, type OutputSearchQuery, type OutputSearchPage, type PlatformEnvironmentInput, type PlatformSubmission, type PlatformInlineSecrets, type PlatformProxyEndpoint, type PlatformProxyEndpointAuth, type PlatformPostHookInput, type Run, type RunModel, type RunEvent, type RunTrace, type UsageSummary, type RunLimits, type RunWebhookDelivery, type RunProvider, type Region, type SecretRecord, type SecretReveal, type RunUnit, type BuiltinToolName, type RuntimeSize, type RuntimeKind, type Skill as SkillRecord, type WhoAmI } from "./_contracts/index.js";
 import { AgentsMd } from "./agents-md.js";
 import { type UploadedAsset } from "./asset-upload.js";
 import { File } from "./file.js";
@@ -40,8 +40,9 @@ export interface AgentExecutorOptions {
  *     secret is bundled into the constructor and split into
  *     `secrets.proxyEndpointAuth` server-side; the public submission
  *     only carries the declaration (`{ name, baseUrl, authShape, … }`).
- *   - `secrets.apiKey` or `secrets.apiKeys[provider]` — REQUIRED: the provider
- *     key for the selected provider. `apiKeys` MAY carry keys for additional
+ *   - `apiKey` / `credentials` / `secrets` — the BYOK provider key(s). A key for
+ *     the selected provider is REQUIRED; the simplest call passes just `apiKey`.
+ *     Use `credentials` (or `secrets.apiKeys`) to carry keys for additional
  *     providers so subagents spawned with a different-family model can use them
  *     (the child inherits the parent's keys server-side). The platform never
  *     holds a long-lived provider key on your behalf.
@@ -171,7 +172,26 @@ export interface SubmitOptions {
      * typing UIs.
      */
     readonly outputMode?: OutputMode;
-    readonly secrets: PlatformInlineSecrets;
+    /**
+     * Single-provider BYOK key sugar — the key for the run's selected `provider`.
+     * The simplest call passes just `apiKey` (no nested `secrets` envelope). When
+     * several sources name a key for the same provider they must agree (else submit
+     * throws); resolution precedence is
+     * `secrets.apiKeys[provider] ?? secrets.apiKey ?? credentials[provider] ?? apiKey`.
+     */
+    readonly apiKey?: string;
+    /**
+     * Multi-provider BYOK key map — the clean way to supply keys for more than one
+     * provider (e.g. so a subagent spawned with a different-family model inherits a
+     * key server-side). Folded into the `secrets.apiKeys` wire shape.
+     */
+    readonly credentials?: Partial<Record<RunProvider, string>>;
+    /**
+     * Advanced inline secrets bundle (per-provider `apiKeys`, MCP headers, proxy
+     * auth, env secrets). OPTIONAL — the common case uses `apiKey` / `credentials`.
+     * `secrets.apiKey` / `secrets.apiKeys` keep working unchanged.
+     */
+    readonly secrets?: PlatformInlineSecrets;
     readonly idempotencyKey?: string;
     /**
      * Lineage parent (agent-session §9). When set, the server admits this run as
@@ -205,6 +225,42 @@ export interface SubmitOptions {
 }
 /** @deprecated Renamed to {@link SubmitOptions}. Kept for one release. */
 export type SubmitRunOptions = SubmitOptions;
+/**
+ * The settle-consistent result of {@link AgentExecutor.run} / `runAndCollect`:
+ * the terminal run record plus its settle-bracketed events, decoded trace,
+ * assistant text, and captured outputs — everything a "do it and give me the
+ * result" caller needs without hand-rolling a poll loop.
+ */
+export interface RunResult {
+    readonly runId: string;
+    /** The full terminal run record (status, costTelemetry, timings). */
+    readonly run: Run;
+    readonly status: string;
+    /** `true` when `status === "succeeded"`. */
+    readonly ok: boolean;
+    /** The assistant's final text (decoded over the settled events). */
+    readonly text: string;
+    /** The settle-bracketed event stream (RUN_STARTED … terminal). */
+    readonly events: readonly RunEvent[];
+    /** Decoded view of the events: tool calls + usage + assistant text. */
+    readonly trace: RunTrace;
+    /** The run's captured output files. */
+    readonly outputs: readonly Output[];
+    /** Aggregate token usage when the deployment exposes it on the record. */
+    readonly usage?: UsageSummary;
+    /** Settle-time showback estimate (USD), from `run.costTelemetry`. */
+    readonly costUsd?: number;
+    /** The run's error message when `!ok`. */
+    readonly error?: string;
+}
+/** Options for {@link AgentExecutor.run} / `runAndCollect`. */
+export interface RunCollectOptions {
+    /** Overall wait budget (ms) for the run to reach a terminal record. */
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+    /** Throw a {@link RunStateError} when the run does not succeed. Default false. */
+    readonly throwOnFailure?: boolean;
+}
 export interface StreamEventsOptions {
     /** Poll interval in ms for the `RunEvent` snapshot loop. Default 1000. */
     readonly intervalMs?: number;
@@ -463,15 +519,26 @@ export declare class AgentExecutor {
         readonly contentType?: string;
     }): Promise<UploadedAsset>;
     /**
-     * Submit a run and wait until its RECORD is terminal — the settle-consistent
-     * "do it and give me the result" primitive. Returns the final `Run`, so on
-     * resolve a subsequent `getRun`/`listOutputs` is guaranteed consistent (it
-     * polls `getRun` via {@link waitForRun}, NOT the RUN_FINISHED event, which the
-     * runner emits before the platform commits the record). For long-running flows
-     * that need live events, prefer `submit` + `streamEnvelopes(runId, {
-     * settleConsistent: true })`, or `submit` + `stream(runId)` + `wait(runId)`.
+     * Submit a run, wait until its RECORD is terminal, and collect the full
+     * {@link RunResult} — the settle-consistent "do it and give me the result"
+     * primitive. Folds the poll loop every consumer hand-rolled into one call:
+     * submit → {@link waitForRun} (polls `getRun`, NOT the earlier RUN_FINISHED
+     * event) → poll `listEvents` until the snapshot is settle-bracketed
+     * (RUN_STARTED + a terminal event present) → `listOutputs` → decode the trace
+     * and assistant text. On resolve, `getRun`/`listOutputs` are guaranteed
+     * consistent.
+     *
+     * Uses polling (portable across backends), NOT the coordinator WebSocket. By
+     * default a failed run resolves with `ok: false` and a populated `error`; pass
+     * `{ throwOnFailure: true }` to throw instead. For live events prefer `submit`
+     * + `streamEnvelopes(runId, { settleConsistent: true })`.
+     */
+    run(options: SubmitOptions, opts?: RunCollectOptions): Promise<RunResult>;
+    /**
+     * Explicit, discoverable alias for {@link run}: submit, wait, and collect the
+     * full {@link RunResult} in one call.
      */
-    run(options: SubmitOptions): Promise<Run>;
+    runAndCollect(options: SubmitOptions, opts?: RunCollectOptions): Promise<RunResult>;
     /**
      * Submit a run and return its run id immediately. Use that id with
      * `wait`, `stream`, `outputs`, `download`, `cancel`, or `delete`.
@@ -503,6 +570,18 @@ export declare class AgentExecutor {
      * `listOutputs` / `readOutputText` to reach any run's deliverables.
      */
     listRuns(query?: RunListQuery): Promise<RunListPage>;
+    /**
+     * 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.
+     */
+    searchOutputs(query?: OutputSearchQuery): Promise<OutputSearchPage>;
     /**
      * Fetch the self-contained `RunUnit`: parsed submission inputs,
      * attempts, indexed events (inline + cursor for the tail), raw

package/dist/client.js

@@ -1,4 +1,4 @@
-import { AexError, DEFAULT_CREDENTIAL_MODE, DEFAULT_RUN_PROVIDER, HttpClient, REGIONS, RUNTIME_KINDS, RunStateError, SecretString, isRunSettled, operations, parseCredentialMode, providersForModel, streamCoordinatorEvents, parseRunLimits, BUILTIN_TOOL_NAMES, TERMINAL_RUN_STATUSES } from "./_contracts/index.js";
+import { AexError, DEFAULT_CREDENTIAL_MODE, DEFAULT_RUN_PROVIDER, HttpClient, REGIONS, RUNTIME_KINDS, RunConfigValidationError, RunStateError, SecretString, isRunSettled, operations, parseCredentialMode, providersForModel, streamCoordinatorEvents, 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";
@@ -286,17 +286,86 @@ export class AgentExecutor {
         });
     }
     /**
-     * Submit a run and wait until its RECORD is terminal — the settle-consistent
-     * "do it and give me the result" primitive. Returns the final `Run`, so on
-     * resolve a subsequent `getRun`/`listOutputs` is guaranteed consistent (it
-     * polls `getRun` via {@link waitForRun}, NOT the RUN_FINISHED event, which the
-     * runner emits before the platform commits the record). For long-running flows
-     * that need live events, prefer `submit` + `streamEnvelopes(runId, {
-     * settleConsistent: true })`, or `submit` + `stream(runId)` + `wait(runId)`.
+     * Submit a run, wait until its RECORD is terminal, and collect the full
+     * {@link RunResult} — the settle-consistent "do it and give me the result"
+     * primitive. Folds the poll loop every consumer hand-rolled into one call:
+     * submit → {@link waitForRun} (polls `getRun`, NOT the earlier RUN_FINISHED
+     * event) → poll `listEvents` until the snapshot is settle-bracketed
+     * (RUN_STARTED + a terminal event present) → `listOutputs` → decode the trace
+     * and assistant text. On resolve, `getRun`/`listOutputs` are guaranteed
+     * consistent.
+     *
+     * Uses polling (portable across backends), NOT the coordinator WebSocket. By
+     * default a failed run resolves with `ok: false` and a populated `error`; pass
+     * `{ throwOnFailure: true }` to throw instead. For live events prefer `submit`
+     * + `streamEnvelopes(runId, { settleConsistent: true })`.
      */
-    async run(options) {
+    async run(options, opts = {}) {
+        const signal = opts.signal ?? options.signal;
         const runId = await this.submit(options);
-        return this.waitForRun(runId, options.signal ? { signal: options.signal } : {});
+        const run = await this.waitForRun(runId, {
+            ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
+            ...(signal ? { signal } : {})
+        });
+        const events = await this.#collectSettledEvents(runId, signal);
+        const outputs = await this.listOutputs(runId);
+        const ok = run.status === "succeeded";
+        const costUsd = run.costTelemetry?.billedCostUsd;
+        const errorMessage = typeof run.errorMessage === "string" && run.errorMessage ? run.errorMessage : undefined;
+        const result = {
+            runId,
+            run,
+            status: run.status,
+            ok,
+            text: textOf(events),
+            events,
+            trace: summarizeRunTrace(events),
+            outputs,
+            ...(run.usage ? { usage: run.usage } : {}),
+            ...(typeof costUsd === "number" ? { costUsd } : {}),
+            ...(!ok && errorMessage ? { error: errorMessage } : {})
+        };
+        if (opts.throwOnFailure && !ok) {
+            throw new RunStateError(`AgentExecutor.run: run ${runId} ended ${run.status}${errorMessage ? `: ${errorMessage}` : ""}`, { runId, status: run.status });
+        }
+        return result;
+    }
+    /**
+     * Explicit, discoverable alias for {@link run}: submit, wait, and collect the
+     * full {@link RunResult} in one call.
+     */
+    runAndCollect(options, opts) {
+        return this.run(options, opts);
+    }
+    /**
+     * 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
@@ -316,7 +385,7 @@ export class AgentExecutor {
      */
     async submit(options) {
         if (!options || typeof options !== "object") {
-            throw new Error("AgentExecutor.submit: options is required");
+            throw new RunConfigValidationError("AgentExecutor.submit: options is required");
         }
         // A model maps to one or more upstream providers (see MODEL_PROVIDER_IDS).
         // `providersForModel` returns the supported providers in priority order, or
@@ -327,27 +396,23 @@ export class AgentExecutor {
         if (options.provider &&
             supportedProviders.length > 0 &&
             !supportedProviders.includes(options.provider)) {
-            throw new Error(`AgentExecutor.submit: provider ${JSON.stringify(options.provider)} is not available for ` +
+            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;
         const credentialMode = parseCredentialMode(options.credentialMode);
-        if (!options.secrets) {
-            throw new Error("AgentExecutor.submit: secrets is required");
-        }
-        // The BYOK provider key (for the selected `provider`) is required. The
-        // shared parser re-runs this check on the server; failing early here
-        // gives the caller a synchronous error before any network call.
-        const selectedProviderKey = options.secrets.apiKeys?.[provider] ?? options.secrets.apiKey;
-        if (typeof selectedProviderKey !== "string" || !selectedProviderKey) {
-            throw new Error("AgentExecutor.submit: secrets.apiKey is required");
-        }
+        // Resolve the BYOK key(s) across the top-level sugar (`apiKey`,
+        // `credentials`) and the advanced `secrets` bundle, folding everything into a
+        // single `apiKeys` map (the wire shape the platform reads). Validates the
+        // selected provider's key is present and that the sources don't disagree,
+        // failing synchronously before any network call.
+        const { foldedApiKeys } = resolveSubmitCredentials(options, provider);
         if (typeof options.model !== "string" || !options.model) {
-            throw new Error("AgentExecutor.submit: model is required");
+            throw new RunConfigValidationError("AgentExecutor.submit: model is required");
         }
         const prompt = normalisePrompt(options.prompt);
         const { endpoints: proxyEndpointDeclarations, auth: proxyEndpointAuthFromInstances } = splitProxyEndpoints(options.proxyEndpoints ?? []);
-        const mergedProxyAuth = mergeProxyEndpointAuth(proxyEndpointAuthFromInstances, options.secrets.proxyEndpointAuth ?? []);
+        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);
@@ -383,7 +448,7 @@ export class AgentExecutor {
         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 { submissionMcpServers, mergedMcpSecrets } = mergeMcpServers(options.mcpServers ?? [], options.secrets?.mcpServers ?? []);
         const outputCapture = outputsForWire(options.outputs);
         const submission = {
             model: options.model,
@@ -424,6 +489,9 @@ export class AgentExecutor {
         };
         const secrets = {
             ...options.secrets,
+            // Folded BYOK keys (sugar + secrets.apiKeys) override; omitted entirely
+            // when empty so a pure legacy `secrets.apiKey` submission stays unchanged.
+            ...(Object.keys(foldedApiKeys).length > 0 ? { apiKeys: foldedApiKeys } : {}),
             ...(mergedMcpSecrets.length > 0 ? { mcpServers: mergedMcpSecrets } : {}),
             ...(mergedProxyAuth.length > 0 ? { proxyEndpointAuth: mergedProxyAuth } : {}),
             ...(Object.keys(envSecretValues).length > 0 ? { envSecrets: envSecretValues } : {})
@@ -483,6 +551,60 @@ export class AgentExecutor {
     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
@@ -714,6 +836,10 @@ const TERMINAL_STATUSES = new Set(TERMINAL_RUN_STATUSES);
 function isTerminal(status) {
     return typeof status === "string" && TERMINAL_STATUSES.has(status);
 }
+/** Escape a literal string for safe interpolation into a RegExp. */
+function escapeRegExp(input) {
+    return input.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 function isOutputPathSelector(selector) {
     return Boolean(selector && typeof selector === "object" && "path" in selector);
 }
@@ -793,20 +919,64 @@ function generateIdempotencyKey() {
 function normalisePrompt(input) {
     if (typeof input === "string") {
         if (!input) {
-            throw new Error("AgentExecutor.submit: prompt must be a non-empty string");
+            throw new RunConfigValidationError("AgentExecutor.submit: prompt must be a non-empty string");
         }
         return [input];
     }
     if (!Array.isArray(input) || input.length === 0) {
-        throw new Error("AgentExecutor.submit: prompt must be a non-empty string or string array");
+        throw new RunConfigValidationError("AgentExecutor.submit: prompt must be a non-empty string or string array");
     }
     for (const segment of input) {
         if (typeof segment !== "string" || !segment) {
-            throw new Error("AgentExecutor.submit: prompt segments must be non-empty strings");
+            throw new RunConfigValidationError("AgentExecutor.submit: prompt segments must be non-empty strings");
         }
     }
     return [...input];
 }
+/**
+ * Resolve the BYOK provider key(s) for a submission across the top-level sugar
+ * (`apiKey`, `credentials`) and the advanced `secrets` bundle, folding them into
+ * one `apiKeys` map (the wire shape the platform reads). Per-provider precedence:
+ * `secrets.apiKeys[p] ?? secrets.apiKey ?? credentials[p] ?? apiKey`. Legacy
+ * `secrets.apiKey` is left in place (not folded) so a pure-legacy submission's
+ * wire shape is unchanged; the platform falls back to it for the selected
+ * provider. Throws synchronously when the selected provider has no key, or when
+ * the sources name DIFFERENT keys for it (a call-site mistake).
+ */
+function resolveSubmitCredentials(options, provider) {
+    const secrets = options.secrets;
+    const selectedCandidates = [
+        secrets?.apiKeys?.[provider],
+        secrets?.apiKey,
+        options.credentials?.[provider],
+        options.apiKey
+    ].filter((value) => typeof value === "string" && value.length > 0);
+    if (new Set(selectedCandidates).size > 1) {
+        throw new RunConfigValidationError(`AgentExecutor.submit: conflicting API keys for provider ${JSON.stringify(provider)} ` +
+            "(secrets.apiKeys / secrets.apiKey / credentials / apiKey disagree). Supply exactly one.");
+    }
+    if (selectedCandidates.length === 0) {
+        throw new RunConfigValidationError("AgentExecutor.submit: a provider API key is required — pass `apiKey`, " +
+            "`credentials[provider]`, `secrets.apiKey`, or `secrets.apiKeys[provider]`.");
+    }
+    // Fold in precedence order (lowest first; later writes win):
+    // apiKey (selected provider) < credentials < secrets.apiKeys.
+    const foldedApiKeys = {};
+    if (typeof options.apiKey === "string" && options.apiKey.length > 0) {
+        foldedApiKeys[provider] = options.apiKey;
+    }
+    for (const [p, key] of Object.entries(options.credentials ?? {})) {
+        if (typeof key === "string" && key.length > 0) {
+            foldedApiKeys[p] = key;
+        }
+    }
+    for (const [p, key] of Object.entries(secrets?.apiKeys ?? {})) {
+        if (typeof key === "string" && key.length > 0) {
+            foldedApiKeys[p] = key;
+        }
+    }
+    return { foldedApiKeys };
+}
 function postHookForWire(input) {
     if (input === undefined || typeof input.command !== "string" || input.command.trim().length === 0) {
         return undefined;
@@ -835,31 +1005,41 @@ function outputsForWire(outputs) {
         ...(outputs.maxFiles !== undefined ? { maxFiles: outputs.maxFiles } : {})
     };
 }
+/**
+ * Resolve a draft's asset id: reuse the cached id from a prior submit, otherwise
+ * upload the bytes and cache the result on the instance.
+ */
+async function resolveAssetId(entry, bundle, uploader) {
+    const cached = entry._cachedAssetId;
+    if (cached !== undefined) {
+        return cached;
+    }
+    const uploaded = await uploader({
+        bytes: bundle.bytes,
+        hash: bundle.contentHash,
+        contentType: "application/zip"
+    });
+    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 Error(`AgentExecutor.submit: skills[${i}] must be a Skill instance`);
-        }
-        if (entry.isConsumed) {
-            throw new Error(`AgentExecutor.submit: skills[${i}] was already consumed by a prior submit`);
+            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 Error(`AgentExecutor.submit: skills[${i}] is draft but has no bytes`);
+                throw new RunConfigValidationError(`AgentExecutor.submit: skills[${i}] is draft but has no bytes`);
             }
-            const uploaded = await uploader({
-                bytes: bundle.bytes,
-                hash: bundle.contentHash,
-                contentType: "application/zip"
-            });
+            const assetId = await resolveAssetId(entry, bundle, uploader);
             refs.push({
                 kind: "asset",
-                assetId: uploaded.assetId,
+                assetId,
                 name: bundle.name
             });
             continue;
@@ -885,7 +1065,7 @@ async function prepareTools(tools, uploader) {
         // A bare string is a builtin tool reference.
         if (typeof entry === "string") {
             if (!BUILTIN_TOOL_NAMES.includes(entry)) {
-                throw new Error(`AgentExecutor.submit: tools[${i}] (${JSON.stringify(entry)}) is not a builtin tool name; ` +
+                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(", ")}`);
             }
             if (!seenBuiltins.has(entry)) {
@@ -895,23 +1075,16 @@ async function prepareTools(tools, uploader) {
             continue;
         }
         if (!(entry instanceof Tool)) {
-            throw new Error(`AgentExecutor.submit: tools[${i}] must be a Tool instance or a builtin tool name`);
-        }
-        if (entry.isConsumed) {
-            throw new Error(`AgentExecutor.submit: tools[${i}] was already consumed by a prior submit`);
+            throw new RunConfigValidationError(`AgentExecutor.submit: tools[${i}] must be a Tool instance or a builtin tool name`);
         }
         const ref = entry.ref;
         if (ref.kind === "draft") {
             const bundle = entry._takeDraftBundle();
             if (!bundle) {
-                throw new Error(`AgentExecutor.submit: tools[${i}] is draft but has no bytes`);
+                throw new RunConfigValidationError(`AgentExecutor.submit: tools[${i}] is draft but has no bytes`);
             }
-            const uploaded = await uploader({
-                bytes: bundle.bytes,
-                hash: bundle.contentHash,
-                contentType: "application/zip"
-            });
-            refs.push({ ...bundle.ref, assetId: uploaded.assetId });
+            const assetId = await resolveAssetId(entry, bundle, uploader);
+            refs.push({ ...bundle.ref, assetId });
             continue;
         }
         refs.push(ref);
@@ -924,25 +1097,18 @@ async function prepareAgentsMd(agentsMds, uploader) {
     for (let i = 0; i < agentsMds.length; i++) {
         const entry = agentsMds[i];
         if (!(entry instanceof AgentsMd)) {
-            throw new Error(`AgentExecutor.submit: agentsMd[${i}] must be an AgentsMd instance`);
-        }
-        if (entry.isConsumed) {
-            throw new Error(`AgentExecutor.submit: agentsMd[${i}] was already consumed by a prior submit`);
+            throw new RunConfigValidationError(`AgentExecutor.submit: agentsMd[${i}] must be an AgentsMd instance`);
         }
         const ref = entry.ref;
         if (ref.kind === "draft") {
             const bundle = entry._takeDraftBundle();
             if (!bundle) {
-                throw new Error(`AgentExecutor.submit: agentsMd[${i}] is draft but has no bytes`);
+                throw new RunConfigValidationError(`AgentExecutor.submit: agentsMd[${i}] is draft but has no bytes`);
             }
-            const uploaded = await uploader({
-                bytes: bundle.bytes,
-                hash: bundle.contentHash,
-                contentType: "application/zip"
-            });
+            const assetId = await resolveAssetId(entry, bundle, uploader);
             refs.push({
                 kind: "asset",
-                assetId: uploaded.assetId,
+                assetId,
                 name: bundle.name
             });
             continue;
@@ -957,25 +1123,18 @@ async function prepareFiles(files, uploader) {
     for (let i = 0; i < files.length; i++) {
         const entry = files[i];
         if (!(entry instanceof File)) {
-            throw new Error(`AgentExecutor.submit: files[${i}] must be a File instance`);
-        }
-        if (entry.isConsumed) {
-            throw new Error(`AgentExecutor.submit: files[${i}] was already consumed by a prior submit`);
+            throw new RunConfigValidationError(`AgentExecutor.submit: files[${i}] must be a File instance`);
         }
         const ref = entry.ref;
         if (ref.kind === "draft") {
             const bundle = entry._takeDraftBundle();
             if (!bundle) {
-                throw new Error(`AgentExecutor.submit: files[${i}] is draft but has no bytes`);
+                throw new RunConfigValidationError(`AgentExecutor.submit: files[${i}] is draft but has no bytes`);
             }
-            const uploaded = await uploader({
-                bytes: bundle.bytes,
-                hash: bundle.contentHash,
-                contentType: "application/zip"
-            });
+            const assetId = await resolveAssetId(entry, bundle, uploader);
             refs.push({
                 kind: "asset",
-                assetId: uploaded.assetId,
+                assetId,
                 name: bundle.name,
                 mountPath: bundle.mountPath
             });
@@ -988,7 +1147,7 @@ async function prepareFiles(files, uploader) {
 function getSubmittedRunId(response) {
     const id = response.id ?? response.runId;
     if (typeof id !== "string" || id.length === 0) {
-        throw new Error("AgentExecutor.submit: submit response did not include a run id");
+        throw new RunStateError("AgentExecutor.submit: submit response did not include a run id");
     }
     return id;
 }
@@ -1001,14 +1160,14 @@ function mergeMcpServers(inputs, explicitSecrets) {
     for (let i = 0; i < inputs.length; i++) {
         const entry = inputs[i];
         if (!(entry instanceof McpServer)) {
-            throw new Error(`AgentExecutor.submit: mcpServers[${i}] must be an McpServer instance`);
+            throw new RunConfigValidationError(`AgentExecutor.submit: 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(`AgentExecutor.submit: mcpServers[${i}].url conflicts with secrets.mcpServers["${secret.name}"]`);
+                throw new RunConfigValidationError(`AgentExecutor.submit: mcpServers[${i}].url conflicts with secrets.mcpServers["${secret.name}"]`);
             }
             secretByName.set(secret.name, secret);
         }
@@ -1036,7 +1195,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(`AgentExecutor.submit: proxyEndpoint "${entry.name}" auth type conflicts ` +
+            throw new RunConfigValidationError(`AgentExecutor.submit: proxyEndpoint "${entry.name}" auth type conflicts ` +
                 `with secrets.proxyEndpointAuth (instance=${entry.value.type}, secrets=${existing.value.type})`);
         }
         byName.set(entry.name, entry);