mixdog 0.9.1 → 0.9.2

package/src/runtime/agent/orchestrator/context/collect.mjs

@@ -1,6 +1,6 @@
 import { readFileSync, existsSync, readdirSync } from 'fs';
 import { homedir } from 'os';
-import { join } from 'path';
+import { dirname, join } from 'path';
 import { maxMtimeRecursive } from '../cache-mtime.mjs';
 import { resolvePluginData, mixdogRoot } from '../../../shared/plugin-paths.mjs';
 import {
@@ -121,6 +121,70 @@ export function loadSkillContent(name, cwd) {
     return readSafe(skill.filePath);
 }
 
+/**
+ * Load full skill content plus its on-disk directory (for base-dir + ${MIXDOG_SKILL_DIR}).
+ */
+export function loadSkillResource(name, cwd) {
+    const skills = collectSkillsCached(cwd);
+    const skill = skills.find(s => s.name === name);
+    if (!skill)
+        return null;
+    const content = readSafe(skill.filePath);
+    if (content == null)
+        return null;
+    return { content, dir: dirname(skill.filePath), filePath: skill.filePath };
+}
+
+function escapeSkillXmlText(value) {
+    return String(value || '').replace(/[<>&]/g, (ch) => ({ '<': '&lt;', '>': '&gt;', '&': '&amp;' }[ch]));
+}
+
+/**
+ * Wrap loaded SKILL.md body for Skill tool results (runtime + loop).
+ */
+export function buildSkillResultEnvelope(name, content, skillDir) {
+    const escapedName = escapeSkillXmlText(name);
+    let body = String(content == null ? '' : content);
+    let dirLine = '';
+    if (skillDir) {
+        const normDir = String(skillDir).replace(/\\/g, '/');
+        body = body.replace(/\$\{MIXDOG_SKILL_DIR\}/g, normDir);
+        const escapedDir = escapeSkillXmlText(normDir);
+        dirLine = `<base-dir>${escapedDir}</base-dir>\n`;
+    }
+    return `<skill>\n<name>${escapedName}</name>\n${dirLine}${body}\n</skill>`;
+}
+
+/**
+ * Short, model-visible tool_result stub for a loaded skill. The full SKILL.md
+ * body is delivered separately as ONE injected user message (newMessages),
+ * never in the tool_result — so the body appears exactly once.
+ */
+export function buildSkillStub(name) {
+    return `Loaded skill: ${String(name || '').trim()}`;
+}
+
+/**
+ * Build the Skill tool-result envelope used by BOTH the agent-loop viewSkill
+ * path and the runtime skillToolContent path so behavior matches across main
+ * + agent sessions:
+ *   - result      = short stub (`Loaded skill: <name>`), no body.
+ *   - newMessages = exactly ONE role:'user' message carrying the full
+ *                   buildSkillResultEnvelope output (<base-dir> + body).
+ * The injected user message is flagged `meta:'skill'` so compaction's
+ * "latest human prompt" selection does not mistake the skill body for the
+ * human's request.
+ */
+export function buildSkillToolEnvelope(name, content, skillDir) {
+    return {
+        __toolEnvelope: true,
+        result: buildSkillStub(name),
+        newMessages: [
+            { role: 'user', content: buildSkillResultEnvelope(name, content, skillDir), meta: 'skill' },
+        ],
+    };
+}
+
 function compactSkillManifestText(value, max = 180) {
     const text = String(value || '').replace(/\s+/g, ' ').trim();
     return text.length > max ? `${text.slice(0, Math.max(1, max - 3))}...` : text;
@@ -194,34 +258,34 @@ export function buildSkillToolDefs(skills, { ownerIsAgentSession = false } = {})
     ];
     return _skillToolDefsCache;
 }
