voratiq 0.1.0-beta.2 → 0.1.0-beta.21

package/dist/commands/run/shim/run-agent-shim.js

@@ -1,222 +1,7 @@
-import { spawn } from "node:child_process";
-import { readFile } from "node:fs/promises";
-import { dirname, isAbsolute, resolve as resolvePath } from "node:path";
+import { resolve as resolvePath } from "node:path";
 import { fileURLToPath } from "node:url";
-import { composeRestrictedEnvironment } from "../../../utils/env.js";
-import { GIT_AUTHOR_EMAIL, GIT_AUTHOR_NAME, GIT_COMMITTER_EMAIL, GIT_COMMITTER_NAME, } from "../../../utils/git.js";
-import { injectPromptArg } from "../argv.js";
-class ShimError extends Error {
-    exitCode;
-    constructor(message, exitCode = 1) {
-        super(message);
-        this.name = "ShimError";
-        this.exitCode = exitCode;
-    }
-}
-export async function main(argv = process.argv.slice(2)) {
-    try {
-        const { configPath } = parseArguments(argv);
-        const resolvedConfigPath = resolvePath(process.cwd(), configPath);
-        const manifest = await loadManifest(resolvedConfigPath);
-        const agentRoot = resolveAgentRoot(resolvedConfigPath);
-        const prompt = await loadPrompt(agentRoot, manifest.promptPath, resolvedConfigPath);
-        let agentArgv;
-        try {
-            agentArgv = injectPromptArg(manifest.argv, prompt);
-        }
-        catch (error) {
-            throw new ShimError(`Failed to inject prompt into argv: ${error instanceof Error ? error.message : String(error)}`);
-        }
-        const exitCode = await launchAgent({
-            manifest,
-            agentRoot,
-            argv: agentArgv,
-        });
-        return exitCode;
-    }
-    catch (error) {
-        if (error instanceof ShimError) {
-            logError(error.message);
-            return error.exitCode;
-        }
-        const message = error instanceof Error ? error.message : String(error);
-        logError(`Unexpected error: ${message}`);
-        return 1;
-    }
-}
-function parseArguments(args) {
-    let configPath;
-    for (let index = 0; index < args.length; index += 1) {
-        const token = args[index];
-        if (token === "--config") {
-            const next = args[index + 1];
-            if (!next) {
-                throw new ShimError("Missing value for --config option");
-            }
-            configPath = next;
-            index += 1;
-            continue;
-        }
-        throw new ShimError(`Unknown argument: ${token}`);
-    }
-    if (!configPath) {
-        throw new ShimError("Missing required --config <path> argument");
-    }
-    return { configPath };
-}
-async function loadManifest(configPath) {
-    let raw;
-    try {
-        raw = await readFile(configPath, "utf8");
-    }
-    catch (error) {
-        const detail = error instanceof Error ? error.message : String(error);
-        throw new ShimError(`Failed to read manifest at "${configPath}": ${detail}`);
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch (error) {
-        const detail = error instanceof Error ? error.message : String(error);
-        throw new ShimError(`Manifest JSON at "${configPath}" is invalid: ${detail}`);
-    }
-    return validateManifest(parsed, configPath);
-}
-function validateManifest(data, configPath) {
-    if (typeof data !== "object" || data === null) {
-        throw new ShimError(`Manifest at "${configPath}" must be a JSON object`);
-    }
-    const record = data;
-    const { binary, argv, promptPath, workspace, env } = record;
-    if (typeof binary !== "string" || binary.trim() === "") {
-        throw new ShimError(`Manifest at "${configPath}" is missing required string field "binary"`);
-    }
-    const manifestArgv = ensureStringArray({
-        value: argv,
-        field: "argv",
-        configPath,
-    });
-    if (typeof promptPath !== "string" || promptPath.trim() === "") {
-        throw new ShimError(`Manifest at "${configPath}" is missing required string field "promptPath"`);
-    }
-    if (typeof workspace !== "string" || workspace.trim() === "") {
-        throw new ShimError(`Manifest at "${configPath}" is missing required string field "workspace"`);
-    }
-    const manifestEnv = ensureEnvRecord({
-        value: env,
-        configPath,
-    });
-    return {
-        binary,
-        argv: manifestArgv,
-        promptPath,
-        workspace,
-        env: manifestEnv,
-    };
-}
-function ensureStringArray(options) {
-    const { value, field, configPath } = options;
-    if (!Array.isArray(value)) {
-        throw new ShimError(`Manifest at "${configPath}" must provide "${field}" as an array of strings`);
-    }
-    const result = [];
-    for (const token of value) {
-        if (typeof token !== "string") {
-            throw new ShimError(`Manifest at "${configPath}" must provide "${field}" as an array of strings`);
-        }
-        result.push(token);
-    }
-    return result;
-}
-function ensureEnvRecord(options) {
-    const { value, configPath } = options;
-    if (value === undefined) {
-        return {};
-    }
-    if (typeof value !== "object" || value === null || Array.isArray(value)) {
-        throw new ShimError(`Manifest at "${configPath}" must provide "env" as an object of string values`);
-    }
-    const result = {};
-    for (const [key, entry] of Object.entries(value)) {
-        if (typeof entry !== "string") {
-            throw new ShimError(`Manifest at "${configPath}" must provide "env" as an object of string values`);
-        }
-        result[key] = entry;
-    }
-    return result;
-}
-function resolveAgentRoot(configPath) {
-    return dirname(configPath);
-}
-async function loadPrompt(agentRoot, manifestPromptPath, configPath) {
-    const promptAbsolute = isAbsolute(manifestPromptPath)
-        ? manifestPromptPath
-        : resolvePath(agentRoot, manifestPromptPath);
-    try {
-        return await readFile(promptAbsolute, "utf8");
-    }
-    catch (error) {
-        const detail = error instanceof Error ? error.message : String(error);
-        throw new ShimError(`Failed to read prompt from "${promptAbsolute}" (manifest: "${configPath}", agentRoot: "${agentRoot}", promptPath: "${manifestPromptPath}"): ${detail}`);
-    }
-}
-async function launchAgent(options) {
-    const { manifest, agentRoot, argv } = options;
-    const binaryPath = isAbsolute(manifest.binary)
-        ? manifest.binary
-        : resolvePath(agentRoot, manifest.binary);
-    const workspacePath = isAbsolute(manifest.workspace)
-        ? manifest.workspace
-        : resolvePath(agentRoot, manifest.workspace);
-    const launchEnv = composeRestrictedEnvironment(manifest.env);
-    // Agent commits generated outside the sandbox reuse this persona via
-    // resolveSandboxPersona in src/commands/run/agents/lifecycle.ts.
-    const personaEnv = {
-        GIT_AUTHOR_NAME,
-        GIT_AUTHOR_EMAIL,
-        GIT_COMMITTER_NAME,
-        GIT_COMMITTER_EMAIL,
-        GIT_TERMINAL_PROMPT: "0",
-    };
-    for (const [key, value] of Object.entries(personaEnv)) {
-        if (launchEnv[key] === undefined) {
-            launchEnv[key] = value;
-        }
-    }
-    return await new Promise((resolve) => {
-        let resolved = false;
-        const child = spawn(binaryPath, argv, {
-            cwd: workspacePath,
-            env: launchEnv,
-            stdio: "inherit",
-        });
-        child.once("error", (error) => {
-            if (resolved) {
-                return;
-            }
-            resolved = true;
-            const detail = error instanceof Error ? error.message : String(error);
-            logError(`Failed to launch agent binary at "${binaryPath}": ${detail}`);
-            resolve(1);
-        });
-        child.once("exit", (code, signal) => {
-            if (resolved) {
-                return;
-            }
-            resolved = true;
-            if (signal) {
-                logError(`Agent terminated by signal ${signal}`);
-                resolve(1);
-                return;
-            }
-            resolve(code ?? 0);
-        });
-    });
-}
-function logError(message) {
-    console.error(`[voratiq] ${message}`);
-}
+import { main } from "../../../agents/runtime/shim/run-agent-shim.js";
+export { main };
 const modulePath = fileURLToPath(import.meta.url);
 const invokedScript = process.argv[1]
     ? resolvePath(process.argv[1])
@@ -226,7 +11,7 @@ if (invokedScript && modulePath === invokedScript) {
         process.exit(exitCode);
     }, (error) => {
         const detail = error instanceof Error ? error.message : String(error);
-        logError(`Unexpected error: ${detail}`);
+        console.error(`[voratiq] Unexpected error: ${detail}`);
         process.exit(1);
     });
 }

