specrails-desktop 2.57.1 → 2.58.0

package/server/dist/modules/agent-runtime/runtime/agent-runtime-settings-router.js

@@ -15,9 +15,10 @@ function withDefaultRoleModels(body) {
     if (!agents || typeof agents !== 'object' || !Array.isArray(providers))
         return body;
     // Only LOCAL roles: a CLI role saved without a model keeps meaning "provider default" (never frozen into the file).
+    const roles = body.roles && typeof body.roles === 'object' && !Array.isArray(body.roles) ? structuredClone(body.roles) : undefined;
     const fixer = body.fixer && typeof body.fixer === 'object' ? structuredClone(body.fixer) : undefined;
-    const filled = (0, agent_runtime_effective_config_1.fillDefaultRoleModels)({ agents: structuredClone(agents), providers: providers, ...(fixer ? { fixer: fixer } : {}) }, { localOnly: true });
-    return { ...body, agents: filled.agents, ...(filled.fixer ? { fixer: filled.fixer } : {}) };
+    const filled = (0, agent_runtime_effective_config_1.fillDefaultRoleModels)({ agents: structuredClone(agents), providers: providers, ...(roles ? { roles: roles } : {}), ...(fixer ? { fixer: fixer } : {}) }, { localOnly: true });
+    return { ...body, agents: filled.agents, ...(filled.roles ? { roles: filled.roles } : {}), ...(filled.fixer ? { fixer: filled.fixer } : {}) };
 }
 const loop_role_engines_1 = require("../../loops/runtime/loop-role-engines");
 function registerAgentRuntimeSettingsRoutes({ router, ctx }) {
@@ -62,12 +63,15 @@ function registerAgentRuntimeSettingsRoutes({ router, ctx }) {
             const project = ctx(_req).project;
             const configured = (0, node_fs_1.existsSync)((0, agent_runtime_settings_1.agentRuntimeConfigPath)(project));
             const config = (0, agent_runtime_settings_1.loadAgentRuntimeConfig)(project);
-            let efficiencyAvailable = false;
+            let efficiencyAvailable = false, openRolesAvailable = false;
             try {
-                efficiencyAvailable = (await (0, agent_runtime_loader_1.loadCoreAgentRuntime)()).api?.capabilities?.efficientRoleExecution === 1;
+                const capabilities = (await (0, agent_runtime_loader_1.loadCoreAgentRuntime)()).api?.capabilities;
+                efficiencyAvailable = capabilities?.efficientRoleExecution === 1;
+                openRolesAvailable = capabilities?.openRoles === 1;
             }
             catch { /* Ordinary settings remain readable without capability support. */ }
-            res.json({ configured, config, runtimeAvailable: (0, agent_runtime_loader_1.findCoreAgentRuntimeEntry)() !== null, efficiencyAvailable });
+            res.json({ configured, config, runtimeAvailable: (0, agent_runtime_loader_1.findCoreAgentRuntimeEntry)() !== null, efficiencyAvailable, openRolesAvailable,
+                workflowRoleDefaults: openRolesAvailable && config ? (0, agent_runtime_effective_config_1.workflowRoleDefaults)(config) : {} });
         }
         catch (err) {
             const validation = err instanceof agent_runtime_settings_1.AgentRuntimeConfigError;
@@ -127,7 +131,7 @@ function registerAgentRuntimeSettingsRoutes({ router, ctx }) {
                 res.status(503).json({ error: 'runtime_unavailable', message: 'Update Core to an installation with the agent runtime before enabling it' });
                 return;
             }
-            let efficiencyAvailable = false;
+            let efficiencyAvailable = false, openRolesAvailable = false;
             if (config.enabled && runtimeAvailable) {
                 try {
                     const runtime = await (0, agent_runtime_loader_1.loadCoreAgentRuntime)();
@@ -135,6 +139,7 @@ function registerAgentRuntimeSettingsRoutes({ router, ctx }) {
                     runtime.validateRuntimeConfig(coreConfig);
                     (0, agent_runtime_loader_1.validateRequestedRoleEfforts)(runtime, coreConfig);
                     efficiencyAvailable = runtime.api?.capabilities?.efficientRoleExecution === 1;
+                    openRolesAvailable = runtime.api?.capabilities?.openRoles === 1;
                 }
                 catch {
                     res.status(503).json({ error: 'runtime_incompatible', message: 'The installed Core runtime could not validate this configuration; update Core and retry' });
@@ -142,7 +147,7 @@ function registerAgentRuntimeSettingsRoutes({ router, ctx }) {
                 }
             }
             const saved = (0, agent_runtime_settings_1.saveAgentRuntimeConfig)(ctx(req).project, config);
-            res.json({ configured: true, config: saved, runtimeAvailable, efficiencyAvailable });
+            res.json({ configured: true, config: saved, runtimeAvailable, efficiencyAvailable, openRolesAvailable });
         }
         catch (err) {
             const validation = err instanceof agent_runtime_settings_1.AgentRuntimeConfigError;

package/server/dist/modules/agent-runtime/runtime/agent-runtime-settings.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AgentRuntimeConfigError = exports.REVIEW_THRESHOLD_FLOORS = exports.MAX_OUTPUT_TOKENS_MAX = exports.MAX_OUTPUT_TOKENS_MIN = exports.CONTEXT_WINDOW_TOKENS_MAX = exports.CONTEXT_WINDOW_TOKENS_MIN = void 0;
+exports.AgentRuntimeConfigError = exports.REVIEW_THRESHOLD_FLOORS = exports.MAX_OUTPUT_TOKENS_MAX = exports.MAX_OUTPUT_TOKENS_MIN = exports.CONTEXT_WINDOW_TOKENS_MAX = exports.CONTEXT_WINDOW_TOKENS_MIN = exports.RUNTIME_ROLE_ID = void 0;
 exports.stripDesktopConnectionFields = stripDesktopConnectionFields;
 exports.coreConnectionFieldGates = coreConnectionFieldGates;
 exports.validateAgentRuntimeConfig = validateAgentRuntimeConfig;
@@ -26,9 +26,14 @@ const node_path_1 = __importDefault(require("node:path"));
 const node_os_1 = __importDefault(require("node:os"));
 const node_crypto_1 = require("node:crypto");
 const ajv_1 = __importDefault(require("ajv"));
+const node_util_1 = require("node:util");
 const agent_runtime_schema_json_1 = __importDefault(require("../../../schemas/agent-runtime.schema.json"));
 const workspace_resolution_1 = require("../../../workspace-resolution");
 const registry_1 = require("../../../providers/registry");
+const agent_catalog_1 = require("../../agents/runtime/agent-catalog");
+const agent_role_descriptor_1 = require("../../agents/runtime/agent-role-descriptor");
+var agent_role_descriptor_2 = require("../../agents/runtime/agent-role-descriptor");
+Object.defineProperty(exports, "RUNTIME_ROLE_ID", { enumerable: true, get: function () { return agent_role_descriptor_2.RUNTIME_ROLE_ID; } });
 const DESKTOP_CONNECTION_FIELDS = ['label', 'defaultModel', 'rates'];
 /** Core-owned small-model fields: known only to cores advertising `capabilities.compactAgentLoop`
  *  (`supportsReasoningEffort` moved here: core forwards it as OpenAI `reasoning_effort`). */
@@ -145,7 +150,7 @@ function validateAgentRuntimeConfig(input) {
     }
     const config = input;
     if (config.rolePrompts !== undefined)
-        validateRuntimeRolePrompts(config.rolePrompts);
+        validateRuntimeRolePrompts(config.rolePrompts, Object.keys(config.roles ?? {}));
     if (new Set(config.providers.map(({ id }) => id)).size !== config.providers.length)
         throw new AgentRuntimeConfigError('Provider IDs must be unique');
     for (const provider of config.providers) {
@@ -165,8 +170,8 @@ function validateAgentRuntimeConfig(input) {
         if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash || provider.baseUrl.includes('\0'))
             throw new AgentRuntimeConfigError('Provider URLs must use HTTP(S) without credentials, query parameters or fragments');
     }
-    for (const role of [...ROLES, ...(config.fixer ? ['fixer'] : [])]) {
-        const agent = role === 'fixer' ? config.fixer : config.agents[role];
+    const assignments = [...Object.entries(config.agents), ...Object.entries(config.roles ?? {}), ...(config.fixer ? [['fixer', config.fixer]] : [])];
+    for (const [role, agent] of assignments) {
         const provider = config.providers.find(({ id }) => id === agent.provider);
         if (!provider)
             throw new AgentRuntimeConfigError(`Role ${role} references a provider that is not configured`);
@@ -191,6 +196,22 @@ function validateAgentRuntimeConfig(input) {
         if (agent.thinking !== undefined && agent.thinking !== 'on' && agent.thinking !== 'off')
             throw new AgentRuntimeConfigError(`Role ${role} thinking must be "on" or "off"`);
     }
+    const builtinPolicies = {
+        architect: { access: 'read', artifacts: 'all', openspecSkill: 'openspec-ff-change' },
+        developer: { access: 'write', artifacts: 'tasks-checkboxes', openspecSkill: 'openspec-apply-change' },
+        reviewer: { access: 'read', artifacts: 'none', openspecSkill: 'openspec-verify-change' },
+    };
+    for (const [id, descriptor] of Object.entries(config.roles ?? {})) {
+        if (!agent_role_descriptor_1.RUNTIME_ROLE_ID.test(id) || id === 'fixer')
+            throw new AgentRuntimeConfigError(`Invalid custom role ID: ${id}`);
+        if (descriptor.prompt !== undefined && (!descriptor.prompt.trim() || descriptor.prompt.includes('\0')))
+            throw new AgentRuntimeConfigError(`Role ${id} requires a nonblank prompt without null bytes`);
+        if (ROLES.includes(id)) {
+            const { access, artifacts, openspecSkill, prompt, ...assignment } = descriptor;
+            if (prompt !== undefined || !(0, node_util_1.isDeepStrictEqual)(assignment, config.agents[id]) || !(0, node_util_1.isDeepStrictEqual)({ access, artifacts, openspecSkill }, builtinPolicies[id]))
+                throw new AgentRuntimeConfigError(`Built-in role ${id} must retain its implicit assignment and access policy`);
+        }
+    }
     for (const [key, value] of Object.entries(config.limits ?? {})) {
         if (!Number.isFinite(value) || (key !== 'maxCostUsd' && !Number.isSafeInteger(value)))
             throw new AgentRuntimeConfigError('Workflow limits must be finite, safe numbers');
@@ -301,7 +322,7 @@ function loadRuntimeConfigFile(file, fallbackProvider) {
             throw new AgentRuntimeConfigError('Configure project role models before using API-only connections');
         for (const role of ROLES)
             config.agents[role].provider = selected.id;
-        return validateAgentRuntimeConfig({ ...config, providers });
+        return withCustomAgentRoles(validateAgentRuntimeConfig({ ...config, providers }), file, fallbackProvider);
     }
     if (Array.isArray(parsed.providers)) {
         const legacy = validateAgentRuntimeConfig(parsed);
@@ -309,9 +330,9 @@ function loadRuntimeConfigFile(file, fallbackProvider) {
             let connection = providers.find(item => item.id === original.id);
             if (connection && JSON.stringify(connection) !== JSON.stringify(original)) {
                 const id = `${original.id.slice(0, 117)}-${(0, node_crypto_1.createHash)('sha256').update(JSON.stringify(original)).digest('hex').slice(0, 10)}`;
-                for (const role of ROLES)
-                    if (legacy.agents[role].provider === original.id)
-                        legacy.agents[role].provider = id;
+                for (const role of [...Object.values(legacy.agents), ...Object.values(legacy.roles ?? {}), ...(legacy.fixer ? [legacy.fixer] : [])])
+                    if (role.provider === original.id)
+                        role.provider = id;
                 connection = providers.find(item => item.id === id);
                 if (!connection)
                     providers.push({ ...original, id });
@@ -324,7 +345,24 @@ function loadRuntimeConfigFile(file, fallbackProvider) {
         atomicJson(file, settings);
         parsed = settings;
     }
-    return validateAgentRuntimeConfig({ ...parsed, enabled: true, providers });
+    return withCustomAgentRoles(validateAgentRuntimeConfig({ ...parsed, enabled: true, providers }), file, fallbackProvider);
+}
+/** Agent Studio documents supply defaults; explicit project roles always win. */
+function withCustomAgentRoles(config, file, fallbackProvider) {
+    const connection = config.providers.find(connection => connection.id === config.agents.architect.provider);
+    const provider = fallbackProvider && (0, registry_1.hasAdapter)(fallbackProvider) && (0, registry_1.adapterKind)(fallbackProvider) !== 'local'
+        ? fallbackProvider : connection?.kind === 'cli' ? connection.cli : 'claude';
+    try {
+        const documents = (0, agent_catalog_1.listNativeAgentFiles)(node_path_1.default.dirname(node_path_1.default.dirname(file)), provider).filter(entry => entry.id.startsWith('custom-'))
+            .map(entry => ({ id: entry.id, content: node_fs_1.default.readFileSync(entry.file, 'utf8') }));
+        if (!documents.length)
+            return config;
+        const roles = (0, agent_role_descriptor_1.projectCustomAgentRoles)(documents, config.agents.architect, config.roles);
+        return validateAgentRuntimeConfig({ ...config, roles });
+    }
+    catch (error) {
+        throw new AgentRuntimeConfigError(error instanceof Error ? error.message : 'Custom agent roles could not be loaded');
+    }
 }
 /** Missing settings use the programmatic engine. Malformed files fail closed. */
 function loadAgentRuntimeConfig(project) {
@@ -339,12 +377,12 @@ function saveAgentRuntimeConfig(project, input) {
     return config;
 }
 const PROMPT_ROLES = [...ROLES, 'fixer'];
-function validateRuntimeRolePrompts(input) {
+function validateRuntimeRolePrompts(input, extraRoles = []) {
     if (!input || typeof input !== 'object' || Array.isArray(input))
         throw new AgentRuntimeConfigError('Role prompts must be an object');
     const prompts = {};
     for (const [role, text] of Object.entries(input)) {
-        if (!PROMPT_ROLES.includes(role) || typeof text !== 'string' || !text.trim() || text.length > 20000 || text.includes('\0'))
+        if (![...PROMPT_ROLES, ...extraRoles].includes(role) || typeof text !== 'string' || !text.trim() || text.length > 20000 || text.includes('\0'))
             throw new AgentRuntimeConfigError('Role prompts must use architect, developer, reviewer or fixer with 1–20000 nonblank characters and no null bytes');
         prompts[role] = text;
     }
@@ -382,14 +420,20 @@ function validateRuntimeProviderOverride(value) {
 /** Older Core runtimes reject unknown top-level keys: drop `guardrails` unless the loaded Core advertises `configurableGuardrails`. */
 function forCoreRuntime(config, capabilities) {
     let out = config;
+    if (capabilities?.openRoles !== 1 && out.roles !== undefined) {
+        if (Object.keys(out.roles).length)
+            throw new AgentRuntimeConfigError('Update the paired Core runtime to use custom roles');
+        const { roles: _roles, ...rest } = out;
+        out = rest;
+    }
     if (capabilities?.configurableGuardrails !== 1 && out.guardrails !== undefined) {
         const { guardrails: _dropped, ...rest } = out;
         out = rest;
     }
     // The per-role thinking switch is known only to cores advertising `roleThinkingControl`.
-    if (capabilities?.roleThinkingControl !== 1 && (Object.values(out.agents ?? {}).some(agent => agent?.thinking !== undefined) || out.fixer?.thinking !== undefined)) {
+    if (capabilities?.roleThinkingControl !== 1 && ([...Object.values(out.agents ?? {}), ...Object.values(out.roles ?? {})].some(agent => agent?.thinking !== undefined) || out.fixer?.thinking !== undefined)) {
         const strip = (agent) => { const { thinking: _t, ...rest } = agent; return rest; };
-        out = { ...out, ...(out.agents ? { agents: Object.fromEntries(Object.entries(out.agents).map(([role, agent]) => [role, strip(agent)])) } : {}), ...(out.fixer ? { fixer: strip(out.fixer) } : {}) };
+        out = { ...out, ...(out.agents ? { agents: Object.fromEntries(Object.entries(out.agents).map(([role, agent]) => [role, strip(agent)])) } : {}), ...(out.fixer ? { fixer: strip(out.fixer) } : {}), ...(out.roles ? { roles: Object.fromEntries(Object.entries(out.roles).map(([id, role]) => [id, strip(role)])) } : {}) };
     }
     return out;
 }

package/server/dist/modules/agents/runtime/agent-catalog.js

@@ -0,0 +1,32 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nativeAgentFile = nativeAgentFile;
+exports.nativeAgentsDirectory = nativeAgentsDirectory;
+exports.listNativeAgentFiles = listNativeAgentFiles;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const providers_1 = require("../../../providers");
+/** Provider-native role storage shared by Agent Studio and runtime projection. */
+function nativeAgentFile(root, agentId, provider) {
+    const adapter = (0, providers_1.getAdapter)(provider);
+    return adapter.customRolePath?.(root, agentId) ?? node_path_1.default.join(root, adapter.projectDirName, 'agents', `${agentId}.md`);
+}
+function nativeAgentsDirectory(root, provider) {
+    const probe = nativeAgentFile(root, '__catalog_probe__', provider);
+    return node_path_1.default.basename(probe) === 'SKILL.md' ? node_path_1.default.dirname(node_path_1.default.dirname(probe)) : node_path_1.default.dirname(probe);
+}
+function listNativeAgentFiles(root, provider) {
+    const directory = nativeAgentsDirectory(root, provider);
+    if (!node_fs_1.default.existsSync(directory))
+        return [];
+    return node_fs_1.default.readdirSync(directory, { withFileTypes: true }).flatMap(entry => {
+        const id = entry.isDirectory() ? entry.name : entry.isFile() && entry.name.endsWith('.md') ? entry.name.slice(0, -3) : undefined;
+        if (!id)
+            return [];
+        const file = nativeAgentFile(root, id, provider);
+        return node_fs_1.default.existsSync(file) ? [{ id, file }] : [];
+    }).sort((a, b) => a.id.localeCompare(b.id));
+}

package/server/dist/modules/agents/runtime/agent-refine-manager.js

@@ -12,6 +12,8 @@ const path_1 = __importDefault(require("path"));
 const crypto_1 = require("crypto");
 const tree_kill_1 = __importDefault(require("tree-kill"));
 const agent_generator_1 = require("./agent-generator");
+const agent_role_descriptor_1 = require("./agent-role-descriptor");
+const kimi_skill_prompt_1 = require("../../../providers/kimi-skill-prompt");
 const ai_invocations_1 = require("../../accounting/runtime/ai-invocations");
 const result_event_1 = require("../../accounting/runtime/result-event");
 const spawn_lifecycle_1 = require("../../execution/runtime/spawn-lifecycle");
@@ -199,6 +201,16 @@ class AgentRefineManager {
         if (draftName && draftName !== currentName) {
             return { ok: false, reason: 'name_changed' };
         }
+        // Force only bypasses concurrent disk edits, never the execution contract.
+        try {
+            (0, agent_role_descriptor_1.projectCustomAgentRole)({ id: session.agent_id, content: session.draft_body }, { provider: this._adapter.id });
+            if (this._adapter.id === 'kimi' && (0, kimi_skill_prompt_1.validateKimiRoleDocument)(session.draft_body, session.agent_id, `${session.agent_id}/SKILL.md`).length > 0) {
+                return { ok: false, reason: 'invalid_agent_role' };
+            }
+        }
+        catch {
+            return { ok: false, reason: 'invalid_agent_role' };
+        }
         fs_1.default.writeFileSync(file, session.draft_body, 'utf8');
         const maxVersion = this._db
             .prepare(`SELECT COALESCE(MAX(version), 0) AS v FROM agent_versions

package/server/dist/modules/agents/runtime/agent-role-descriptor.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RUNTIME_ROLE_ID = void 0;
+exports.projectCustomAgentRole = projectCustomAgentRole;
+exports.projectCustomAgentRoles = projectCustomAgentRoles;
+const js_yaml_1 = require("js-yaml");
+exports.RUNTIME_ROLE_ID = /^[a-z][a-z0-9-]{0,63}$/;
+const BUILTINS = new Set(['architect', 'developer', 'reviewer', 'fixer']);
+const object = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+/** Pure frontmatter-to-role mapping; source access never follows model/prompt wording. */
+function projectCustomAgentRole(document, fallback) {
+    const id = document.id.startsWith('custom-') ? document.id.slice(7) : '';
+    if (!exports.RUNTIME_ROLE_ID.test(id) || BUILTINS.has(id))
+        throw new Error(`Custom agent ${document.id} must map to a non-built-in role matching ${exports.RUNTIME_ROLE_ID.source}`);
+    const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)([\s\S]*)$/.exec(document.content);
+    if (!match && document.content.startsWith('---'))
+        throw new Error(`Custom agent ${document.id} has incomplete YAML frontmatter`);
+    const metadata = match ? (0, js_yaml_1.load)(match[1], { schema: js_yaml_1.JSON_SCHEMA }) : {};
+    if (!object(metadata))
+        throw new Error(`Custom agent ${document.id} has invalid frontmatter`);
+    if (metadata.name !== undefined && metadata.name !== document.id)
+        throw new Error(`Custom agent ${document.id} frontmatter name differs from its file identity`);
+    const prompt = (match ? match[2] : document.content).trim();
+    if (!prompt || prompt.length > 20_000 || prompt.includes('\0'))
+        throw new Error(`Custom agent ${document.id} instructions must contain 1–20,000 characters`);
+    const access = metadata.access ?? 'read', artifacts = metadata.artifacts ?? 'none';
+    if (!['read', 'write'].includes(String(access)) || !['none', 'tasks-checkboxes', 'all'].includes(String(artifacts)))
+        throw new Error(`Custom agent ${document.id} declares invalid source or artifact access`);
+    if (metadata.openspecSkill !== undefined && !['openspec-ff-change', 'openspec-apply-change', 'openspec-verify-change'].includes(String(metadata.openspecSkill)))
+        throw new Error(`Custom agent ${document.id} declares an unsupported OpenSpec skill`);
+    const engine = metadata.engine === undefined ? {} : metadata.engine;
+    if (!object(engine) || Object.keys(engine).some(key => !['provider', 'model', 'effort', 'thinking', 'maxTurns', 'escalation'].includes(key)))
+        throw new Error(`Custom agent ${document.id} engine must contain only provider, model, effort, thinking, maxTurns and escalation`);
+    const provider = engine.provider ?? fallback.provider;
+    const model = engine.model ?? (metadata.model === 'inherit' ? undefined : metadata.model) ?? fallback.model;
+    const effort = engine.effort ?? metadata.effort ?? fallback.effort;
+    if (typeof provider !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(provider) ||
+        model !== undefined && (typeof model !== 'string' || !model || model.length > 256 || /^-|[\r\n\0]/.test(model)) ||
+        effort !== undefined && (typeof effort !== 'string' || !/^[a-z][a-z0-9_-]{0,31}$/.test(effort)) ||
+        engine.thinking !== undefined && !['on', 'off'].includes(String(engine.thinking)) ||
+        engine.maxTurns !== undefined && (!Number.isSafeInteger(engine.maxTurns) || engine.maxTurns < 1))
+        throw new Error(`Custom agent ${document.id} has invalid engine settings`);
+    const escalation = engine.escalation;
+    if (escalation !== undefined && (!object(escalation) || Object.keys(escalation).some(key => !['model', 'effort'].includes(key)) ||
+        typeof escalation.model !== 'string' || !escalation.model || escalation.model.length > 256 || /^-|[\r\n\0]/.test(escalation.model) ||
+        escalation.effort !== undefined && (typeof escalation.effort !== 'string' || !/^[a-z][a-z0-9_-]{0,31}$/.test(escalation.effort)) ||
+        !model || escalation.model === model && escalation.effort === effort))
+        throw new Error(`Custom agent ${document.id} escalation requires a valid, different model or effort and an explicit base model`);
+    return { id, role: { provider, ...(model === undefined ? {} : { model: model }), ...(effort === undefined ? {} : { effort: effort }),
+            access: access, artifacts: artifacts, prompt,
+            ...(metadata.openspecSkill === undefined ? {} : { openspecSkill: metadata.openspecSkill }),
+            ...(engine.thinking === undefined ? {} : { thinking: engine.thinking }), ...(engine.maxTurns === undefined ? {} : { maxTurns: engine.maxTurns }),
+            ...(escalation === undefined ? {} : { escalation: escalation }) } };
+}
+function projectCustomAgentRoles(documents, fallback, explicit = {}) {
+    const roles = {};
+    for (const document of documents) {
+        const { id, role } = projectCustomAgentRole(document, fallback);
+        if (Object.hasOwn(roles, id))
+            throw new Error(`Duplicate custom agent role ${id}`);
+        roles[id] = { ...role, ...explicit[id] };
+    }
+    return { ...roles, ...Object.fromEntries(Object.entries(explicit).filter(([id]) => !Object.hasOwn(roles, id))) };
+}

package/server/dist/modules/agents/runtime/profiles-router.js

@@ -6,6 +6,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.providerSupportsAgentStudioAutomation = providerSupportsAgentStudioAutomation;
 exports.createProfilesRouter = createProfilesRouter;
 const fs_1 = __importDefault(require("fs"));
+const agent_catalog_1 = require("./agent-catalog");
+const agent_role_descriptor_1 = require("./agent-role-descriptor");
 const core_runtime_1 = require("../../../core-runtime");
 const path_1 = __importDefault(require("path"));
 const express_1 = require("express");
@@ -60,38 +62,13 @@ function projectAdapter(project, provider) {
     return (0, providers_1.getAdapter)(provider ?? project.provider ?? 'claude');
 }
 function agentFile(project, agentId, provider) {
-    const root = specRoot(project);
-    const adapter = projectAdapter(project, provider);
-    return adapter.customRolePath?.(root, agentId)
-        ?? path_1.default.join(root, adapter.projectDirName, 'agents', `${agentId}.md`);
+    return (0, agent_catalog_1.nativeAgentFile)(specRoot(project), agentId, provider ?? project.provider ?? 'claude');
 }
-/** The provider-native roles catalog directory. */
 function agentsCatalogDir(project, provider) {
-    const probe = agentFile(project, '__catalog_probe__', provider);
-    // File-based roles use `<catalog>/<id>.md`; skill-based roles (Kimi) use
-    // `<catalog>/<id>/SKILL.md`.
-    return path_1.default.basename(probe) === 'SKILL.md'
-        ? path_1.default.dirname(path_1.default.dirname(probe))
-        : path_1.default.dirname(probe);
+    return (0, agent_catalog_1.nativeAgentsDirectory)(specRoot(project), provider ?? project.provider ?? 'claude');
 }
 function listAgentFiles(project, provider) {
-    const dir = agentsCatalogDir(project, provider);
-    if (!fs_1.default.existsSync(dir))
-        return [];
-    const out = [];
-    for (const entry of fs_1.default.readdirSync(dir, { withFileTypes: true })) {
-        const id = entry.isDirectory()
-            ? entry.name
-            : entry.isFile() && entry.name.endsWith('.md')
-                ? entry.name.slice(0, -3)
-                : null;
-        if (!id)
-            continue;
-        const file = agentFile(project, id, provider);
-        if (fs_1.default.existsSync(file))
-            out.push({ id, file });
-    }
-    return out;
+    return (0, agent_catalog_1.listNativeAgentFiles)(specRoot(project), provider ?? project.provider ?? 'claude');
 }
 const AGENTS_SECTION_ENABLED = process.env.SPECRAILS_AGENTS_SECTION !== 'false';
 function handleError(res, err) {
@@ -135,9 +112,14 @@ function requireSafeStudioPolicy(res, provider) {
  * leaf (fs/path/js-yaml only), so this direct import does not create a router /
  * adapter cycle. */
 function validateCustomRoleBody(provider, agentId, body) {
-    if (provider !== 'kimi')
-        return [];
-    return (0, kimi_skill_prompt_1.validateKimiRoleDocument)(body, agentId, `${agentId}/SKILL.md`);
+    const errors = provider === 'kimi' ? (0, kimi_skill_prompt_1.validateKimiRoleDocument)(body, agentId, `${agentId}/SKILL.md`) : [];
+    try {
+        (0, agent_role_descriptor_1.projectCustomAgentRole)({ id: agentId, content: body }, { provider });
+    }
+    catch (error) {
+        errors.push(error instanceof Error ? error.message : 'Invalid Core role descriptor');
+    }
+    return errors;
 }
 function createProfilesRouter() {
     const router = (0, express_1.Router)({ mergeParams: true });
@@ -419,8 +401,18 @@ function createProfilesRouter() {
                     continue;
                 let description;
                 let model;
+                let projected = {};
                 try {
                     const body = fs_1.default.readFileSync(entry.file, 'utf8');
+                    if (kind === 'custom') {
+                        try {
+                            const result = (0, agent_role_descriptor_1.projectCustomAgentRole)({ id, content: body }, { provider });
+                            projected = { roleId: result.id, runtimeRoleDefaults: result.role };
+                        }
+                        catch (error) {
+                            projected = { runtimeRoleError: error instanceof Error ? error.message : 'Invalid Core role descriptor' };
+                        }
+                    }
                     if (provider === 'kimi') {
                         // Use the same js-yaml metadata parser as validation/execution so
                         // folded/literal descriptions and quoted scalars render correctly.
@@ -466,7 +458,7 @@ function createProfilesRouter() {
                 catch {
                     // ignore unreadable files
                 }
-                agents.push({ id, kind, description, model });
+                agents.push({ id, kind, description, model, ...projected });
             }
             agents.sort((a, b) => a.id.localeCompare(b.id));
             res.json({ agents });
@@ -517,7 +509,7 @@ function createProfilesRouter() {
             }
             const roleErrors = validateCustomRoleBody(provider, id, body);
             if (roleErrors.length > 0) {
-                res.status(400).json({ error: 'invalid_kimi_skill', details: roleErrors });
+                res.status(400).json({ error: provider === 'kimi' ? 'invalid_kimi_skill' : 'invalid_agent_role', details: roleErrors });
                 return;
             }
             const file = agentFile(project, id, provider);
@@ -556,7 +548,7 @@ function createProfilesRouter() {
             }
             const roleErrors = validateCustomRoleBody(provider, agentId, body);
             if (roleErrors.length > 0) {
-                res.status(400).json({ error: 'invalid_kimi_skill', details: roleErrors });
+                res.status(400).json({ error: provider === 'kimi' ? 'invalid_kimi_skill' : 'invalid_agent_role', details: roleErrors });
                 return;
             }
             const file = agentFile(project, agentId, provider);