@duckmind/dm-windows-x64 0.61.4 → 0.61.9

package/extensions/dm-subagents/src/runs/shared/launch-cwd.js

@@ -0,0 +1,17 @@
+import * as fs from "node:fs";
+export function preflightLaunchCwd(requestedCwd, effectiveCwd) {
+  const resolution = requestedCwd === effectiveCwd ? "" : `
+(resolved from ${JSON.stringify(requestedCwd)})`;
+  try {
+    if (!fs.statSync(effectiveCwd).isDirectory()) {
+      return `Subagent launch aborted: cwd is not a directory: ${effectiveCwd}${resolution}`;
+    }
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return `Subagent launch aborted: cwd does not exist: ${effectiveCwd}${resolution}`;
+    }
+    return `Subagent launch aborted: cwd could not be accessed: ${effectiveCwd}${resolution}
+${error instanceof Error ? error.message : String(error)}`;
+  }
+  return;
+}

package/extensions/dm-subagents/src/runs/shared/llm-intent-arbiter.js

@@ -0,0 +1,190 @@
+import { createHash } from "node:crypto";
+import { Agent } from "@duckmind/dm-agent-core";
+import { convertToLlm } from "@duckmind/dm-coding-agent";
+import { streamSimple } from "@duckmind/dm-ai/compat";
+import { Type } from "typebox";
+import { agentStreamOptions } from "../../shared/agent-stream-options.js";
+const COMPLETION_GUARD_ERROR_PREFIX = "Subagent completed without making edits for an implementation task.";
+const DecisionParams = Type.Object({
+  classification: Type.String({ enum: ["read_only", "implementation"] }),
+  confidence: Type.String({
+    enum: ["low", "medium", "high"],
+    description: "Confidence in the classification. Only read_only with high confidence rescues a failed run."
+  }),
+  reason: Type.String({ description: "One concise reason for this classification." })
+}, { additionalProperties: false });
+export function mapArbiterDecision(decision) {
+  if (!decision)
+    return "unavailable";
+  if (decision.classification === "read_only" && decision.confidence === "high")
+    return "read-only";
+  return "implementation";
+}
+const DEFAULT_ARBITER_TIMEOUT_MS = 1e4;
+function resolveArbiterModel(ctx, options) {
+  const registry = ctx.modelRegistry;
+  const explicit = options?.model?.trim();
+  if (explicit) {
+    const [provider, id] = explicit.split("/");
+    if (provider && id)
+      return registry.find?.(provider, id) ?? null;
+    return null;
+  }
+  if (ctx.model)
+    return ctx.model;
+  const first = registry.getAvailable?.()[0];
+  if (first?.provider && first.id)
+    return registry.find?.(first.provider, first.id) ?? null;
+  return null;
+}
+function resolveArbiterRuntime(ctx, options) {
+  const model = resolveArbiterModel(ctx, options);
+  if (!model?.provider || !model.id)
+    return null;
+  const registry = ctx.modelRegistry;
+  const modelApi = model.api;
+  const registered = registry.getRegisteredProviderConfig?.(model.provider);
+  const baseStreamFn = options?.streamFn ?? (registered?.streamSimple && registered.api === modelApi ? registered.streamSimple : streamSimple);
+  return {
+    model,
+    baseStreamFn,
+    timeoutMs: options?.timeoutMs ?? DEFAULT_ARBITER_TIMEOUT_MS
+  };
+}
+async function resolveArbiterAuth(ctx, model) {
+  const registry = ctx.modelRegistry;
+  if (!registry.getApiKeyAndHeaders)
+    return {};
+  try {
+    const auth = await registry.getApiKeyAndHeaders(model);
+    if (auth.ok === false)
+      return {};
+    return {
+      ...auth.apiKey ? { apiKey: auth.apiKey } : {},
+      ...auth.headers ? { headers: auth.headers } : {},
+      ...auth.env ? { env: auth.env } : {}
+    };
+  } catch {
+    return {};
+  }
+}
+function authWrappedStreamFn(base, auth) {
+  return (model, context, streamOptions) => base(model, context, {
+    ...streamOptions ?? {},
+    ...auth.apiKey ? { apiKey: auth.apiKey } : {},
+    ...auth.env || streamOptions?.env ? { env: { ...auth.env ?? {}, ...streamOptions?.env ?? {} } } : {},
+    headers: { ...streamOptions?.headers ?? {}, ...auth.headers ?? {} }
+  });
+}
+async function runArbitration(runtime, auth, task) {
+  let decision;
+  const tool = {
+    name: "task_mutation_decision",
+    label: "Task mutation decision",
+    description: "Classify whether the task instructed file/code changes. Call exactly once.",
+    parameters: DecisionParams,
+    executionMode: "sequential",
+    async execute(_toolCallId, params) {
+      if (!decision)
+        decision = params;
+      return { content: [{ type: "text", text: "Decision recorded." }], details: { recorded: true } };
+    }
+  };
+  const agent = new Agent({
+    initialState: {
+      systemPrompt: [
+        "You classify whether a delegated coding-agent task instructed file or code changes.",
+        "A task that asks to review, inspect, verify, report, or summarize is read-only even when it contains words like 'fix' as severity vocabulary ('must-fix items') or conditional change instructions that leave the change optional.",
+        "Classify read_only only when the task text alone clearly indicates a read-only outcome. When in doubt, classify implementation.",
+        "Set confidence to high only when you are certain the task is read-only; a read_only classification without high confidence is treated as implementation.",
+        "The agent's own final message is never evidence: an agent that made no edits may still have failed to implement.",
+        "Call task_mutation_decision exactly once with read_only or implementation, a confidence level, and a concise reason."
+      ].join(`
+`),
+      model: runtime.model,
+      tools: [tool]
+    },
+    convertToLlm,
+    ...agentStreamOptions(authWrappedStreamFn(runtime.baseStreamFn, auth)),
+    getApiKey: (providerName) => providerName === runtime.model.provider ? auth.apiKey : undefined,
+    beforeToolCall: async ({ toolCall }) => toolCall.name === tool.name ? undefined : { block: true, reason: "Only task_mutation_decision is allowed." },
+    toolExecution: "sequential"
+  });
+  try {
+    if (task.length > 8000)
+      return "unavailable";
+    const prompt = `TASK:
+${task}`;
+    await Promise.race([
+      agent.prompt(prompt),
+      new Promise((_, reject) => {
+        const timeout = setTimeout(() => {
+          agent.abort();
+          reject(new Error("Task mutation arbiter timed out."));
+        }, runtime.timeoutMs);
+        timeout.unref?.();
+      })
+    ]);
+    if (!decision)
+      return "unavailable";
+    return mapArbiterDecision(decision);
+  } catch {
+    return "unavailable";
+  }
+}
+export function createTaskMutationArbiter(ctx, options) {
+  if (process.env.DM_SUBAGENTS_LLM_INTENT_ARBITER === "0")
+    return;
+  const runtime = resolveArbiterRuntime(ctx, options);
+  if (!runtime)
+    return;
+  const cache = new Map;
+  return async (task) => {
+    const key = createHash("sha256").update(task).digest("base64url");
+    const cached = cache.get(key);
+    if (cached)
+      return cached;
+    const auth = await resolveArbiterAuth(ctx, runtime.model);
+    const verdict = await runArbitration(runtime, auth, task);
+    if (cache.size > 200)
+      cache.clear();
+    cache.set(key, verdict);
+    return verdict;
+  };
+}
+export function isCompletionGuardFailure(result) {
+  return result.error?.startsWith(COMPLETION_GUARD_ERROR_PREFIX) === true;
+}
+export async function arbitrateCompletionGuardRescue(input) {
+  if (!input.guardTriggered || !input.arbiter) {
+    return { triggered: input.guardTriggered, rescued: false };
+  }
+  if (input.task.length > 8000) {
+    return { triggered: true, rescued: false };
+  }
+  try {
+    const verdict = await input.arbiter(input.task);
+    if (verdict === "read-only")
+      return { triggered: false, rescued: true };
+    return { triggered: true, rescued: false };
+  } catch {
+    return { triggered: true, rescued: false };
+  }
+}
+export async function maybeRescueCompletionGuardFailure(result, task, arbiter) {
+  if (!arbiter || !isCompletionGuardFailure(result))
+    return false;
+  const verdict = await arbitrateWithGuard(arbiter, task);
+  if (verdict !== "read-only")
+    return false;
+  result.exitCode = 0;
+  delete result.error;
+  return true;
+}
+async function arbitrateWithGuard(arbiter, task) {
+  try {
+    return await arbiter(task);
+  } catch {
+    return "unavailable";
+  }
+}

