@pi-harness/pi-harness 0.1.30 → 0.1.32

package/packages/api-gateway/src/marketplace.ts

@@ -29,6 +29,8 @@ export interface MarketplaceStatistics {
 export type MarketplaceStatisticsFetcher = (url: string, init?: RequestInit) => Promise<Response>;
 
 export interface MarketplaceStatisticsLoaderOptions {
+  readonly concurrency?: number;
+  readonly failureMaxTtlMs?: number;
   readonly failureTtlMs?: number;
   readonly fetcher?: MarketplaceStatisticsFetcher;
   readonly now?: () => number;
@@ -36,6 +38,18 @@ export interface MarketplaceStatisticsLoaderOptions {
   readonly ttlMs?: number;
 }
 
+export interface MarketplaceCachedStatistics {
+  /** False until every catalogued package has been looked up once. A caller that reorders on statistics uses this to reorder once, when the set is complete, rather than on every poll while the background warm-up trickles in. */
+  readonly ready: boolean;
+  readonly statistics: ReadonlyMap<string, MarketplaceStatistics>;
+}
+
+export interface MarketplaceStatisticsLoader {
+  (plugins: readonly MarketplacePlugin[]): Promise<ReadonlyMap<string, MarketplaceStatistics>>;
+  // Returns only what is already cached and warms the misses in the background, so a request never waits on the npm registry.
+  readonly readCached: (plugins: readonly MarketplacePlugin[]) => MarketplaceCachedStatistics;
+}
+
 interface NpmPackageStatisticsResult {
   readonly failed: boolean;
   readonly statistics?: MarketplaceStatistics;
@@ -55,6 +69,36 @@ export interface MarketplaceCategory {
   readonly count: number;
 }
 
+export interface MarketplaceCapability {
+  readonly id: string;
+  readonly label: string;
+  readonly count: number;
+}
+
+/** What a plugin does to the machine it is installed on, ordered from the least invasive to the most, so a reader can decide from the badges alone. This replaced free text, which produced 299 values across 78 entries with 284 of them held by a single plugin: the filter listed nearly one option per plugin and nothing could be compared against anything else. Every value here is derived from the plugin's own imports, including those it inherits from a plugin it depends on. */
+const MARKETPLACE_CAPABILITY_VOCABULARY: readonly { readonly id: string; readonly label: string }[] = [
+  { id: "read-only", label: "只读运行" },
+  { id: "session-data", label: "读取会话内容" },
+  { id: "reads-files", label: "读取本机文件" },
+  { id: "writes-files", label: "写入本机文件" },
+  { id: "runs-commands", label: "执行本机命令" },
+  { id: "local-server", label: "监听本地端口" },
+  { id: "network-access", label: "访问网络" },
+  { id: "model-calls", label: "额外调用模型" },
+];
+
+/** A badge that says a plugin changes nothing is a claim about trust, so an entry that also carries one of these is rejected rather than shown. */
+const MARKETPLACE_EFFECT_CAPABILITIES: readonly string[] = ["writes-files", "runs-commands", "local-server", "network-access", "model-calls"];
+
+const marketplaceCapabilityLabels = new Map(MARKETPLACE_CAPABILITY_VOCABULARY.map((capability) => [capability.id, capability.label]));
+
+function isMarketplaceCapabilityList(value: unknown): value is readonly string[] {
+  if (!Array.isArray(value) || value.length === 0) return false;
+  const capabilities = value.filter((entry): entry is string => typeof entry === "string" && marketplaceCapabilityLabels.has(entry));
+  if (capabilities.length !== value.length || new Set(capabilities).size !== capabilities.length) return false;
+  return !capabilities.includes("read-only") || !capabilities.some((entry) => MARKETPLACE_EFFECT_CAPABILITIES.includes(entry));
+}
+
 const npmPackagePattern = /^(?:@[a-z0-9._~-]+\/)?[a-z0-9._~-]+(?:\/[a-z0-9._~-]+)*$/;
 const entryIdPattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const versionPattern = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
@@ -92,9 +136,7 @@ function isMarketplacePlugin(value: unknown): value is MarketplacePlugin {
     categoryIdPattern.test(category.id) &&
     typeof category.label === "string" &&
     category.label.trim() !== "" &&
-    Array.isArray(value.capabilities) &&
-    value.capabilities.length > 0 &&
-    value.capabilities.every((entry) => typeof entry === "string" && entry.trim() !== "") &&
+    isMarketplaceCapabilityList(value.capabilities) &&
     Array.isArray(value.hooks) &&
     value.hooks.length > 0 &&
     value.hooks.every((entry) => typeof entry === "string" && entry.trim() !== "") &&
@@ -129,11 +171,17 @@ function loadMarketplacePlugins(): readonly MarketplacePlugin[] {
     });
   const ids = new Set<string>();
   const packages = new Set<string>();
+  // The category tabs are built from whichever entry is read first, so two entries that spell the same category differently would make the label depend on file order.
+  const categoryLabels = new Map<string, string>();
   for (const plugin of plugins) {
     if (ids.has(plugin.id)) throw new Error(`Duplicate marketplace id: ${plugin.id}`);
     if (packages.has(plugin.packageName)) throw new Error(`Duplicate marketplace package: ${plugin.packageName}`);
+    const categoryLabel = categoryLabels.get(plugin.category.id);
+    if (categoryLabel !== undefined && categoryLabel !== plugin.category.label)
+      throw new Error(`Conflicting marketplace category label for ${plugin.category.id}: ${categoryLabel} and ${plugin.category.label}`);
     ids.add(plugin.id);
     packages.add(plugin.packageName);
+    categoryLabels.set(plugin.category.id, plugin.category.label);
   }
   return plugins;
 }
@@ -199,35 +247,82 @@ async function fetchNpmPackageStatistics(packageName: string, fetcher: Marketpla
   return { failed, statistics };
 }
 
-export function createMarketplaceStatisticsLoader(options: MarketplaceStatisticsLoaderOptions = {}) {
+export function createMarketplaceStatisticsLoader(options: MarketplaceStatisticsLoaderOptions = {}): MarketplaceStatisticsLoader {
   const fetcher = options.fetcher ?? ((url: string, init?: RequestInit) => globalThis.fetch(url, init));
   const failureTtlMs = options.failureTtlMs ?? 60_000;
+  // Consecutive failures double the retry window up to this ceiling: an open console polls the catalog every few seconds, so a flat failure window would send one registry lookup per catalogued package every minute for as long as the tab stays open.
+  const failureMaxTtlMs = options.failureMaxTtlMs ?? 30 * 60_000;
   const now = options.now ?? Date.now;
   const timeoutMs = options.timeoutMs ?? 3_000;
   const ttlMs = options.ttlMs ?? 6 * 60 * 60 * 1_000;
-  const cache = new Map<string, { readonly expiresAt: number; readonly result: NpmPackageStatisticsResult }>();
+  // The registry answers an unthrottled fan-out over the whole catalogue with 429s, so lookups queue behind a small number of slots instead of leaving at once.
+  const concurrency = Math.max(1, Math.trunc(options.concurrency ?? 4));
+  const cache = new Map<string, { readonly expiresAt: number; readonly failures: number; readonly result: NpmPackageStatisticsResult }>();
   const inFlight = new Map<string, Promise<NpmPackageStatisticsResult>>();
+  const waiting: (() => void)[] = [];
+  let active = 0;
+  const acquireSlot = async (): Promise<void> => {
+    if (active < concurrency) {
+      active += 1;
+      return;
+    }
+    await new Promise<void>((resolveSlot) => waiting.push(resolveSlot));
+  };
+  const releaseSlot = (): void => {
+    const next = waiting.shift();
+    if (next === undefined) active -= 1;
+    else next();
+  };
+  const failureTtl = (failures: number): number => Math.min(failureTtlMs * 2 ** Math.min(failures - 1, 20), failureMaxTtlMs);
   const loadPackage = async (packageName: string): Promise<NpmPackageStatisticsResult> => {
     const timestamp = now();
     const cached = cache.get(packageName);
     if (cached !== undefined && cached.expiresAt > timestamp) return cached.result;
     const pending = inFlight.get(packageName);
     if (pending !== undefined) return pending;
-    const request = fetchNpmPackageStatistics(packageName, fetcher, timeoutMs);
+    // The slot is taken inside the promise so the in-flight entry is still registered synchronously and concurrent callers keep sharing one request.
+    const request = (async () => {
+      await acquireSlot();
+      try {
+        return await fetchNpmPackageStatistics(packageName, fetcher, timeoutMs);
+      } finally {
+        releaseSlot();
+      }
+    })();
     inFlight.set(packageName, request);
     try {
       const result = await request;
-      cache.set(packageName, { expiresAt: now() + (result.failed ? failureTtlMs : ttlMs), result });
+      const failures = result.failed ? (cached?.failures ?? 0) + 1 : 0;
+      cache.set(packageName, { expiresAt: now() + (result.failed ? failureTtl(failures) : ttlMs), failures, result });
       return result;
     } finally {
       if (inFlight.get(packageName) === request) inFlight.delete(packageName);
     }
   };
-  return async (plugins: readonly MarketplacePlugin[]): Promise<ReadonlyMap<string, MarketplaceStatistics>> => {
-    const packageNames = [...new Set(plugins.map((plugin) => marketplaceNpmPackageName(plugin.packageName)))].sort();
-    const entries = await Promise.all(packageNames.map(async (packageName) => [packageName, await loadPackage(packageName)] as const));
+  const packageNames = (plugins: readonly MarketplacePlugin[]): readonly string[] =>
+    [...new Set(plugins.map((plugin) => marketplaceNpmPackageName(plugin.packageName)))].sort();
+  const load = async (plugins: readonly MarketplacePlugin[]): Promise<ReadonlyMap<string, MarketplaceStatistics>> => {
+    const entries = await Promise.all(packageNames(plugins).map(async (packageName) => [packageName, await loadPackage(packageName)] as const));
     return new Map(entries.flatMap(([packageName, result]) => (result.statistics === undefined ? [] : [[packageName, result.statistics] as const])));
   };
+  const readCached = (plugins: readonly MarketplacePlugin[]): MarketplaceCachedStatistics => {
+    const timestamp = now();
+    const statistics = new Map<string, MarketplaceStatistics>();
+    // Readiness tracks whether a package has ever been looked up, not whether its entry is fresh, so an expiring entry refreshes in the background without dropping the catalogue back to an unsorted order.
+    let ready = true;
+    for (const packageName of packageNames(plugins)) {
+      const cached = cache.get(packageName);
+      if (cached === undefined) ready = false;
+      if (cached !== undefined && cached.expiresAt > timestamp) {
+        if (cached.result.statistics !== undefined) statistics.set(packageName, cached.result.statistics);
+        continue;
+      }
+      // A prewarm has nobody to report to, and a catalogue sorted without npm statistics is not worth crashing the process over an unhandled rejection.
+      void loadPackage(packageName).catch(() => {});
+    }
+    return { ready, statistics };
+  };
+  return Object.assign(load, { readCached });
 }
 
 export function attachMarketplaceStatistics(
@@ -259,7 +354,9 @@ export function searchMarketplace(query = "", capability = "", category = ""): r
   const normalizedCapability = capability.trim().toLowerCase();
   const normalizedCategory = category.trim().toLowerCase();
   return MARKETPLACE_PLUGINS.filter((plugin) => {
-    const searchable = [plugin.name, plugin.packageName, plugin.description, plugin.author, ...plugin.capabilities, ...plugin.hooks].join(" ").toLowerCase();
+    // The capability labels are searched alongside their ids: the ids are what the filter and the URL carry, and the labels are what the reader sees on the card.
+    const capabilities = plugin.capabilities.flatMap((item) => [item, marketplaceCapabilityLabels.get(item) ?? item]);
+    const searchable = [plugin.name, plugin.packageName, plugin.description, plugin.author, ...capabilities, ...plugin.hooks].join(" ").toLowerCase();
     return (
       (normalizedQuery === "" || searchable.includes(normalizedQuery)) &&
       (normalizedCapability === "" || plugin.capabilities.some((item) => item.toLowerCase() === normalizedCapability)) &&
@@ -281,7 +378,11 @@ export function paginateMarketplace(items: readonly MarketplacePlugin[], page =
   };
 }
 
-export const MARKETPLACE_CAPABILITIES = [...new Set(MARKETPLACE_PLUGINS.flatMap((plugin) => plugin.capabilities))].sort();
+// Kept in vocabulary order rather than sorted, so the filter reads from the least invasive option to the most, and an unused capability is left out rather than offering a filter that returns nothing.
+export const MARKETPLACE_CAPABILITIES: readonly MarketplaceCapability[] = MARKETPLACE_CAPABILITY_VOCABULARY.map((capability) => ({
+  ...capability,
+  count: MARKETPLACE_PLUGINS.filter((plugin) => plugin.capabilities.includes(capability.id)).length,
+})).filter((capability) => capability.count > 0);
 export const MARKETPLACE_CATEGORIES: readonly MarketplaceCategory[] = [
   ...new Map(MARKETPLACE_PLUGINS.map((plugin) => [plugin.category.id, { id: plugin.category.id, label: plugin.category.label, count: 0 }])).values(),
 ]

package/packages/api-gateway/test/index.test.ts

@@ -10,7 +10,7 @@ import timerPlugin from "@deepseek-ai/cordis-plugin-timer";
 import { SessionManager } from "@earendil-works/pi-coding-agent";
 import { afterEach, describe, expect, test, vi } from "vitest";
 import webServerPlugin from "@pi-harness/host-webserver";
-import { PiPluginUiRegistry, PiToolRegistry } from "@pi-harness/core";
+import { PiPluginUiRegistry, PiToolRegistry, PiToolRegistryLeasedError } from "@pi-harness/core";
 import type { MarketplacePlugin } from "../src/marketplace.js";
 import apiPlugin from "../src/index.js";
 import type * as FsPromises from "node:fs/promises";
@@ -2122,11 +2122,11 @@ describe("API gateway plugin", () => {
     context.provide("piHarnessLaunch", { cwd: "/tmp", agentDir: "/tmp/agent", args: [], requestExit() {} });
     await context.plugin(apiPlugin);
 
-    const response = await fetch(context.webServer.url + "/api/marketplace?q=timer&capability=scheduling&category=runtime&page=0&pageSize=1");
+    const response = await fetch(context.webServer.url + "/api/marketplace?q=timer&capability=read-only&category=runtime&page=0&pageSize=1");
     expect(response.status).toBe(200);
     const payload = (await response.json()) as {
       items?: readonly { packageName?: unknown; status?: unknown }[];
-      capabilities?: readonly unknown[];
+      capabilities?: readonly { id?: unknown; label?: unknown; count?: unknown }[];
       categories?: readonly { id?: unknown; label?: unknown; count?: unknown }[];
       total?: number;
       page?: number;
@@ -2136,7 +2136,7 @@ describe("API gateway plugin", () => {
     expect(payload.items).toHaveLength(1);
     expect(payload.items?.[0]).toMatchObject({ packageName: "@deepseek-ai/cordis-plugin-timer", status: "verified" });
     expect(payload).toMatchObject({ total: 1, page: 0, pageSize: 1, hasNext: false });
-    expect(payload.capabilities).toContain("scheduling");
+    expect(payload.capabilities).toEqual(expect.arrayContaining([expect.objectContaining({ id: "read-only", label: "只读运行" })]));
     expect(payload.categories).toEqual(expect.arrayContaining([expect.objectContaining({ id: "runtime", label: "运行时", count: 1 })]));
     const tooLong = await fetch(context.webServer.url + "/api/marketplace?q=" + "x".repeat(121));
     expect(tooLong.status).toBe(400);
@@ -2146,6 +2146,89 @@ describe("API gateway plugin", () => {
     expect(invalidSort.status).toBe(400);
   });
 
+  // The console renders nothing until every one of its startup requests has answered, so the recommended sort is served from the npm statistics already cached and the misses are warmed behind the response. A registry that never answers must cost the page nothing.
+  test("answers the recommended marketplace sort while the npm registry never replies", async () => {
+    const context = new Context();
+    contexts.push(context);
+    await context.plugin(webServerPlugin, { host: "127.0.0.1", port: 0 });
+    const session = { sessionId: "marketplace-sort-session", sessionFile: undefined, messages: [], isStreaming: false, subscribe: () => () => {} };
+    context.provide("piRuntime", { session, prompt: () => Promise.resolve(), abort: () => Promise.resolve(), dispose: () => Promise.resolve() } as never);
+    context.provide("piModels", { model: { provider: "test", id: "model" }, runtime: { getModels: () => [], getModel: () => undefined } } as never);
+    context.provide("piHarnessLaunch", { cwd: "/tmp", agentDir: "/tmp/agent", args: [], requestExit() {} });
+    await context.plugin(apiPlugin);
+    const originalFetch = globalThis.fetch;
+    const registryRequests: string[] = [];
+    globalThis.fetch = (input: RequestInfo | URL, init?: RequestInit) => {
+      const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+      if (url.startsWith("https://registry.npmjs.org/") || url.startsWith("https://api.npmjs.org/")) {
+        registryRequests.push(url);
+        return new Promise<Response>(() => {});
+      }
+      return originalFetch(input, init);
+    };
+    try {
+      const response = await fetch(context.webServer.url + "/api/marketplace?sort=recommended&pageSize=2");
+
+      expect(response.status).toBe(200);
+      const payload = (await response.json()) as { items?: readonly unknown[]; page?: number; pageSize?: number };
+      expect(payload.items).toHaveLength(2);
+      expect(payload).toMatchObject({ page: 0, pageSize: 2 });
+      // The background prewarm queues behind a handful of slots instead of asking the registry about every catalogued package at once.
+      await vi.waitFor(() => expect(registryRequests.length).toBeGreaterThan(0));
+      expect(registryRequests.length).toBeLessThanOrEqual(4);
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  // The message goes straight to a console user who clicked a button, so it reads as npm's own report; the command line stays on the error cause for the log.
+  test("reports a failed plugin install in npm's own words without the command line", async () => {
+    const directory = await mkdtemp(join(tmpdir(), "pi-harness-api-plugin-install-failure-"));
+    temporaryDirectories.push(directory);
+    const shimDirectory = join(directory, "bin");
+    await mkdir(shimDirectory);
+    await writeFile(join(directory, "package.json"), '{ "name": "harness" }\n', "utf8");
+    const configPath = join(directory, "profile.yml");
+    const profileBefore = '- id: runtime\n  name: "@pi-harness/core/plugins/runtime"\n  config: {}\n';
+    await writeFile(configPath, profileBefore, "utf8");
+    await writeFile(
+      join(shimDirectory, "npm"),
+      "#!/bin/sh\nprintf 'npm error code E404\\nnpm error 404 Not Found - GET https://registry.npmjs.org/@pi-harness/plugin-skill-guard\\nnpm error 404 The package is not in the npm registry\\nnpm error A complete log of this run can be found in: /tmp/npm-debug.log\\n' >&2\nexit 1\n",
+      { mode: 0o755 },
+    );
+    const context = new Context();
+    contexts.push(context);
+    await context.plugin(webServerPlugin, { host: "127.0.0.1", port: 0 });
+    const session = { sessionId: "install-failure-session", sessionFile: undefined, messages: [], isStreaming: false, subscribe: () => () => {} };
+    context.provide("piRuntime", { session, prompt: () => Promise.resolve(), abort: () => Promise.resolve(), dispose: () => Promise.resolve() } as never);
+    context.provide("piModels", { model: { provider: "test", id: "model" } } as never);
+    context.provide("piHarnessLaunch", { cwd: directory, agentDir: directory, configPath, args: [], requestExit() {} });
+    context.reflect.provide("loader", { entries: () => [], create: () => Promise.resolve("marketplace-entry"), remove: () => Promise.resolve() });
+    await context.plugin(apiPlugin);
+
+    const originalPath = process.env.PATH ?? "";
+    process.env.PATH = `${shimDirectory}:${originalPath}`;
+    let response: Response;
+    try {
+      response = await fetch(context.webServer.url + "/api/marketplace/install", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ id: "skill-guard" }),
+      });
+    } finally {
+      process.env.PATH = originalPath;
+    }
+
+    expect(response.status).toBe(502);
+    const payload = (await response.json()) as { error?: string };
+    expect(payload.error).toBe(
+      "npm error code E404 npm error 404 Not Found - GET https://registry.npmjs.org/@pi-harness/plugin-skill-guard npm error 404 The package is not in the npm registry",
+    );
+    expect(payload.error).not.toContain("--save-exact");
+    expect(payload.error).not.toContain("npm-debug.log");
+    await expect(readFile(configPath, "utf8")).resolves.toBe(profileBefore);
+  });
+
   // An official plugin is its own npm package, so it takes the same install path a community package takes: npm first, then the profile row, then the loader entry. Nothing about `source: "official"` shortcuts any of it.
   test("installs an official plugin through npm exactly like a community package", async () => {
     const directory = await mkdtemp(join(tmpdir(), "pi-harness-api-plugin-install-"));
@@ -2190,12 +2273,167 @@ describe("API gateway plugin", () => {
     }
 
     expect(response.status).toBe(200);
-    await expect(response.json()).resolves.toMatchObject({ installed: true, plugin: { id: "skill-guard" } });
+    await expect(response.json()).resolves.toMatchObject({ installed: true, restartRequired: false, plugin: { id: "skill-guard" } });
     expect((await readFile(npmLog, "utf8")).trim()).toMatch(/^install --save-exact --package-lock=false @pi-harness\/plugin-skill-guard@\d/u);
     expect(created).toEqual([expect.objectContaining({ name: "@pi-harness/plugin-skill-guard" })]);
     await expect(readFile(configPath, "utf8")).resolves.toContain('name: "@pi-harness/plugin-skill-guard"');
   });
 
+  // A plugin registers its tools while it activates, and pi-runtime takes the tool registry when it activates, so an installed entry only works if it sits ahead of the runtime inside the runtime's own group.
+  test("installs a marketplace plugin into the runtime's group ahead of the runtime", async () => {
+    const directory = await mkdtemp(join(tmpdir(), "pi-harness-api-plugin-placement-"));
+    temporaryDirectories.push(directory);
+    const shimDirectory = join(directory, "bin");
+    await mkdir(shimDirectory);
+    await writeFile(join(directory, "package.json"), '{ "name": "harness" }\n', "utf8");
+    const configPath = join(directory, "profile.yml");
+    await writeFile(
+      configPath,
+      '- id: agent\n  name: cordis:group\n  group: true\n  config:\n    - id: tools\n      name: "@pi-harness/core/plugins/tools"\n      config: {}\n    - id: runtime\n      name: "@pi-harness/core/plugins/runtime"\n      config: {}\n',
+      "utf8",
+    );
+    await writeFile(join(shimDirectory, "npm"), "#!/bin/sh\nexit 0\n", { mode: 0o755 });
+    const context = new Context();
+    contexts.push(context);
+    await context.plugin(webServerPlugin, { host: "127.0.0.1", port: 0 });
+    const session = { sessionId: "marketplace-placement-session", sessionFile: undefined, messages: [], isStreaming: false, subscribe: () => () => {} };
+    context.provide("piRuntime", { session, prompt: () => Promise.resolve(), abort: () => Promise.resolve(), dispose: () => Promise.resolve() } as never);
+    context.provide("piModels", { model: { provider: "test", id: "model" } } as never);
+    context.provide("piHarnessLaunch", { cwd: directory, agentDir: directory, configPath, args: [], requestExit() {} });
+    const runtimeOptions = { id: "runtime", name: "@pi-harness/core/plugins/runtime", config: {} };
+    const runtimeGroup = { data: [{ id: "tools", name: "@pi-harness/core/plugins/tools", config: {} }, runtimeOptions] };
+    const loaderEntries = [
+      // The loader addresses a nested group by its qualified id, while the profile file names the same entry by its own id.
+      { id: "profile:agent", options: { id: "agent", name: "cordis:group" }, subgroup: runtimeGroup },
+      { id: "profile:runtime", options: runtimeOptions, parent: runtimeGroup },
+    ];
+    const created: Array<[unknown, unknown, unknown]> = [];
+    context.reflect.provide("loader", {
+      entries: () => loaderEntries,
+      create: (options: unknown, parent: unknown, position: unknown) => {
+        created.push([options, parent, position]);
+        return Promise.resolve("marketplace-entry");
+      },
+      resolve: () => ({ fiber: { await: () => Promise.resolve() } }),
+      remove: () => Promise.resolve(),
+    });
+    await context.plugin(apiPlugin);
+
+    const originalPath = process.env.PATH ?? "";
+    process.env.PATH = `${shimDirectory}:${originalPath}`;
+    let response: Response;
+    try {
+      response = await fetch(context.webServer.url + "/api/marketplace/install", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ id: "skill-guard" }),
+      });
+    } finally {
+      process.env.PATH = originalPath;
+    }
+
+    expect(response.status).toBe(200);
+    await expect(response.json()).resolves.toMatchObject({ installed: true, restartRequired: false });
+    expect(created).toEqual([[expect.objectContaining({ id: "marketplace-skill-guard", name: "@pi-harness/plugin-skill-guard" }), "profile:agent", 1]]);
+    await expect(readFile(configPath, "utf8")).resolves.toBe(
+      '- id: agent\n  name: cordis:group\n  group: true\n  config:\n    - id: tools\n      name: "@pi-harness/core/plugins/tools"\n      config: {}\n    - id: marketplace-skill-guard\n      name: "@pi-harness/plugin-skill-guard"\n      config: {}\n    - id: runtime\n      name: "@pi-harness/core/plugins/runtime"\n      config: {}\n',
+    );
+  });
+
+  // The runtime snapshots the tool set when it takes the registry, so a plugin that contributes tools cannot join a harness that is already running. Rolling the install back would leave the user unable to install it at all, so the package and the profile row stay and the console asks for a restart.
+  test("keeps an installed plugin in place when the runtime already leased the tool registry", async () => {
+    const directory = await mkdtemp(join(tmpdir(), "pi-harness-api-plugin-leased-"));
+    temporaryDirectories.push(directory);
+    const shimDirectory = join(directory, "bin");
+    await mkdir(shimDirectory);
+    await writeFile(join(directory, "package.json"), '{ "name": "harness", "dependencies": {} }\n', "utf8");
+    const configPath = join(directory, "profile.yml");
+    await writeFile(configPath, '- id: runtime\n  name: "@pi-harness/core/plugins/runtime"\n  config: {}\n', "utf8");
+    await writeFile(join(shimDirectory, "npm"), "#!/bin/sh\nexit 0\n", { mode: 0o755 });
+    const context = new Context();
+    contexts.push(context);
+    await context.plugin(webServerPlugin, { host: "127.0.0.1", port: 0 });
+    const session = { sessionId: "marketplace-leased-session", sessionFile: undefined, messages: [], isStreaming: false, subscribe: () => () => {} };
+    context.provide("piRuntime", { session, prompt: () => Promise.resolve(), abort: () => Promise.resolve(), dispose: () => Promise.resolve() } as never);
+    context.provide("piModels", { model: { provider: "test", id: "model" } } as never);
+    context.provide("piHarnessLaunch", { cwd: directory, agentDir: directory, configPath, args: [], requestExit() {} });
+    const removed: string[] = [];
+    context.reflect.provide("loader", {
+      entries: () => [],
+      create: () => Promise.resolve("marketplace-entry"),
+      // The loader wraps an activation failure in its own error chain, which is what the gateway has to see through.
+      resolve: () => ({
+        fiber: {
+          await: () => Promise.reject(new Error("failed to apply loader entry", { cause: new PiToolRegistryLeasedError("skill_scan") })),
+        },
+      }),
+      remove: (id: string) => {
+        removed.push(id);
+        return Promise.resolve();
+      },
+    });
+    await context.plugin(apiPlugin);
+
+    const originalPath = process.env.PATH ?? "";
+    process.env.PATH = `${shimDirectory}:${originalPath}`;
+    let response: Response;
+    try {
+      response = await fetch(context.webServer.url + "/api/marketplace/install", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ id: "skill-guard" }),
+      });
+    } finally {
+      process.env.PATH = originalPath;
+    }
+
+    expect(response.status).toBe(200);
+    await expect(response.json()).resolves.toMatchObject({ installed: true, restartRequired: true, plugin: { id: "skill-guard" } });
+    expect(removed).toEqual(["marketplace-entry"]);
+    await expect(readFile(configPath, "utf8")).resolves.toContain('name: "@pi-harness/plugin-skill-guard"');
+    await expect(readFile(join(directory, "package.json"), "utf8")).resolves.toBe('{ "name": "harness", "dependencies": {} }\n');
+  });
+
+  // Reverting the profile here would leave a plugin that can be switched off but never on again, so the change stays and the plugin comes back on the next start.
+  test("keeps a re-enabled plugin enabled in the profile when the runtime already leased the tool registry", async () => {
+    const context = new Context();
+    contexts.push(context);
+    const directory = await mkdtemp(join(tmpdir(), "pi-harness-api-plugin-toggle-leased-"));
+    temporaryDirectories.push(directory);
+    const configPath = join(directory, "profile.yml");
+    const loaderEntry = {
+      id: "profile:marketplace-skill-guard",
+      options: { id: "marketplace-skill-guard", name: "@pi-harness/plugin-skill-guard", config: {} },
+      update: () => Promise.reject(new Error("failed to apply loader entry", { cause: new PiToolRegistryLeasedError("skill_scan") })),
+    };
+    await writeFile(
+      configPath,
+      '- id: marketplace-skill-guard\n  name: "@pi-harness/plugin-skill-guard"\n  disabled: true\n  config: {}\n- id: runtime\n  name: "@pi-harness/core/plugins/runtime"\n  config: {}\n',
+      "utf8",
+    );
+    await context.plugin(webServerPlugin, { host: "127.0.0.1", port: 0 });
+    const session = { sessionId: "plugin-toggle-leased-session", sessionFile: undefined, messages: [], isStreaming: false, subscribe: () => () => {} };
+    context.provide("piRuntime", { session, prompt: () => Promise.resolve(), abort: () => Promise.resolve(), dispose: () => Promise.resolve() } as never);
+    context.provide("piModels", { model: { provider: "test", id: "model" }, runtime: { getModels: () => [], getModel: () => undefined } } as never);
+    context.provide("piHarnessLaunch", { cwd: directory, agentDir: directory, configPath, args: [], requestExit() {} });
+    context.reflect.provide("loader", {
+      *entries() {
+        yield loaderEntry;
+      },
+    });
+    await context.plugin(apiPlugin);
+
+    const response = await fetch(context.webServer.url + "/api/plugins/toggle", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ id: "marketplace-skill-guard", enabled: true }),
+    });
+
+    expect(response.status).toBe(200);
+    await expect(response.json()).resolves.toMatchObject({ restartRequired: true, plugin: { id: "marketplace-skill-guard" } });
+    await expect(readFile(configPath, "utf8")).resolves.not.toContain("disabled: true");
+  });
+
   test("locks marketplace installation before reading a request body", async () => {
     const cwd = await mkdtemp(join(tmpdir(), "pi-harness-api-plugin-install-lock-"));
     temporaryDirectories.push(cwd);
@@ -2455,6 +2693,60 @@ describe("API gateway plugin", () => {
     await expect(readFile(configPath, "utf8")).resolves.toContain("- id: sibling");
   });
 
+  test("reports a failed plugin uninstall in npm's own words without the command line", async () => {
+    const context = new Context();
+    contexts.push(context);
+    const directory = await mkdtemp(join(tmpdir(), "pi-harness-api-uninstall-failure-"));
+    temporaryDirectories.push(directory);
+    const shimDirectory = join(directory, "bin");
+    await mkdir(shimDirectory);
+    await writeFile(join(directory, "package.json"), '{ "name": "harness" }\n', "utf8");
+    await writeFile(join(shimDirectory, "npm"), "#!/bin/sh\nprintf 'npm error code EACCES\\nnpm error syscall unlink\\n' >&2\nexit 1\n", { mode: 0o755 });
+    const configPath = join(directory, "profile.yml");
+    const entryId = "skill-guard";
+    const loaderEntry = {
+      id: `profile:${entryId}`,
+      options: { id: entryId, name: "@pi-harness/plugin-skill-guard", config: {} },
+      parent: { tree: { write() {} }, remove: () => Promise.resolve() },
+    };
+    const profileBefore = `- id: ${entryId}\n  name: ${JSON.stringify(loaderEntry.options.name)}\n  config: {}\n- id: sibling\n  name: "@pi-harness/core/plugins/runtime"\n  config: {}\n`;
+    await writeFile(configPath, profileBefore, "utf8");
+    await context.plugin(webServerPlugin, { host: "127.0.0.1", port: 0 });
+    const session = { sessionId: "uninstall-failure-session", sessionFile: undefined, messages: [], isStreaming: false, subscribe: () => () => {} };
+    context.provide("piRuntime", { session, prompt: () => Promise.resolve(), abort: () => Promise.resolve(), dispose: () => Promise.resolve() } as never);
+    context.provide("piModels", { model: { provider: "test", id: "model" }, runtime: { getModels: () => [], getModel: () => undefined } } as never);
+    context.provide("piHarnessLaunch", { cwd: directory, agentDir: directory, configPath, args: [], requestExit() {} });
+    const restored: unknown[] = [];
+    context.reflect.provide("loader", {
+      entries: () => [loaderEntry],
+      create: (options: unknown) => {
+        restored.push(options);
+        return Promise.resolve(`profile:${entryId}`);
+      },
+    });
+    await context.plugin(apiPlugin);
+
+    const originalPath = process.env.PATH ?? "";
+    process.env.PATH = `${shimDirectory}:${originalPath}`;
+    let response: Response;
+    try {
+      response = await fetch(context.webServer.url + "/api/plugins/uninstall", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ id: entryId }),
+      });
+    } finally {
+      process.env.PATH = originalPath;
+    }
+
+    expect(response.status).toBe(502);
+    const payload = (await response.json()) as { error?: string };
+    expect(payload.error).toBe("npm error code EACCES npm error syscall unlink");
+    expect(payload.error).not.toContain("--package-lock=false");
+    expect(restored).toEqual([expect.objectContaining({ id: entryId, name: "@pi-harness/plugin-skill-guard" })]);
+    await expect(readFile(configPath, "utf8")).resolves.toBe(profileBefore);
+  });
+
   test("commits selected workspace files only after an explicit message", async () => {
     const context = new Context();
     contexts.push(context);

package/packages/api-gateway/test/marketplace-schema.test.ts

@@ -31,6 +31,9 @@ const supportedKeywords = new Set([
   "if",
   "then",
   "else",
+  "allOf",
+  "contains",
+  "not",
 ]);
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -75,6 +78,8 @@ function validate(schema: Schema, value: unknown, path = "$"): string[] {
     if (typeof schema.minItems === "number" && value.length < schema.minItems) errors.push(`${path}: fewer than ${schema.minItems} items`);
     if (schema.uniqueItems === true && new Set(value.map((item) => JSON.stringify(item))).size !== value.length) errors.push(`${path}: items are not unique`);
     if (isRecord(schema.items)) value.forEach((item, index) => errors.push(...validate(schema.items as Schema, item, `${path}[${index}]`)));
+    if (isRecord(schema.contains) && !value.some((item) => validate(schema.contains as Schema, item, path).length === 0))
+      errors.push(`${path}: contains no item matching ${JSON.stringify(schema.contains)}`);
   }
   if (isRecord(value)) {
     const properties = isRecord(schema.properties) ? schema.properties : {};
@@ -91,6 +96,8 @@ function validate(schema: Schema, value: unknown, path = "$"): string[] {
     const branch = validate(schema.if, value, path).length === 0 ? schema.then : schema.else;
     if (isRecord(branch)) errors.push(...validate(branch, value, path));
   }
+  if (isRecord(schema.not) && validate(schema.not, value, path).length === 0) errors.push(`${path}: matches ${JSON.stringify(schema.not)}`);
+  if (Array.isArray(schema.allOf)) for (const branch of schema.allOf) if (isRecord(branch)) errors.push(...validate(branch, value, path));
   return errors;
 }
 
@@ -133,6 +140,11 @@ describe("marketplace entry schema", () => {
     expect(validate(schema, { ...validEntry(), profile: { name: "@pi-harness/plugin-agent-teams", config: [] } })).not.toEqual([]);
     expect(validate(schema, { ...groupEntry(), profile: { name: "@deepseek-ai/cordis-plugin-group", group: true, config: {} } })).not.toEqual([]);
     expect(validate(schema, { ...validEntry(), capabilities: [] })).not.toEqual([]);
+    expect(validate(schema, { ...validEntry(), capabilities: ["bounded skill packaging"] })).not.toEqual([]);
+    expect(validate(schema, { ...validEntry(), capabilities: ["read-only", "read-only"] })).not.toEqual([]);
+    // A plugin cannot claim it changes nothing and also declare an effect; the console shows that claim as a badge next to the Install button.
+    expect(validate(schema, { ...validEntry(), capabilities: ["read-only", "runs-commands"] })).not.toEqual([]);
+    expect(validate(schema, { ...validEntry(), capabilities: ["session-data", "runs-commands"] })).toEqual([]);
     expect(validate(schema, { ...validEntry(), repository: "http://example.com" })).not.toEqual([]);
     expect(validate(schema, { ...validEntry(), unexpected: true })).not.toEqual([]);
   });