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

package/dist/configs/agents/defaults.d.ts

@@ -1,10 +1,39 @@
 export declare const MODEL_PLACEHOLDER: "{{MODEL}}";
 export interface AgentDefault {
+    readonly id: string;
     readonly provider: string;
     readonly model: string;
+    readonly extraArgs?: readonly string[];
     readonly argv: readonly string[];
+    readonly runOnly?: true;
+}
+export declare const AGENT_PRESET_CHOICES: readonly ["pro", "lite", "manual"];
+export type AgentPreset = (typeof AGENT_PRESET_CHOICES)[number];
+export type BuiltinAgentProvider = "claude" | "codex" | "gemini";
+export interface AgentCatalogEntry {
+    readonly provider: BuiltinAgentProvider;
+    readonly model: string;
+    readonly id?: string;
+    readonly extraArgs?: readonly string[];
+    readonly runOnly?: true;
 }
 export declare function sanitizeAgentIdFromModel(model: string): string;
-export declare const DEFAULT_AGENT_DEFAULTS: readonly AgentDefault[];
+export declare function getAgentDefaultId(agentDefault: {
+    readonly id: string;
+}): string;
+export declare const PRO_AGENT_DEFAULTS: readonly AgentDefault[];
+export declare const LITE_AGENT_DEFAULTS: readonly AgentDefault[];
+export declare const BUILTIN_AGENT_DEFAULTS: readonly AgentDefault[];
+interface AgentCatalogGuardrailInput {
+    readonly builtinCatalog: readonly AgentCatalogEntry[];
+    readonly presetCatalogs: readonly {
+        readonly presetName: Exclude<AgentPreset, "manual">;
+        readonly catalog: readonly AgentCatalogEntry[];
+    }[];
+}
+export declare function assertAgentCatalogGuardrails(input: AgentCatalogGuardrailInput): void;
 export declare function getDefaultAgentIdByProvider(provider: string): string | undefined;
-export declare function getAgentDefault(provider: string): AgentDefault | undefined;
+export declare function getAgentDefault(reference: string): AgentDefault | undefined;
+export declare function getAgentDefaultsForPreset(preset: AgentPreset): readonly AgentDefault[];
+export declare function getSupportedAgentDefaults(): readonly AgentDefault[];
+export {};

package/dist/configs/agents/defaults.js

@@ -1,59 +1,375 @@
+import { sanitizeSlug } from "../../utils/slug.js";
 export const MODEL_PLACEHOLDER = "{{MODEL}}";