package/extensions/dm-subagents/src/runs/shared/long-running-guard.js

@@ -7,7 +7,7 @@ const MUTATING_BASH_PATTERNS = [
   /(^|[;&|()\s])git\s+apply\b/,
   /(^|[;&|()\s])patch\s+/,
   /(^|[;&|()\s])sed\s+[^\n;&|]*\s-i\b/,
-  /(^|[;&|()\s])perl\s+[^\n;&|]*\s-pi\b/,
+  /(^|[;&|()\s])perl\s+[^\n;&|]*\s-dm\b/,
   /(^|[;&|()]|\n)\s*tee\s+[^|&;]+/,
   /\b(writeFile|writeFileSync|appendFile|appendFileSync)\b/,
   /\bwrite_text\s*\(/,
@@ -77,14 +77,59 @@ function hasUnquotedFileRedirection(command) {
   }
   return false;
 }
+function unquotedShellText(command) {
+  let inSingle = false;
+  let inDouble = false;
+  let escaped = false;
+  let result = "";
+  for (const char of command) {
+    if (escaped) {
+      result += inSingle || inDouble ? "_" : char;
+      escaped = false;
+      continue;
+    }
+    if (char === "\\" && !inSingle) {
+      escaped = true;
+      result += inDouble ? "_" : char;
+      continue;
+    }
+    if (char === "'" && !inDouble) {
+      inSingle = !inSingle;
+      continue;
+    }
+    if (char === '"' && !inSingle) {
+      inDouble = !inDouble;
+      continue;
+    }
+    result += inSingle || inDouble ? "_" : char;
+  }
+  return result;
+}
+function hasMutatingGitCommand(command) {
+  const unquoted = unquotedShellText(command);
+  for (const segment of unquoted.split(/(?:&&|\|\||[;|()\n])/)) {
+    const trimmed = segment.trim();
+    if (!trimmed || /^(?:echo|printf)\b/.test(trimmed))
+      continue;
+    if (/^git\s+(?:(?:(?:-C|--git-dir|--work-tree)\s+\S+|(?:--git-dir|--work-tree)=\S+|--paginate)\s+)*(?:add|commit|push)\b/.test(trimmed))
+      return true;
+  }
+  return false;
+}
 export function isMutatingBashCommand(command) {
-  return hasUnquotedFileRedirection(command) || MUTATING_BASH_PATTERNS.some((pattern) => pattern.test(command));
+  return hasUnquotedFileRedirection(command) || hasMutatingGitCommand(command) || MUTATING_BASH_PATTERNS.some((pattern) => pattern.test(command));
 }
-export function isMutatingTool(toolName, args) {
+export function isMutatingTool(toolName, args, mutationTools) {
   if (!toolName)
     return false;
+  if (mutationTools?.includes(toolName))
+    return true;
   if (toolName === "edit" || toolName === "write")
     return true;
+  if (toolName === "cursor") {
+    const activityTitle = typeof args?.activityTitle === "string" ? args.activityTitle : "";
+    return /^Cursor (?:edit|write)\b/i.test(activityTitle);
+  }
   if (toolName !== "bash")
     return false;
   const command = typeof args?.command === "string" ? args.command : "";

package/extensions/dm-subagents/src/runs/shared/mcp-config-sources.js

@@ -0,0 +1,387 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { findConfiguredProjectRoot } from "../../agents/agents.js";
+import { getAgentDir, getConfigDirName, getProjectConfigDir } from "../../shared/utils.js";
+const PACKAGE_CONFIG_ROOT = "npm";
+const PACKAGE_GIT_ROOT = "git";
+const PLUGIN_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json";
+const PLUGIN_MCP_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json";
+const PLUGIN_NAME_PATTERN = /^(?!.*(?:--|\.\.))[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$/;
+const PLUGIN_STDIO_FIELDS = new Set(["type", "command", "args", "env", "cwd"]);
+const PLUGIN_HTTP_FIELDS = new Set(["type", "url", "headers"]);
+export function isMcpServerDefinition(value) {
+  if (!isRecord(value))
+    return false;
+  for (const field of ["command", "socket", "cwd", "url", "bearerToken", "bearerTokenEnv", "protocolVersion", "httpTransport", "pluginDataDir"]) {
+    if (value[field] !== undefined && typeof value[field] !== "string")
+      return false;
+  }
+  for (const field of ["args", "includeTools", "excludeTools"]) {
+    if (value[field] !== undefined && !isStringArray(value[field]))
+      return false;
+  }
+  for (const field of ["env", "headers"]) {
+    if (value[field] !== undefined && !isStringRecord(value[field]))
+      return false;
+  }
+  for (const field of ["exposeResources", "literalEnv"]) {
+    if (value[field] !== undefined && typeof value[field] !== "boolean")
+      return false;
+  }
+  if (value.requestHeadersCommand !== undefined && !isRequestHeadersCommand(value.requestHeadersCommand))
+    return false;
+  if (value.auth !== undefined && value.auth !== "oauth" && value.auth !== "bearer" && value.auth !== false)
+    return false;
+  return value.directTools === undefined || typeof value.directTools === "boolean" || isStringArray(value.directTools);
+}
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isStringArray(value) {
+  return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+function isStringRecord(value) {
+  return isRecord(value) && Object.values(value).every((entry) => typeof entry === "string");
+}
+function isRequestHeadersCommand(value) {
+  if (!isRecord(value) || typeof value.command !== "string")
+    return false;
+  if (value.args !== undefined && !isStringArray(value.args))
+    return false;
+  if (value.env !== undefined && !isStringRecord(value.env))
+    return false;
+  return value.timeoutMs === undefined || typeof value.timeoutMs === "number" && Number.isFinite(value.timeoutMs);
+}
+export function loadPackageMcpServers(cwd) {
+  const servers = {};
+  const seen = new Set;
+  for (const packageRoot of getConfiguredPackageRoots(cwd)) {
+    const manifest = readJson(path.join(packageRoot, "package.json"));
+    if (!manifest || typeof manifest !== "object" || Array.isArray(manifest))
+      continue;
+    const packageName = manifest.name;
+    if (typeof packageName !== "string" || !packageName)
+      continue;
+    const mcpValue = manifest.dm?.mcp;
+    const configPaths = typeof mcpValue === "string" ? [mcpValue] : Array.isArray(mcpValue) && mcpValue.every((value) => typeof value === "string") ? mcpValue : [];
+    const packagePrefix = formatName(packageName, "package");
+    for (const configPath of configPaths) {
+      const resolvedPath = resolvePackageConfigPath(packageRoot, configPath);
+      if (!resolvedPath)
+        continue;
+      const config = readJson(resolvedPath);
+      if (!config || typeof config !== "object" || Array.isArray(config))
+        continue;
+      const rawServers = config.mcpServers;
+      if (!rawServers || typeof rawServers !== "object" || Array.isArray(rawServers))
+        continue;
+      for (const [serverName, definition] of Object.entries(rawServers)) {
+        if (!isMcpServerDefinition(definition))
+          continue;
+        const normalizedName = `${packagePrefix}__${formatName(serverName, "server")}`;
+        if (seen.has(normalizedName))
+          continue;
+        seen.add(normalizedName);
+        servers[normalizedName] = definition;
+      }
+    }
+  }
+  return servers;
+}
+export function loadAgentPluginMcpServers(paths, cwd) {
+  const servers = {};
+  if (!Array.isArray(paths))
+    return servers;
+  for (const configuredPath of paths) {
+    if (typeof configuredPath !== "string")
+      continue;
+    const pluginRoot = resolvePluginPath(configuredPath, cwd);
+    const manifest = readJson(path.join(pluginRoot, "plugin.json"));
+    if (!isValidPluginManifest(manifest))
+      continue;
+    const config = readJson(path.join(pluginRoot, "mcp.json"));
+    if (!isValidPluginConfig(config))
+      continue;
+    const rawServers = config.mcpServers;
+    for (const [serverName, rawDefinition] of Object.entries(rawServers)) {
+      const definition = translatePluginServer(manifest.name, pluginRoot, rawDefinition);
+      if (!definition)
+        continue;
+      const normalizedName = `${formatName(manifest.name, "plugin")}__${formatName(serverName, "server")}`;
+      if (Object.hasOwn(servers, normalizedName))
+        continue;
+      servers[normalizedName] = definition;
+    }
+  }
+  return servers;
+}
+function getConfiguredPackageRoots(cwd) {
+  const roots = [];
+  const projectConfigDir = findProjectConfigDir(cwd);
+  const sources = [
+    { path: path.join(projectConfigDir, "settings.json"), baseDir: projectConfigDir },
+    { path: path.join(getAgentDir(), "settings.json"), baseDir: getAgentDir() }
+  ];
+  for (const source of sources) {
+    const settings = readJson(source.path);
+    if (!settings || typeof settings !== "object" || Array.isArray(settings))
+      continue;
+    const packages = settings.packages;
+    if (!Array.isArray(packages))
+      continue;
+    for (const entry of packages) {
+      const packageSource = typeof entry === "string" ? entry : entry && typeof entry === "object" && !Array.isArray(entry) && typeof entry.source === "string" ? entry.source : undefined;
+      if (!packageSource)
+        continue;
+      const root = resolvePackageRoot(packageSource, source.baseDir);
+      if (root && !roots.includes(root))
+        roots.push(root);
+    }
+  }
+  return roots;
+}
+function findProjectConfigDir(cwd) {
+  const projectRoot = findConfiguredProjectRoot(path.resolve(cwd));
+  return projectRoot ? getProjectConfigDir(projectRoot) : path.join(path.resolve(cwd), getConfigDirName());
+}
+function resolvePackageRoot(source, baseDir) {
+  const trimmed = source.trim();
+  if (!trimmed)
+    return;
+  if (trimmed.startsWith("npm:")) {
+    const packageName = parseNpmPackageName(trimmed);
+    return packageName ? resolveContainedPath(path.join(baseDir, PACKAGE_CONFIG_ROOT, "node_modules"), packageName) ?? undefined : undefined;
+  }
+  if (trimmed.startsWith("git:") || /^(?:https?:\/\/|ssh:\/\/|git@[^:]+:)/.test(trimmed)) {
+    const parsed = parseGitPackagePath(trimmed.startsWith("git:") ? trimmed : `git:${trimmed}`);
+    return parsed ? path.join(baseDir, PACKAGE_GIT_ROOT, parsed.host, parsed.repoPath) : undefined;
+  }
+  const localPath = trimmed.startsWith("file:") ? trimmed.slice(5) : trimmed;
+  if (localPath === "~")
+    return os.homedir();
+  if (localPath.startsWith("~/"))
+    return path.join(os.homedir(), localPath.slice(2));
+  return path.isAbsolute(localPath) ? path.resolve(localPath) : path.resolve(baseDir, localPath);
+}
+function parseNpmPackageName(source) {
+  const spec = source.slice(4).trim();
+  if (!spec)
+    return;
+  const match = spec.match(/^(@?[^@]+(?:\/[^@]+)?)(?:@(.+))?$/);
+  const packageName = match?.[1] ?? spec;
+  return resolveContainedPath("/", packageName) ? packageName : undefined;
+}
+function parseGitPackagePath(source) {
+  const spec = source.slice(4).trim();
+  if (!spec)
+    return;
+  let host = "";
+  let repoPath = "";
+  const scpLike = spec.match(/^git@([^:]+):(.+)$/);
+  if (scpLike) {
+    host = scpLike[1] ?? "";
+    repoPath = scpLike[2] ?? "";
+  } else if (/^[a-z][a-z0-9+.-]*:\/\//i.test(spec)) {
+    try {
+      const url = new URL(spec);
+      host = url.hostname;
+      repoPath = url.pathname.replace(/^\/+/, "");
+    } catch {
+      return;
+    }
+  } else {
+    const slashIndex = spec.indexOf("/");
+    if (slashIndex < 0)
+      return;
+    host = spec.slice(0, slashIndex);
+    repoPath = spec.slice(slashIndex + 1);
+  }
+  const normalizedPath = stripGitRef(repoPath).replace(/\.git$/, "").replace(/^\/+/, "");
+  if (!host || !isSafePackagePath(host) || !isSafePackagePath(normalizedPath) || normalizedPath.split(/[\\/]/).length < 2) {
+    return;
+  }
+  return { host, repoPath: normalizedPath };
+}
+function stripGitRef(repoPath) {
+  const atIndex = repoPath.indexOf("@");
+  const hashIndex = repoPath.indexOf("#");
+  const refIndex = [atIndex, hashIndex].filter((index) => index >= 0).sort((a, b) => a - b)[0];
+  return refIndex === undefined ? repoPath : repoPath.slice(0, refIndex);
+}
+function isSafePackagePath(value) {
+  return value.length > 0 && !path.isAbsolute(value) && value.split(/[\\/]/).every((part) => part.length > 0 && part !== "." && part !== "..");
+}
+function resolvePackageConfigPath(packageRoot, configuredPath) {
+  const lexicalPath = resolveContainedPath(packageRoot, configuredPath);
+  if (!lexicalPath || !fs.existsSync(lexicalPath))
+    return;
+  try {
+    if (!fs.statSync(lexicalPath).isFile())
+      return;
+    const packageRealPath = fs.realpathSync(packageRoot);
+    const configRealPath = fs.realpathSync(lexicalPath);
+    return resolveContainedPath(packageRealPath, configRealPath) ?? undefined;
+  } catch {
+    return;
+  }
+}
+function resolveContainedPath(root, value) {
+  const resolved = path.resolve(root, value);
+  const relative = path.relative(root, resolved);
+  return relative === "" || !relative.startsWith("..") && !relative.startsWith(path.sep) && !path.isAbsolute(relative) ? resolved : undefined;
+}
+function resolvePluginPath(configuredPath, cwd) {
+  if (configuredPath === "~")
+    return path.resolve(process.env.HOME ?? "", ".");
+  if (configuredPath.startsWith("~/"))
+    return path.resolve(process.env.HOME ?? "", configuredPath.slice(2));
+  return path.isAbsolute(configuredPath) ? path.resolve(configuredPath) : path.resolve(cwd, configuredPath);
+}
+function isValidPluginManifest(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return false;
+  const manifest = value;
+  return manifest.$schema === PLUGIN_SCHEMA && typeof manifest.name === "string" && manifest.name.length >= 1 && manifest.name.length <= 64 && PLUGIN_NAME_PATTERN.test(manifest.name);
+}
+function isValidPluginConfig(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return false;
+  const config = value;
+  return config.$schema === PLUGIN_MCP_SCHEMA && Object.keys(config).every((key) => key === "$schema" || key === "mcpServers") && !!config.mcpServers && typeof config.mcpServers === "object" && !Array.isArray(config.mcpServers);
+}
+function translatePluginServer(pluginName, pluginRoot, value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return;
+  const raw = value;
+  if (raw.type === "stdio")
+    return translatePluginStdioServer(pluginName, pluginRoot, raw);
+  if (raw.type === "streamable-http" || raw.type === "sse")
+    return translatePluginHttpServer(raw);
+  return;
+}
+function translatePluginStdioServer(pluginName, pluginRoot, raw) {
+  if ([...Object.keys(raw)].some((key) => !PLUGIN_STDIO_FIELDS.has(key)))
+    return;
+  if (typeof raw.command !== "string" || !raw.command)
+    return;
+  if (!isBareCommand(raw.command) && !raw.command.startsWith("./"))
+    return;
+  const args = stringArray(raw.args);
+  if (raw.args !== undefined && !args)
+    return;
+  const env = stringRecord(raw.env);
+  if (raw.env !== undefined && !env)
+    return;
+  if (env && (Object.hasOwn(env, "PLUGIN_ROOT") || Object.hasOwn(env, "PLUGIN_DATA")))
+    return;
+  const pluginDataDir = path.join(getAgentDir(), "agent-plugin-data", pluginName);
+  const command = raw.command.startsWith("./") ? resolveContainedPath(pluginRoot, raw.command) : raw.command;
+  if (!command)
+    return;
+  const cwd = resolvePluginCwd(raw.cwd, pluginRoot, pluginDataDir);
+  if (!cwd)
+    return;
+  return {
+    command,
+    args: (args ?? []).map((value) => expandPluginPlaceholders(value, pluginRoot, pluginDataDir)),
+    env: {
+      ...Object.fromEntries(Object.entries(env ?? {}).map(([key, value]) => [key, expandPluginPlaceholders(value, pluginRoot, pluginDataDir)])),
+      PLUGIN_ROOT: pluginRoot,
+      PLUGIN_DATA: pluginDataDir
+    },
+    cwd,
+    pluginDataDir,
+    literalEnv: true
+  };
+}
+function translatePluginHttpServer(raw) {
+  if ([...Object.keys(raw)].some((key) => !PLUGIN_HTTP_FIELDS.has(key)))
+    return;
+  if (typeof raw.url !== "string" || !isValidPluginUrl(raw.url))
+    return;
+  const headers = stringRecord(raw.headers);
+  if (raw.headers !== undefined && !headers)
+    return;
+  if (headers) {
+    const normalized = new Set;
+    for (const key of Object.keys(headers)) {
+      const lower = key.toLowerCase();
+      if (normalized.has(lower))
+        return;
+      normalized.add(lower);
+    }
+    try {
+      new Headers(headers);
+    } catch {
+      return;
+    }
+  }
+  return { url: raw.url, ...headers ? { headers } : {}, httpTransport: raw.type };
+}
+function resolvePluginCwd(value, pluginRoot, pluginDataDir) {
+  if (value === undefined)
+    return pluginRoot;
+  if (typeof value !== "string")
+    return;
+  if (value.startsWith("./"))
+    return resolveContainedPath(pluginRoot, value);
+  if (value === "${PLUGIN_ROOT}" || value.startsWith("${PLUGIN_ROOT}/"))
+    return resolveContainedPath(pluginRoot, value.replace("${PLUGIN_ROOT}", "."));
+  if (value === "${PLUGIN_DATA}" || value.startsWith("${PLUGIN_DATA}/"))
+    return resolveContainedPath(pluginDataDir, value.replace("${PLUGIN_DATA}", "."));
+  return;
+}
+function expandPluginPlaceholders(value, pluginRoot, pluginDataDir) {
+  return value.replaceAll("${PLUGIN_ROOT}", pluginRoot).replaceAll("${PLUGIN_DATA}", pluginDataDir);
+}
+function isBareCommand(command) {
+  return !command.includes("/") && !command.includes("\\") && !command.includes("${PLUGIN_ROOT}") && !command.includes("${PLUGIN_DATA}");
+}
+function isValidPluginUrl(value) {
+  if (value.includes("${") || value.includes("$env:") || value.includes("{env:"))
+    return false;
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return false;
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:")
+    return false;
+  if (url.username || url.password || url.hash)
+    return false;
+  if (url.protocol === "https:")
+    return true;
+  const host = url.hostname.toLowerCase();
+  return host === "localhost" || host === "127.0.0.1" || host === "::1" || host === "[::1]" || /^127(?:\.\d{1,3}){3}$/.test(host);
+}
+function stringArray(value) {
+  return Array.isArray(value) && value.every((entry) => typeof entry === "string") ? value : undefined;
+}
+function stringRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return;
+  const entries = Object.entries(value);
+  if (entries.some(([, entry]) => typeof entry !== "string"))
+    return;
+  return Object.fromEntries(entries);
+}
+function formatName(value, fallback) {
+  return value.replace(/[^A-Za-z0-9_-]+/g, "_").replace(/^[_-]+|[_-]+$/g, "") || fallback;
+}
+function readJson(filePath) {
+  let content;
+  try {
+    content = fs.readFileSync(filePath, "utf-8");
+  } catch (error) {
+    if (error.code === "ENOENT")
+      return;
+    throw new Error(`Failed to read JSON file '${filePath}': ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+  }
+  try {
+    return JSON.parse(content);
+  } catch (error) {
+    throw new Error(`Invalid JSON in '${filePath}': ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+  }
+}