@aexhq/sdk 0.29.0 → 0.31.0

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_RUN_PROVIDER, HttpClient, RunConfigValidationError, RunStateError, SecretString, isRunSettled, operations, 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";
@@ -55,18 +55,6 @@ export class SkillsClient {
     findByName(name) {
         return operations.findSkillByName(this.#http, name);
     }
-    /**
-     * Internal: post a pre-bundled skill zip to the BFF. Only
-     * `Skill.upload` calls this. NOT part of the public API.
-     */
-    async _uploadSkillBundle(args) {
-        return operations.createSkillBundle(this.#http, {
-            name: args.name,
-            body: args.body,
-            contentType: "application/zip",
-            filename: `${args.name}.zip`
-        });
-    }
 }
 /**
  * Workspace AgentsMd admin operations exposed under `client.agentsMd`.
@@ -230,21 +218,6 @@ export class AgentExecutor {
         this.files = new FilesClient(this.#http);
         this.secrets = new SecretsClient(this.#http);
     }
-    /**
-     * Internal: forwards to `SkillsClient._uploadSkillBundle`. NOT part of
-     * the public API.
-     *
-     * NOTE (tech-debt): this is part of the legacy workspace-skill upload
-     * surface (`SkillsClient` + `operations.createSkillBundle` + the TUS
-     * chunked path in asset-upload.ts). The live submit path materializes
-     * inline skills via `uploadAsset` instead; `Skill.upload(client)`
-     * pre-stages a draft explicitly for reuse. This surface is retained
-     * pending a deliberate deprecation pass (it still threads into the CLI
-     * host commands), tracked in the remediation plan as item 4a.
-     */
-    async _uploadSkillBundle(args) {
-        return this.skills._uploadSkillBundle(args);
-    }
     /**
      * Internal: an `AgentsMd.upload(this)` shortcut that bypasses
      * `client.agentsMd` indirection. Forwarded to
@@ -286,17 +259,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,8 +358,9 @@ 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");
         }
+        assertNoRemovedSubmitFields(options);
         // A model maps to one or more upstream providers (see MODEL_PROVIDER_IDS).
         // `providersForModel` returns the supported providers in priority order, or
         // `[]` for an unknown model string (the model check below then rejects it).
@@ -327,43 +370,20 @@ 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");
-        }
+        validateSubmitCredentials(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);
-        // Validate the runtime selector before any network I/O — inline drafts
-        // are uploaded below, so an invalid runtime must reject first rather than
-        // leak an asset upload.
-        if (options.runtime !== undefined &&
-            !RUNTIME_KINDS.includes(options.runtime)) {
-            throw new AexError("RUNTIME_UNSUPPORTED", `AgentExecutor.submit: runtime must be one of: ${RUNTIME_KINDS.join(", ")} ` +
-                `(got ${JSON.stringify(options.runtime)})`);
-        }
-        if (options.region !== undefined &&
-            !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
         // (shape + positivity + allow-list), failing fast before any asset upload.
         // Normalizes an all-absent override (e.g. `{}`) away.
@@ -383,7 +403,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,
@@ -436,12 +456,6 @@ export class AgentExecutor {
             // shared parser still defaults to `anthropic` when callers omit
             // the field entirely, but the SDK has resolved it by here.
             provider,
-            ...(credentialMode !== DEFAULT_CREDENTIAL_MODE ? { credentialMode } : {}),
-            // `runtime` is optional on the wire — absent means let the
-            // dispatcher auto-route. Only emit it when the caller asked for
-            // a specific runtime so the wire shape stays minimal.
-            ...(options.runtime ? { runtime: options.runtime } : {}),
-            ...(options.region ? { region: options.region } : {}),
             submission,
             ...(options.runtimeSize ? { runtimeSize: options.runtimeSize } : {}),
             ...(options.timeout ? { timeout: options.timeout } : {}),
@@ -483,6 +497,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
@@ -526,7 +594,7 @@ export class AgentExecutor {
     }
     /**
      * Stream the unified {@link AexEvent} envelope live over the coordinator
-     * WebSocket. The Worker's ticket broker authorizes the connection (workspace
+     * WebSocket. The hosted API's ticket broker authorizes the connection (workspace
      * token → short-lived coordinator ticket); the shared client replays from
      * the cursor, tails live, and resumes exactly-once across reconnects. The
      * ticket is re-minted on each (re)connect so a long run never outlives it.
@@ -714,6 +782,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 +865,41 @@ 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];
 }
+function assertNoRemovedSubmitFields(options) {
+    const record = options;
+    for (const field of ["credentialMode", "runtime", "region", "apiKey", "credentials"]) {
+        if (Object.prototype.hasOwnProperty.call(record, field)) {
+            throw new RunConfigValidationError(`AgentExecutor.submit: ${field} is not a supported option; use the managed path with secrets.apiKeys[provider].`);
+        }
+    }
+    const secrets = record.secrets;
+    if (secrets && typeof secrets === "object" && !Array.isArray(secrets) && Object.prototype.hasOwnProperty.call(secrets, "apiKey")) {
+        throw new RunConfigValidationError("AgentExecutor.submit: secrets.apiKey is not supported; use secrets.apiKeys[provider].");
+    }
+}
+function validateSubmitCredentials(options, provider) {
+    if (options.parentRunId) {
+        return;
+    }
+    const key = options.secrets?.apiKeys?.[provider];
+    if (typeof key !== "string" || key.length === 0) {
+        throw new RunConfigValidationError(`AgentExecutor.submit: a provider API key is required — pass secrets.apiKeys[${JSON.stringify(provider)}].`);
+    }
+}
 function postHookForWire(input) {
     if (input === undefined || typeof input.command !== "string" || input.command.trim().length === 0) {
         return undefined;
@@ -835,31 +928,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 +988,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 +998,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 +1020,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 +1046,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 +1070,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 +1083,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 +1118,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);