@jstn-sdk/ma 0.1.12 → 0.14.0

package/src/runtime/universal-plugin-broker-core.js

@@ -0,0 +1,898 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { ensureDir, readJson, writeFileIfMissing, writeJson } from "../fs-utils.js";
+import { getRuntimeSubsystemPath } from "../paths.js";
+import { agentRegistry, sanitizeSkillName } from "./skills-registry-export.js";
+
+export const universalPluginBrokerSchemaVersion = "0.1.0";
+export const universalPluginManifestSchemaVersion = "0.1.0";
+
+const mcpInjectorHosts = ["claude-code", "antigravity", "cursor", "codex"];
+
+function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function quoteTomlString(value) {
+  return JSON.stringify(`${value}`);
+}
+
+function quotePosixShell(value) {
+  const text = `${value}`;
+  if (text.includes("\0")) {
+    throw new Error("plugin command and args must not contain NUL bytes");
+  }
+  return `'${text.replaceAll("'", "'\\''")}'`;
+}
+
+function dedupe(values) {
+  return [...new Set(values)];
+}
+
+function mcpServerNameForPlugin(pluginName) {
+  const safeName = sanitizeSkillName(pluginName);
+  const baseName = safeName.startsWith("ma-") ? safeName.slice(3) : safeName;
+  return `ma-plugin-${baseName}`;
+}
+
+async function pathExists(targetPath) {
+  try {
+    await fs.access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function directoryExists(targetPath) {
+  try {
+    return (await fs.stat(targetPath)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+async function readJsonOrDefault(filePath, fallback) {
+  try {
+    return JSON.parse(await fs.readFile(filePath, "utf8"));
+  } catch (error) {
+    if (error?.code === "ENOENT") return structuredClone(fallback);
+    throw new Error(`Invalid JSON configuration: ${filePath}`, { cause: error });
+  }
+}
+
+async function readTextOrEmpty(filePath) {
+  try {
+    return await fs.readFile(filePath, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return "";
+    throw new Error(`Unable to read vendor configuration: ${filePath}`, { cause: error });
+  }
+}
+
+async function writeJsonConfig(filePath, config) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, `${JSON.stringify(config, null, 2)}\n`);
+}
+
+async function fileHash(filePath) {
+  try {
+    if ((await fs.lstat(filePath)).isSymbolicLink()) {
+      throw new Error(`Refusing to hash symlinked vendor path: ${filePath}`);
+    }
+    return crypto
+      .createHash("sha256")
+      .update(await fs.readFile(filePath))
+      .digest("hex");
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw new Error(`Unable to read vendor configuration: ${filePath}`, { cause: error });
+  }
+}
+
+async function pathHash(target) {
+  try {
+    const stat = await fs.lstat(target);
+    if (stat.isSymbolicLink()) throw new Error(`Refusing to hash symlinked path: ${target}`);
+    if (stat.isDirectory()) {
+      const entries = (await fs.readdir(target)).sort();
+      const parts = [];
+      for (const entry of entries)
+        parts.push(`${entry}\0${await pathHash(path.join(target, entry))}`);
+      return crypto
+        .createHash("sha256")
+        .update(`dir\0${parts.join("\0")}`)
+        .digest("hex");
+    }
+    return crypto
+      .createHash("sha256")
+      .update(await fs.readFile(target))
+      .digest("hex");
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+async function assertNoSymlinkPath(target) {
+  if (!target) return;
+  let current = path.parse(path.resolve(target)).root;
+  for (const part of path.relative(current, path.resolve(target)).split(path.sep).filter(Boolean)) {
+    current = path.join(current, part);
+    const stat = await fs.lstat(current).catch((error) => {
+      if (error?.code === "ENOENT") return null;
+      throw error;
+    });
+    if (stat?.isSymbolicLink()) throw new Error(`Refusing symlinked vendor path: ${current}`);
+  }
+}
+
+function hostConfigPath({ host, home, platform, env }) {
+  if (host === "claude-code") return path.join(home, ".claude.json");
+  if (host === "antigravity") return path.join(home, ".antigravity", "config.toml");
+  if (host === "cursor") return cursorStoragePath({ home, platform, env });
+  if (host === "codex") return path.join(home, ".codex", "config.toml");
+  return null;
+}
+
+async function snapshotHostConfig({ host, home, platform, env, backupRoot }) {
+  const configPath = hostConfigPath({ host, home, platform, env });
+  if (!configPath) return { host, path: null, backupPath: null, beforeHash: null };
+  await assertNoSymlinkPath(configPath);
+  const beforeHash = await fileHash(configPath);
+  const backupPath = path.join(backupRoot, `${host}.bak`);
+  if (beforeHash) {
+    await fs.mkdir(backupRoot, { recursive: true });
+    await fs.copyFile(configPath, backupPath);
+  }
+  return { host, path: configPath, backupPath: beforeHash ? backupPath : null, beforeHash };
+}
+
+function cursorStoragePath({
+  home = os.homedir(),
+  platform = process.platform,
+  env = process.env,
+} = {}) {
+  if (platform === "win32") {
+    return path.join(
+      env.APPDATA || path.join(home, "AppData", "Roaming"),
+      "Cursor",
+      "User",
+      "globalStorage",
+      "storage.json",
+    );
+  }
+  if (platform === "darwin") {
+    return path.join(
+      home,
+      "Library",
+      "Application Support",
+      "Cursor",
+      "User",
+      "globalStorage",
+      "storage.json",
+    );
+  }
+  return path.join(home, ".config", "Cursor", "User", "globalStorage", "storage.json");
+}
+
+function createMcpDefinition({ manifest, pluginDir, wrapperPath, useWrapper = true }) {
+  const manifestArgs = asArray(manifest.mcp?.args).map((arg) =>
+    `${arg}`.replaceAll("{{PLUGIN_DIR}}", pluginDir),
+  );
+  if (useWrapper) {
+    return {
+      command: wrapperPath,
+      args: [],
+    };
+  }
+  return {
+    command: manifest.mcp.command,
+    args: manifestArgs,
+  };
+}
+
+export function renderWrapperScript({ manifest, pluginDir }) {
+  const args = asArray(manifest.mcp?.args).map((arg) =>
+    `${arg}`.replaceAll("{{PLUGIN_DIR}}", pluginDir),
+  );
+  if (manifest.mcp.command === "node" && args.length > 0) {
+    const [entrypoint, ...rest] = args;
+    const quotedRest = rest.map(quotePosixShell).join(" ");
+    return `#!/usr/bin/env sh\nexec ${quotePosixShell("node")} ${quotePosixShell(entrypoint)}${quotedRest ? ` ${quotedRest}` : ""} "$@"\n`;
+  }
+  const quotedArgs = args.map(quotePosixShell).join(" ");
+  return `#!/usr/bin/env sh\nexec ${quotePosixShell(manifest.mcp.command)}${quotedArgs ? ` ${quotedArgs}` : ""} "$@"\n`;
+}
+
+export function getUniversalPluginBrokerCorePath() {
+  return getRuntimeSubsystemPath("context", "universal-plugin-broker-core.json");
+}
+
+export function createDefaultUniversalPluginBrokerCore() {
+  const supportedAgents = Object.keys(agentRegistry).sort();
+  return {
+    schemaVersion: universalPluginBrokerSchemaVersion,
+    product: "Meta-Architect",
+    purpose:
+      "Defines the MA-owned hybrid plugin contract: universal MCP tooling plus vendor-agnostic MA skill context payloads across supported host agents.",
+    architecture: {
+      tooling_layer: {
+        protocol: "MCP stdio JSON-RPC",
+        server_contract: "ma-manifest.json#mcp",
+        usable_by: mcpInjectorHosts,
+      },
+      context_layer: {
+        canonical_skill_dir: ".agents/skills",
+        prompt_contract: "ma-manifest.json#ma_roles",
+        usable_by: supportedAgents,
+      },
+    },
+    lifecycle: ["resolve", "isolate", "generate", "mutate"],
+    mutation_policy: {
+      may_write_vendor_configs: true,
+      writes_only_detected_or_requested_hosts: true,
+      may_mutate_release_state: false,
+      may_mutate_decisions: false,
+      records_as: "plugin_compatibility_configuration",
+      never_records_as: "build_evidence",
+      requires_session_reload_for: ["claude-code", "antigravity", "codex"],
+    },
+    supported_agents: supportedAgents,
+    mcp_injector_hosts: mcpInjectorHosts,
+  };
+}
+
+export function validateUniversalPluginBrokerCore(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("universal plugin broker core must be an object");
+  }
+  if (value.schemaVersion !== universalPluginBrokerSchemaVersion) {
+    throw new Error(`Unsupported universal plugin broker schemaVersion: ${value.schemaVersion}`);
+  }
+  if (value.mutation_policy?.may_mutate_release_state !== false) {
+    throw new Error("plugin broker must not mutate release state");
+  }
+  if (value.mutation_policy?.may_mutate_decisions !== false) {
+    throw new Error("plugin broker must not mutate decisions");
+  }
+  if (value.mutation_policy?.records_as !== "plugin_compatibility_configuration") {
+    throw new Error("plugin broker must record as plugin_compatibility_configuration");
+  }
+  if (value.mutation_policy?.never_records_as !== "build_evidence") {
+    throw new Error("plugin broker must never record as build_evidence");
+  }
+  for (const host of mcpInjectorHosts) {
+    if (!value.mcp_injector_hosts?.includes(host)) {
+      throw new Error(`plugin broker missing MCP injector host: ${host}`);
+    }
+  }
+  return value;
+}
+
+export async function seedUniversalPluginBrokerCoreArtifacts() {
+  await ensureDir(getRuntimeSubsystemPath("context"));
+  await writeFileIfMissing(
+    getUniversalPluginBrokerCorePath(),
+    `${JSON.stringify(createDefaultUniversalPluginBrokerCore(), null, 2)}\n`,
+  );
+}
+
+export async function loadUniversalPluginBrokerCore() {
+  return validateUniversalPluginBrokerCore(await readJson(getUniversalPluginBrokerCorePath()));
+}
+
+export function createUniversalPluginManifest({
+  name,
+  version = "0.1.0",
+  description = "",
+  entrypoint,
+  mcp = null,
+  ma_roles: maRoles = {},
+}) {
+  const safeName = sanitizeSkillName(name);
+  if (!safeName) {
+    throw new Error("plugin manifest requires name");
+  }
+  const normalizedMcp = mcp ?? {
+    command: "node",
+    args: ["{{PLUGIN_DIR}}/dist/index.js"],
+  };
+  return validateUniversalPluginManifest({
+    schemaVersion: universalPluginManifestSchemaVersion,
+    name: safeName,
+    version,
+    description,
+    entrypoint,
+    mcp: {
+      command: normalizedMcp.command,
+      args: asArray(normalizedMcp.args),
+    },
+    ma_roles: {
+      bind: dedupe(asArray(maRoles.bind)),
+      prompt_injection_file: maRoles.prompt_injection_file ?? null,
+    },
+  });
+}
+
+export function validateUniversalPluginManifest(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("plugin manifest must be an object");
+  }
+  const name = sanitizeSkillName(value.name);
+  if (!name) {
+    throw new Error("plugin manifest requires name");
+  }
+  if (typeof value.version !== "string" || value.version.trim() === "") {
+    throw new Error("plugin manifest requires version");
+  }
+  if (typeof value.entrypoint !== "string" || value.entrypoint.trim() === "") {
+    throw new Error("plugin manifest requires entrypoint");
+  }
+  if (typeof value.mcp?.command !== "string" || value.mcp.command.trim() === "") {
+    throw new Error("plugin manifest requires mcp.command");
+  }
+  if (!Array.isArray(value.mcp?.args)) {
+    throw new Error("plugin manifest requires mcp.args array");
+  }
+  const roleBindings = asArray(value.ma_roles?.bind);
+  for (const role of roleBindings) {
+    if (typeof role !== "string" || !role.startsWith("$")) {
+      throw new Error("plugin manifest role bindings must use MA trigger names such as $vet");
+    }
+  }
+  return {
+    schemaVersion: value.schemaVersion ?? universalPluginManifestSchemaVersion,
+    name,
+    version: value.version,
+    description: value.description ?? "",
+    entrypoint: value.entrypoint,
+    mcp: {
+      command: value.mcp.command,
+      args: value.mcp.args.map((arg) => `${arg}`),
+    },
+    ma_roles: {
+      bind: dedupe(roleBindings),
+      prompt_injection_file: value.ma_roles?.prompt_injection_file ?? null,
+    },
+  };
+}
+
+export async function loadUniversalPluginManifest(sourceDir) {
+  return validateUniversalPluginManifest(await readJson(path.join(sourceDir, "ma-manifest.json")));
+}
+
+export function renderUniversalMcpServerTemplate({
+  serverName = "ma-plugin-universal-executor",
+  toolName = "execute_plugin_action",
+} = {}) {
+  return `import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+
+const server = new Server({ name: ${JSON.stringify(serverName)}, version: "1.0.0" }, { capabilities: { tools: {} } });
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [{
+    name: ${JSON.stringify(toolName)},
+    description: "Executes plugin logic through MA-compatible MCP stdio.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        targetFilePath: { type: "string" },
+        payload: { type: "string" }
+      },
+      required: ["targetFilePath", "payload"]
+    }
+  }]
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  if (request.params.name !== ${JSON.stringify(toolName)}) throw new Error("Tool not found");
+  const { targetFilePath, payload } = request.params.arguments;
+  return { content: [{ type: "text", text: JSON.stringify({ status: "success", targetFilePath, payload }) }] };
+});
+
+await server.connect(new StdioServerTransport());
+`;
+}
+
+export function renderPluginContextSkillMd(manifest) {
+  const plugin = validateUniversalPluginManifest(manifest);
+  const serverName = mcpServerNameForPlugin(plugin.name);
+  const roles = plugin.ma_roles.bind.length > 0 ? plugin.ma_roles.bind : ["$maestro"];
+  return [
+    "---",
+    `name: ${serverName}`,
+    `description: ${plugin.description || `MA universal plugin context payload for ${plugin.name}`}`,
+    "---",
+    "",
+    `# ${serverName}`,
+    "",
+    "This is a Meta-Architect universal plugin context payload.",
+    "",
+    "## Role Binding",
+    "",
+    ...roles.map((role) => `- ${role}`),
+    "",
+    "## Execution Contract",
+    "",
+    `- MCP server name: \`${serverName}\``,
+    "- Use the MCP tool only when the active MA lane selects this plugin as task-relevant.",
+    "- Route authoritative state changes through `$maestro` or the owning lane.",
+    "- Do not mutate `.ma/release.json`, `.ma/decisions.json`, `.ma/plans/`, or `.ma/specs/` directly.",
+    "- Record plugin output as `plugin_compatibility_configuration` or lane-scoped context, never as `build_evidence`.",
+    "- If the host MCP client was already running, report that `/reload-mcp` or a session restart may be required.",
+    "",
+  ].join("\n");
+}
+
+export async function writePluginContextSkill({ manifest, home = os.homedir() }) {
+  const plugin = validateUniversalPluginManifest(manifest);
+  const serverName = mcpServerNameForPlugin(plugin.name);
+  const skillDir = path.join(home, ".agents", "skills", serverName);
+  await assertNoSymlinkPath(skillDir);
+  for (const fileName of ["SKILL.md", "ma-plugin-manifest.json", "ma-plugin-broker-receipt.json"]) {
+    await assertNoSymlinkPath(path.join(skillDir, fileName));
+  }
+  await fs.mkdir(skillDir, { recursive: true });
+  await fs.writeFile(path.join(skillDir, "SKILL.md"), renderPluginContextSkillMd(plugin));
+  await writeJson(path.join(skillDir, "ma-plugin-manifest.json"), plugin);
+  const receipt = {
+    schemaVersion: universalPluginBrokerSchemaVersion,
+    record_type: "plugin_context_skill_receipt",
+    plugin: plugin.name,
+    skill: serverName,
+    path: skillDir,
+    records_as: "plugin_compatibility_configuration",
+    build_evidence: false,
+  };
+  await writeJson(path.join(skillDir, "ma-plugin-broker-receipt.json"), receipt);
+  return receipt;
+}
+
+export async function detectInstalledPluginHosts({
+  home = os.homedir(),
+  platform = process.platform,
+  env = process.env,
+} = {}) {
+  const hosts = [];
+  if (
+    (await pathExists(path.join(home, ".claude.json"))) ||
+    (await directoryExists(path.join(home, ".claude")))
+  ) {
+    hosts.push("claude-code");
+  }
+  if (await directoryExists(path.join(home, ".antigravity"))) {
+    hosts.push("antigravity");
+  }
+  if (
+    (await pathExists(cursorStoragePath({ home, platform, env }))) ||
+    (await directoryExists(path.dirname(cursorStoragePath({ home, platform, env }))))
+  ) {
+    hosts.push("cursor");
+  }
+  if (await directoryExists(path.join(home, ".codex"))) {
+    hosts.push("codex");
+  }
+  return hosts;
+}
+
+export async function injectClaudeCodeMcpServer({
+  home = os.homedir(),
+  serverName,
+  command,
+  args,
+}) {
+  const claudeJsonPath = path.join(home, ".claude.json");
+  await assertNoSymlinkPath(claudeJsonPath);
+  if (!(await pathExists(claudeJsonPath)) && !(await directoryExists(path.join(home, ".claude")))) {
+    return { host: "claude-code", status: "skipped", reason: "Claude Code config not detected" };
+  }
+  const config = await readJsonOrDefault(claudeJsonPath, {});
+  config.mcpServers = config.mcpServers ?? {};
+  config.mcpServers[serverName] = { command, args };
+  await writeJsonConfig(claudeJsonPath, config);
+  return { host: "claude-code", status: "configured", path: claudeJsonPath };
+}
+
+export async function injectAntigravityMcpServer({
+  home = os.homedir(),
+  serverName,
+  command,
+  args,
+}) {
+  const antigravityRoot = path.join(home, ".antigravity");
+  if (!(await directoryExists(antigravityRoot))) {
+    return {
+      host: "antigravity",
+      status: "skipped",
+      reason: "Antigravity config root not detected",
+    };
+  }
+  const configPath = path.join(antigravityRoot, "config.toml");
+  await assertNoSymlinkPath(configPath);
+  const existing = (await readTextOrEmpty(configPath)).trimEnd();
+  const marker = `name = ${quoteTomlString(serverName)}`;
+  if (existing.includes(marker)) {
+    return { host: "antigravity", status: "configured", path: configPath, idempotent: true };
+  }
+  const argList = `[${args.map((arg) => quoteTomlString(arg)).join(", ")}]`;
+  const block = [
+    "",
+    "[[mcp_servers]]",
+    `name = ${quoteTomlString(serverName)}`,
+    `command = ${quoteTomlString(command)}`,
+    `args = ${argList}`,
+    'env = ["NODE_ENV=production"]',
+    "",
+  ].join("\n");
+  await fs.mkdir(path.dirname(configPath), { recursive: true });
+  await fs.writeFile(configPath, `${existing}${block}`);
+  return { host: "antigravity", status: "configured", path: configPath };
+}
+
+export async function injectCursorMcpServer({
+  home = os.homedir(),
+  platform = process.platform,
+  env = process.env,
+  serverName,
+  command,
+  args,
+}) {
+  const settingsPath = cursorStoragePath({ home, platform, env });
+  await assertNoSymlinkPath(settingsPath);
+  if (!(await pathExists(settingsPath)) && !(await directoryExists(path.dirname(settingsPath)))) {
+    return { host: "cursor", status: "skipped", reason: "Cursor storage not detected" };
+  }
+  const storage = await readJsonOrDefault(settingsPath, {});
+  storage["mcp.mcpServers"] = storage["mcp.mcpServers"] ?? {};
+  storage["mcp.mcpServers"][serverName] = {
+    name: serverName,
+    type: "command",
+    command: [command, ...args.map((arg) => `"${arg.replaceAll('"', '\\"')}"`)].join(" ").trim(),
+    enabled: true,
+  };
+  await writeJsonConfig(settingsPath, storage);
+  return { host: "cursor", status: "configured", path: settingsPath };
+}
+
+export async function injectCodexMcpServer({ home = os.homedir(), serverName, command, args }) {
+  const codexRoot = path.join(home, ".codex");
+  if (!(await directoryExists(codexRoot))) {
+    return { host: "codex", status: "skipped", reason: "Codex config root not detected" };
+  }
+  const configPath = path.join(codexRoot, "config.toml");
+  await assertNoSymlinkPath(configPath);
+  const existing = (await readTextOrEmpty(configPath)).trimEnd();
+  const header = `[mcp_servers.${quoteTomlString(serverName)}]`;
+  if (existing.includes(header)) {
+    return { host: "codex", status: "configured", path: configPath, idempotent: true };
+  }
+  const argList = `[${args.map((arg) => quoteTomlString(arg)).join(", ")}]`;
+  const block = ["", header, `command = ${quoteTomlString(command)}`, `args = ${argList}`, ""].join(
+    "\n",
+  );
+  await fs.mkdir(path.dirname(configPath), { recursive: true });
+  await fs.writeFile(configPath, `${existing}${block}`);
+  return { host: "codex", status: "configured", path: configPath };
+}
+
+export async function injectPluginToVendors({
+  manifest,
+  pluginDir,
+  wrapperPath,
+  home = os.homedir(),
+  targets = null,
+  platform = process.platform,
+  env = process.env,
+  useWrapper = true,
+  backupRoot = null,
+} = {}) {
+  const plugin = validateUniversalPluginManifest(manifest);
+  const selectedTargets = targets ?? (await detectInstalledPluginHosts({ home, platform, env }));
+  const serverName = mcpServerNameForPlugin(plugin.name);
+  const definition = createMcpDefinition({ manifest: plugin, pluginDir, wrapperPath, useWrapper });
+  const receipts = [];
+  const snapshots = new Map();
+  try {
+    for (const target of selectedTargets) {
+      const snapshot = backupRoot
+        ? await snapshotHostConfig({ host: target, home, platform, env, backupRoot })
+        : null;
+      if (snapshot) snapshots.set(target, snapshot);
+      if (target === "claude-code") {
+        receipts.push(await injectClaudeCodeMcpServer({ home, serverName, ...definition }));
+      } else if (target === "antigravity") {
+        receipts.push(await injectAntigravityMcpServer({ home, serverName, ...definition }));
+      } else if (target === "cursor") {
+        receipts.push(
+          await injectCursorMcpServer({ home, platform, env, serverName, ...definition }),
+        );
+      } else if (target === "codex") {
+        receipts.push(await injectCodexMcpServer({ home, serverName, ...definition }));
+      } else {
+        receipts.push({ host: target, status: "skipped", reason: "No MA MCP injector for host" });
+      }
+    }
+  } catch (error) {
+    const rollbackErrors = [];
+    for (const snapshot of snapshots.values()) {
+      try {
+        if (snapshot.backupPath) await fs.copyFile(snapshot.backupPath, snapshot.path);
+        else await fs.rm(snapshot.path, { force: true });
+      } catch (rollbackError) {
+        rollbackErrors.push(rollbackError);
+      }
+    }
+    if (rollbackErrors.length > 0) {
+      throw new AggregateError([error, ...rollbackErrors], "Plugin vendor rollback failed");
+    }
+    throw error;
+  }
+  for (const receipt of receipts) {
+    const snapshot = backupRoot ? snapshots.get(receipt.host) : null;
+    if (snapshot) {
+      receipt.backupPath = snapshot.backupPath;
+      receipt.beforeHash = snapshot.beforeHash;
+      receipt.afterHash = await fileHash(snapshot.path);
+    }
+  }
+  return {
+    record_type: "vendor_manifest_injection",
+    plugin: plugin.name,
+    serverName,
+    mcp: definition,
+    receipts,
+    configured_hosts: receipts
+      .filter((receipt) => receipt.status === "configured")
+      .map((receipt) => receipt.host),
+    records_as: "plugin_compatibility_configuration",
+    build_evidence: false,
+  };
+}
+
+export async function installUniversalPlugin({
+  sourceDir,
+  home = os.homedir(),
+  targets = null,
+  platform = process.platform,
+  env = process.env,
+  useWrapper = true,
+  dryRun = false,
+} = {}) {
+  if (!sourceDir) {
+    throw new Error("installUniversalPlugin requires sourceDir");
+  }
+  const manifest = await loadUniversalPluginManifest(sourceDir);
+  const sourceEntrypoint = path.join(sourceDir, manifest.entrypoint);
+  if (!(await pathExists(sourceEntrypoint))) {
+    throw new Error(`Plugin entrypoint missing: ${manifest.entrypoint}`);
+  }
+  const selectedTargets = targets ?? (await detectInstalledPluginHosts({ home, platform, env }));
+  if (dryRun) {
+    return {
+      schemaVersion: universalPluginBrokerSchemaVersion,
+      record_type: "universal_plugin_broker_dry_run",
+      plugin: manifest.name,
+      targets: selectedTargets,
+      files: selectedTargets
+        .map((host) => hostConfigPath({ host, home, platform, env }))
+        .filter(Boolean),
+      records_as: "plugin_compatibility_configuration",
+      build_evidence: false,
+    };
+  }
+  await preflightVendorConfigs({ selectedTargets, home, platform, env });
+  const pluginDir = path.join(home, ".ma", "plugins", manifest.name);
+  const wrapperPath = path.join(home, ".ma", "bin", mcpServerNameForPlugin(manifest.name));
+  const backupRoot = path.join(home, ".ma", "backups", "plugins", manifest.name, `${Date.now()}`);
+  let previousPaths;
+  let contextSkillReceipt;
+  let vendorInjection;
+  let installedPaths;
+  try {
+    const contextSkillPath = path.join(
+      home,
+      ".agents",
+      "skills",
+      mcpServerNameForPlugin(manifest.name),
+    );
+    await assertNoSymlinkPath(backupRoot);
+    await assertNoSymlinkPath(pluginDir);
+    await assertNoSymlinkPath(wrapperPath);
+    await assertNoSymlinkPath(contextSkillPath);
+    await fs.mkdir(backupRoot, { recursive: true });
+    previousPaths = {
+      pluginDir: await backupPathIfPresent(pluginDir, path.join(backupRoot, "previous-plugin")),
+      wrapperPath: await backupPathIfPresent(
+        wrapperPath,
+        path.join(backupRoot, "previous-wrapper"),
+      ),
+      contextSkill: await backupPathIfPresent(
+        contextSkillPath,
+        path.join(backupRoot, "previous-skill"),
+      ),
+    };
+    await fs.mkdir(path.dirname(pluginDir), { recursive: true });
+    await fs.cp(sourceDir, pluginDir, { recursive: true });
+    await fs.mkdir(path.dirname(wrapperPath), { recursive: true });
+    await fs.writeFile(wrapperPath, renderWrapperScript({ manifest, pluginDir }));
+    await fs.chmod(wrapperPath, 0o755);
+    contextSkillReceipt = await writePluginContextSkill({ manifest, home });
+    vendorInjection = await injectPluginToVendors({
+      manifest,
+      pluginDir,
+      wrapperPath,
+      home,
+      targets: selectedTargets,
+      platform,
+      env,
+      useWrapper,
+      backupRoot,
+    });
+    installedPaths = {
+      pluginDir: await pathHash(pluginDir),
+      wrapperPath: await pathHash(wrapperPath),
+      contextSkill: await pathHash(contextSkillReceipt.path),
+    };
+    const receipt = {
+      schemaVersion: universalPluginBrokerSchemaVersion,
+      record_type: "universal_plugin_broker_install_receipt",
+      plugin: manifest.name,
+      pluginDir,
+      wrapperPath,
+      contextSkillReceipt,
+      previousPaths,
+      installedPaths,
+      vendorInjection,
+      backupRoot,
+      activation_notice:
+        "Plugin configured. Run /reload-mcp where supported or restart active agent sessions to activate newly injected MCP servers.",
+      records_as: "plugin_compatibility_configuration",
+      build_evidence: false,
+    };
+    await writeJson(path.join(backupRoot, "receipt.json"), receipt);
+    return receipt;
+  } catch (error) {
+    if (vendorInjection && previousPaths) {
+      try {
+        await rollbackUniversalPluginInstall({
+          pluginDir,
+          wrapperPath,
+          contextSkillReceipt,
+          previousPaths,
+          installedPaths,
+          vendorInjection,
+          backupRoot,
+        });
+      } catch (rollbackError) {
+        const failure = error instanceof Error ? error : new Error(String(error));
+        failure.cause = rollbackError;
+        throw failure;
+      }
+    } else {
+      if (previousPaths) {
+        await restorePath(pluginDir, previousPaths.pluginDir);
+        await restorePath(wrapperPath, previousPaths.wrapperPath);
+        await restorePath(
+          path.join(home, ".agents", "skills", mcpServerNameForPlugin(manifest.name)),
+          previousPaths.contextSkill,
+        );
+      }
+      await fs.rm(backupRoot, { recursive: true, force: true });
+    }
+    throw error;
+  }
+}
+
+async function preflightVendorConfigs({ selectedTargets, home, platform, env }) {
+  for (const target of selectedTargets) {
+    if (target === "claude-code") {
+      const configPath = path.join(home, ".claude.json");
+      if (await pathExists(configPath)) await readJsonOrDefault(configPath, {});
+    }
+    if (target === "cursor") {
+      const configPath = cursorStoragePath({ home, platform, env });
+      if (await pathExists(configPath)) await readJsonOrDefault(configPath, {});
+    }
+    if (target === "antigravity" || target === "codex") {
+      const configPath = hostConfigPath({ host: target, home, platform, env });
+      if (configPath) await readTextOrEmpty(configPath);
+    }
+  }
+}
+
+async function backupPathIfPresent(source, backup) {
+  if (!(await pathExists(source))) return null;
+  await fs.cp(source, backup, { recursive: true, force: true });
+  return backup;
+}
+
+async function restorePath(target, backup) {
+  if (!target) return;
+  await fs.rm(target, { recursive: true, force: true });
+  if (backup) await fs.cp(backup, target, { recursive: true, force: true });
+}
+
+export async function rollbackUniversalPluginInstall(receipt) {
+  if (receipt?.installedPaths) {
+    for (const [label, expectedHash] of Object.entries(receipt.installedPaths)) {
+      const target =
+        label === "pluginDir"
+          ? receipt.pluginDir
+          : label === "wrapperPath"
+            ? receipt.wrapperPath
+            : receipt.contextSkillReceipt?.path;
+      if ((await pathHash(target)) !== expectedHash) {
+        throw new Error(`Refusing rollback: installed ${label} changed after installation`);
+      }
+    }
+  }
+  const entries = receipt?.vendorInjection?.receipts ?? [];
+  const validated = [];
+  for (const entry of entries) {
+    if (!entry.path) continue;
+    const currentHash = await fileHash(entry.path);
+    const expectedHash = entry.afterHash ?? null;
+    if (currentHash !== expectedHash) {
+      throw new Error(`Refusing rollback for ${entry.host}: vendor config changed after injection`);
+    }
+    const backupExists = entry.backupPath && (await pathExists(entry.backupPath));
+    if (entry.status === "configured" && entry.beforeHash && !backupExists) {
+      throw new Error(`Refusing rollback for ${entry.host}: rollback source is missing`);
+    }
+    validated.push({
+      entry,
+      current: currentHash === null ? null : await fs.readFile(entry.path),
+      desired: backupExists ? await fs.readFile(entry.backupPath) : null,
+    });
+  }
+  try {
+    for (const { entry, desired } of validated) {
+      if (desired) await fs.writeFile(entry.path, desired);
+      else if (entry.status === "configured") await fs.rm(entry.path, { force: true });
+    }
+  } catch (error) {
+    const restoreErrors = [];
+    for (const { entry, current } of validated) {
+      try {
+        await assertNoSymlinkPath(entry.path);
+        if (current) await fs.writeFile(entry.path, current);
+        else await fs.rm(entry.path, { force: true });
+      } catch (restoreError) {
+        restoreErrors.push(restoreError);
+      }
+    }
+    if (restoreErrors.length > 0) {
+      throw new AggregateError(restoreErrors, "Plugin vendor rollback recovery failed");
+    }
+    throw new Error("Plugin rollback failed; prior vendor state was restored where possible", {
+      cause: error,
+    });
+  }
+  const pathRestoreErrors = [];
+  for (const [target, backup] of [
+    [receipt.pluginDir, receipt.previousPaths?.pluginDir],
+    [receipt.wrapperPath, receipt.previousPaths?.wrapperPath],
+    [receipt.contextSkillReceipt?.path, receipt.previousPaths?.contextSkill],
+  ]) {
+    try {
+      await assertNoSymlinkPath(target);
+      await restorePath(target, backup);
+    } catch (restoreError) {
+      pathRestoreErrors.push(restoreError);
+    }
+  }
+  if (pathRestoreErrors.length > 0) {
+    throw new AggregateError(pathRestoreErrors, "Plugin rollback recovery failed");
+  }
+  if (receipt.backupRoot) await fs.rm(receipt.backupRoot, { recursive: true, force: true });
+  return {
+    rolledBack: validated
+      .filter(({ entry }) => entry.status === "configured")
+      .map(({ entry }) => entry.host),
+  };
+}