package/dist/commands/run/validation.d.ts

@@ -1,16 +1,15 @@
 import type { AgentDefinition } from "../../configs/agents/types.js";
 import type { EnvironmentConfig } from "../../configs/environment/types.js";
-import type { EvalDefinition } from "../../configs/evals/types.js";
 export interface ValidationInput {
     readonly root: string;
     readonly specAbsolutePath: string;
+    readonly resolvedAgentIds?: readonly string[];
     readonly maxParallel?: number;
 }
 export interface ValidationResult {
-    readonly prompt: string;
+    readonly specContent: string;
     readonly baseRevisionSha: string;
     readonly agents: readonly AgentDefinition[];
-    readonly evalPlan: readonly EvalDefinition[];
     readonly effectiveMaxParallel: number;
     readonly environment: EnvironmentConfig;
 }

package/dist/commands/run/validation.js

@@ -1,31 +1,68 @@
 import { readFile } from "node:fs/promises";
-import { loadAgentCatalog } from "../../configs/agents/loader.js";
+import { verifyAgentProviders } from "../../agents/runtime/auth.js";
+import { loadAgentCatalogDiagnostics } from "../../configs/agents/loader.js";
 import { EnvironmentConfigParseError, MissingEnvironmentConfigError, } from "../../configs/environment/errors.js";
 import { DEFAULT_ENVIRONMENT_FILE_DISPLAY, loadEnvironmentConfig, } from "../../configs/environment/loader.js";
