@app-vitals/agent-runtime 1.4.0 → 1.6.0

package/boot.ts

@@ -523,13 +523,22 @@ export async function startAgent(
         });
 
         // Install agent-specific plugins from bundle (non-fatal)
-        if (bundle.plugins?.length) {
-          await installPlugins(undefined, undefined, bundle.plugins).catch(
-            (err) =>
-              console.warn(
-                "[config-sync] agent plugin install failed (non-fatal):",
-                (err as Error).message,
-              ),
+        if (bundle.plugins?.length || bundle.marketplaces?.length) {
+          await installPlugins(
+            undefined,
+            undefined,
+            bundle.plugins,
+            undefined,
+            undefined,
+            undefined,
+            undefined,
+            undefined,
+            bundle.marketplaces,
+          ).catch((err) =>
+            console.warn(
+              "[config-sync] agent plugin install failed (non-fatal):",
+              (err as Error).message,
+            ),
           );
         }
 

package/entrypoint.ts

@@ -20,6 +20,7 @@
 import { join } from "node:path";
 import type { AgentPlugin } from "@app-vitals/agent-admin";
 import type { AgentConfigClient } from "./agent-config-client.ts";
+import type { RemoteMarketplace } from "./setup.ts";
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
@@ -43,6 +44,12 @@ export interface EntrypointDeps {
     execFn?: ExecFn,
     cwd?: string,
     plugins?: AgentPlugin[],
+    shipwrightRepoRootOverride?: string,
+    pluginManifestPath?: string,
+    extraMarketplaceDirs?: string[],
+    extraMarketplacesRoot?: string,
+    env?: Record<string, string | undefined>,
+    remoteMarketplaces?: RemoteMarketplace[],
   ) => Promise<void>;
   spawnAgentServer: (cmd: string, args: string[]) => void;
   exit: (code: number) => void;
@@ -130,7 +137,17 @@ export async function runEntrypoint(deps: EntrypointDeps): Promise<void> {
     await runMiseStartup(agentHome);
 
     // Step 7: Install plugins
-    await installPlugins(undefined, undefined, config.plugins);
+    await installPlugins(
+      undefined,
+      undefined,
+      config.plugins,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      config.marketplaces,
+    );
 
     // Step 8: Spawn agent server
     spawnAgentServer("bun", ["run", join(import.meta.dir, "..", "index.ts")]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@app-vitals/agent-runtime",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/app-vitals/agent.git",
@@ -40,8 +40,8 @@
     "./workspace-paths": "./workspace-paths.ts"
   },
   "dependencies": {
-    "@app-vitals/agent-admin": "1.4.0",
-    "@app-vitals/agent-lib": "1.4.0",
+    "@app-vitals/agent-admin": "1.6.0",
+    "@app-vitals/agent-lib": "1.6.0",
     "@octokit/auth-app": "^8.2.0",
     "@sentry/bun": "^10.63.0",
     "@slack/bolt": "^5.0.0",

package/setup.integration.test.ts

@@ -1590,3 +1590,239 @@ describe("installPlugins stale shipwright marketplace healing", () => {
     expect(calls).toEqual([["plugin", "marketplace", "add", root]]);
   });
 });
+
+// ---------------------------------------------------------------------------
+// installPlugins — remote marketplaces (PMK-1.3)
+// ---------------------------------------------------------------------------
+
+describe("installPlugins — remote marketplaces", () => {
+  const ROW = { name: "mkt", source: "owner/mkt", ref: "v1" };
+  const NO_REPO = () => join(testHome, "no-repo");
+  const registryPath = () => join(testHome, "known_marketplaces.json");
+  const manifestPath = () => join(testHome, "installed_plugins.json");
+
+  const writeRegistry = (registry: unknown) => {
+    mkdirSync(testHome, { recursive: true });
+    writeFileSync(registryPath(), JSON.stringify(registry));
+  };
+
+  // A marketplace dir the registry can point at.
+  const installDir = (withManifest: boolean): string => {
+    const dir = join(testHome, "marketplaces-cache", "mkt");
+    mkdirSync(join(dir, ".claude-plugin"), { recursive: true });
+    if (withManifest) {
+      writeFileSync(
+        join(dir, ".claude-plugin", "marketplace.json"),
+        JSON.stringify({ name: "mkt" }),
+      );
+    }
+    return dir;
+  };
+
+  const githubEntry = (
+    repo: string,
+    ref: string | undefined,
+    installLocation: string,
+  ) => ({
+    source: { source: "github", repo, ...(ref ? { ref } : {}) },
+    installLocation,
+    lastUpdated: "2026-11-09T00:00:00.000Z",
+  });
+
+  const run = async (
+    exec: (
+      cmd: string,
+      args: string[],
+      opts: { cwd: string },
+    ) => Promise<{ stdout: string; exitCode: number }>,
+    rows: Array<{ name: string; source: string; ref?: string | null }>,
+    extraDirs: string[] = NO_EXTRA_MARKETPLACES,
+    plugins: AgentPlugin[] = [],
+  ) =>
+    installPlugins(
+      exec,
+      testHome,
+      plugins,
+      NO_REPO(),
+      manifestPath(),
+      extraDirs,
+      undefined,
+      {},
+      rows,
+    );
+
+  const recorder = (exitFor: (args: string[]) => number = () => 0) => {
+    const calls: string[][] = [];
+    const exec = async (_cmd: string, args: string[]) => {
+      calls.push(args);
+      return { stdout: "", exitCode: exitFor(args) };
+    };
+    return { calls, exec };
+  };
+
+  it("with no rows the call sequence is unchanged", async () => {
+    const { calls, exec } = recorder();
+    await run(exec, [], NO_EXTRA_MARKETPLACES, [SHIPWRIGHT_ROW]);
+    expect(calls).toEqual([
+      ["plugin", "install", "shipwright@shipwright"],
+      ["plugin", "update", "shipwright@shipwright"],
+    ]);
+  });
+
+  it("fresh home: baked adds, remote add <source>#<ref>, update, then plugins", async () => {
+    const baked = join(testHome, "baked", "baked-mkt");
+    const { calls, exec } = recorder();
+    await run(exec, [ROW], [baked], [SHIPWRIGHT_ROW]);
+    expect(calls).toEqual([
+      ["plugin", "marketplace", "add", baked],
+      ["plugin", "marketplace", "add", "owner/mkt#v1"],
+      ["plugin", "marketplace", "update", "mkt"],
+      ["plugin", "install", "shipwright@shipwright"],
+      ["plugin", "update", "shipwright@shipwright"],
+    ]);
+  });
+
+  it("adds without a ref suffix when the row has no ref", async () => {
+    const { calls, exec } = recorder();
+    await run(exec, [{ name: "mkt", source: "owner/mkt", ref: null }]);
+    expect(calls[0]).toEqual(["plugin", "marketplace", "add", "owner/mkt"]);
+  });
+
+  it("same source and ref: only update", async () => {
+    writeRegistry({ mkt: githubEntry("owner/mkt", "v1", installDir(true)) });
+    const { calls, exec } = recorder();
+    await run(exec, [ROW]);
+    expect(calls).toEqual([["plugin", "marketplace", "update", "mkt"]]);
+  });
+
+  it("different ref: remove, add, update", async () => {
+    writeRegistry({ mkt: githubEntry("owner/mkt", "v0", installDir(true)) });
+    const { calls, exec } = recorder();
+    await run(exec, [ROW]);
+    expect(calls).toEqual([
+      ["plugin", "marketplace", "remove", "mkt"],
+      ["plugin", "marketplace", "add", "owner/mkt#v1"],
+      ["plugin", "marketplace", "update", "mkt"],
+    ]);
+  });
+
+  it("different source: remove, add, update", async () => {
+    writeRegistry({ mkt: githubEntry("other/mkt", "v1", installDir(true)) });
+    const { calls, exec } = recorder();
+    await run(exec, [ROW]);
+    expect(calls.map((c) => c[2])).toEqual(["remove", "add", "update"]);
+  });
+
+  it("installLocation without marketplace.json: remove, add, update", async () => {
+    writeRegistry({ mkt: githubEntry("owner/mkt", "v1", installDir(false)) });
+    const { calls, exec } = recorder();
+    await run(exec, [ROW]);
+    expect(calls.map((c) => c[2])).toEqual(["remove", "add", "update"]);
+  });
+
+  it("a git URL source matches its registered form", async () => {
+    writeRegistry({
+      mkt: {
+        source: {
+          source: "git",
+          url: "https://github.com/Owner/mkt.git",
+          ref: "v1",
+        },
+        installLocation: installDir(true),
+      },
+    });
+    const { calls, exec } = recorder();
+    await run(exec, [{ ...ROW, source: "https://github.com/owner/mkt" }]);
+    expect(calls).toEqual([["plugin", "marketplace", "update", "mkt"]]);
+  });
+
+  it("a baked dir of the same name suppresses the row with a warning", async () => {
+    const baked = join(testHome, "baked", "mkt");
+    const warn = spyOn(console, "warn").mockImplementation(() => {});
+    const { calls, exec } = recorder();
+    await run(exec, [ROW], [baked]);
+    expect(calls).toEqual([["plugin", "marketplace", "add", baked]]);
+    expect(warn.mock.calls.flat().join("\n")).toContain("baked marketplace");
+    warn.mockRestore();
+  });
+
+  it("warns on a manifest name mismatch", async () => {
+    // The CLI registers under the manifest name, not the row name.
+    writeRegistry({
+      actual: githubEntry("owner/mkt", "v1", installDir(true)),
+    });
+    const warn = spyOn(console, "warn").mockImplementation(() => {});
+    const { exec } = recorder();
+    await run(exec, [ROW]);
+    expect(warn.mock.calls.flat().join("\n")).toContain("named actual");
+    warn.mockRestore();
+  });
+
+  it("failed add, remove and update warn and boot continues", async () => {
+    writeRegistry({ mkt: githubEntry("owner/mkt", "v0", installDir(true)) });
+    const warn = spyOn(console, "warn").mockImplementation(() => {});
+    const { calls, exec } = recorder((args) =>
+      args[0] === "plugin" && args[1] === "marketplace" ? 1 : 0,
+    );
+    await run(exec, [ROW], NO_EXTRA_MARKETPLACES, [SHIPWRIGHT_ROW]);
+    const text = warn.mock.calls.flat().join("\n");
+    expect(text).toContain("marketplace remove mkt exited 1");
+    expect(text).toContain("marketplace add owner/mkt#v1 exited 1");
+    expect(text).toContain("marketplace update mkt exited 1");
+    expect(calls.at(-1)).toEqual(["plugin", "update", "shipwright@shipwright"]);
+    warn.mockRestore();
+  });
+
+  it("never removes registrations the agent does not manage", async () => {
+    writeRegistry({
+      unmanaged: githubEntry("x/y", undefined, installDir(false)),
+      mkt: githubEntry("owner/mkt", "v1", installDir(true)),
+    });
+    const { calls, exec } = recorder();
+    await run(exec, [ROW]);
+    expect(calls.some((c) => c.includes("unmanaged"))).toBe(false);
+    expect(calls.some((c) => c[2] === "remove")).toBe(false);
+  });
+
+  it("keeps the baked stale-registration heal working alongside rows", async () => {
+    const baked = join(testHome, "baked", "heal-mkt");
+    writeRegistry({
+      "heal-mkt": {
+        source: { source: "directory", path: "/nonexistent-app" },
+        installLocation: "/nonexistent-app",
+      },
+    });
+    const { calls, exec } = recorder();
+    await run(exec, [ROW], [baked]);
+    expect(calls.slice(0, 2)).toEqual([
+      ["plugin", "marketplace", "remove", "heal-mkt"],
+      ["plugin", "marketplace", "add", baked],
+    ]);
+  });
+
+  it("two consecutive boots are idempotent", async () => {
+    // Fake CLI that persists registrations the way `claude` does.
+    const cliExec = async (_cmd: string, args: string[]) => {
+      const [, sub, action, target] = args;
+      if (sub === "marketplace") {
+        const reg = existsSync(registryPath())
+          ? JSON.parse(readFileSync(registryPath(), "utf8"))
+          : {};
+        if (action === "add" && target?.startsWith("owner/")) {
+          const [repo, ref] = target.split("#");
+          reg.mkt = githubEntry(repo, ref, installDir(true));
+        } else if (action === "remove") {
+          delete reg[target as string];
+        }
+        writeFileSync(registryPath(), JSON.stringify(reg));
+      }
+      return { stdout: "", exitCode: 0 };
+    };
+    const firstCalls: string[][] = [];
+    const secondCalls: string[][] = [];
+    await run(async (c, a) => (firstCalls.push(a), cliExec(c, a)), [ROW]);
+    await run(async (c, a) => (secondCalls.push(a), cliExec(c, a)), [ROW]);
+    expect(firstCalls.map((c) => c[2])).toEqual(["add", "update"]);
+    expect(secondCalls).toEqual([["plugin", "marketplace", "update", "mkt"]]);
+  });
+});

package/setup.ts

@@ -382,30 +382,168 @@ export function findStalePluginSpecs(
   });
 }
 
