capabilityTool,

  defaultCapabilityGapRecorder,

  discoverPluginCatalog,

  matchCapabilities,

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

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

import { existsSync } from "node:fs";

          (buildTier !== undefined && initialTier !== undefined

            ? { initial: initialTier, build: buildTier }

            : undefined),

        (prompt) => capabilityRetrieval(prompt),

      );

      // The resumed thread's history goes on the session before anything new,

        return described;

      };

      // Retrieval is the harness's job (OpenAgentsInc/openagents#42): score

      // the catalog against each incoming message, auto-load what clearly

      // matches so the model simply sees the right tool, and note a weaker

      // match for the model to load itself. Nothing matched costs nothing.

      const capabilityRetrieval = async (prompt: string): Promise<string | undefined> => {

        const matches = matchCapabilities(catalog, prompt);

        const held = new Set(plugins.map((plugin) => plugin.manifest.name));

        const materialized: string[] = [];

        for (const match of matches.filter((candidate) => candidate.hits >= 2).slice(0, 2)) {

          if (held.has(match.entry.name)) {

            materialized.push(match.entry.name);

            continue;

          }

          const described = loadPlugin(match.entry.manifestPath);

          if (described.startsWith("Loaded plugin")) materialized.push(match.entry.name);

        }

        if (materialized.length > 0) {

          const names = materialized.map((name) => `\`${name}\``).join(", ");

          return (

            `[Attached by the harness: installed capabilities matched this request, and ` +

            `${names} ${materialized.length === 1 ? "is" : "are"} loaded and available as ` +

            `${materialized.length === 1 ? "a tool" : "tools"} right now. Prefer ` +

            `${materialized.length === 1 ? "it" : "them"} over scripting the same thing.]`

          );

        }

        const near = matches.slice(0, 2);

        if (near.length > 0) {

          const names = near.map((candidate) => `\`${candidate.entry.name}\``).join(", ");

          return (

            `[Attached by the harness: ${names} in the installed capability catalog may ` +

            `cover this. Load one with the capability tool, name set exactly, if it fits.]`

          );

        }

        return undefined;

      };

      const locateForeignSessionsManifest = (): string | undefined => {

        let here = dirname(fileURLToPath(import.meta.url));

        while (true) {

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

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

 */

/** Most capabilities the standing summary names; the rest ride behind `query`. */

const SUMMARY_CAP = 12;

/** Most candidates one search returns; the rest are counted, not listed. */

const SEARCH_LIMIT = 5;

/** A description's first sentence, for the one-line standing summary. */

/** A description's first sentence, for a one-line candidate row. */

const firstSentence = (text: string): string => {

  const at = text.indexOf(". ");

  return at > 0 ? text.slice(0, at + 1) : text;

};

/** "; and K more" when the catalog holds more than one answer showed. */

const remainder = (beyond: number): string =>

  beyond > 0 ? `\n…and ${String(beyond)} more; search again with other words.` : "";

/**

 * Lexical retrieval over the catalog: token overlap between the query and

 * each manifest's name and description, best first, at most [`SEARCH_LIMIT`].

 *

 * Retrieval narrows candidates; it never routes. The model still invokes by

 * the exact returned name and the load still verifies the digest, so the

 * no-keyword-routing law holds. An embedding index can replace this scoring

 * without changing the surface (OpenAgentsInc/openagents#42).

 */

const searchCatalog = (

  catalog: ReadonlyArray<PluginCatalogEntry>,

  query: string,

): PluginCatalogEntry[] =>

  matchCapabilities(catalog, query)

    .slice(0, SEARCH_LIMIT)

    .map((candidate) => candidate.entry);

/**

 * Score the catalog against free text, best first.

 *

 * Exported because retrieval is the harness's job, not only the model's

 * (OpenAgentsInc/openagents#42): the session runs this over each incoming

 * message and materializes what matches, so the model sees the right tool

 * without having consulted anything.

 */

export const matchCapabilities = (

  catalog: ReadonlyArray<PluginCatalogEntry>,

  text: string,

): Array<{ readonly entry: PluginCatalogEntry; readonly hits: number }> => {

  const terms = tokens(text);

  if (terms.length === 0) return [];

  const scored = catalog

    .map((entry) => {

      const haystack = new Set(tokens(`${entry.name} ${entry.description}`));

      const hits = terms.filter((term) => haystack.has(term)).length;

      return { entry, hits };

    })

    .filter((candidate) => candidate.hits > 0);

  scored.sort((left, right) => right.hits - left.hits);

  return scored;

};

/** Lowercased word stems of three letters or more; the rest is noise. */

const tokens = (text: string): string[] =>

  text

    .toLowerCase()

    .split(/[^a-z0-9]+/)

    .filter((word) => word.length >= 3);

export function capabilityTool(options: CapabilityOptions): CoderTool {

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

  // The catalog's names and first sentences ride in the standing

  // description: a model that has never heard what is installed answers

  // "read that conversation back" with an improvised shell script, and the

  // sandboxed, bounded capability sits unused. One tool, but an honest one.

  const shown = catalog.slice(0, SUMMARY_CAP);

  const beyond = catalog.length - shown.length;

  const summary =

    catalog.length === 0

      ? ""

      : "Installed: " +

        shown

          .map((entry) => `\`${entry.name}\` (${firstSentence(entry.description)})`)

          .join("; ") +

        (beyond > 0 ? `; and ${String(beyond)} more via \`query\`` : "") +

        ". When one of these covers the work, load and call it instead of improvising a script: it is sandboxed, bounded, and returns structured output. ";

  return {

    name: "capability",

    // Constant-size on purpose (OpenAgentsInc/openagents#42): the catalog is

    // searched, never enumerated here, so the standing prompt does not grow

    // as capabilities are installed.

    description:

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

      summary +

      "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.",

      "Discover and load installed plugin capabilities: sandboxed, sealed programs this " +

      "machine already holds for common agent work. Before writing a script for a task, " +

      "search here first — a capability that covers it is bounded, reviewable, and returns " +

      "structured output. Call with `query` describing what you need to get the best " +

      "matches; then call again with `name` set to the exact returned name to load it and " +

      "make its dedicated tool available. Every later call to the loaded capability uses " +

      "that exact name as the tool name.",

    parameters: {

      type: "object",

      properties: {

      }

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

        if (catalog.length === 0) {

        const ranked = searchCatalog(catalog, query);

        if (ranked.length === 0) {

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

          return catalog.length === 0

            ? "No capabilities are installed on this machine."

            : "Nothing installed matches that. The full catalog:\n\n" +

                `${catalogDescription(catalog.slice(0, SEARCH_LIMIT))}` +

                remainder(catalog.length - SEARCH_LIMIT) +

                "\n\nCall `capability` with `name` set to an exact name to load it.";

        }

        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."

          "Best matches, most relevant first:\n\n" +

          ranked

            .map((entry) => `- \`${entry.name}\` — ${firstSentence(entry.description)}`)

            .join("\n") +

          remainder(catalog.length - ranked.length) +

          "\n\nCall `capability` with `name` set to the exact name you want to load."

        );

      }

        history: ReadonlyArray<unknown>,

      ): Promise<ReplySource>;

    },

    /**

     * Harness-side capability retrieval, run over each submitted prompt.

     *

     * Returns a short note to attach to the outgoing turn — after loading

     * whatever matched, so the model sees the right tool rather than being

     * asked to go looking — or undefined when nothing matched, which costs

     * the turn nothing. The model is never expected to consult a registry.

     */

    private readonly retrieve?: (prompt: string) => Promise<string | undefined>,

  ) {

    this.tier = tiers?.initial;

    // A child reporting progress has to reach the renderer, and the renderer

    try {

      await this.applyPendingTier();

      // Retrieval before the turn goes out: what matched is loaded and its

      // note rides the prompt. A failed retrieval is a turn without a note,

      // never a failed turn.

      const attached =

        this.retrieve === undefined

          ? undefined

          : await this.retrieve(prompt).catch(() => undefined);

      // The reader's entry above keeps what they typed; the model receives the

      // standing context ahead of it on the first turn only.

      const sent =

        this.source.useContext !== undefined

          ? prompt

          : `${this.standing}\n\n---\n\n${prompt}`;

      const outgoing = attached === undefined ? sent : `${sent}\n\n${attached}`;

      for await (const chunk of this.source.reply(sent, controller.signal)) {

      for await (const chunk of this.source.reply(outgoing, controller.signal)) {

        if (controller.signal.aborted) break;

        if (chunk.type === "text") {

  lane: string,

  standing?: string,

): string => {

  const lines = [`You are \`openagents coder\`, a coding assistant in a terminal. ${lane}`, ""];

  const lines = [

    `You are \`openagents coder\`, a coding assistant in a terminal. ${lane}`,

    "",

    "Answer very concisely unless the reader asks for a longer response.",

    "",

  ];

  if (tools.length === 0) {

    lines.push(

  discoverPluginCatalog,

  type CapabilityGap,

  type PluginCatalogEntry,

  matchCapabilities,

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

import {

  isRefusal,

];

describe("capabilityTool", () => {

  it("declares one standing tool that names the catalog, capped rather than unbounded", () => {

    // The description deliberately carries the installed names and first

    // sentences: a model that has never heard what is installed answered

    // "read that conversation back" with an improvised shell script while

    // the capability sat unused. The growth is capped, not zero — past the

    // cap, the rest ride behind `query`.

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

  it("declares one standing tool whose description is constant, however big the catalog", () => {

    // The constant-size contract (OpenAgentsInc/openagents#42): the catalog

    // is searched, never enumerated in the standing prompt, so installing a

    // capability costs zero standing bytes. The behavioral sentence — search

    // before scripting — is what keeps the tool reachable without the list.

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

      ...baseCatalog[0],

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

    }));

    const tool = capabilityTool({

    const small = capabilityTool({

      catalog: [],

      approval: new PluginApproval(),

      recordGap: () => {},

      onSelect: () => {},

    });

    const big = capabilityTool({

      catalog: bigCatalog,

      approval: new PluginApproval(),

      recordGap: () => {},

      onSelect: () => {},

    });

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

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

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

    const properties = big.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).toContain("demo_0");

    expect(tool.description).toContain("demo_11");

    expect(tool.description).not.toContain("demo_12");

    expect(tool.description).toContain("and 8 more");

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

    expect(big.description).toBe(small.description);

    expect(big.description).not.toContain("demo_");

    expect(big.description).toContain("search here first");

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

  });

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

  it("searches the catalog on a query: candidates narrow, invocation stays exact-name", async () => {

    const catalog: ReadonlyArray<PluginCatalogEntry> = [

      baseCatalog[0],

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

      recordGap: () => {},

      onSelect: () => {},

    });

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

    const output = await tool.run(

      { query: "statistics about words" },

      new AbortController().signal,

    );

    // The match leads; the miss is counted, not listed.

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

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

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

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

    expect(output).toContain("and 1 more");

    expect(output).toContain("exact name");

    // A query nothing matches still shows a bounded catalog to choose from.

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

    expect(missed).toContain("Nothing installed matches");

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

  });

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

    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/);

    expect(output).toContain("No capabilities are installed");

  });

});

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

  });

});