-import { buildEvalDefinitions, loadEvalConfig, } from "../../configs/evals/loader.js";
-import { RunOptionValidationError } from "../../records/errors.js";
+import { loadRepoSettings } from "../../configs/settings/loader.js";
+import { NoAgentsEnabledError, RunPreflightError, } from "../../domain/run/competition/errors.js";
+import { RunOptionValidationError } from "../../domain/run/model/errors.js";
+import { toErrorMessage } from "../../utils/errors.js";
 import { getHeadRevision } from "../../utils/git.js";
 import { WorkspaceMissingEntryError } from "../../workspace/errors.js";
-import { verifyAgentProviders } from "./agents/auth-stage.js";
-import { NoAgentsEnabledError } from "./errors.js";
-import { buildAgentPrompt } from "./prompts.js";
+import { resolveEffectiveMaxParallel } from "../shared/max-parallel.js";
 /**
  * Validate command parameters, load spec, and prepare execution prerequisites.
  */
 export async function validateAndPrepare(input) {
-    const { root, specAbsolutePath, maxParallel: requestedMaxParallel } = input;
+    const { root, specAbsolutePath, resolvedAgentIds, maxParallel: requestedMaxParallel, } = input;
     if (requestedMaxParallel !== undefined &&
         (!Number.isInteger(requestedMaxParallel) || requestedMaxParallel <= 0)) {
         throw new RunOptionValidationError("maxParallel", "must be a positive integer");
     }
     const specContent = await readFile(specAbsolutePath, "utf8");
-    const prompt = buildAgentPrompt({ specContent });
     const baseRevisionSha = await getHeadRevision(root);
-    const agents = loadAgentCatalog({ root });
-    if (agents.length === 0) {
-        throw new NoAgentsEnabledError();
+    const preflightIssues = [];
+    let agents;
+    if (resolvedAgentIds) {
+        if (resolvedAgentIds.length === 0) {
+            throw new NoAgentsEnabledError();
+        }
+        const selectedAgentIds = new Set(resolvedAgentIds);
+        const agentDiagnostics = loadAgentCatalogDiagnostics({ root });
+        preflightIssues.push(...agentDiagnostics.issues.filter((issue) => selectedAgentIds.has(issue.agentId)));
+        const catalogById = new Map(agentDiagnostics.catalog.map((agent) => [agent.id, agent]));
+        agents = resolvedAgentIds.flatMap((agentId) => {
+            const agent = catalogById.get(agentId);
+            return agent ? [agent] : [];
+        });
+    }
+    else {
+        const agentDiagnostics = loadAgentCatalogDiagnostics({ root });
+        const enabledAgents = agentDiagnostics.enabledAgents;
+        if (enabledAgents.length === 0) {
+            throw new NoAgentsEnabledError();
+        }
+        preflightIssues.push(...agentDiagnostics.issues);
+        agents = agentDiagnostics.catalog;
+    }
+    try {
+        loadRepoSettings({ root });
+    }
+    catch (error) {
+        preflightIssues.push({
+            agentId: "settings",
+            message: toErrorMessage(error),
+        });
+    }
+    const preProviderIssueCount = preflightIssues.length;
+    const providerIssues = await verifyAgentProviders(agents.map((agent) => ({
+        id: agent.id,
+        provider: agent.provider,
+    })));
+    preflightIssues.push(...providerIssues);
+    if (preflightIssues.length > 0) {
+        throw new RunPreflightError(preflightIssues, preProviderIssueCount === 0 ? [] : undefined);
     }
-    await verifyAgentProviders(agents);
     const environment = (() => {
         try {
             return loadEnvironmentConfig({ root });
@@ -38,23 +75,15 @@ export async function validateAndPrepare(input) {
             throw error;
         }
     })();
-    const evalConfig = loadEvalConfig({ root });
-    const evalPlan = buildEvalDefinitions(evalConfig);
-    const effectiveMaxParallel = resolveMaxParallel(agents, requestedMaxParallel);
+    const effectiveMaxParallel = resolveEffectiveMaxParallel({
+        competitorCount: agents.length,
+        requestedMaxParallel,
+    });
     return {
-        prompt,
+        specContent,
         baseRevisionSha,
         agents,
-        evalPlan,
         effectiveMaxParallel,
         environment,
     };
 }
-function resolveMaxParallel(agents, requestedMaxParallel) {
-    const agentCount = agents.length;
-    if (agentCount === 0) {
-        return 0;
-    }
-    const resolvedInput = requestedMaxParallel !== undefined ? requestedMaxParallel : agentCount;
-    return Math.min(agentCount, Math.max(1, resolvedInput));
-}

package/dist/commands/shared/max-parallel.d.ts

@@ -0,0 +1,5 @@
+export interface ResolveEffectiveMaxParallelOptions {
+    competitorCount: number;
+    requestedMaxParallel?: number;
+}
+export declare function resolveEffectiveMaxParallel(options: ResolveEffectiveMaxParallelOptions): number;

package/dist/commands/shared/max-parallel.js

@@ -0,0 +1,15 @@
+export function resolveEffectiveMaxParallel(options) {
+    const { competitorCount, requestedMaxParallel } = options;
+    if (!Number.isInteger(competitorCount) || competitorCount < 0) {
+        throw new Error("competitorCount must be a non-negative integer");
+    }
+    if (competitorCount === 0) {
+        return 0;
+    }
+    if (requestedMaxParallel !== undefined &&
+        (!Number.isInteger(requestedMaxParallel) || requestedMaxParallel <= 0)) {
+        throw new Error("requestedMaxParallel must be a positive integer");
+    }
+    const resolved = requestedMaxParallel !== undefined ? requestedMaxParallel : competitorCount;
+    return Math.min(competitorCount, Math.max(1, resolved));
+}

package/dist/commands/shared/preview.d.ts

@@ -0,0 +1,10 @@
+export interface MarkdownPreviewOptions {
+    language?: string;
+    pad?: boolean;
+}
+export interface MarkdownSectionOptions {
+    heading: string;
+    level?: number;
+}
+export declare function buildMarkdownPreviewLines(content: string, options?: MarkdownPreviewOptions): string[];
+export declare function extractMarkdownSection(content: string, options: MarkdownSectionOptions): string | undefined;

package/dist/commands/shared/preview.js

@@ -0,0 +1,60 @@
+export function buildMarkdownPreviewLines(content, options = {}) {
+    const { language = "markdown", pad = false } = options;
+    const normalizedContent = content.replace(/(?:\r?\n)+$/g, "");
+    const lines = normalizedContent.split(/\r?\n/);
+    const fence = buildFence(normalizedContent);
+    const output = [];
+    if (pad) {
+        output.push("");
+    }
+    output.push(`${fence}${language}`, ...lines, fence);
+    if (pad) {
+        output.push("");
+    }
+    return output;
+}
+export function extractMarkdownSection(content, options) {
+    const { heading, level = 2 } = options;
+    const normalizedContent = content.replace(/\r\n/g, "\n");
+    const lines = normalizedContent.split("\n");
+    const headingPrefix = `${"#".repeat(level)} `;
+    const headingPattern = new RegExp(`^${escapeRegExp(headingPrefix)}${escapeRegExp(heading)}\\s*$`, "iu");
+    const nextHeadingPattern = new RegExp(`^${escapeRegExp(headingPrefix)}`, "u");
+    const startIndex = lines.findIndex((line) => headingPattern.test(line.trim()));
+    if (startIndex < 0) {
+        return undefined;
+    }
+    let endIndex = lines.length;
+    for (let index = startIndex + 1; index < lines.length; index += 1) {
+        if (nextHeadingPattern.test(lines[index]?.trim() ?? "")) {
+            endIndex = index;
+            break;
+        }
+    }
+    const sectionLines = lines.slice(startIndex, endIndex);
+    while (sectionLines.length > 0 &&
+        sectionLines[sectionLines.length - 1]?.trim() === "") {
+        sectionLines.pop();
+    }
+    return sectionLines.join("\n");
+}
+function buildFence(content) {
+    let maxRun = 0;
+    let current = 0;
+    for (const ch of content) {
+        if (ch === "`") {
+            current += 1;
+            if (current > maxRun) {
+                maxRun = current;
+            }
+        }
+        else {
+            current = 0;
+        }
+    }
+    const fenceLength = Math.max(3, maxRun + 1);
+    return "`".repeat(fenceLength);
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/dist/commands/shared/resolve-reduction-competitors.d.ts

@@ -0,0 +1,15 @@
+import type { AgentDefinition } from "../../configs/agents/types.js";
+export interface ResolveReductionCompetitorsInput {
+    root: string;
+    cliAgentIds?: readonly string[];
+    cliOverrideFlag?: string;
+    profileName?: string;
+    profileFlag?: string;
+    includeDefinitions?: boolean;
+}
+export interface ReductionCompetitionPlan {
+    source: "cli" | "orchestration";
+    agentIds: readonly string[];
+    competitors: readonly AgentDefinition[];
+}
+export declare function resolveReductionCompetitors(input: ResolveReductionCompetitorsInput): ReductionCompetitionPlan;

package/dist/commands/shared/resolve-reduction-competitors.js

@@ -0,0 +1,13 @@
+import { resolveStageCompetitors } from "./resolve-stage-competitors.js";
+export function resolveReductionCompetitors(input) {
+    const plan = resolveStageCompetitors({
+        root: input.root,
+        stageId: "reduce",
+        cliAgentIds: input.cliAgentIds,
+        cliOverrideFlag: input.cliOverrideFlag,
+        profileName: input.profileName,
+        profileFlag: input.profileFlag,
+        includeDefinitions: input.includeDefinitions,
+    });
+    return plan;
+}

package/dist/commands/shared/resolve-stage-competitors.d.ts

@@ -0,0 +1,19 @@
+import type { AgentDefinition } from "../../configs/agents/types.js";
+import type { OrchestrationStageId } from "../../configs/orchestration/types.js";
+export interface ResolveStageCompetitorsInput {
+    root: string;
+    stageId: OrchestrationStageId;
+    cliAgentIds?: readonly string[];
+    cliOverrideFlag?: string;
+    profileName?: string;
+    profileFlag?: string;
+    enforceSingleCompetitor?: boolean;
+    includeDefinitions?: boolean;
+}
+export interface CompetitionPlan {
+    source: "cli" | "orchestration";
+    agentIds: readonly string[];
+    competitors: readonly AgentDefinition[];
+}
+export type StageCompetitorResolution = CompetitionPlan;
+export declare function resolveStageCompetitors(input: ResolveStageCompetitorsInput): CompetitionPlan;

package/dist/commands/shared/resolve-stage-competitors.js

@@ -0,0 +1,171 @@
+import { AgentDisabledError, AgentNotFoundError, } from "../../configs/agents/errors.js";
+import { readAgentsConfig } from "../../configs/agents/loader.js";
+import { loadAgentById } from "../../configs/agents/loader.js";
+import { loadOrchestrationConfig } from "../../configs/orchestration/loader.js";
+import { HintedError } from "../../utils/errors.js";
+import { readUtf8File } from "../../utils/fs.js";
+import { resolveWorkspacePath, VORATIQ_AGENTS_FILE, VORATIQ_ORCHESTRATION_FILE, } from "../../workspace/structure.js";
+const ORCHESTRATION_CONFIG_DISPLAY_PATH = VORATIQ_ORCHESTRATION_FILE;
+const DEFAULT_PROFILE_NAME = "default";
+export function resolveStageCompetitors(input) {
+    const { root, stageId, cliAgentIds, cliOverrideFlag = "--agent", profileName, profileFlag = "--profile", enforceSingleCompetitor = false, includeDefinitions = true, } = input;
+    const normalizedCliAgentIds = normalizeAgentIds(cliAgentIds);
+    assertNoDuplicateCliAgentIds(stageId, normalizedCliAgentIds, cliOverrideFlag);
+    const source = normalizedCliAgentIds.length > 0 ? "cli" : "orchestration";
+    const selectedProfileName = profileName === undefined ? DEFAULT_PROFILE_NAME : profileName.trim();
+    let selectedProfile;
+    if (source === "orchestration" || profileName !== undefined) {
+        const orchestrationConfig = loadOrchestrationConfig({ root });
+        selectedProfile = resolveOrchestrationProfile({
+            config: orchestrationConfig,
+            profileName: selectedProfileName,
+            profileFlag,
+        });
+    }
+    const resolvedAgentIds = source === "cli"
+        ? normalizedCliAgentIds
+        : getProfileAgentIds(selectedProfile, stageId);
+    assertResolvedAgentCount({
+        stageId,
+        agentIds: resolvedAgentIds,
+        selectedProfileName,
+        enforceSingleCompetitor,
+    });
+    if (!includeDefinitions) {
+        validateResolvedAgentIds({ root, agentIds: resolvedAgentIds });
+    }
+    const competitors = includeDefinitions
+        ? resolvedAgentIds.map((agentId) => loadAgentById(agentId, { root }))
+        : [];
+    return {
+        source,
+        agentIds: [...resolvedAgentIds],
+        competitors,
+    };
+}
+function resolveOrchestrationProfile(options) {
+    const { config, profileName, profileFlag } = options;
+    const selectedProfile = config.profiles[profileName];
+    if (selectedProfile) {
+        return selectedProfile;
+    }
+    const availableProfileNames = Object.keys(config.profiles).sort();
+    const availableDisplay = availableProfileNames.map((name) => `\`${name}\``);
+    throw new HintedError(`Unknown orchestration profile \`${profileName}\`.`, {
+        detailLines: availableDisplay.length > 0
+            ? [`Available profiles: ${availableDisplay.join(", ")}.`]
+            : [],
+        hintLines: [
+            `Review \`${profileFlag}\` and update \`${ORCHESTRATION_CONFIG_DISPLAY_PATH}\` if needed.`,
+        ],
+    });
+}
+function normalizeAgentIds(agentIds) {
+    if (!agentIds || agentIds.length === 0) {
+        return [];
+    }
+    return agentIds
+        .map((agentId) => agentId.trim())
+        .filter((agentId) => agentId.length > 0);
+}
+function assertNoDuplicateCliAgentIds(stageId, cliAgentIds, cliOverrideFlag) {
+    if (cliAgentIds.length < 2) {
+        return;
+    }
+    const seen = new Set();
+    const duplicates = new Set();
+    for (const agentId of cliAgentIds) {
+        if (seen.has(agentId)) {
+            duplicates.add(agentId);
+            continue;
+        }
+        seen.add(agentId);
+    }
+    if (duplicates.size === 0) {
+        return;
+    }
+    const duplicateList = Array.from(duplicates)
+        .sort((left, right) => left.localeCompare(right))
+        .map((agentId) => `\`${agentId}\``)
+        .join(", ");
+    throw new HintedError(duplicateAgentHeadline(stageId, cliOverrideFlag), {
+        detailLines: [`Duplicate agent ids: ${duplicateList}.`],
+        hintLines: [`Pass each \`${cliOverrideFlag}\` value once.`],
+    });
+}
+function validateResolvedAgentIds(options) {
+    const { root, agentIds } = options;
+    const agentsPath = resolveWorkspacePath(root, VORATIQ_AGENTS_FILE);
+    const config = readAgentsConfig(readUtf8File(agentsPath, "utf8"));
+    const entriesById = new Map(config.agents.map((entry) => [entry.id, entry]));
+    const enabledAgentIds = config.agents
+        .filter((entry) => entry.enabled !== false)
+        .map((entry) => entry.id);
+    for (const agentId of agentIds) {
+        const entry = entriesById.get(agentId);
+        if (!entry) {
+            throw new AgentNotFoundError(agentId, enabledAgentIds);
+        }
+        if (entry.enabled === false) {
+            throw new AgentDisabledError(agentId);
+        }
+    }
+}
+function assertResolvedAgentCount(options) {
+    const { stageId, agentIds, selectedProfileName, enforceSingleCompetitor } = options;
+    const stageAgentsPath = profileAgentPath(selectedProfileName, stageId);
+    if (agentIds.length === 0) {
+        const configInstruction = enforceSingleCompetitor
+            ? `Configure exactly one agent under \`${stageAgentsPath}\` in \`${ORCHESTRATION_CONFIG_DISPLAY_PATH}\`.`
+            : `Configure at least one agent under \`${stageAgentsPath}\` in \`${ORCHESTRATION_CONFIG_DISPLAY_PATH}\`.`;
+        const overrideInstruction = enforceSingleCompetitor || stageId === "reduce"
+            ? []
+            : ["Or pass one or more `--agent` overrides."];
+        throw new HintedError(missingAgentsHeadline(stageId), {
+            detailLines: stageId === "reduce"
+                ? []
+                : [
+                    `Checked \`${stageAgentsPath}\` in \`${ORCHESTRATION_CONFIG_DISPLAY_PATH}\`.`,
+                ],
+            hintLines: stageId === "reduce"
+                ? [configInstruction, "Or pass one or more `--agent` overrides."]
+                : [configInstruction, ...overrideInstruction],
+        });
+    }
+    if (!enforceSingleCompetitor || agentIds.length === 1) {
+        return;
+    }
+    throw new HintedError(multipleAgentsHeadline(stageId), {
+        detailLines: [`This command supports one agent for ${stageNoun(stageId)}.`],
+        hintLines: [
+            `Configure exactly one agent under \`${stageAgentsPath}\` in \`${ORCHESTRATION_CONFIG_DISPLAY_PATH}\`.`,
+        ],
+    });
+}
+function getProfileAgentIds(profile, stageId) {
+    if (!profile) {
+        return [];
+    }
+    return profile[stageId].agents.map((agent) => agent.id);
+}
+function profileAgentPath(profileName, stageId) {
+    return `profiles.${profileName}.${stageId}.agents`;
+}
+function stageNoun(stageId) {
+    return stageId === "reduce" ? "reduce" : `stage \`${stageId}\``;
+}
+function duplicateAgentHeadline(stageId, cliOverrideFlag) {
+    return stageId === "reduce"
+        ? `Duplicate \`${cliOverrideFlag}\` values for reduce.`
+        : `Duplicate \`${cliOverrideFlag}\` values for stage \`${stageId}\`.`;
+}
+function missingAgentsHeadline(stageId) {
+    return stageId === "reduce"
+        ? "No reducer agents configured."
+        : `No agents configured for stage \`${stageId}\`.`;
+}
+function multipleAgentsHeadline(stageId) {
+    return stageId === "reduce"
+        ? "Multiple agents configured for reduce."
+        : `Multiple agents configured for stage \`${stageId}\`.`;
+}