@duckmind/dm-windows-x64 0.61.4 → 0.61.9

package/extensions/dm-subagents/src/agents/runtime-agent-registry.js

@@ -0,0 +1,412 @@
+import { CODE_OWNED_EXTERNAL_CLI_ADAPTER_LABEL, isCodeOwnedExternalCliAdapterId, parseExternalCliCapabilityNarrowing, validateCodeOwnedProfileRunner } from "../runs/shared/external-cli-contract.js";
+import { validateAcceptanceInput } from "../runs/shared/acceptance.js";
+import { validatePermissionRules } from "../runs/shared/permissions.js";
+import { validateToolBudgetConfig } from "../runs/shared/tool-budget.js";
+import { BUILTIN_AGENT_NAMES } from "./builtin-names.js";
+export const RUNTIME_AGENT_REGISTRY_KEY = "dm-subagents.runtime-agents.v1";
+const MAX_RUNTIME_AGENTS_PER_PI = 200;
+const MAX_AGENT_NAME_LENGTH = 128;
+const MAX_DESCRIPTION_LENGTH = 4096;
+const MAX_SYSTEM_PROMPT_LENGTH = 1024 * 1024;
+const MAX_FIELD_STRING_LENGTH = 8192;
+function defaultSystemPromptMode(name) {
+  return name === "delegate" ? "append" : "replace";
+}
+function defaultInheritProjectContext(name) {
+  return name === "delegate";
+}
+function defaultInheritSkills() {
+  return false;
+}
+function registry() {
+  const key = Symbol.for(RUNTIME_AGENT_REGISTRY_KEY);
+  const globalObject = globalThis;
+  const existing = globalObject[key];
+  if (existing === undefined) {
+    const created = { version: 1, byPi: new WeakMap };
+    globalObject[key] = created;
+    return created;
+  }
+  if (!existing || typeof existing !== "object" || Array.isArray(existing)) {
+    throw new Error(`Malformed runtime agent registry at Symbol.for("${RUNTIME_AGENT_REGISTRY_KEY}").`);
+  }
+  const candidate = existing;
+  if (candidate.version !== 1 || !(candidate.byPi instanceof WeakMap)) {
+    throw new Error(`Unsupported runtime agent registry at Symbol.for("${RUNTIME_AGENT_REGISTRY_KEY}").`);
+  }
+  return candidate;
+}
+function validatePi(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error("Runtime agent dm must be an ExtensionAPI object.");
+  const dm = value;
+  if (typeof dm.on !== "function" || typeof dm.registerTool !== "function")
+    throw new Error("Runtime agent dm must be an ExtensionAPI object.");
+  return value;
+}
+function validateString(value, field, maxLength) {
+  if (typeof value !== "string" || value.length === 0 || value.trim() !== value) {
+    throw new Error(`${field} must be a non-empty string without leading or trailing whitespace.`);
+  }
+  if (value.length > maxLength)
+    throw new Error(`${field} must be at most ${maxLength} characters.`);
+  if (value.includes("\x00"))
+    throw new Error(`${field} must not contain NUL characters.`);
+  return value;
+}
+function validateOptionalString(value, field, maxLength = MAX_FIELD_STRING_LENGTH) {
+  if (value === undefined)
+    return;
+  return validateString(value, field, maxLength);
+}
+function validateStringList(value, field) {
+  if (value === undefined)
+    return;
+  if (!Array.isArray(value))
+    throw new Error(`${field} must be an array of strings when provided.`);
+  return [...new Set(value.map((entry, index) => validateString(entry, `${field}[${index}]`, MAX_FIELD_STRING_LENGTH)))];
+}
+function validatePositiveInteger(value, field) {
+  if (value === undefined)
+    return;
+  if (typeof value !== "number" || !Number.isInteger(value) || value <= 0)
+    throw new Error(`${field} must be a positive integer when provided.`);
+  return value;
+}
+function validateBoolean(value, field) {
+  if (value === undefined)
+    return;
+  if (typeof value !== "boolean")
+    throw new Error(`${field} must be a boolean when provided.`);
+  return value;
+}
+function isJsonSerializable(value) {
+  if (value === null || typeof value === "string" || typeof value === "boolean")
+    return true;
+  if (typeof value === "number")
+    return Number.isFinite(value);
+  if (Array.isArray(value))
+    return value.every(isJsonSerializable);
+  if (value && typeof value === "object")
+    return Object.values(value).every(isJsonSerializable);
+  return false;
+}
+function validateRunner(value) {
+  if (value === undefined)
+    return;
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error("Runtime agent definition runner must be an object when provided.");
+  const runner = value;
+  if (runner.type === "dm") {
+    if (Object.keys(runner).some((key) => key !== "type"))
+      throw new Error("Runtime agent definition DM runner supports only 'type'.");
+    return { type: "dm" };
+  }
+  if (runner.type === "external-job") {
+    if (typeof runner.provider !== "string" || !runner.provider.trim() || runner.provider.trim() !== runner.provider)
+      throw new Error("Runtime agent definition external-job runner requires a non-empty trimmed provider string.");
+    if (runner.options !== undefined && (!runner.options || typeof runner.options !== "object" || Array.isArray(runner.options) || !isJsonSerializable(runner.options)))
+      throw new Error("Runtime agent definition external-job runner options must be a JSON-serializable object.");
+    const supported = new Set(["type", "provider", "options"]);
+    const unknown = Object.keys(runner).filter((key) => !supported.has(key));
+    if (unknown.length > 0)
+      throw new Error(`Runtime agent definition external-job runner has unsupported fields: ${unknown.join(", ")}.`);
+    return { type: "external-job", provider: runner.provider, ...runner.options ? { options: runner.options } : {} };
+  }
+  if (runner.type !== "external-cli")
+    throw new Error("Runtime agent definition runner.type must be 'dm', 'external-cli', or 'external-job'.");
+  if (typeof runner.command !== "string" || !runner.command.trim())
+    throw new Error("Runtime agent definition external-cli runner requires a non-empty command string.");
+  if (runner.args !== undefined && (!Array.isArray(runner.args) || runner.args.some((arg) => typeof arg !== "string")))
+    throw new Error("Runtime agent definition external-cli runner args must be an array of strings.");
+  if (runner.adapter !== undefined && !isCodeOwnedExternalCliAdapterId(runner.adapter))
+    throw new Error(`Runtime agent definition external-cli runner adapter must be ${CODE_OWNED_EXTERNAL_CLI_ADAPTER_LABEL}.`);
+  if (runner.adapter !== undefined && Array.isArray(runner.args) && runner.args.length > 0)
+    throw new Error(`Runtime agent definition ${runner.adapter} adapter owns its argv; runner args are not supported.`);
+  if (runner.promptDelivery !== undefined && runner.promptDelivery !== "stdin")
+    throw new Error("Runtime agent definition external-cli runner promptDelivery must be 'stdin'.");
+  const capabilities = parseExternalCliCapabilityNarrowing(runner.capabilities, "Runtime agent definition external-cli runner capabilities");
+  const supported = new Set(["type", "adapter", "command", "args", "promptDelivery", "capabilities"]);
+  const unknown = Object.keys(runner).filter((key) => !supported.has(key));
+  if (unknown.length > 0)
+    throw new Error(`Runtime agent definition external-cli runner has unsupported fields: ${unknown.join(", ")}.`);
+  const args = runner.args;
+  return { type: "external-cli", ...isCodeOwnedExternalCliAdapterId(runner.adapter) ? { adapter: runner.adapter } : {}, command: runner.command.trim(), ...args?.length ? { args } : {}, ...runner.promptDelivery ? { promptDelivery: "stdin" } : {}, ...capabilities ? { capabilities } : {} };
+}
+function validateAcceptance(value) {
+  const errors = validateAcceptanceInput(value, "Runtime agent definition defaultAcceptance");
+  if (errors.length > 0)
+    throw new Error(errors.join(" "));
+  return value;
+}
+function validateToolBudget(value) {
+  const result = validateToolBudgetConfig(value, "Runtime agent definition toolBudget");
+  if (result.error)
+    throw new Error(result.error);
+  return result.budget;
+}
+function validateDefinition(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error("Runtime agent definition must be an object.");
+  const definition = value;
+  const supported = new Set([
+    "description",
+    "systemPrompt",
+    "aliases",
+    "tools",
+    "allowNestedSubagents",
+    "mcpDirectTools",
+    "model",
+    "fallbackModels",
+    "thinking",
+    "systemPromptMode",
+    "inheritProjectContext",
+    "inheritGlobalContext",
+    "inheritSkills",
+    "defaultContext",
+    "defaultAsync",
+    "defaultTimeoutMs",
+    "defaultToolTimeoutMs",
+    "defaultAcceptance",
+    "acceptanceRole",
+    "runner",
+    "skills",
+    "skillPath",
+    "extensions",
+    "subagentOnlyExtensions",
+    "mutationTools",
+    "output",
+    "outputMode",
+    "defaultReads",
+    "defaultProgress",
+    "interactive",
+    "maxSubagentDepth",
+    "completionGuard",
+    "toolBudget",
+    "permissions"
+  ]);
+  const unknown = Object.keys(definition).filter((key) => !supported.has(key));
+  if (unknown.length > 0)
+    throw new Error(`Runtime agent definition has unknown fields: ${unknown.join(", ")}.`);
+  const systemPromptMode = definition.systemPromptMode;
+  if (systemPromptMode !== undefined && systemPromptMode !== "append" && systemPromptMode !== "replace")
+    throw new Error("Runtime agent definition systemPromptMode must be 'append' or 'replace'.");
+  const defaultContext = definition.defaultContext;
+  if (defaultContext !== undefined && defaultContext !== "fresh" && defaultContext !== "fork")
+    throw new Error("Runtime agent definition defaultContext must be 'fresh' or 'fork'.");
+  const thinking = definition.thinking;
+  if (thinking !== undefined && thinking !== false && typeof thinking !== "string")
+    throw new Error("Runtime agent definition thinking must be a string or false when provided.");
+  const acceptanceRole = definition.acceptanceRole;
+  if (acceptanceRole !== undefined && acceptanceRole !== "read-only" && acceptanceRole !== "writer")
+    throw new Error("Runtime agent definition acceptanceRole must be 'read-only' or 'writer'.");
+  const outputMode = definition.outputMode;
+  if (outputMode !== undefined && outputMode !== "inline" && outputMode !== "file-only")
+    throw new Error("Runtime agent definition outputMode must be 'inline' or 'file-only'.");
+  const aliases = validateStringList(definition.aliases, "Runtime agent definition aliases");
+  const tools = validateStringList(definition.tools, "Runtime agent definition tools");
+  const allowNestedSubagents = validateBoolean(definition.allowNestedSubagents, "Runtime agent definition allowNestedSubagents");
+  const mcpDirectTools = validateStringList(definition.mcpDirectTools, "Runtime agent definition mcpDirectTools");
+  const model = validateOptionalString(definition.model, "Runtime agent definition model");
+  const fallbackModels = validateStringList(definition.fallbackModels, "Runtime agent definition fallbackModels");
+  const inheritProjectContext = validateBoolean(definition.inheritProjectContext, "Runtime agent definition inheritProjectContext");
+  const inheritGlobalContext = validateBoolean(definition.inheritGlobalContext, "Runtime agent definition inheritGlobalContext");
+  const inheritSkills = validateBoolean(definition.inheritSkills, "Runtime agent definition inheritSkills");
+  const defaultAsync = validateBoolean(definition.defaultAsync, "Runtime agent definition defaultAsync");
+  const defaultTimeoutMs = validatePositiveInteger(definition.defaultTimeoutMs, "Runtime agent definition defaultTimeoutMs");
+  const defaultToolTimeoutMs = validatePositiveInteger(definition.defaultToolTimeoutMs, "Runtime agent definition defaultToolTimeoutMs");
+  const defaultAcceptance = validateAcceptance(definition.defaultAcceptance);
+  const runner = validateRunner(definition.runner);
+  const skills = validateStringList(definition.skills, "Runtime agent definition skills");
+  const skillPath = validateStringList(definition.skillPath, "Runtime agent definition skillPath");
+  const extensions = validateStringList(definition.extensions, "Runtime agent definition extensions");
+  const subagentOnlyExtensions = validateStringList(definition.subagentOnlyExtensions, "Runtime agent definition subagentOnlyExtensions");
+  const mutationTools = validateStringList(definition.mutationTools, "Runtime agent definition mutationTools");
+  const output = validateOptionalString(definition.output, "Runtime agent definition output");
+  const defaultReads = validateStringList(definition.defaultReads, "Runtime agent definition defaultReads");
+  const defaultProgress = validateBoolean(definition.defaultProgress, "Runtime agent definition defaultProgress");
+  const interactive = validateBoolean(definition.interactive, "Runtime agent definition interactive");
+  const maxSubagentDepth = validatePositiveInteger(definition.maxSubagentDepth, "Runtime agent definition maxSubagentDepth");
+  const completionGuard = validateBoolean(definition.completionGuard, "Runtime agent definition completionGuard");
+  const toolBudget = validateToolBudget(definition.toolBudget);
+  const permissions = validatePermissionRules(definition.permissions, "Runtime agent definition permissions");
+  return {
+    description: validateString(definition.description, "Runtime agent definition description", MAX_DESCRIPTION_LENGTH),
+    systemPrompt: validateString(definition.systemPrompt, "Runtime agent definition systemPrompt", MAX_SYSTEM_PROMPT_LENGTH),
+    ...aliases ? { aliases } : {},
+    ...tools ? { tools } : {},
+    ...allowNestedSubagents !== undefined ? { allowNestedSubagents } : {},
+    ...mcpDirectTools ? { mcpDirectTools } : {},
+    ...model ? { model } : {},
+    ...fallbackModels ? { fallbackModels } : {},
+    ...thinking !== undefined ? { thinking } : {},
+    ...systemPromptMode !== undefined ? { systemPromptMode } : {},
+    ...inheritProjectContext !== undefined ? { inheritProjectContext } : {},
+    ...inheritGlobalContext !== undefined ? { inheritGlobalContext } : {},
+    ...inheritSkills !== undefined ? { inheritSkills } : {},
+    ...defaultContext !== undefined ? { defaultContext } : {},
+    ...defaultAsync !== undefined ? { defaultAsync } : {},
+    ...defaultTimeoutMs !== undefined ? { defaultTimeoutMs } : {},
+    ...defaultToolTimeoutMs !== undefined ? { defaultToolTimeoutMs } : {},
+    ...defaultAcceptance !== undefined ? { defaultAcceptance } : {},
+    ...acceptanceRole !== undefined ? { acceptanceRole } : {},
+    ...runner !== undefined ? { runner } : {},
+    ...skills ? { skills } : {},
+    ...skillPath ? { skillPath } : {},
+    ...extensions ? { extensions } : {},
+    ...subagentOnlyExtensions ? { subagentOnlyExtensions } : {},
+    ...mutationTools ? { mutationTools } : {},
+    ...output ? { output } : {},
+    ...outputMode !== undefined ? { outputMode } : {},
+    ...defaultReads ? { defaultReads } : {},
+    ...defaultProgress !== undefined ? { defaultProgress } : {},
+    ...interactive !== undefined ? { interactive } : {},
+    ...maxSubagentDepth !== undefined ? { maxSubagentDepth } : {},
+    ...completionGuard !== undefined ? { completionGuard } : {},
+    ...toolBudget !== undefined ? { toolBudget } : {},
+    ...permissions !== undefined ? { permissions } : {}
+  };
+}
+function normalizeAliases(rawAliases, agentName) {
+  const aliases = [...new Set((rawAliases ?? []).map((alias) => alias.trim()).filter(Boolean))].filter((alias) => alias !== agentName);
+  return aliases.length > 0 ? aliases : undefined;
+}
+function identityKeys(agent) {
+  return [agent.name, ...agent.localName ? [agent.localName] : [], ...agent.aliases ?? []];
+}
+function assertNoIdentityCollisions(agents, context) {
+  const seen = new Map;
+  for (const agent of agents) {
+    for (const key of identityKeys(agent)) {
+      const previous = seen.get(key);
+      if (previous !== undefined)
+        throw new Error(`${context} collision for '${key}' between '${previous}' and '${agent.name}'.`);
+      seen.set(key, agent.name);
+    }
+  }
+}
+function assertNoRuntimeCollision(agent, existing) {
+  const existingKeys = new Map;
+  for (const registered of existing) {
+    for (const key of identityKeys(registered))
+      existingKeys.set(key, registered.name);
+  }
+  for (const key of identityKeys(agent)) {
+    const previous = existingKeys.get(key);
+    if (previous !== undefined)
+      throw new Error(`Runtime agent '${agent.name}' collides with runtime agent '${previous}' on name or alias '${key}'.`);
+  }
+}
+function assertNoBuiltinCollision(agent) {
+  for (const key of identityKeys(agent)) {
+    if (BUILTIN_AGENT_NAMES.includes(key))
+      throw new Error(`Runtime agent '${agent.name}' collides with builtin agent '${key}'.`);
+  }
+}
+function toAgentConfig(name, definition) {
+  const aliases = normalizeAliases(definition.aliases, name);
+  const agent = {
+    name,
+    description: definition.description,
+    ...aliases ? { aliases } : {},
+    ...definition.runner !== undefined ? { runner: definition.runner } : {},
+    ...definition.tools !== undefined ? { tools: [...definition.tools] } : {},
+    ...definition.allowNestedSubagents !== undefined ? { allowNestedSubagents: definition.allowNestedSubagents } : {},
+    ...definition.mcpDirectTools !== undefined ? { mcpDirectTools: [...definition.mcpDirectTools] } : {},
+    ...definition.model !== undefined ? { model: definition.model } : {},
+    ...definition.fallbackModels !== undefined ? { fallbackModels: [...definition.fallbackModels] } : {},
+    ...definition.thinking !== undefined ? { thinking: definition.thinking } : {},
+    systemPromptMode: definition.systemPromptMode ?? defaultSystemPromptMode(name),
+    inheritProjectContext: definition.inheritProjectContext ?? defaultInheritProjectContext(name),
+    inheritGlobalContext: definition.inheritGlobalContext ?? false,
+    inheritSkills: definition.inheritSkills ?? defaultInheritSkills(),
+    ...definition.defaultContext !== undefined ? { defaultContext: definition.defaultContext } : {},
+    ...definition.defaultAsync !== undefined ? { defaultAsync: definition.defaultAsync } : {},
+    ...definition.defaultTimeoutMs !== undefined ? { defaultTimeoutMs: definition.defaultTimeoutMs } : {},
+    ...definition.defaultToolTimeoutMs !== undefined ? { defaultToolTimeoutMs: definition.defaultToolTimeoutMs } : {},
+    ...definition.defaultAcceptance !== undefined ? { defaultAcceptance: definition.defaultAcceptance } : {},
+    ...definition.acceptanceRole !== undefined ? { acceptanceRole: definition.acceptanceRole } : {},
+    systemPrompt: definition.systemPrompt,
+    source: "runtime",
+    filePath: `runtime:${name}`,
+    ...definition.skills !== undefined ? { skills: [...definition.skills] } : {},
+    ...definition.skillPath !== undefined ? { skillPath: [...definition.skillPath] } : {},
+    ...definition.extensions !== undefined ? { extensions: [...definition.extensions] } : {},
+    ...definition.subagentOnlyExtensions !== undefined ? { subagentOnlyExtensions: [...definition.subagentOnlyExtensions] } : {},
+    ...definition.mutationTools !== undefined ? { mutationTools: [...definition.mutationTools] } : {},
+    ...definition.output !== undefined ? { output: definition.output } : {},
+    ...definition.outputMode !== undefined ? { outputMode: definition.outputMode } : {},
+    ...definition.defaultReads !== undefined ? { defaultReads: [...definition.defaultReads] } : {},
+    ...definition.defaultProgress !== undefined ? { defaultProgress: definition.defaultProgress } : {},
+    ...definition.interactive !== undefined ? { interactive: definition.interactive } : {},
+    ...definition.maxSubagentDepth !== undefined ? { maxSubagentDepth: definition.maxSubagentDepth } : {},
+    ...definition.completionGuard !== undefined ? { completionGuard: definition.completionGuard } : {},
+    ...definition.toolBudget !== undefined ? { toolBudget: definition.toolBudget } : {},
+    ...definition.permissions !== undefined ? { permissions: definition.permissions } : {}
+  };
+  assertNoIdentityCollisions([agent], `Runtime agent '${name}'`);
+  return agent;
+}
+export function registerRuntimeAgent(input) {
+  const dm = validatePi(input.dm);
+  const name = validateString(input.name, "Runtime agent name", MAX_AGENT_NAME_LENGTH);
+  const definition = validateDefinition(input.definition);
+  const agent = toAgentConfig(name, definition);
+  const profileError = validateCodeOwnedProfileRunner(agent);
+  if (profileError)
+    throw new Error(profileError);
+  assertNoBuiltinCollision(agent);
+  const current = registry();
+  const records = current.byPi.get(dm) ?? [];
+  if (records.length >= MAX_RUNTIME_AGENTS_PER_PI)
+    throw new Error(`Runtime agent registry supports at most ${MAX_RUNTIME_AGENTS_PER_PI} agents per DM runtime.`);
+  assertNoRuntimeCollision(agent, records.map((record) => record.agent));
+  const record = { dm, agent };
+  records.push(record);
+  current.byPi.set(dm, records);
+  let disposed = false;
+  return {
+    dispose() {
+      if (disposed)
+        return;
+      disposed = true;
+      const latest = current.byPi.get(dm);
+      if (!latest)
+        return;
+      const next = latest.filter((entry) => entry !== record);
+      if (next.length > 0)
+        current.byPi.set(dm, next);
+      else
+        current.byPi.delete(dm);
+    }
+  };
+}
+export function clearRuntimeAgentsForPi(dm) {
+  registry().byPi.delete(dm);
+}
+export function listRuntimeAgentConfigs(dm) {
+  return (registry().byPi.get(dm) ?? []).map((record) => ({ ...record.agent, aliases: record.agent.aliases ? [...record.agent.aliases] : undefined }));
+}
+function assertNoConfiguredCollision(configuredAgents, runtimeAgents) {
+  const configured = new Map;
+  for (const agent of configuredAgents) {
+    for (const key of identityKeys(agent))
+      configured.set(key, agent.name);
+  }
+  for (const agent of runtimeAgents) {
+    for (const key of identityKeys(agent)) {
+      const previous = configured.get(key);
+      if (previous !== undefined) {
+        throw new Error(`Runtime agent '${agent.name}' collides with configured agent '${previous}' on name or alias '${key}'.`);
+      }
+    }
+  }
+}
+export function mergeRuntimeAgents(dm, discovered, configuredAgents = discovered.agents) {
+  const runtimeAgents = listRuntimeAgentConfigs(dm).filter((agent) => agent.disabled !== true);
+  if (runtimeAgents.length === 0)
+    return discovered;
+  assertNoIdentityCollisions(runtimeAgents, "Runtime agent registration");
+  assertNoConfiguredCollision(configuredAgents, runtimeAgents);
+  return { ...discovered, agents: [...discovered.agents, ...runtimeAgents] };
+}