-// --- Role-scoped instruction loader ---
-// Emits a BP2 role/system block scoped to the calling role:
-//   - Public/custom agents: their own agents/<role>.md when present,
+// --- Agent-scoped instruction loader ---
+// Emits a BP2 agent/system block scoped to the calling agent:
+//   - Public/custom agents: their own agents/<agent>.md when present,
 //     plus the public agent-worker contract.
-//   - Hidden roles: their own rules/agent/<role>.md section only.
-//   - Null role: falls back to the full all-in-one block
+//   - Hidden agents: their own rules/agent/<agent>.md section only.
+//   - Null agent: falls back to the full all-in-one block
 //     (explicit-cache unified-shard path).
 //
-// Role-specific markdown intentionally rides BP2, behind the shared BP1 tool
-// and skill manifest prefix, so role changes do not disturb the common layer.
+// Agent-specific markdown intentionally rides BP2, behind the shared BP1 tool
+// and skill manifest prefix, so agent changes do not disturb the common layer.
 //
 // Classification is dynamic — hidden retrieval/maintenance sets come from the
-// `kind` field in internal-roles.mjs. Any other non-null role is public/custom.
+// `kind` field in internal-agents.mjs. Any other non-null agent is public/custom.
 import {
-    listHiddenRolesByKind,
-    isHiddenRole,
-    getRoleCatalogShareAgents,
-    isInboundEventRole,
-} from '../internal-roles.mjs';
+    listHiddenAgentsByKind,
+    isHiddenAgent,
+    getAgentCatalogShareAgents,
+    isInboundEventAgent,
+} from '../internal-agents.mjs';
 
