"note": "Heuristic false-green LEADS, not findings. A finding requires a demonstrated reproduction (surviving mutation via mutation-runner). Do not treat a candidate as a confirmed false green. Coverage-theater leads may include tests that delegate their assertion to a custom helper the classifier does not recognise; verify before acting.",

  "sourceDigest": "sha256:dd810dd48c5bdbc9becd7fcc01dd41a4ca2abf0b2d6f6a545907247f6e3e8361",

  "summary": {

    "filesScanned": 2469,

    "filesScanned": 2470,

    "candidateCount": 16,

    "byMode": {

      "false_green_coverage_theater": 15,

{

  "schemaVersion": "1",

  "repository": "OpenAgentsInc/openagents",

  "sourceDigest": "sha256:d6a28da451ce9ef6f5cf228f613eb7a4a8e932087110a750f3bb6d198737304c",

  "sourceDigest": "sha256:6b3d3d24bcf4c883ce8e7c533b6d8f547bf5aee845e8631fb086f84af9bc4b16",

  "surfaces": [

    {

      "id": "app:@openagentsinc/acceptance-runner",

      "oracles": [

        {

          "type": "test",

          "ref": "packages/openagents-cli (64 tracked test files)"

          "ref": "packages/openagents-cli (65 tracked test files)"

        },

        {

          "type": "behavior-contract",

  loadPluginFromManifest,

  pluginIdentity,

  pluginTool,

  PluginApproval,

  type LoadedPlugin,

} from "./coder-plugins.js";

import {

  capabilityTool,

  defaultCapabilityGapRecorder,

  discoverPluginCatalog,

} from "./coder-capability.js";

import { runForeignResume } from "./coder-foreign-resume.js";

import { existsSync } from "node:fs";

import { spawnSync } from "node:child_process";

      // plugin materializes one tool for the rest of this session and nothing

      // outlives the process.

      const plugins: LoadedPlugin[] = [];

      const declareTools = () => {

      const catalog = discoverPluginCatalog(fileURLToPath(import.meta.url));

      const onSelect = (outcome: LoadedPlugin, manifestFile: string) => {

        // Reloading a name replaces it: a demo iterates on one plugin, and

        // two tools with one name would be a declaration the model cannot

        // tell apart.

        const at = plugins.findIndex((held) => held.manifest.name === outcome.manifest.name);

        if (at >= 0) plugins.splice(at, 1);

        plugins.push(outcome);

        declareTools();

        const identity = pluginIdentity(outcome);

        session.recordPluginEvent({

          message: describeLoad(outcome),

          event: "plugin_loaded",

          plugin: {

            name: identity.name,

            version: identity.version,

            artifactDigest: identity.artifactDigest,

            bytes: identity.bytes,

            abi: identity.abi,

            timeoutMs: identity.timeoutMs,

            capabilities: identity.capabilities,

            manifestPath: manifestFile,

            toolName: identity.toolName,

          },

        });

      };

      const capability = capabilityTool({

        catalog,

        approval: new PluginApproval(),

        recordGap: defaultCapabilityGapRecorder(),

        onSelect,

      });

      let declareTools: () => void;

      declareTools = () => {

        const active = skills.active();

        const tools = [

          shellTool(process.cwd()),

          ...(active.length === 0 ? [] : [skillTool(active)]),

          openagentsTool(),

          ...(setup === undefined ? [] : [delegateTool(setup.delegation)]),

          capability,

          ...plugins.map((plugin) => pluginTool(plugin)),

        ];

        source.useTools?.(tools);

          });

          return described;

        }

        // Reloading a name replaces it: a demo iterates on one plugin, and

        // two tools with one name would be a declaration the model cannot

        // tell apart.

        const at = plugins.findIndex((held) => held.manifest.name === outcome.manifest.name);

        if (at >= 0) plugins.splice(at, 1);

        plugins.push(outcome);

        declareTools();

        const identity = pluginIdentity(outcome);

        session.recordPluginEvent({

          message: described,

          event: "plugin_loaded",

          plugin: {

            name: identity.name,

            version: identity.version,

            artifactDigest: identity.artifactDigest,

            bytes: identity.bytes,

            abi: identity.abi,

            timeoutMs: identity.timeoutMs,

            capabilities: identity.capabilities,

            manifestPath: manifestFile,

            toolName: identity.toolName,

          },

        });

        onSelect(outcome, manifestFile);

        return described;

      };

/**

 * The standing `capability` tool and the local plugin catalog it searches.

 *

 * A session starts with exactly one `capability` tool. The model searches the

 * catalog of installed, digest-pinned plugins by describing what it needs. This

 * package has no embedding path, so the tool does not rank or filter by

 * keyword; it returns the full catalog and lets the model pick by exact name.

 *

 * When the model calls `capability` with the exact catalog name, the plugin is

 * approved, loaded, and added to the session tools. Its own schema then becomes

 * available, so every later call uses the exact catalog name as the tool name.

 */

import { appendFile, mkdir } from "node:fs/promises";

import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";

import { homedir } from "node:os";

import { dirname, join } from "node:path";

import { fileURLToPath } from "node:url";

import type { CoderTool } from "./coder-tools.js";

import {

  describeLoad,

  isRefusal,

  loadPluginFromManifest,

  type LoadedPlugin,

  type PluginApproval,

  type PluginManifest,

  type PluginRefusal,

  validateManifest,

} from "./coder-plugins.js";

/** One installed, digest-pinned plugin as the catalog sees it. */

export interface PluginCatalogEntry {

  readonly name: string;

  readonly version: string;

  readonly description: string;

  readonly manifestPath: string;

  readonly artifact: { readonly path: string; readonly digest: string };

  readonly capabilities: PluginManifest["capabilities"];

}

/** A recorded request for a capability the local catalog could not satisfy. */

export interface CapabilityGap {

  /** Epoch milliseconds. */

  readonly requestedAt: number;

  readonly query?: string | undefined;

  readonly requestedName?: string | undefined;

}

export interface CapabilityOptions {

  readonly catalog: ReadonlyArray<PluginCatalogEntry>;

  readonly approval: PluginApproval;

  /**

   * Record a no-match for later registry loop consumption. Called before the

   * tool returns, so the record is not lost if the caller then fails.

   */

  readonly recordGap: (gap: CapabilityGap) => void | Promise<void>;

  /**

   * Called when a plugin is approved and loaded so the session can declare its

   * dedicated tool. The manifest path is passed along for provenance records.

   */

  readonly onSelect: (plugin: LoadedPlugin, manifestPath: string) => void;

  /** Load a manifest into a verified, digest-pinned plugin. Defaults to the host loader. */

  readonly load?: (manifestPath: string) => LoadedPlugin | PluginRefusal;

}

/**

 * Walk upward from the caller's location until a `plugins/` directory is found,

 * then read every child `manifest.json` inside it. Invalid manifests are ignored;

 * this is discovery, not verification, and verification happens at load time.

 */

export function discoverPluginCatalog(from = import.meta.url): ReadonlyArray<PluginCatalogEntry> {

  const start = from.startsWith("file:") ? fileURLToPath(from) : from;

  let here = start;

  while (true) {

    const candidate = join(here, "plugins");

    if (existsSync(candidate) && statSync(candidate).isDirectory()) {

      const found: PluginCatalogEntry[] = [];

      for (const dir of readdirSync(candidate)) {

        const manifestPath = join(candidate, dir, "manifest.json");

        if (!existsSync(manifestPath)) continue;

        let raw: string;

        try {

          raw = readFileSync(manifestPath, "utf8");

        } catch {

          continue;

        }

        let parsed: unknown;

        try {

          parsed = JSON.parse(raw);

        } catch {

          continue;

        }

        const manifest = validateManifest(parsed);

        if (isRefusal(manifest)) continue;

        found.push({

          name: manifest.name,

          version: manifest.version,

          description: manifest.description,

          manifestPath,

          artifact: manifest.artifact,

          capabilities: manifest.capabilities,

        });

      }

      return found;

    }

    const parent = dirname(here);

    if (parent === here) break;

    here = parent;

  }

  return [];

}

/**

 * A default local record of capability gaps, for later registry loop consumption.

 *

 * Writes one JSON object per line to `~/.openagents/capability-gaps.jsonl`.

 * The recorder only writes; it does not read back. Callers that need to act on

 * the record can read the file themselves.

 */

export function defaultCapabilityGapRecorder(

  path = join(homedir(), ".openagents", "capability-gaps.jsonl"),

): (gap: CapabilityGap) => Promise<void> {

  return async (gap) => {

    await mkdir(dirname(path), { recursive: true });

    await appendFile(path, `${JSON.stringify(gap)}\n`, "utf8");

  };

}

function catalogDescription(catalog: ReadonlyArray<PluginCatalogEntry>): string {

  const entries = catalog

    .map((entry) => `- \`${entry.name}\` v${entry.version}: ${entry.description}`)

    .join("\n");

  return catalog.length === 0

    ? "The local catalog is empty."

    : `Installed capabilities:\n${entries}`;

}

/**

 * The one standing tool for discovering and loading plugin capabilities.

 *

 * The description and parameters contain only the `capability` tool: no

 * installed plugin names, no plugin parameter schemas, and no catalog enum.

 * Those appear only after a search with `query` returns the catalog and an

 * exact-name call with `name` loads the chosen plugin.

 */

export function capabilityTool(options: CapabilityOptions): CoderTool {

  const { catalog, approval, recordGap, onSelect, load = loadPluginFromManifest } = options;

  return {

    name: "capability",

    description:

      "Discover and load a local plugin capability from the installed catalog. " +

      "No semantic embedding is available in this package, so `query` returns " +

      "the full catalog of installed capabilities and their descriptions for you " +

      "to choose from. Do not try to guess a name by substring or keyword. " +

      "Once you see the exact catalog name, call `capability` again with `name` " +

      "set to that exact name to load it and make its dedicated tool available. " +

      "Every later call to the loaded capability uses that exact catalog name as the tool name.",

    parameters: {

      type: "object",

      properties: {

        query: {

          type: "string",

          description:

            "Describe the capability you need. No semantic embedding is available, so the full catalog is returned.",

        },

        name: {

          type: "string",

          description:

            "Exact catalog name of the capability to load. Use the exact name from a previous `query` result.",

        },

      },

      additionalProperties: false,

    },

    run: async (args, _signal) => {

      const query = typeof args["query"] === "string" ? args["query"].trim() : undefined;

      const name = typeof args["name"] === "string" ? args["name"].trim() : undefined;

      if (name !== undefined && name.length > 0) {

        const entry = catalog.find((candidate) => candidate.name === name);

        if (entry === undefined) {

          await recordGap({ requestedAt: Date.now(), requestedName: name, query });

          return `No capability named \`${name}\` is in the local catalog.\n\n${catalogDescription(catalog)}`;

        }

        const approvalResult = await approval.check({

          name: entry.name,

          digest: entry.artifact.digest,

          capabilities: entry.capabilities,

        });

        if (isRefusal(approvalResult)) {

          return `Capability \`${name}\` was not allowed (${approvalResult.code}): ${approvalResult.reason}`;

        }

        const outcome = load(entry.manifestPath);

        if (isRefusal(outcome)) {

          return describeLoad(outcome);

        }

        onSelect(outcome, entry.manifestPath);

        return describeLoad(outcome);

      }

      if (query !== undefined && query.length > 0) {

        if (catalog.length === 0) {

          await recordGap({ requestedAt: Date.now(), query });

        }

        return (

          "No semantic embedding is available, so the full catalog is shown for you to choose.\n\n" +

          `${catalogDescription(catalog)}\n\n` +

          "Call `capability` with `name` set to the exact catalog name you want to load."

        );

      }

      return "Provide `query` to see the catalog or `name` to load a capability by exact catalog name.";

    },

  };

}

    | "timeout"

    | "cancelled"

    | "trap"

    | "bad_packet";

    | "bad_packet"

    | "approval_unavailable"

    | "approval_refused";

  readonly reason: string;

}

  return { manifest, wasm, digest, mounts };

}

function validateManifest(value: unknown): PluginManifest | PluginRefusal {

export function validateManifest(value: unknown): PluginManifest | PluginRefusal {

  const bad = (what: string): PluginRefusal =>

    refuse("manifest_invalid", `the manifest is missing or mistypes ${what}`);

    "declared to the model for this session. Experimental."

  );

}

/**

 * Plugin capability approval.

 *

 * The host has three fixed tiers:

 * - pure compute (no mounts and no declared hosts) is allowed without asking;

 * - read-only mounts are asked once and then cached for the same verified

 *   digest and declared capabilities;

 * - network hosts or writable mounts are asked every time, with no cache.

 *

 * If no approver is configured, any tier that needs an operator refuses. This

 * is the safe default: an unattended session must not grant high-surface

 * capabilities without an explicit operator. An interactive caller can supply

 * an approver that prompts.

 */

export interface PluginApprovalRequest {

  readonly name: string;

  readonly digest: string;

  readonly capabilities: {

    readonly mounts: ReadonlyArray<{ readonly path: string; readonly readonly: boolean }>;

    readonly hosts: ReadonlyArray<unknown>;

  };

}

export interface PluginApprover {

  ask(request: PluginApprovalRequest): "allow" | "refuse" | Promise<"allow" | "refuse">;

}

export class PluginApproval {

  private readonly approved = new Set<string>();

  constructor(private readonly approver?: PluginApprover) {}

  async check(request: PluginApprovalRequest): Promise<"approved" | PluginRefusal> {

    const hasHosts = request.capabilities.hosts.length > 0;

    const hasWritableMounts = request.capabilities.mounts.some((mount) => !mount.readonly);

    const hasMounts = request.capabilities.mounts.length > 0;

    if (!hasMounts && !hasHosts) return "approved";

    const askEveryTime = hasHosts || hasWritableMounts;

    const key = `${request.digest}:${JSON.stringify(request.capabilities)}`;

    if (!askEveryTime && this.approved.has(key)) return "approved";

    if (this.approver === undefined) {

      return refuse("approval_unavailable", "No approver is configured for this capability tier.");

    }

    const answer = await this.approver.ask(request);

    if (answer !== "allow") {

      return refuse("approval_refused", "The operator refused this capability.");

    }

    if (!askEveryTime) this.approved.add(key);

    return "approved";

  }

}

import { fileURLToPath } from "node:url";

import { describe, expect, it } from "vitest";

import {

  capabilityTool,

  defaultCapabilityGapRecorder,

  discoverPluginCatalog,

  type CapabilityGap,

  type PluginCatalogEntry,

} from "../src/coder-capability.js";

import {

  isRefusal,

  loadPluginFromManifest,

  PluginApproval,

  type LoadedPlugin,

  type PluginApprovalRequest,

} from "../src/coder-plugins.js";

const MANIFEST = fileURLToPath(

  new URL("../../../plugins/word-stats/manifest.json", import.meta.url),

);

const loadedFixture = ((): LoadedPlugin => {

  const outcome = loadPluginFromManifest(MANIFEST);

  if (isRefusal(outcome)) throw new Error(`${outcome.code}: ${outcome.reason}`);

  return outcome;

})();

const baseCatalog: ReadonlyArray<PluginCatalogEntry> = [

  {

    name: loadedFixture.manifest.name,

    version: loadedFixture.manifest.version,

    description: loadedFixture.manifest.description,

    manifestPath: MANIFEST,

    artifact: loadedFixture.manifest.artifact,

    capabilities: loadedFixture.manifest.capabilities,

  },

];

describe("capabilityTool", () => {

  it("declares one standing tool whose description does not grow with the catalog", () => {

    const bigCatalog = Array.from({ length: 20 }, (_unused, index) => ({

      ...baseCatalog[0],

      name: `demo_${String(index)}`,

    }));

    const tool = capabilityTool({

      catalog: bigCatalog,

      approval: new PluginApproval(),

      recordGap: () => {},

      onSelect: () => {},

    });

    expect(tool.name).toBe("capability");

    const properties = tool.parameters["properties"] as Record<string, unknown>;

    expect(Object.keys(properties)).toContain("query");

    expect(Object.keys(properties)).toContain("name");

    expect(tool.description).toMatch(/No semantic embedding is available/);

    expect(tool.description).not.toMatch(/demo_/);

    expect(tool.parameters["additionalProperties"]).toBe(false);

  });

  it("returns the full catalog on a query and does not use keyword selection", async () => {

    const catalog: ReadonlyArray<PluginCatalogEntry> = [

      baseCatalog[0],

      { ...baseCatalog[0], name: "git_lost_work", description: "Scan a git repository." },

    ];

    const tool = capabilityTool({

      catalog,

      approval: new PluginApproval(),

      recordGap: () => {},

      onSelect: () => {},

    });

    const output = await tool.run({ query: "word" }, new AbortController().signal);

    expect(output).toContain("word_stats");

    expect(output).toContain("git_lost_work");

    expect(output).toMatch(/No semantic embedding is available/);

  });

  it("loads and selects a capability by exact catalog name", async () => {

    const selected: Array<{ readonly plugin: LoadedPlugin; readonly manifestPath: string }> = [];

    const tool = capabilityTool({

      catalog: baseCatalog,

      approval: new PluginApproval(),

      recordGap: () => {},

      onSelect: (plugin, manifestPath) => selected.push({ plugin, manifestPath }),

      load: loadPluginFromManifest,

    });

    const output = await tool.run({ name: "word_stats" }, new AbortController().signal);

    expect(output).toMatch(/Loaded plugin `word_stats`/);

    expect(selected).toHaveLength(1);

    expect(selected[0].plugin.manifest.name).toBe("word_stats");

  });

  it("records a capability gap when an exact name is not in the catalog", async () => {

    const gaps: CapabilityGap[] = [];

    const tool = capabilityTool({

      catalog: baseCatalog,

      approval: new PluginApproval(),

      recordGap: (gap) => {

        gaps.push(gap);

      },

      onSelect: () => {

        throw new Error("onSelect should not be called for a missing capability");

      },

    });

    const output = await tool.run({ name: "not_installed" }, new AbortController().signal);

    expect(gaps).toHaveLength(1);

    expect(gaps[0].requestedName).toBe("not_installed");

    expect(output).toMatch(/No capability named `not_installed`/);

  });

  it("records a gap when the catalog is empty on a query", async () => {

    const gaps: CapabilityGap[] = [];

    const tool = capabilityTool({

      catalog: [],

      approval: new PluginApproval(),

      recordGap: (gap) => {

        gaps.push(gap);

      },

      onSelect: () => {},

    });

    const output = await tool.run({ query: "something" }, new AbortController().signal);

    expect(gaps).toHaveLength(1);

    expect(gaps[0].query).toBe("something");

    expect(output).toMatch(/The local catalog is empty/);

  });

});

describe("PluginApproval", () => {

  it("auto-approves capabilities with no mounts and no hosts", async () => {

    const asked: PluginApprovalRequest[] = [];

    const approval = new PluginApproval({

      ask: (request) => {

        asked.push(request);

        return "allow";

      },

    });

    const result = await approval.check({

      name: "pure",

      digest: "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

      capabilities: { mounts: [], hosts: [] },

    });

    expect(result).toBe("approved");

    expect(asked).toHaveLength(0);

  });

  it("asks once for read-only mounts and caches by digest and capabilities", async () => {

    const asked: PluginApprovalRequest[] = [];

    const approval = new PluginApproval({

      ask: (request) => {

        asked.push(request);

        return "allow";

      },

    });

    const request = {

      name: "reader",

      digest: "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",

      capabilities: { mounts: [{ path: "data", readonly: true as boolean }], hosts: [] },

    };

    expect(await approval.check(request)).toBe("approved");

    expect(await approval.check(request)).toBe("approved");

    expect(asked).toHaveLength(1);

  });

  it("asks every time for declared hosts", async () => {

    const asked: PluginApprovalRequest[] = [];

    const approval = new PluginApproval({

      ask: (request) => {

        asked.push(request);

        return "allow";

      },

    });

    const request = {

      name: "net",

      digest: "sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",

      capabilities: { mounts: [], hosts: ["api.example.com"] },

    };

    await approval.check(request);

    await approval.check(request);

    expect(asked).toHaveLength(2);

  });

  it("asks every time for writable mounts", async () => {

    const asked: PluginApprovalRequest[] = [];

    const approval = new PluginApproval({

      ask: (request) => {

        asked.push(request);

        return "allow";

      },

    });

    const request = {

      name: "writer",

      digest: "sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",

      capabilities: { mounts: [{ path: "data", readonly: false }], hosts: [] },

    };

    await approval.check(request);

    await approval.check(request);

    expect(asked).toHaveLength(2);

  });

  it("refuses non-pure capabilities when no approver is configured", async () => {

    const approval = new PluginApproval();

    const result = await approval.check({

      name: "reader",

      digest: "sha256:eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",

      capabilities: { mounts: [{ path: "data", readonly: true }], hosts: [] },

    });

    expect(isRefusal(result) && result.code).toBe("approval_unavailable");

  });

});

describe("discoverPluginCatalog", () => {

  it("discovers the checked-in demo plugins from this repository", () => {

    const catalog = discoverPluginCatalog(fileURLToPath(import.meta.url));

    const names = catalog.map((entry) => entry.name).sort();

    expect(names).toContain("word_stats");

    expect(names).toContain("dir_stats");

    expect(names).toContain("file_stats");

    expect(names).toContain("git_lost_work");

    expect(names).toContain("foreign_sessions");

    expect(catalog.every((entry) => entry.artifact.digest.startsWith("sha256:"))).toBe(true);

  });

});

describe("defaultCapabilityGapRecorder", () => {

  it("produces an async writer for the default gap file", () => {

    const recorder = defaultCapabilityGapRecorder();

    expect(typeof recorder).toBe("function");

  });

});