package/extensions/dm-subagents/src/agents/skills.js

@@ -2,6 +2,7 @@ import { execSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { parseFrontmatter } from "./frontmatter.js";
 import { getAgentDir, getProjectConfigDir } from "../shared/utils.js";
 const skillCache = new Map;
 const MAX_CACHE_SIZE = 50;
@@ -59,20 +60,32 @@ function extractSkillPathsFromPackageRoot(packageRoot, source, bestEffort = fals
   const pkg = bestEffort ? readJsonFileBestEffort(packageJsonPath) : readOptionalJsonFile(packageJsonPath, "package manifest");
   if (!pkg || typeof pkg !== "object" || Array.isArray(pkg))
     return [];
-  const pi = pkg.pi;
-  if (!pi || typeof pi !== "object" || Array.isArray(pi))
+  const dm = pkg.dm;
+  if (!dm || typeof dm !== "object" || Array.isArray(dm))
     return [];
-  const skills = pi.skills;
+  const skills = dm.skills;
   if (!Array.isArray(skills))
     return [];
   return skills.filter((entry) => typeof entry === "string").map((entry) => ({ path: path.resolve(packageRoot, entry), source }));
 }
 let cachedGlobalNpmRoot = null;
 function getGlobalNpmRoot() {
+  const offline = process.env.PI_OFFLINE?.toLowerCase();
+  if (offline === "1" || offline === "true" || offline === "yes")
+    return null;
   if (cachedGlobalNpmRoot !== null)
     return cachedGlobalNpmRoot;
+  const windowsGlobalRoot = process.platform === "win32" && process.env.APPDATA ? path.join(process.env.APPDATA, "npm", "node_modules") : undefined;
+  if (windowsGlobalRoot) {
+    try {
+      if (fs.statSync(windowsGlobalRoot).isDirectory()) {
+        cachedGlobalNpmRoot = fs.realpathSync(windowsGlobalRoot);
+        return cachedGlobalNpmRoot;
+      }
+    } catch {}
+  }
   try {
-    cachedGlobalNpmRoot = execSync("npm root -g", { encoding: "utf-8", timeout: 5000 }).trim();
+    cachedGlobalNpmRoot = fs.realpathSync(execSync("npm root -g", { encoding: "utf-8", timeout: 5000, windowsHide: true }).trim());
     return cachedGlobalNpmRoot;
   } catch {
     cachedGlobalNpmRoot = "";
@@ -315,22 +328,12 @@ function chooseHigherPrioritySkill(existing, candidate) {
     return existing;
   return candidate.order < existing.order ? candidate : existing;
 }
+function parseSkillDescription(content) {
+  return parseFrontmatter(content).frontmatter.description;
+}
 function maybeReadSkillDescription(filePath) {
   try {
-    const content = fs.readFileSync(filePath, "utf-8");
-    const normalized = content.replace(/\r\n/g, `
-`);
-    if (!normalized.startsWith("---"))
-      return;
-    const endIndex = normalized.indexOf(`
----`, 3);
-    if (endIndex === -1)
-      return;
-    const frontmatter = normalized.slice(3, endIndex).trim();
-    const match = frontmatter.match(/^description:\s*(.+)$/m);
-    if (!match)
-      return;
-    return match[1]?.trim().replace(/^['\"]|['\"]$/g, "");
+    return parseSkillDescription(fs.readFileSync(filePath, "utf-8"));
   } catch {
     return;
   }
@@ -345,15 +348,17 @@ function collectFilesystemSkills(cwd, agentDir, skillPaths) {
     if (!fs.existsSync(resolvedFile))
       return;
     const source = inferSkillSource(resolvedFile, cwd, agentDir, sourceHint);
+    const description = maybeReadSkillDescription(resolvedFile);
     const existingIndex = seen.get(resolvedFile);
     if (existingIndex !== undefined) {
       const existing = entries[existingIndex];
       if (existing && (SOURCE_PRIORITY[source] ?? 0) > (SOURCE_PRIORITY[existing.source] ?? 0)) {
+        const { description: _description, ...existingWithoutDescription } = existing;
         entries[existingIndex] = {
-          ...existing,
+          ...existingWithoutDescription,
           name,
           source,
-          description: maybeReadSkillDescription(resolvedFile)
+          ...description !== undefined ? { description } : {}
         };
       }
       return;
@@ -363,7 +368,7 @@ function collectFilesystemSkills(cwd, agentDir, skillPaths) {
       name,
       filePath: resolvedFile,
       source,
-      description: maybeReadSkillDescription(resolvedFile),
+      ...description !== undefined ? { description } : {},
       order: order++
     });
   };
@@ -501,12 +506,12 @@ function readSkill(skillName, skillPath, source) {
     }
     const raw = fs.readFileSync(skillPath, "utf-8");
     const content = stripSkillFrontmatter(raw);
-    const description = maybeReadSkillDescription(skillPath);
+    const description = parseSkillDescription(raw);
     const skill = {
       name: skillName,
       path: skillPath,
       content,
-      description,
+      ...description !== undefined ? { description } : {},
       source
     };
     skillCache.set(skillPath, { mtime: stat.mtimeMs, skill });
@@ -520,9 +525,21 @@ function readSkill(skillName, skillPath, source) {
     return;
   }
 }
-export function resolveSkills(skillNames, cwd) {
+export function resolveSkills(skillNames, cwd, localSkillPaths, localBaseDir) {
   const resolved = [];
   const missing = [];
+  const localByName = new Map;
+  if (localSkillPaths?.length) {
+    const agentDir = getAgentDir();
+    const localEntries = collectFilesystemSkills(cwd, agentDir, localSkillPaths.map((entry) => ({
+      path: path.resolve(localBaseDir ?? cwd, entry),
+      source: "unknown"
+    })));
+    for (const entry of localEntries) {
+      if (!localByName.has(entry.name))
+        localByName.set(entry.name, entry);
+    }
+  }
   for (const name of skillNames) {
     const trimmed = name.trim();
     if (!trimmed)
@@ -531,22 +548,22 @@ export function resolveSkills(skillNames, cwd) {
       missing.push(trimmed);
       continue;
     }
-    const location = resolveSkillPath(trimmed, cwd);
-    if (!location) {
-      missing.push(trimmed);
-      continue;
+    const local = localByName.get(trimmed);
+    let skill = local ? readSkill(trimmed, local.filePath, local.source) : undefined;
+    if (!skill) {
+      const location = resolveSkillPath(trimmed, cwd);
+      if (location)
+        skill = readSkill(trimmed, location.path, location.source);
     }
-    const skill = readSkill(trimmed, location.path, location.source);
-    if (skill) {
+    if (skill)
       resolved.push(skill);
-    } else {
+    else
       missing.push(trimmed);
-    }
   }
   return { resolved, missing };
 }
-export function resolveSkillsWithFallback(skillNames, primaryCwd, fallbackCwd) {
-  const primary = resolveSkills(skillNames, primaryCwd);
+export function resolveSkillsWithFallback(skillNames, primaryCwd, fallbackCwd, localSkillPaths, localBaseDir) {
+  const primary = resolveSkills(skillNames, primaryCwd, localSkillPaths, localBaseDir);
   if (!fallbackCwd || primary.missing.length === 0)
     return primary;
   if (path.resolve(primaryCwd) === path.resolve(fallbackCwd))
@@ -605,7 +622,7 @@ export function discoverAvailableSkills(cwd) {
   return skills.filter((s) => s.name !== SUBAGENT_ORCHESTRATION_SKILL).map((s) => ({
     name: s.name,
     source: s.source,
-    description: s.description
+    ...s.description !== undefined ? { description: s.description } : {}
   })).sort((a, b) => a.name.localeCompare(b.name));
 }
 export function clearSkillCache() {

package/extensions/dm-subagents/src/api/agents.js

@@ -0,0 +1,6 @@
+export { registerRuntimeAgent as registerAgent } from "../agents/runtime-agent-registry.js";
+export {
+  RUNTIME_AGENT_REGISTER_EVENT,
+  RUNTIME_AGENT_REGISTER_VERSION,
+  registerAgentViaEvents
+} from "../agents/runtime-agent-events.js";