-function loadRoleClassification() {
+function loadAgentClassification() {
     // Not cached — called only on instruction rebuild (mtime-busted), and
-    // listHiddenRolesByKind now reads from the mtime-aware cache inside
-    // internal-roles.mjs so the classification always reflects the current
-    // hidden-roles.json on disk.
+    // listHiddenAgentsByKind now reads from the mtime-aware cache inside
+    // internal-agents.mjs so the classification always reflects the current
+    // agents.json on disk.
     return {
-        retrieval: new Set(listHiddenRolesByKind('retrieval')),
-        maintenance: new Set(listHiddenRolesByKind('maintenance')),
+        retrieval: new Set(listHiddenAgentsByKind('retrieval')),
+        maintenance: new Set(listHiddenAgentsByKind('maintenance')),
     };
 }
 
@@ -235,7 +299,7 @@ const _scopedRoleInstructionsCache = new Map();
 const _scopedRoleInstructionsMtimeCache = new Map();
 const _ROLE_INSTRUCTIONS_MTIME_TTL_MS = 2000;
 
-function loadHiddenRoleSnippets(pluginRoot) {
+function loadHiddenAgentSnippets(pluginRoot) {
     try {
         const agentRulesDir = join(pluginRoot, 'rules', 'agent');
         if (!existsSync(agentRulesDir)) return [];
@@ -262,11 +326,11 @@ function loadAgentSections(pluginRoot) {
     const agentSections = [];
     if (!existsSync(agentsDir)) return agentSections;
     // agents/ holds two layouts that must BOTH be loaded:
-    //   - flat:    agents/<role>.md                 (legacy: scheduler-task, webhook-handler)
-    //   - nested:  agents/<role>/AGENT.md           (current: worker, heavy-worker, reviewer, …)
-    // The previous flat-only readdir silently dropped every nested role, so a
-    // public role like heavy-worker produced an EMPTY scoped instruction block
-    // (BP2) — the model lost its role contract and the tool smoke's
+    //   - flat:    agents/<agent>.md                (legacy: scheduler-task, webhook-handler)
+    //   - nested:  agents/<agent>/AGENT.md          (current: worker, heavy-worker, reviewer, …)
+    // The previous flat-only readdir silently dropped every nested agent, so a
+    // public agent like heavy-worker produced an EMPTY scoped instruction block
+    // (BP2) — the model lost its agent contract and the tool smoke's
     // "heavy-worker AGENT.md must be included" assertion failed. Walk both.
     let entries;
     try {
@@ -295,22 +359,22 @@ function loadAgentSections(pluginRoot) {
     return agentSections;
 }
 
-// Empty by design: scoped role markdown already rides BP2 for every provider.
+// Empty by design: scoped agent markdown already rides BP2 for every provider.
 // Keeping the set in place preserves the old branch point for a future
 // provider-specific experiment without changing today's cache layout.
 const EXPLICIT_CACHE_PROVIDERS = new Set();
 
-// Inbound-event maintenance roles that report results back to Lead are
-// declared via `inboundEvent: true` in defaults/hidden-roles.json and read
-// through isInboundEventRole(). Such roles must follow
+// Inbound-event maintenance agents that report results back to Lead are
+// declared via `inboundEvent: true` in defaults/agents.json and read
+// through isInboundEventAgent(). Such agents must follow
 // rules/agent/20-skip-protocol.md so genuine no-ops (label-only events,
 // dedup, "nothing to report") prefix their output with `[meta:silent]` and the
-// dispatch layer suppresses the Lead inject. Other roles (cycle1/cycle2 memory
-// maintenance, retrieval roles) never emit toward Lead.
+// dispatch layer suppresses the Lead inject. Other agents (cycle1/cycle2 memory
+// maintenance, retrieval agents) never emit toward Lead.
 
-export function loadScopedRoleInstructions(role, provider = null) {
+export function loadScopedRoleInstructions(agent, provider = null) {
     const useUnified = !!(provider && EXPLICIT_CACHE_PROVIDERS.has(provider));
-    const cacheKey = useUnified ? '__unified__' : (role || '__all__');
+    const cacheKey = useUnified ? '__unified__' : (agent || '__all__');
     const cached = _scopedRoleInstructionsCache.get(cacheKey);
     const pluginRoot = mixdogRoot();
     // Use maxMtimeRecursive so edits to .md files inside agents/ and
@@ -327,7 +391,7 @@ export function loadScopedRoleInstructions(role, provider = null) {
             mtime = maxMtimeRecursive([
                 join(pluginRoot, 'agents'),
                 join(pluginRoot, 'rules', 'agent'),
-                join(pluginRoot, 'defaults', 'hidden-roles.json'),
+                join(pluginRoot, 'defaults', 'agents.json'),
             ]);
             _scopedRoleInstructionsMtimeCache.set(cacheKey, { mtime, checkedAt: Date.now() });
             if (_scopedRoleInstructionsMtimeCache.size > 16) {
@@ -338,68 +402,68 @@ export function loadScopedRoleInstructions(role, provider = null) {
     if (cached && mtime <= cached.mtime) {
         return cached.value;
     }
-    // Compute classification before file loading — internal-roles metadata
-    // failures (malformed/missing hidden-roles.json) must propagate, not be
+    // Compute classification before file loading — internal-agents metadata
+    // failures (malformed/missing agents.json) must propagate, not be
     // silently swallowed by the file-IO catch below.
-    const classification = loadRoleClassification();
-    const roleSharesCatalog = role && classification.retrieval.has(role)
-        ? new Set(getRoleCatalogShareAgents(role))
+    const classification = loadAgentClassification();
+    const agentSharesCatalog = agent && classification.retrieval.has(agent)
+        ? new Set(getAgentCatalogShareAgents(agent))
         : new Set();
-    const roleIsInboundEvent = role && classification.maintenance.has(role)
-        ? isInboundEventRole(role)
+    const agentIsInboundEvent = agent && classification.maintenance.has(agent)
+        ? isInboundEventAgent(agent)
         : false;
 
     try {
         const agentSections = loadAgentSections(pluginRoot);
-        const hiddenPairs = loadHiddenRoleSnippets(pluginRoot);
+        const hiddenPairs = loadHiddenAgentSnippets(pluginRoot);
 
-        // Pick which agent-rule sections + agents/<role>.md sections to emit
-        // based on role classification. Self-only emit keeps BP2 minimal.
+        // Pick which agent-rule sections + agents/<agent>.md sections to emit
+        // based on agent classification. Self-only emit keeps BP2 minimal.
         let agentRuleSectionsToEmit = null; // null -> drop the agent-rule block entirely
-        let agentSectionsToEmit = agentSections; // default: full (unknown-role fallback)
+        let agentSectionsToEmit = agentSections; // default: full (unknown-agent fallback)
         if (useUnified) {
-            // Explicit-cache providers — every role sees the same all-in-one
-            // instruction surface. Cross-role calls hit the same provider-side prefix
-            // shard, eliminating the role-shard miss seen on Pool C
+            // Explicit-cache providers — every agent sees the same all-in-one
+            // instruction surface. Cross-agent calls hit the same provider-side prefix
+            // shard, eliminating the agent-shard miss seen on Pool C
             // transitions for openai-oauth/openai. This branch is disabled by the
-            // empty provider set above; BP2 remains the active role surface.
+            // empty provider set above; BP2 remains the active agent surface.
             agentRuleSectionsToEmit = hiddenPairs.map(p => `## ${p.name}\n\n${p.body}`);
             agentSectionsToEmit = agentSections;
-        } else if (role && classification.retrieval.has(role)) {
-            // Retrieval roles (explorer) get their own contract section
+        } else if (agent && classification.retrieval.has(agent)) {
+            // Retrieval agents (explorer) get their own contract section
             // (rules/agent/30-explorer.md) in BP2.
-            const self = hiddenPairs.find(p => p.name === role);
+            const self = hiddenPairs.find(p => p.name === agent);
             agentRuleSectionsToEmit = self ? [`## ${self.name}\n\n${self.body}`] : [];
             agentSectionsToEmit = agentSections.filter(s =>
-                [...roleSharesCatalog].some(name => s.startsWith(`## ${name}\n`)));
-        } else if (role && classification.maintenance.has(role)) {
-            const self = hiddenPairs.find(p => p.name === role);
+                [...agentSharesCatalog].some(name => s.startsWith(`## ${name}\n`)));
+        } else if (agent && classification.maintenance.has(agent)) {
+            const self = hiddenPairs.find(p => p.name === agent);
             agentRuleSectionsToEmit = [];
             if (self) {
                 agentRuleSectionsToEmit.push(`## ${self.name}\n\n${self.body}`);
             } else {
-                // Fallback: maintenance role without rules/agent/*.md entry —
-                // pull self body from agents/<role>.md instead so newly-added
-                // hidden roles work without needing a duplicate agent rule file.
-                const fromAgent = agentSections.find(s => s.startsWith(`## ${role}\n`));
+                // Self body from agents/<agent>.md for a maintenance agent
+                // without a rules/agent/*.md entry so newly-added hidden agents
+                // work without needing a duplicate agent rule file.
+                const fromAgent = agentSections.find(s => s.startsWith(`## ${agent}\n`));
                 if (fromAgent) agentRuleSectionsToEmit.push(fromAgent);
             }
-            // Inbound-event roles also need the skip-protocol rule so they
+            // Inbound-event agents also need the skip-protocol rule so they
             // can opt their no-op outputs out of the Lead inject (BP1 would
             // waste the bytes on unrelated agents).
-            if (roleIsInboundEvent) {
+            if (agentIsInboundEvent) {
                 const skip = hiddenPairs.find(p => p.name === 'skip-protocol');
                 if (skip) agentRuleSectionsToEmit.push(`## ${skip.name}\n\n${skip.body}`);
             }
             agentSectionsToEmit = [];
-        } else if (role) {
-            // Public/custom role — self-only agents/<role>.md when present,
+        } else if (agent) {
+            // Public/custom agent — self-only agents/<agent>.md when present,
             // not the full hidden/maintenance bundle. The universal agent
             // contract rides BP2 (rules/agent/00-common.md).
             agentRuleSectionsToEmit = [];
-            agentSectionsToEmit = agentSections.filter(s => s.startsWith(`## ${role}\n`));
+            agentSectionsToEmit = agentSections.filter(s => s.startsWith(`## ${agent}\n`));
         } else {
-            // Null role — full instruction surface emitted (explicit-cache providers that
+            // Null agent — full instruction surface emitted (explicit-cache providers that
             // shard by __all__ key).
             agentRuleSectionsToEmit = hiddenPairs.map(p => `## ${p.name}\n\n${p.body}`);
             // agentSectionsToEmit already set to full agentSections above.
@@ -448,7 +512,7 @@ export function composeSystemPrompt(opts) {
     // ── BP2: role/system layer ─────────────────────────────────────────
     const roleInstructionContext = opts.skipRoleCatalog
         ? ''
-        : loadScopedRoleInstructions(opts.role || null, opts.provider || null);
+        : loadScopedRoleInstructions(opts.agent || null, opts.provider || null);
     const stableSystemParts = [];
     if (opts.roleRules) stableSystemParts.push(opts.roleRules);
     if (opts.userPrompt) stableSystemParts.push(opts.userPrompt);

package/src/runtime/agent/orchestrator/{internal-roles.mjs → internal-agents.mjs}

@@ -1,50 +1,50 @@
 /**
- * Internal hidden roles — Mixdog-managed, user-untouchable.
+ * Internal hidden agents — Mixdog-managed, user-untouchable.
  *
- * Unlike public workflow agents, these hidden roles are NEVER exposed to callers of the `agent` tool. They are
+ * Unlike public workflow agents, these hidden agents are NEVER exposed to callers of the `agent` tool. They are
  * invoked only by internal handlers (explore / recall / search) and carry
  * their own system prompt + tool-set policy.
  *
  * Lookup order (agent-dispatch.resolvePresetName):
  *   1. explicit preset arg
  *   2. opts.preset
- *   3. hidden-role registry (defaults/hidden-roles.json + systemFile frontmatter)
+ *   3. hidden-agent registry (defaults/agents.json + systemFile frontmatter)
  *
- * Role definitions live in defaults/hidden-roles.json and the referenced
+ * Agent definitions live in defaults/agents.json and the referenced
  * systemFile markdown frontmatter. Editing those files is a Mixdog source change.
  *
  * The preset names refer to entries seeded in mixdog-config.json (agent.presets)
  * via DEFAULT_PRESETS (see config.mjs). If the user deletes the referenced preset
- * from their config the hidden roles degrade gracefully — `resolvePresetName`
+ * from their config the hidden agents degrade gracefully — `resolvePresetName`
  * returns a name, but session creation will fail with a clear "preset not
  * found" error rather than silently mis-dispatching.
  *
  * Kind classification:
- *   - 'retrieval'   : short-lived hidden retrieval roles (explore).
- *   - 'maintenance' : background-trigger hidden roles (memory cycle, scheduler,
+ *   - 'retrieval'   : short-lived hidden retrieval agents (explore).
+ *   - 'maintenance' : background-trigger hidden agents (memory cycle, scheduler,
  *                     webhook). Receive only their own self section in BP2.
  *
  * Permission classification:
  *   - 'read'       : read-only — apply_patch/shell blocked at loop.mjs runtime
- *                    guard with the same error string public read-only roles see.
- *   - 'read-write' : full tool surface — used by hidden roles that legitimately
+ *                    guard with the same error string public read-only agents see.
+ *   - 'read-write' : full tool surface — used by hidden agents that legitimately
  *                    mutate state (scheduler-task launches commands,
  *                    webhook-handler persists payloads). agent-dispatch honors this
- *                    declaratively instead of forcing every hidden role to 'read'.
+ *                    declaratively instead of forcing every hidden agent to 'read'.
  *
  * Tool schema profile:
- *   - 'none' : no tools exposed; pure transform/classifier roles.
+ *   - 'none' : no tools exposed; pure transform/classifier agents.
  *   - 'read' : read/search/code-navigation tools only.
  *   - 'full' : shared agent tool schema for provider cache reuse.
  *
- * Role-specific instruction metadata (consumed by rules-builder.cjs
+ * Agent-specific instruction metadata (consumed by rules-builder.cjs
  * buildAgentRoleSpecificContent + collect.mjs):
- *   - inboundEvent   : role reports results back to Lead and must carry the
+ *   - inboundEvent   : agent reports results back to Lead and must carry the
  *                      skip-protocol rule (rules/agent/20-skip-protocol.md)
- *                      in its BP2 role-rule block so no-op outputs opt out of the Lead
+ *                      in its BP2 agent-rule block so no-op outputs opt out of the Lead
  *                      inject.
  *   - instructionDir : DATA_DIR subdir whose *.md tree is folded into the
- *                      role's BP4-adjacent user/task data (webhook-handler →
+ *                      agent's BP4-adjacent user/task data (webhook-handler →
  *                      webhooks, scheduler-task → schedules).
  */
 
@@ -56,24 +56,24 @@ import {
   parseMarkdownFrontmatter,
 } from '../../shared/markdown-frontmatter.mjs'
 
-// Resolve the path to defaults/hidden-roles.json once.
+// Resolve the path to defaults/agents.json once.
 const _MIXDOG_ROOT = mixdogRoot()
-const _HIDDEN_ROLES_PATH = (() => {
-  return join(_MIXDOG_ROOT, 'defaults', 'hidden-roles.json')
+const _AGENTS_PATH = (() => {
+  return join(_MIXDOG_ROOT, 'defaults', 'agents.json')
 })()
 
 /** @type {{ mtime: number, map: object } | null} */
-let _hiddenRolesCache = null
+let _hiddenAgentsCache = null
 
 function _mtimeSafe(file) {
   try { return statSync(file).mtimeMs } catch { return 0 }
 }
 
-function _hiddenRolesDependencyMtime() {
-  let mtime = _mtimeSafe(_HIDDEN_ROLES_PATH)
+function _hiddenAgentsDependencyMtime() {
+  let mtime = _mtimeSafe(_AGENTS_PATH)
   try {
-    const raw = JSON.parse(readFileSync(_HIDDEN_ROLES_PATH, 'utf8'))
-    for (const entry of (raw.roles || [])) {
+    const raw = JSON.parse(readFileSync(_AGENTS_PATH, 'utf8'))
+    for (const entry of (raw.agents || [])) {
       const systemFile = typeof entry?.systemFile === 'string' ? entry.systemFile.trim() : ''
       if (!systemFile) continue
       mtime = Math.max(mtime, _mtimeSafe(join(_MIXDOG_ROOT, systemFile)))
@@ -82,7 +82,7 @@ function _hiddenRolesDependencyMtime() {
   return mtime
 }
 
-function _loadHiddenRoleFrontmatter(systemFile) {
+function _loadHiddenAgentFrontmatter(systemFile) {
   const rel = typeof systemFile === 'string' ? systemFile.trim() : ''
   if (!rel) return {}
   try {
@@ -92,8 +92,8 @@ function _loadHiddenRoleFrontmatter(systemFile) {
   }
 }
 
-function _mergeHiddenRoleFrontmatter(entry) {
-  const fm = _loadHiddenRoleFrontmatter(entry.systemFile)
+function _mergeHiddenAgentFrontmatter(entry) {
+  const fm = _loadHiddenAgentFrontmatter(entry.systemFile)
   const merged = { ...entry }
   const permission = normalizeAgentPermissionOrNone(fm.permission)
   if (permission) merged.permission = permission
@@ -111,62 +111,62 @@ function _mergeHiddenRoleFrontmatter(entry) {
 }
 
 /**
- * Read and parse defaults/hidden-roles.json. Throws on missing/malformed.
+ * Read and parse defaults/agents.json. Throws on missing/malformed.
  */
-function _loadHiddenRoles() {
+function _loadHiddenAgents() {
   try {
-    const raw = JSON.parse(readFileSync(_HIDDEN_ROLES_PATH, 'utf8'))
+    const raw = JSON.parse(readFileSync(_AGENTS_PATH, 'utf8'))
     const map = Object.create(null)
-    for (const entry of (raw.roles || [])) {
-      if (entry && entry.name) map[entry.name] = Object.freeze(_mergeHiddenRoleFrontmatter(entry))
+    for (const entry of (raw.agents || [])) {
+      if (entry && entry.agent) map[entry.agent] = Object.freeze(_mergeHiddenAgentFrontmatter(entry))
     }
     return Object.freeze(map)
   } catch (err) {
-    // Fail loudly — a missing or malformed hidden-roles.json breaks dispatch.
-    throw new Error(`[internal-roles] failed to load defaults/hidden-roles.json: ${err.message}`)
+    // Fail loudly — a missing or malformed agents.json breaks dispatch.
+    throw new Error(`[internal-agents] failed to load defaults/agents.json: ${err.message}`)
   }
 }
 
 /**
- * Return the hidden-role map, re-reading from disk when the file mtime has
+ * Return the hidden-agent map, re-reading from disk when the file mtime has
  * changed since the last load. This ensures that BP2 cache rebuilds triggered
- * by a hidden-roles.json modification (tracked via maxMtimeRecursive in
+ * by an agents.json modification (tracked via maxMtimeRecursive in
  * collect.mjs) consume fresh metadata in the same process.
  */
-function _getHiddenRoles() {
+function _getHiddenAgents() {
   try {
-    const mtime = _hiddenRolesDependencyMtime()
-    if (_hiddenRolesCache && mtime <= _hiddenRolesCache.mtime) {
-      return _hiddenRolesCache.map
+    const mtime = _hiddenAgentsDependencyMtime()
+    if (_hiddenAgentsCache && mtime <= _hiddenAgentsCache.mtime) {
+      return _hiddenAgentsCache.map
     }
-    const map = _loadHiddenRoles()
-    _hiddenRolesCache = { mtime, map }
+    const map = _loadHiddenAgents()
+    _hiddenAgentsCache = { mtime, map }
     return map
   } catch (err) {
     // Fail loudly — re-throw with a clear message. A cache hit is never used
     // when statSync fails because the caller expects current data.
-    throw new Error(`[internal-roles] failed to load defaults/hidden-roles.json: ${err.message}`)
+    throw new Error(`[internal-agents] failed to load defaults/agents.json: ${err.message}`)
   }
 }
 
 // Eager validate at module init so startup failures are immediate.
-_getHiddenRoles()
+_getHiddenAgents()
 
 /**
- * Return the hidden-role definition, or null if the name is not internal.
+ * Return the hidden-agent definition, or null if the name is not internal.
  */
-export function getHiddenRole(name) {
+export function getHiddenAgent(name) {
   if (!name) return null
-  return _getHiddenRoles()[name] || null
+  return _getHiddenAgents()[name] || null
 }
 
 /**
- * Resolve permission stamped on a agent session. Hidden roles declared
+ * Resolve permission stamped on a agent session. Hidden agents declared
  * `permission: 'read'` are read-locked — caller opts cannot upgrade them.
  * Other built-in permissions include `none`, `read-write`, `mcp`, and `full`.
  */
-export function resolveAgentSessionPermission(role, callerPermission) {
-  const hidden = getHiddenRole(role)
+export function resolveAgentSessionPermission(agent, callerPermission) {
+  const hidden = getHiddenAgent(agent)
   if (hidden && hidden.permission === 'read') return 'read'
   if (callerPermission != null && callerPermission !== '') return callerPermission
   if (hidden?.permission) return hidden.permission
@@ -176,61 +176,61 @@ export function resolveAgentSessionPermission(role, callerPermission) {
 /**
  * Boolean check — useful for branching inside agent-dispatch / session-manager.
  */
-export function isHiddenRole(name) {
+export function isHiddenAgent(name) {
   if (!name) return false
-  return Object.prototype.hasOwnProperty.call(_getHiddenRoles(), name)
+  return Object.prototype.hasOwnProperty.call(_getHiddenAgents(), name)
 }
 
 /**
- * List all hidden role names. Used by diagnostics / setup UI guards to ensure
- * a user-defined role doesn't collide with an internal one.
+ * List all hidden agent names. Used by diagnostics / setup UI guards to ensure
+ * a user-defined agent doesn't collide with an internal one.
  */
-export function listHiddenRoleNames() {
-  return Object.keys(_getHiddenRoles())
+export function listHiddenAgentNames() {
+  return Object.keys(_getHiddenAgents())
 }
 
 /**
- * List hidden role names matching a given kind ('retrieval' | 'maintenance').
- * Consumed by collect.mjs to drive BP2 role-shard classification dynamically
- * instead of hard-coding role-name sets.
+ * List hidden agent names matching a given kind ('retrieval' | 'maintenance').
+ * Consumed by collect.mjs to drive BP2 agent-shard classification dynamically
+ * instead of hard-coding agent-name sets.
  */
-export function listHiddenRolesByKind(kind) {
+export function listHiddenAgentsByKind(kind) {
   const out = []
-  for (const [name, def] of Object.entries(_getHiddenRoles())) {
+  for (const [name, def] of Object.entries(_getHiddenAgents())) {
     if (def.kind === kind) out.push(name)
   }
   return out
 }
 
 /**
- * Return the agents/<name>.md sections a hidden role shares in its BP2 catalog
+ * Return the agents/<name>.md sections a hidden agent shares in its BP2 catalog
  * (in addition to its own self section). Drives the explorer→worker cache
- * alignment declaratively instead of a hard-coded role-name branch in
- * collect.mjs. Returns [] when the role declares none.
+ * alignment declaratively instead of a hard-coded agent-name branch in
+ * collect.mjs. Returns [] when the agent declares none.
  */
-export function getRoleCatalogShareAgents(name) {
-  const hidden = getHiddenRole(name)
+export function getAgentCatalogShareAgents(name) {
+  const hidden = getHiddenAgent(name)
   if (!hidden || !Array.isArray(hidden.catalogShareAgents)) return []
   return hidden.catalogShareAgents.map((n) => String(n || '').trim()).filter(Boolean)
 }
 
 /**
- * True when a hidden role reports results back to Lead and must carry the
- * skip-protocol rule in its BP2 role-rule block. Replaces the hard-coded
+ * True when a hidden agent reports results back to Lead and must carry the
+ * skip-protocol rule in its BP2 agent-rule block. Replaces the hard-coded
  * INBOUND_EVENT_ROLES set in collect.mjs.
  */
-export function isInboundEventRole(name) {
-  const hidden = getHiddenRole(name)
+export function isInboundEventAgent(name) {
+  const hidden = getHiddenAgent(name)
   return !!(hidden && hidden.inboundEvent === true)
 }
 
 /**
  * Return the DATA_DIR subdir whose *.md tree rides as BP4-adjacent
- * user/task data, or null when the role declares none. Replaces the
+ * user/task data, or null when the agent declares none. Replaces the
  * webhook/scheduler ternary in rules-builder.cjs buildAgentRoleSpecificContent.
  */
-export function getRoleInstructionDir(name) {
-  const hidden = getHiddenRole(name)
+export function getAgentInstructionDir(name) {
+  const hidden = getHiddenAgent(name)
   const dir = hidden && typeof hidden.instructionDir === 'string' ? hidden.instructionDir.trim() : ''
   return dir || null
 }