@aexhq/sdk 0.28.1 → 0.30.0

package/dist/client.js

@@ -1,4 +1,4 @@
-import { AexError, DEFAULT_CREDENTIAL_MODE, DEFAULT_RUN_PROVIDER, HttpClient, RUN_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);
@@ -360,8 +425,8 @@ export class AgentExecutor {
                 `(got ${JSON.stringify(options.runtime)})`);
         }
         if (options.region !== undefined &&
-            !RUN_REGIONS.includes(options.region)) {
-            throw new AexError("RUN_CONFIG_INVALID", `AgentExecutor.submit: region must be one of: ${RUN_REGIONS.join(", ")} ` +
+            !REGIONS.includes(options.region)) {
+            throw new AexError("RUN_CONFIG_INVALID", `AgentExecutor.submit: region must be one of: ${REGIONS.join(", ")} ` +
                 `(got ${JSON.stringify(options.region)})`);
         }
         // Validate the per-run limits override with the SAME parser the server runs
@@ -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);