mixdog 0.9.1 → 0.9.3

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 {
@@ -33,6 +33,47 @@ function mixdogAssetDirs(projectDir, kind) {
     dirs.push(mixdogGlobalDir(kind));
     return dirs;
 }
+/**
+ * Absolute path to the plugin registry file, or null when the data dir is
+ * unresolvable. Included in the skills mtime gate so plugin add/remove
+ * (which rewrites registry.json) invalidates the cached skill list even
+ * when no surviving skills dir got a newer mtime.
+ */
+function pluginRegistryPath() {
+    try {
+        return join(resolvePluginData(), 'plugins', 'registry.json');
+    } catch {
+        return null;
+    }
+}
+/**
+ * Read `<resolvePluginData()>/plugins/registry.json` (safe JSON parse, ignore
+ * errors) and yield `<root>/skills` for each registered plugin whose `root`
+ * exists on disk and has a `skills` subdirectory.
+ */
+function pluginSkillDirs() {
+    const registryPath = pluginRegistryPath();
+    if (!registryPath)
+        return [];
+    let registry;
+    try {
+        registry = JSON.parse(readFileSync(registryPath, 'utf-8'));
+    } catch {
+        return [];
+    }
+    if (!registry || !Array.isArray(registry.plugins))
+        return [];
+    const dirs = [];
+    for (const entry of registry.plugins) {
+        const root = entry && typeof entry.root === 'string' ? entry.root : null;
+        if (!root || !existsSync(root))
+            continue;
+        const skillsDir = join(root, 'skills');
+        if (existsSync(skillsDir))
+            dirs.push(skillsDir);
+    }
+    return dirs;
+}
 /**
  * Collect available skills (frontmatter only — token efficient).
  * Full content loaded on demand via loadSkillContent().
@@ -49,6 +90,9 @@ export function collectSkills(cwd) {
     // first, then user-global. When cwd is missing, only the global dir is
     // searched.
     const dirs = mixdogAssetDirs(projectDir, 'skills');
+    // Plugin-provided skills load last so project-local and global mixdog
+    // skill dirs keep precedence; `seen` below dedupes by frontmatter name.
+    dirs.push(...pluginSkillDirs());
     const seen = new Set();
     for (const dir of dirs) {
         if (!existsSync(dir))
@@ -88,6 +132,13 @@ export function collectSkillsCached(cwd) {
     const projectDir = (typeof cwd === 'string' && cwd.length > 0) ? cwd : null;
     // Same mixdog-owned dirs collectSkills() reads, used as the freshness gate.
     const skillsDirs = mixdogAssetDirs(projectDir, 'skills');
+    skillsDirs.push(...pluginSkillDirs());
+    // registry.json itself gates plugin add/remove: removal deletes the
+    // plugin's skills dir (so no dir mtime advances), but saveRegistry()
+    // always rewrites this file. maxMtimeRecursive stats plain files directly.
+    const registryPath = pluginRegistryPath();
+    if (registryPath)
+        skillsDirs.push(registryPath);
     let mtime;
     const mtimeCached = _mtimeCache.get(key);
     if (mtimeCached && Date.now() - mtimeCached.checkedAt < _MTIME_TTL_MS) {
@@ -121,6 +172,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 +309,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 +350,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 +377,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 +410,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 +442,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 +453,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 +563,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);