+/** A remote marketplace row from the agent config bundle. */
+export interface RemoteMarketplace {
+  name: string;
+  source: string;
+  ref?: string | null;
+}
+
+/** Name of the built-in marketplace: its manifest name, else `shipwright`. */
+function builtinMarketplaceName(repoRoot: string): string {
+  try {
+    const manifest = JSON.parse(
+      readFileSync(
+        join(repoRoot, ".claude-plugin", "marketplace.json"),
+        "utf8",
+      ),
+    );
+    if (typeof manifest?.name === "string") return manifest.name;
+  } catch {}
+  return "shipwright";
+}
+
+interface RegisteredMarketplace {
+  source?: { repo?: unknown; url?: unknown; path?: unknown; ref?: unknown };
+  installLocation?: unknown;
+}
+
 /**
  * Reads the Claude CLI's known-marketplaces registry
- * (`known_marketplaces.json`, a sibling of `installed_plugins.json`) and
- * returns the install location it records for `name`. Defensive: returns
- * `undefined` for a missing or unparsable registry or an unknown name, and
+ * (`known_marketplaces.json`, a sibling of `installed_plugins.json`).
+ * Defensive: returns an empty registry for a missing or unparsable file, and
  * warns when the file exists but cannot be read.
  */
-function readRegisteredMarketplaceLocation(
+function readMarketplaceRegistry(
   registryPath: string,
-  name: string,
-): string | undefined {
-  if (!existsSync(registryPath)) return undefined;
+): Record<string, RegisteredMarketplace | null> {
+  if (!existsSync(registryPath)) return {};
   try {
-    const registry = JSON.parse(readFileSync(registryPath, "utf8")) as Record<
-      string,
-      { installLocation?: unknown } | null
-    >;
-    const location = registry?.[name]?.installLocation;
-    return typeof location === "string" ? location : undefined;
+    const registry = JSON.parse(readFileSync(registryPath, "utf8"));
+    return registry && typeof registry === "object" ? registry : {};
   } catch (err) {
     console.warn(
       `[agent] could not read ${registryPath} (nothing to heal): ${(err as Error).message}`,
     );
-    return undefined;
+    return {};
+  }
+}
+
+/** The install location the registry records for `name`, if any. */
+function readRegisteredMarketplaceLocation(
+  registryPath: string,
+  name: string,
+): string | undefined {
+  const location = readMarketplaceRegistry(registryPath)[name]?.installLocation;
+  return typeof location === "string" ? location : undefined;
+}
+
+/** Normalises a marketplace source (`owner/repo` or git URL) for comparison. */
+function normalizeMarketplaceSource(source: string): string {
+  return source
+    .trim()
+    .replace(/^https:\/\/github\.com\//i, "")
+    .replace(/\/+$/, "")
+    .replace(/\.git$/i, "")
+    .toLowerCase();
+}
+
+/** Whether a registry entry was added from the same source and ref as `row`. */
+function registeredMatchesRow(
+  entry: RegisteredMarketplace | null | undefined,
+  row: RemoteMarketplace,
+): boolean {
+  const src = entry?.source;
+  const registeredSource = [src?.repo, src?.url, src?.path].find(
+    (v): v is string => typeof v === "string",
+  );
+  if (registeredSource === undefined) return false;
+  const registeredRef = typeof src?.ref === "string" ? src.ref : null;
+  return (
+    normalizeMarketplaceSource(registeredSource) ===
+      normalizeMarketplaceSource(row.source) &&
+    registeredRef === (row.ref ?? null)
+  );
+}
+
+/** Runs `claude plugin marketplace <args>`; a non-zero exit warns, never throws. */
+async function runMarketplaceCommand(
+  execFn: ExecFn,
+  cwd: string,
+  args: string[],
+): Promise<boolean> {
+  const result = await execFn("claude", ["plugin", "marketplace", ...args], {
+    cwd,
+  });
+  if (result.exitCode !== 0) {
+    console.warn(
+      `[agent] claude plugin marketplace ${args.join(" ")} exited ${result.exitCode}: ${result.stdout}`,
+    );
+  }
+  return result.exitCode === 0;
+}
+
+/**
+ * Reconciles one remote marketplace row (from the agent config bundle) to its
+ * desired state, then updates it:
+ *   1. a baked/built-in marketplace of the same name wins (warn, skip)
+ *   2. registered with another source/ref, or with an installLocation that has
+ *      no marketplace.json -> remove first
+ *   3. not registered -> add `<source>[#ref]`
+ *   4. update
+ * Only the row's own name is ever touched. Failures warn and continue.
+ */
+async function reconcileRemoteMarketplace(
+  row: RemoteMarketplace,
+  managedLocalNames: Set<string>,
+  registryPath: string,
+  execFn: ExecFn,
+  cwd: string,
+): Promise<void> {
+  if (managedLocalNames.has(row.name)) {
+    console.warn(
+      `[agent] remote marketplace ${row.name} ignored: a baked marketplace with the same name takes precedence`,
+    );
+    return;
+  }
+
+  const entry = readMarketplaceRegistry(registryPath)[row.name];
+  let registered = entry !== undefined && entry !== null;
+  if (registered) {
+    const location =
+      typeof entry?.installLocation === "string"
+        ? entry.installLocation
+        : undefined;
+    const dangling =
+      location === undefined ||
+      !existsSync(join(location, ".claude-plugin", "marketplace.json"));
+    if (dangling || !registeredMatchesRow(entry, row)) {
+      console.log(
+        `[agent] marketplace ${row.name} is registered with a different source/ref or no marketplace.json — removing before re-adding ${row.source}`,
+      );
+      await runMarketplaceCommand(execFn, cwd, ["remove", row.name]);
+      registered = false;
+    }
+  }
+
+  if (!registered) {
+    const spec = row.ref ? `${row.source}#${row.ref}` : row.source;
+    await runMarketplaceCommand(execFn, cwd, ["add", spec]);
+  }
+  await runMarketplaceCommand(execFn, cwd, ["update", row.name]);
+
+  // The CLI registers a marketplace under its manifest name, so a mismatch
+  // leaves the registry without an entry for the row's name.
+  const after = readMarketplaceRegistry(registryPath);
+  if (after[row.name] === undefined) {
+    const actual = Object.entries(after).find(([, e]) =>
+      registeredMatchesRow(e, row),
+    )?.[0];
+    if (actual !== undefined) {
+      console.warn(
+        `[agent] remote marketplace row ${row.name} cloned a manifest named ${actual} — plugin specs must use @${actual}`,
+      );
+    }
   }
 }
 
@@ -446,6 +584,7 @@ export async function installPlugins(
   extraMarketplaceDirs?: string[],
   extraMarketplacesRoot: string = BAKED_MARKETPLACES_ROOT,
   env: Record<string, string | undefined> = process.env,
+  remoteMarketplaces: RemoteMarketplace[] = [],
 ): Promise<void> {
   const shipwrightRepoRoot =
     shipwrightRepoRootOverride ?? resolveShipwrightRepoRoot(env);
@@ -477,16 +616,7 @@ export async function installPlugins(
         console.log(
           `[agent] marketplace ${name} is registered at ${registered} with no marketplace.json — removing before re-adding ${dir}`,
         );
-        const remove = await execFn(
-          "claude",
-          ["plugin", "marketplace", "remove", name],
-          { cwd },
-        );
-        if (remove.exitCode !== 0) {
-          console.warn(
-            `[agent] claude plugin marketplace remove ${name} exited ${remove.exitCode}: ${remove.stdout}`,
-          );
-        }
+        await runMarketplaceCommand(execFn, cwd, ["remove", name]);
       }
       const extraAdd = await execFn(
         "claude",
@@ -526,6 +656,21 @@ export async function installPlugins(
       }
     }
 
+    // Reconcile remote marketplaces (config bundle rows) after every local one
+    // is registered, before any plugin install.
+    const managedLocalNames = new Set(extraDirs.map((dir) => basename(dir)));
+    if (hasRepoMarketplace)
+      managedLocalNames.add(builtinMarketplaceName(shipwrightRepoRoot));
+    for (const row of remoteMarketplaces) {
+      await reconcileRemoteMarketplace(
+        row,
+        managedLocalNames,
+        registryPath,
+        execFn,
+        cwd,
+      );
+    }
+
     const allSpecs = agentPlugins.map((p) => `${p.plugin}@${p.marketplace}`);
 
     // Uninstall any plugin whose recorded installPath no longer exists. This