describe("matchCapabilities", () => {

  const catalog: ReadonlyArray<PluginCatalogEntry> = [

    {

      name: "read_conversation",

      version: "0.1.0",

      description: "Read a conversation back from this machine: a Claude Code or Codex session.",

      manifestPath: "/tmp/a.json",

      artifact: { path: "a.wasm", digest: "sha256:aa" },

      capabilities: { mounts: [], hosts: [], timeout_ms: 1000, memory_max_mib: 64 },

    },

    {

      name: "word_stats",

      version: "0.1.0",

      description: "Compute statistics for a piece of text.",

      manifestPath: "/tmp/b.json",

      artifact: { path: "b.wasm", digest: "sha256:bb" },

      capabilities: { mounts: [], hosts: [], timeout_ms: 1000, memory_max_mib: 64 },

    },

  ];

  it("scores the catalog against free text, best first, misses dropped", () => {

    const matches = matchCapabilities(catalog, "read back the conversation on this machine");

    expect(matches[0]?.entry.name).toBe("read_conversation");

    expect(matches[0]?.hits).toBeGreaterThanOrEqual(2);

    expect(matches.some((match) => match.entry.name === "word_stats")).toBe(false);

  });

  it("returns nothing for text nothing matches, so a turn costs nothing", () => {

    expect(matchCapabilities(catalog, "deploy the kubernetes cluster")).toEqual([]);

  });

});

    expect(notices).not.toContain(TIER_MODELS.flash);

  });

});

// Retrieval is the harness's job: the hook runs over the submitted prompt

// and its note rides the outgoing turn, so the model sees the match without

// having consulted anything (OpenAgentsInc/openagents#42).

describe("session capability retrieval", () => {

  it("attaches the retrieval note to what the source receives", async () => {

    const seen: string[] = [];

    const source: ReplySource = {

      model: "Coder Auto",

      async *reply(prompt: string) {

        seen.push(prompt);

        yield { type: "text", value: "ok" } as const;

      },

    };

    const session = new CoderSession(

      source,

      "repo",

      "main",

      undefined,

      undefined,

      undefined,

      undefined,

      (prompt) =>

        Promise.resolve(

          prompt.includes("conversation") ? "[Attached by the harness: loaded.]" : undefined,

        ),

    );

    await session.submit("read the conversation");

    await session.submit("hello there");

    expect(seen[0]).toContain("read the conversation");

    expect(seen[0]).toContain("[Attached by the harness: loaded.]");

    expect(seen[1]).toBe("hello there");

  });

});