+export const AGENT_PRESET_CHOICES = ["pro", "lite", "manual"];
+const CLAUDE_DEFAULT_ARGV = [
+    "--model",
+    MODEL_PLACEHOLDER,
+    "--output-format",
+    "json",
+    "--dangerously-skip-permissions",
+    "-p",
+];
+const CODEX_DEFAULT_ARGV = [
+    "exec",
+    "--model",
+    MODEL_PLACEHOLDER,
+    "--experimental-json",
+    "--dangerously-bypass-approvals-and-sandbox",
+];
+const GEMINI_DEFAULT_ARGV = [
+    "--model",
+    MODEL_PLACEHOLDER,
+    "--output-format",
+    "json",
+    "--yolo",
+];
+const DEFAULT_ARGV_BY_PROVIDER = {
+    claude: CLAUDE_DEFAULT_ARGV,
+    codex: CODEX_DEFAULT_ARGV,
+    gemini: GEMINI_DEFAULT_ARGV,
+};
 export function sanitizeAgentIdFromModel(model) {
-    const lowered = model.toLowerCase();
-    const replaced = lowered.replace(/[^a-z0-9]+/g, "-");
-    const collapsed = replaced.replace(/-+/g, "-");
-    const trimmed = collapsed.replace(/^-+/u, "").replace(/-+$/u, "");
-    if (!trimmed) {
-        throw new Error(`Unable to derive agent id from model "${model}". Provide a model slug with at least one alphanumeric character.`);
+    const sanitized = sanitizeSlug(model);
+    if (!sanitized) {
+        throw new Error(`Unable to derive agent id from model "${model}". Provide a model identifier with at least one alphanumeric character.`);
+    }
+    return sanitized;
+}
+export function getAgentDefaultId(agentDefault) {
+    return agentDefault.id;
+}
+function resolveAgentCatalogEntryId(entry) {
+    const explicit = entry.id?.trim();
+    if (explicit) {
+        return explicit;
     }
-    return trimmed;
+    return sanitizeAgentIdFromModel(entry.model);
 }
-export const DEFAULT_AGENT_DEFAULTS = [
+function generateAgentDefaults(entries) {
+    return entries.map(({ provider, model, id, extraArgs, runOnly }) => ({
+        id: resolveAgentCatalogEntryId({ id, model }),
+        provider,
+        model,
+        extraArgs: extraArgs && extraArgs.length > 0 ? [...extraArgs] : undefined,
+        argv: DEFAULT_ARGV_BY_PROVIDER[provider],
+        ...(runOnly ? { runOnly } : {}),
+    }));
+}
+const DEFAULT_AGENT_CATALOG_ENTRIES = [
+    {
+        id: "claude-haiku-4-5-20251001",
+        provider: "claude",
+        model: "claude-haiku-4-5-20251001",
+        extraArgs: ["--effort", "high"],
+    },
     {
+        id: "claude-sonnet-4-5-20250929",
         provider: "claude",
         model: "claude-sonnet-4-5-20250929",
-        argv: [
-            "--model",
-            MODEL_PLACEHOLDER,
-            "--output-format",
-            "json",
-            "--dangerously-skip-permissions",
-            "-p",
-        ],
+        extraArgs: ["--effort", "high"],
+    },
+    {
+        id: "claude-sonnet-4-6",
+        provider: "claude",
+        model: "claude-sonnet-4-6",
+        extraArgs: ["--effort", "high"],
+    },
+    {
+        id: "claude-opus-4-5-20251101",
+        provider: "claude",
+        model: "claude-opus-4-5-20251101",
+        extraArgs: ["--effort", "high"],
+    },
+    {
+        id: "claude-opus-4-6",
+        provider: "claude",
+        model: "claude-opus-4-6",
+        extraArgs: ["--effort", "high"],
+    },
+    {
+        id: "gpt-5-codex",
+        provider: "codex",
+        model: "gpt-5-codex",
+    },
+    {
+        id: "gpt-5-1-codex-mini",
+        provider: "codex",
+        model: "gpt-5.1-codex-mini",
+    },
+    {
+        id: "gpt-5-1-codex",
+        provider: "codex",
+        model: "gpt-5.1-codex",
+    },
+    {
+        id: "gpt-5-1-codex-max",
+        provider: "codex",
+        model: "gpt-5.1-codex-max",
     },
     {
+        id: "gpt-5-1-codex-max-xhigh",
+        provider: "codex",
+        model: "gpt-5.1-codex-max",
+        extraArgs: ["--config", "model_reasoning_effort=xhigh"],
+    },
+    {
+        id: "gpt-5-2",
+        provider: "codex",
+        model: "gpt-5.2",
+    },
+    {
+        id: "gpt-5-2-high",
+        provider: "codex",
+        model: "gpt-5.2",
+        extraArgs: ["--config", "model_reasoning_effort=high"],
+    },
+    {
+        id: "gpt-5-2-xhigh",
+        provider: "codex",
+        model: "gpt-5.2",
+        extraArgs: ["--config", "model_reasoning_effort=xhigh"],
+    },
+    {
+        id: "gpt-5-2-codex",
+        provider: "codex",
+        model: "gpt-5.2-codex",
+    },
+    {
+        id: "gpt-5-2-codex-high",
+        provider: "codex",
+        model: "gpt-5.2-codex",
+        extraArgs: ["--config", "model_reasoning_effort=high"],
+    },
+    {
+        id: "gpt-5-2-codex-xhigh",
         provider: "codex",
         model: "gpt-5.2-codex",
-        argv: [
-            "exec",
-            "--model",
-            MODEL_PLACEHOLDER,
-            "--experimental-json",
-            "--dangerously-bypass-approvals-and-sandbox",
-            "-c",
-            "mcp_servers={}",
-        ],
+        extraArgs: ["--config", "model_reasoning_effort=xhigh"],
+    },
+    {
+        id: "gpt-5-3-codex-spark",
+        provider: "codex",
+        model: "gpt-5.3-codex-spark",
     },
     {
+        id: "gpt-5-3-codex",
+        provider: "codex",
+        model: "gpt-5.3-codex",
+    },
+    {
+        id: "gpt-5-3-codex-high",
+        provider: "codex",
+        model: "gpt-5.3-codex",
+        extraArgs: ["--config", "model_reasoning_effort=high"],
+    },
+    {
+        id: "gpt-5-3-codex-xhigh",
+        provider: "codex",
+        model: "gpt-5.3-codex",
+        extraArgs: ["--config", "model_reasoning_effort=xhigh"],
+    },
+    {
+        id: "gpt-5-4-mini",
+        provider: "codex",
+        model: "gpt-5.4-mini",
+    },
+    {
+        id: "gpt-5-4",
+        provider: "codex",
+        model: "gpt-5.4",
+    },
+    {
+        id: "gpt-5-4-high",
+        provider: "codex",
+        model: "gpt-5.4",
+        extraArgs: ["--config", "model_reasoning_effort=high"],
+    },
+    {
+        id: "gpt-5-4-xhigh",
+        provider: "codex",
+        model: "gpt-5.4",
+        extraArgs: ["--config", "model_reasoning_effort=xhigh"],
+    },
+    {
+        id: "gemini-2-5-flash",
+        provider: "gemini",
+        model: "gemini-2.5-flash",
+    },
+    {
+        id: "gemini-2-5-flash-lite",
+        provider: "gemini",
+        model: "gemini-2.5-flash-lite",
+    },
+    {
+        id: "gemini-3-flash-preview",
+        provider: "gemini",
+        model: "gemini-3-flash-preview",
+    },
+    {
+        id: "gemini-2-5-pro",
         provider: "gemini",
         model: "gemini-2.5-pro",
-        argv: ["--model", MODEL_PLACEHOLDER, "--output-format", "json", "--yolo"],
+    },
+    {
+        id: "gemini-3-1-pro-preview",
+        provider: "gemini",
+        model: "gemini-3.1-pro-preview",
+    },
+];
+const PRO_AGENT_PRESET_ENTRIES = [
+    {
+        id: "claude-opus-4-6",
+        provider: "claude",
+        model: "claude-opus-4-6",
+        extraArgs: ["--effort", "high"],
+    },
+    {
+        id: "gpt-5-4-high",
+        provider: "codex",
+        model: "gpt-5.4",
+        extraArgs: ["--config", "model_reasoning_effort=high"],
+    },
+    {
+        id: "gemini-3-1-pro-preview",
+        provider: "gemini",
+        model: "gemini-3.1-pro-preview",
+        runOnly: true,
+    },
+];
+const LITE_AGENT_PRESET_ENTRIES = [
+    {
+        id: "claude-haiku-4-5-20251001",
+        provider: "claude",
+        model: "claude-haiku-4-5-20251001",
+        extraArgs: ["--effort", "high"],
+    },
+    {
+        id: "gpt-5-3-codex-spark",
+        provider: "codex",
+        model: "gpt-5.3-codex-spark",
+    },
+    {
+        id: "gemini-3-flash-preview",
+        provider: "gemini",
+        model: "gemini-3-flash-preview",
+        runOnly: true,
     },
 ];
-const AGENT_DEFAULTS_BY_PROVIDER = new Map(DEFAULT_AGENT_DEFAULTS.map((agentDefault) => [agentDefault.provider, agentDefault]));
+export const PRO_AGENT_DEFAULTS = generateAgentDefaults(PRO_AGENT_PRESET_ENTRIES);
+export const LITE_AGENT_DEFAULTS = generateAgentDefaults(LITE_AGENT_PRESET_ENTRIES);
+export const BUILTIN_AGENT_DEFAULTS = generateAgentDefaults(DEFAULT_AGENT_CATALOG_ENTRIES);
+export function assertAgentCatalogGuardrails(input) {
+    const supportedDefaults = generateAgentDefaults(input.builtinCatalog);
+    const byId = new Map();
+    for (const agentDefault of supportedDefaults) {
+        const existing = byId.get(agentDefault.id);
+        if (existing) {
+            throw new Error(`SUPPORTED_AGENT_CATALOG contains duplicate agent id "${agentDefault.id}" for "${existing.model}" and "${agentDefault.model}".`);
+        }
+        byId.set(agentDefault.id, agentDefault);
+    }
+    for (const { presetName, catalog } of input.presetCatalogs) {
+        const presetDefaults = generateAgentDefaults(catalog);
+        const seenPresetIds = new Set();
+        for (const presetDefault of presetDefaults) {
+            if (seenPresetIds.has(presetDefault.id)) {
+                throw new Error(`${presetName.toUpperCase()}_AGENT_PRESET contains duplicate agent id "${presetDefault.id}".`);
+            }
+            seenPresetIds.add(presetDefault.id);
+            const supported = byId.get(presetDefault.id);
+            if (!supported) {
+                throw new Error(`${presetName.toUpperCase()}_AGENT_PRESET entry "${presetDefault.id}" is not present in SUPPORTED_AGENT_CATALOG.`);
+            }
+            if (supported.provider !== presetDefault.provider ||
+                supported.model !== presetDefault.model ||
+                !stringListsEqual(supported.extraArgs, presetDefault.extraArgs)) {
+                throw new Error(`${presetName.toUpperCase()}_AGENT_PRESET entry "${presetDefault.id}" must exactly match SUPPORTED_AGENT_CATALOG (provider/model/extraArgs).`);
+            }
+        }
+    }
+}
+function stringListsEqual(left, right) {
+    const leftList = left ?? [];
+    const rightList = right ?? [];
+    if (leftList.length !== rightList.length) {
+        return false;
+    }
+    for (const [index, value] of leftList.entries()) {
+        if (value !== rightList[index]) {
+            return false;
+        }
+    }
+    return true;
+}
+assertAgentCatalogGuardrails({
+    builtinCatalog: DEFAULT_AGENT_CATALOG_ENTRIES,
+    presetCatalogs: [
+        { presetName: "pro", catalog: PRO_AGENT_PRESET_ENTRIES },
+        { presetName: "lite", catalog: LITE_AGENT_PRESET_ENTRIES },
+    ],
+});
+function buildAgentDefaultsByProvider(agentDefaults) {
+    const map = new Map();
+    for (const agentDefault of agentDefaults) {
+        const existing = map.get(agentDefault.provider);
+        if (existing) {
+            throw new Error(`Duplicate agent defaults for provider "${agentDefault.provider}": "${existing.model}" and "${agentDefault.model}".`);
+        }
+        map.set(agentDefault.provider, agentDefault);
+    }
+    return map;
+}
+function buildAgentDefaultsByReference(agentDefaults) {
+    const map = new Map();
+    for (const agentDefault of agentDefaults) {
+        const keys = [agentDefault.provider, agentDefault.id];
+        for (const key of keys) {
+            const existing = map.get(key);
+            if (existing && existing.provider !== agentDefault.provider) {
+                throw new Error(`Agent default reference "${key}" is ambiguous: "${existing.provider}" and "${agentDefault.provider}".`);
+            }
+            map.set(key, agentDefault);
+        }
+    }
+    return map;
+}
+const AGENT_DEFAULTS_BY_PROVIDER = buildAgentDefaultsByProvider(PRO_AGENT_DEFAULTS);
+const AGENT_DEFAULTS_BY_REFERENCE = buildAgentDefaultsByReference(PRO_AGENT_DEFAULTS);
 export function getDefaultAgentIdByProvider(provider) {
     const entry = AGENT_DEFAULTS_BY_PROVIDER.get(provider);
-    return entry ? sanitizeAgentIdFromModel(entry.model) : undefined;
+    return entry ? entry.id : undefined;
 }
-export function getAgentDefault(provider) {
-    const agentDefault = AGENT_DEFAULTS_BY_PROVIDER.get(provider);
+export function getAgentDefault(reference) {
+    const agentDefault = AGENT_DEFAULTS_BY_REFERENCE.get(reference);
     return agentDefault ? cloneAgentDefault(agentDefault) : undefined;
 }
+export function getAgentDefaultsForPreset(preset) {
+    switch (preset) {
+        case "pro":
+            return PRO_AGENT_DEFAULTS;
+        case "lite":
+            return LITE_AGENT_DEFAULTS;
+        case "manual":
+            return [];
+        default:
+            return assertNever(preset);
+    }
+}
+export function getSupportedAgentDefaults() {
+    return BUILTIN_AGENT_DEFAULTS;
+}
 function cloneAgentDefault(agentDefault) {
     return {
+        id: agentDefault.id,
         provider: agentDefault.provider,
         model: agentDefault.model,
+        extraArgs: agentDefault.extraArgs && agentDefault.extraArgs.length > 0
+            ? [...agentDefault.extraArgs]
+            : undefined,
         argv: [...agentDefault.argv],
     };
 }
+function assertNever(_value) {
+    void _value;
+    throw new Error("Unsupported agent preset.");
+}

package/dist/configs/agents/errors.js

@@ -15,7 +15,7 @@ export class AgentsConfigError extends AgentsError {
 export class MissingAgentsConfigError extends AgentsConfigError {
     filePath;
     constructor(filePath) {
-        super(`Missing agent configuration file at ${filePath}.`);
+        super("Missing `agents.yaml`.");
         this.filePath = filePath;
         this.name = "MissingAgentsConfigError";
     }
@@ -30,7 +30,7 @@ export class DuplicateAgentIdError extends AgentsConfigError {
     agentId;
     displayPath;
     constructor(agentId, displayPath) {
-        super(`${DEFAULT_ERROR_CONTEXT}: Duplicate enabled agent id "${agentId}" in ${displayPath}. Agent ids must be unique.`);
+        super(`${DEFAULT_ERROR_CONTEXT}: Duplicate enabled agent id \`${agentId}\` in \`${displayPath}\`. Agent ids must be unique.`);
         this.agentId = agentId;
         this.displayPath = displayPath;
         this.name = "DuplicateAgentIdError";
@@ -40,10 +40,13 @@ export class AgentNotFoundError extends AgentsConfigError {
     agentId;
     enabledAgentIds;
     constructor(agentId, enabledAgentIds) {
-        const enabledList = enabledAgentIds.length > 0
-            ? enabledAgentIds.slice().sort().join(", ")
-            : "none";
-        super(`${DEFAULT_ERROR_CONTEXT}: Agent "${agentId}" is not defined in agents.yaml. Enabled agents: ${enabledList}.`);
+        const enabledList = enabledAgentIds
+            .slice()
+            .sort((left, right) => left.localeCompare(right))
+            .map((id) => `\`${id}\``)
+            .join(", ");
+        const enabledSuffix = enabledList.length > 0 ? ` Enabled agents: ${enabledList}.` : "";
+        super(`${DEFAULT_ERROR_CONTEXT}: Agent \`${agentId}\` is not defined in \`agents.yaml\`.${enabledSuffix}`);
         this.agentId = agentId;
         this.enabledAgentIds = enabledAgentIds;
         this.name = "AgentNotFoundError";
@@ -52,7 +55,7 @@ export class AgentNotFoundError extends AgentsConfigError {
 export class AgentDisabledError extends AgentsConfigError {
     agentId;
     constructor(agentId) {
-        super(`${DEFAULT_ERROR_CONTEXT}: Agent "${agentId}" is disabled in agents.yaml.`);
+        super(`${DEFAULT_ERROR_CONTEXT}: Agent \`${agentId}\` is disabled in \`agents.yaml\`.`);
         this.agentId = agentId;
         this.name = "AgentDisabledError";
     }
@@ -61,7 +64,7 @@ export class ModelPlaceholderMissingError extends AgentsError {
     agentId;
     placeholder;
     constructor(agentId, placeholder) {
-        super(`Expected argv for agent ${agentId} to include ${placeholder}`);
+        super(`Expected argv for agent \`${agentId}\` to include \`${placeholder}\`.`);
         this.agentId = agentId;
         this.placeholder = placeholder;
         this.name = "ModelPlaceholderMissingError";
@@ -71,7 +74,7 @@ export class UnknownAgentProviderTemplateError extends AgentsConfigError {
     agentId;
     provider;
     constructor(agentId, provider) {
-        super(`${DEFAULT_ERROR_CONTEXT}: Unknown provider "${provider}" referenced by agent "${agentId}" in agents.yaml.`);
+        super(`${DEFAULT_ERROR_CONTEXT}: Unknown provider \`${provider}\` referenced by agent \`${agentId}\` in \`agents.yaml\`.`);
         this.agentId = agentId;
         this.provider = provider;
         this.name = "UnknownAgentProviderTemplateError";
@@ -80,7 +83,7 @@ export class UnknownAgentProviderTemplateError extends AgentsConfigError {
 export class AgentBinaryMissingError extends AgentsConfigError {
     agentId;
     constructor(agentId) {
-        super(`${DEFAULT_ERROR_CONTEXT}: Agent "${agentId}" must provide a binary path. Update agents.yaml with the CLI location for this agent.`);
+        super(`${DEFAULT_ERROR_CONTEXT}: Agent \`${agentId}\` must define a binary path in \`agents.yaml\`.`);
         this.agentId = agentId;
         this.name = "AgentBinaryMissingError";
     }
@@ -90,7 +93,7 @@ export class AgentBinaryAccessError extends AgentsConfigError {
     binaryPath;
     detail;
     constructor(agentId, binaryPath, detail) {
-        super(`${DEFAULT_ERROR_CONTEXT}: Agent "${agentId}" binary "${binaryPath}" is not executable (${detail}).`);
+        super(`${DEFAULT_ERROR_CONTEXT}: Agent \`${agentId}\` binary \`${binaryPath}\` is not executable (${detail}).`);
         this.agentId = agentId;
         this.binaryPath = binaryPath;
         this.detail = detail;

package/dist/configs/agents/loader.d.ts

@@ -1,4 +1,4 @@
-import { type AgentCatalog, type AgentDefinition, type AgentsConfig } from "./types.js";
+import { type AgentCatalog, type AgentConfigEntry, type AgentDefinition, type AgentsConfig } from "./types.js";
 export declare function readAgentsConfig(content: string): AgentsConfig;
 export interface LoadAgentCatalogOptions {
     root?: string;
@@ -6,4 +6,14 @@ export interface LoadAgentCatalogOptions {
     readFile?: (path: string) => string;
 }
 export declare function loadAgentCatalog(options?: LoadAgentCatalogOptions): AgentCatalog;
+export interface AgentCatalogDiagnostics {
+    readonly enabledAgents: readonly AgentConfigEntry[];
+    readonly catalog: AgentCatalog;
+    readonly issues: readonly AgentCatalogIssue[];
+}
+export interface AgentCatalogIssue {
+    readonly agentId: string;
+    readonly message: string;
+}
+export declare function loadAgentCatalogDiagnostics(options?: LoadAgentCatalogOptions): AgentCatalogDiagnostics;
 export declare function loadAgentById(id: string, options?: LoadAgentCatalogOptions): AgentDefinition;

package/dist/configs/agents/loader.js

@@ -1,6 +1,7 @@
 import { accessSync, constants as fsConstants } from "node:fs";
+import { basename } from "node:path";
+import { toErrorMessage } from "../../utils/errors.js";
 import { isFileSystemError } from "../../utils/fs.js";
-import { relativeToRoot } from "../../utils/path.js";
 import { parseYamlDocument, } from "../../utils/yaml-reader.js";
 import { resolveWorkspacePath } from "../../workspace/structure.js";
 import { createConfigLoader } from "../shared/loader-factory.js";
@@ -30,7 +31,7 @@ const loadAgentsConfigInternal = createConfigLoader({
     parse: (content, context) => {
         const config = readAgentsConfig(content);
         const enabledAgents = config.agents.filter((entry) => entry.enabled !== false);
-        const displayPath = relativeToRoot(context.root, context.filePath);
+        const displayPath = basename(context.filePath);
         const seenAgentIds = new Set();
         for (const entry of enabledAgents) {
             if (seenAgentIds.has(entry.id)) {
@@ -50,6 +51,29 @@ export function loadAgentCatalog(options = {}) {
     validateAgentBinaries(catalog);
     return catalog;
 }
+export function loadAgentCatalogDiagnostics(options = {}) {
+    const { enabledAgents } = loadAgentsConfig(options);
+    const catalog = [];
+    const issues = [];
+    for (const entry of enabledAgents) {
+        let definition;
+        try {
+            definition = buildAgentDefinition(entry);
+        }
+        catch (error) {
+            issues.push(...coerceAgentIssues(entry.id, error));
+            continue;
+        }
+        try {
+            assertAgentBinary(definition);
+        }
+        catch (error) {
+            issues.push(...coerceAgentIssues(entry.id, error));
+        }
+        catalog.push(definition);
+    }
+    return { enabledAgents, catalog, issues };
+}
 export function loadAgentById(id, options = {}) {
     const { config, enabledAgents } = loadAgentsConfig(options);
     const entry = config.agents.find((agent) => agent.id === id);
@@ -89,6 +113,49 @@ function formatBinaryAccessError(error) {
     }
     return "unknown error";
 }
+function coerceAgentIssues(agentId, error) {
+    if (error instanceof AgentBinaryMissingError) {
+        return [{ agentId, message: "missing binary path" }];
+    }
+    if (error instanceof AgentBinaryAccessError) {
+        return [
+            {
+                agentId,
+                message: `binary \`${error.binaryPath}\` is not executable (${error.detail})`,
+            },
+        ];
+    }
+    if (error instanceof UnknownAgentProviderTemplateError) {
+        return [
+            {
+                agentId,
+                message: `unknown provider \`${error.provider}\` referenced in \`agents.yaml\``,
+            },
+        ];
+    }
+    if (error instanceof ModelPlaceholderMissingError) {
+        return [
+            {
+                agentId,
+                message: `argv missing \`${error.placeholder}\``,
+            },
+        ];
+    }
+    if (error instanceof AgentsYamlParseError) {
+        const normalized = stripPrefix(error.message, `${DEFAULT_ERROR_CONTEXT}: `);
+        return [{ agentId, message: normalized }];
+    }
+    if (error instanceof Error && error.message) {
+        return [{ agentId, message: error.message }];
+    }
+    return [{ agentId, message: toErrorMessage(error) }];
+}
+function stripPrefix(message, prefix) {
+    if (message.startsWith(prefix)) {
+        return message.slice(prefix.length);
+    }
+    return message;
+}
 function buildAgentDefinition(entry) {
     const template = resolveTemplateForEntry(entry);
     const argv = substituteModelPlaceholder(template.argv, entry.model, entry.id);
@@ -108,10 +175,10 @@ function validateExtraArgs(extraArgs, agentId) {
         return;
     }
     if (extraArgs.includes(MODEL_PLACEHOLDER)) {
-        throw new AgentsYamlParseError(`${DEFAULT_ERROR_CONTEXT}: Agent "${agentId}" extraArgs cannot include bare ${MODEL_PLACEHOLDER}.`);
+        throw new AgentsYamlParseError(`${DEFAULT_ERROR_CONTEXT}: Agent \`${agentId}\` extraArgs cannot include bare \`${MODEL_PLACEHOLDER}\`.`);
     }
     if (extraArgs.some((arg) => arg === "--model")) {
-        throw new AgentsYamlParseError(`${DEFAULT_ERROR_CONTEXT}: Agent "${agentId}" extraArgs cannot override --model. Remove "--model" from extraArgs.`);
+        throw new AgentsYamlParseError(`${DEFAULT_ERROR_CONTEXT}: Agent \`${agentId}\` extraArgs cannot override \`--model\`. Remove \`--model\` from extraArgs.`);
     }
 }
 function resolveTemplateForEntry(entry) {

package/dist/configs/agents/types.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
-export const agentIdSchema = z.string().regex(/^[a-z0-9_-]{1,32}$/u, {
-    message: "Agent id must match /^[a-z0-9_-]{1,32}$/",
+export const agentIdSchema = z.string().regex(/^[a-z0-9_-]{1,64}$/u, {
+    message: "Agent id must match /^[a-z0-9_-]{1,64}$/",
 });
 export const agentConfigEntrySchema = z.object({
     id: agentIdSchema,