what each child returned, and where the width stands. A backlog run that reports

only at the end is one nobody can steer.

## What is not yours to decide

## Working and completing issues

Closing an issue, pushing, and commenting are visible to other people at once.

Do the work and report it; ask before the first write that leaves the machine.

When assigned or requested to fix or work on an issue, deliver the solution

completely: verify the fix with tests, push directly to `main` (or the working branch),

and close the issue without a separate confirmation step.

An agent reporting that it finished is not evidence that it did. Read the diff,

run the test, look at the output.

Take care not to step on other people's concurrent work: check git status and remotes

before pushing. An agent reporting that it finished is not evidence that it did:

read the diff, run the test, and verify the output before closing.

  discoverPluginCatalog,

  matchCapabilities,

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

import { knowledgeHits, knowledgeNote } from "./coder-knowledge.js";

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

import { existsSync } from "node:fs";

import { spawnSync } from "node:child_process";

      // outlives the process.

      const plugins: LoadedPlugin[] = [];

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

      // Turn-scoped visibility (the owner's decision, 2026-08-25): a tool the

      // current message does not need is not shown to the model. A plugin the

      // reader loaded by hand (`/plugin load`) is pinned for the session; one

      // the harness or the model brought in stays declared only while it is

      // warm — matched by retrieval or invoked within the last two turns —

      // and then leaves the tool list. The instance itself stays cached in

      // `plugins`, so coming back is free.

      let turn = 0;

      const pinnedNames = new Set<string>();

      const warmUntil = new Map<string, number>();

      const warm = (name: string): void => {

        warmUntil.set(name, turn + 2);

      };

      const visiblePlugins = (): LoadedPlugin[] =>

        plugins.filter(

          (plugin) =>

            pinnedNames.has(plugin.manifest.name) ||

            (warmUntil.get(plugin.manifest.name) ?? -1) >= turn,

        );

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

        warm(outcome.manifest.name);

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

          openagentsTool(),

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

          capability,

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

          ...visiblePlugins().map((plugin) => {

            const tool = pluginTool(plugin);

            // Using a tool keeps it visible: the warmth window restarts on

            // every invocation, so a follow-up still finds it declared.

            return {

              ...tool,

              run: (args: Record<string, unknown>, signal: AbortSignal) => {

                warm(plugin.manifest.name);

                return tool.run(args, signal);

              },

            };

          }),

        ];

        session.declareTools(tools);

      };

      declareTools();

      const loadPlugin = (manifestPath: string): string => {

      // `pin` distinguishes who asked: the reader's `/plugin load` pins the

      // tool for the whole session, while harness retrieval loads unpinned

      // and lets the warmth window govern visibility.

      const loadPlugin = (manifestPath: string, pin = true): string => {

        const manifestFile = resolvePath(process.cwd(), manifestPath);

        const outcome = loadPluginFromManifest(manifestFile);

        const described = describeLoad(outcome);

          return described;

        }

        onSelect(outcome, manifestFile);

        if (pin) pinnedNames.add(outcome.manifest.name);

        return described;

      };

      // The knowledge-base rail (OpenAgentsInc/openagents#49): the corpus

      // plugin is consulted directly by the harness on every message and is

      // never declared as a tool — its answers arrive as attached context.

      // Loaded lazily and kept out of `plugins` on purpose.

      let knowledgeBase: LoadedPlugin | undefined;

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

        if (knowledgeBase === undefined) {

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

          if (entry === undefined) return undefined;

          const outcome = loadPluginFromManifest(entry.manifestPath);

          if (isRefusal(outcome)) return undefined;

          knowledgeBase = outcome;

        }

        try {

          const packet = new TextEncoder().encode(JSON.stringify({ query: prompt, limit: 3 }));

          const answered = await invokePlugin(knowledgeBase, packet);

          if (isRefusal(answered)) return undefined;

          const envelope: unknown = JSON.parse(new TextDecoder().decode(answered));

          return knowledgeNote(knowledgeHits(envelope));

        } catch {

          // The rail degrades to silence, never to a broken turn.

          return undefined;

        }

      };

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

        // Each incoming message opens a turn; the warmth window that governs

        // which plugin tools the model sees is measured in these.

        turn += 1;

        const notes: string[] = [];

        const fromKnowledge = await knowledgeBaseNote(prompt);

        if (fromKnowledge !== undefined) notes.push(fromKnowledge);

        // The knowledge base is a rail, not a tool: it never materializes.

        const matches = matchCapabilities(catalog, prompt).filter(

          (candidate) => candidate.entry.name !== "knowledge_base",

        );

        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)) {

            warm(match.entry.name);

            materialized.push(match.entry.name);

            continue;

          }

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

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

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

        }

        // Re-declared after the warmth window moved: this turn's tool list is

        // what matched this message, what is pinned, and what was just used —

        // not everything ever loaded.

        declareTools();

        if (materialized.length > 0) {

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

          return (

          notes.push(

            `[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.]`

              `${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.]`,

          );

        } else {

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

          if (near.length > 0) {

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

            notes.push(

              `[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;

        return notes.length === 0 ? undefined : notes.join("\n\n");

      };

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

/**

 * The knowledge-base rail (OpenAgentsInc/openagents#49): the harness asks the

 * `knowledge_base` plugin about each incoming message and, when the corpus

 * clearly answers, attaches its stances and doc summaries to the outgoing

 * turn. The model never calls the knowledge base as a tool — by the time it

 * writes, the documented position is already in front of it, dated and

 * sourced, so it can prefer what the project actually decided over a guess.

 */

/** One hit as the `knowledge_base` guest returns it. */

export interface KnowledgeHit {

  readonly kind: "stance" | "doc";

  readonly title: string;

  readonly body: string;

  readonly state?: string | undefined;

  readonly sources: ReadonlyArray<string>;

  readonly date?: string | undefined;

  readonly score: number;

}

/**

 * The overlap a hit needs before it is worth attaching. The guest scores a

 * question-level word at 3, so the floor asks for roughly two intent-carrying

 * words — a lone body-text collision never interrupts the conversation.

 */

export const KNOWLEDGE_ATTACH_FLOOR = 5;

/** Most hits one note carries; more is noise, not context. */

const NOTE_LIMIT = 2;

/** A body's share of the note; stances are prose and can run long. */

const BODY_BOUND = 700;

const clipped = (text: string): string =>

  text.length <= BODY_BOUND ? text : `${text.slice(0, BODY_BOUND - 1).trimEnd()}…`;

const line = (hit: KnowledgeHit): string => {

  const provenance =

    hit.kind === "stance"

      ? `stance${hit.state === undefined ? "" : `, ${hit.state}`}${

          hit.date === undefined ? "" : `; reviewed ${hit.date}`

        }`

      : `doc${hit.sources.length === 0 ? "" : `, ${hit.sources[0] ?? ""}`}`;

  return `- ${hit.title} (${provenance}): ${clipped(hit.body)}`;

};

/**

 * The note for one message, or nothing when the corpus has nothing strong

 * enough to say. Hits arrive best-first from the guest; the floor and the

 * limit are applied here so the plugin stays a plain ranking function.

 */

export const knowledgeNote = (hits: ReadonlyArray<KnowledgeHit>): string | undefined => {

  const strong = hits.filter((hit) => hit.score >= KNOWLEDGE_ATTACH_FLOOR).slice(0, NOTE_LIMIT);

  if (strong.length === 0) return undefined;

  return (

    "[From the OpenAgents knowledge base — reviewed positions and public docs. " +

    "Where these speak, prefer them over general knowledge, and say when a thing " +

    "is parked or planned rather than live:\n" +

    strong.map(line).join("\n") +

    "]"

  );

};

/** A guarded read of the guest's envelope into typed hits; junk is no hits. */

export const knowledgeHits = (envelope: unknown): KnowledgeHit[] => {

  if (envelope === null || typeof envelope !== "object") return [];

  const ok = (envelope as Record<string, unknown>)["ok"];

  if (ok === null || typeof ok !== "object") return [];

  const hits = (ok as Record<string, unknown>)["hits"];

  if (!Array.isArray(hits)) return [];

  const typed: KnowledgeHit[] = [];

  for (const candidate of hits) {

    if (candidate === null || typeof candidate !== "object") continue;

    const record = candidate as Record<string, unknown>;

    const kind = record["kind"];

    const title = record["title"];

    const body = record["body"];

    const score = record["score"];

    if (kind !== "stance" && kind !== "doc") continue;

    if (typeof title !== "string" || typeof body !== "string" || typeof score !== "number") {

      continue;

    }

    typed.push({

      kind,

      title,

      body,

      state: typeof record["state"] === "string" ? record["state"] : undefined,

      sources: Array.isArray(record["sources"])

        ? record["sources"].filter((source): source is string => typeof source === "string")

        : [],

      date: typeof record["date"] === "string" ? record["date"] : undefined,

      score,

    });

  }

  return typed;

};

 *   inspection, before instantiation, so the sandbox is a property of what

 *   was loaded rather than a hope about what it does.

 * - **Mounts are read-only and confined.** A declared mount resolves to a

 *   real directory at load (relative to the manifest, absolute, or

 *   `~`-expanded); at invocation the engine's `read_file` and `list_dir`

 *   real directory at load (relative to the manifest, absolute,

 *   `~`-expanded, or the literal `${workspace}`, which is the process

 *   working directory); at invocation the engine's `read_file` and `list_dir`

 *   imports canonicalize every path, refuse absolute paths, `..` escapes,

 *   and symlinks, bound the bytes per file, and bound the entries per

 *   listing.

  /**

   * Directory path. Relative paths resolve against the manifest's

   * directory; absolute paths are taken as-is; a leading `~/` (or a bare

   * `~`) expands to the invoking user's home directory. Whatever the form,

   * the root must exist and be a directory at load, or the plugin refuses

   * to load.

   * `~`) expands to the invoking user's home directory; the literal

   * `${workspace}` resolves to the process working directory at load time

   * (the parameterized workspace mount, OpenAgentsInc/openagents#44).

   * Whatever the form, the root must exist and be a directory at load, or

   * the plugin refuses to load.

   */

  readonly path: string;

  /** Only `true` is accepted; a writable mount is refused, not downgraded. */

  const manifestDir = dirname(manifestPath);

  const mounts: string[] = [];

  for (const mount of manifest.capabilities.mounts) {

    const declared = resolve(manifestDir, expandMountPath(mount.path));

    // The parameterized workspace mount (OpenAgentsInc/openagents#44): the

    // literal `${workspace}` resolves to the process working directory at

    // load time, so a checked-in manifest can grant "the repository the

    // coder is standing in" without naming a machine-specific path.

    const expanded = mount.path === "${workspace}" ? process.cwd() : expandMountPath(mount.path);

    const declared = resolve(manifestDir, expanded);

    let root: string;

    try {

      root = realpathSync(declared);

      const heading =

        running === 0

          ? `${BOLD}children${RESET}`

          : `${BOLD}children${RESET} ${DIM}${String(running)} working${RESET}`;

          ? `${BOLD}subagents${RESET}`

          : `${BOLD}subagents${RESET} ${DIM}${String(running)} working${RESET}`;

      const rows: string[] = [

        heading,

/**

 * The git facts reader through the real boundary: the checked-in

 * `git_facts` plugin against a staged fixture "repo" — a hand-written

 * `.git/HEAD`, loose ref, `packed-refs`, `logs/HEAD` reflog, and a

 * hand-built binary version-2 index, with matching and mismatching

 * workdir files around them. The parsing logic is unit-tested against a

 * fake host in `plugins/git-facts/src/tests.rs`; this file proves the

 * same facts hold through the WASM sandbox, and that a workspace with no

 * git repository is refused. The checked-in manifest declares the

 * `${workspace}` mount; here it is rewritten to the fixture root, the

 * established pattern for mount-bearing plugins.

 */

import { mkdirSync, mkdtempSync, copyFileSync, readFileSync, utimesSync, writeFileSync } from "node:fs";

import { tmpdir } from "node:os";

import { join } from "node:path";

import { fileURLToPath } from "node:url";

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

import {

  invokePlugin,

  isRefusal,

  loadPluginFromManifest,

  type LoadedPlugin,

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

const MANIFEST = fileURLToPath(new URL("../../../plugins/git-facts/manifest.json", import.meta.url));

const WASM = fileURLToPath(new URL("../../../plugins/git-facts/git_facts.wasm", import.meta.url));

const SHA_A = "a".repeat(40);

const SHA_B = "b".repeat(40);

const ZERO = "0".repeat(40);

/** Whole seconds, so index mtimes and filesystem mtimes agree exactly. */

const KEPT_MTIME_MS = 1_700_000_000_000;

const DRIFT_MTIME_MS = 1_700_000_100_000;

/**

 * Build a version-2 git index: the 12-byte DIRC header, 62-byte fixed

 * entries with 8-byte-aligned NUL padding after each path, and a zeroed

 * 20-byte trailing checksum (the plugin never verifies it).

 */

const buildIndex = (entries: Array<{ path: string; size: number; mtimeMs: number }>): Buffer => {

  const parts: Buffer[] = [];

  const header = Buffer.alloc(12);

  header.write("DIRC", 0, "ascii");

  header.writeUInt32BE(2, 4);

  header.writeUInt32BE(entries.length, 8);

  parts.push(header);

  for (const entry of entries) {

    const name = Buffer.from(entry.path, "utf8");

    const entryLen = (62 + name.length + 8) & ~7;

    const buffer = Buffer.alloc(entryLen);

    buffer.writeUInt32BE(Math.floor(entry.mtimeMs / 1000), 8); // mtime sec

    buffer.writeUInt32BE((entry.mtimeMs % 1000) * 1_000_000, 12); // mtime nsec

    buffer.writeUInt32BE(0o100644, 24); // mode

    buffer.writeUInt32BE(entry.size, 36);

    buffer.writeUInt16BE(name.length, 60); // flags: name length

    name.copy(buffer, 62);

    parts.push(buffer);

  }

  parts.push(Buffer.alloc(20));

  return Buffer.concat(parts);

};

const reflogLine = (oldId: string, newId: string, seconds: number, message: string): string =>

  `${oldId} ${newId} Ada Lovelace <ada@example.com> ${seconds} -0600\t${message}\n`;

const touch = (path: string, mtimeMs: number): void => {

  utimesSync(path, new Date(mtimeMs), new Date(mtimeMs));

};

const load = (workspace: string): LoadedPlugin => {

  const dir = mkdtempSync(join(tmpdir(), "git-facts-plugin-"));

  const manifest = JSON.parse(readFileSync(MANIFEST, "utf8")) as {

    capabilities: { mounts: Array<{ path: string; readonly: true }> };

  };

  manifest.capabilities.mounts = [{ path: workspace, readonly: true }];

  writeFileSync(join(dir, "manifest.json"), JSON.stringify(manifest));

  copyFileSync(WASM, join(dir, "git_facts.wasm"));

  const outcome = loadPluginFromManifest(join(dir, "manifest.json"));

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

  return outcome;

};

/**

 * A fixture repo on branch `main`: one loose ref, one packed branch, a

 * two-entry reflog, and a three-entry index against a workdir where

 * `kept.txt` matches its index stat, `drifted.txt` differs in size,

 * `gone.txt` is absent, and `extra.txt` is untracked.

 */

const stageRepo = (): string => {

  const workspace = mkdtempSync(join(tmpdir(), "git-facts-repo-"));

  const git = join(workspace, ".git");

  mkdirSync(join(git, "refs", "heads"), { recursive: true });

  mkdirSync(join(git, "logs"), { recursive: true });

  writeFileSync(join(git, "HEAD"), "ref: refs/heads/main\n");

  writeFileSync(join(git, "refs", "heads", "main"), `${SHA_A}\n`);

  writeFileSync(

    join(git, "packed-refs"),

    `# pack-refs with: peeled fully-peeled sorted \n${SHA_B} refs/heads/archive\n`,

  );

  writeFileSync(

    join(git, "logs", "HEAD"),

    reflogLine(ZERO, SHA_B, 1_700_000_000, "commit (initial): begin") +

      reflogLine(SHA_B, SHA_A, 1_700_000_100, "commit: keep\tgoing"),

  );

  writeFileSync(join(workspace, "kept.txt"), "kept\n");

  touch(join(workspace, "kept.txt"), KEPT_MTIME_MS);

  writeFileSync(join(workspace, "drifted.txt"), "drifted longer now\n");

  touch(join(workspace, "drifted.txt"), DRIFT_MTIME_MS);

  writeFileSync(join(workspace, "extra.txt"), "new\n");

  writeFileSync(

    join(git, "index"),

    buildIndex([

      { path: "drifted.txt", size: 8, mtimeMs: DRIFT_MTIME_MS },

      { path: "gone.txt", size: 5, mtimeMs: KEPT_MTIME_MS },

      { path: "kept.txt", size: 5, mtimeMs: KEPT_MTIME_MS },

    ]),

  );

  return workspace;

};

type PathFacts = { count: number; paths: string[] };

type Output = {

  head?: { branch?: string; detached?: string };

  branches?: Array<{ name: string; id: string }>;

  log?: Array<{ id: string; at_ms: number; message: string }>;

  status?: {

    tracked: number;

    changed_candidates: PathFacts;

    untracked: PathFacts;

    missing: PathFacts;

    walk_truncated: boolean;

    comparison: string;

  };

  notes: string[];

};

/** The guest envelope: `ok` on success, `refusal` as a value otherwise. */

type Envelope = { ok?: Output; refusal?: { code: string; reason: string } };

const invoke = async (plugin: LoadedPlugin, input: Record<string, unknown>): Promise<Envelope> => {

  const packet = new TextEncoder().encode(JSON.stringify(input));

  const outcome = await invokePlugin(plugin, packet);

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

  return JSON.parse(new TextDecoder().decode(outcome)) as Envelope;

};

const call = async (plugin: LoadedPlugin, input: Record<string, unknown>): Promise<Output> => {

  const envelope = await invoke(plugin, input);

  if (envelope.ok === undefined) throw new Error(JSON.stringify(envelope.refusal));

  return envelope.ok;

};

describe("the git_facts plugin through the sandbox", () => {

  it("reads head, branches, log, and status from the plumbing files", async () => {

    const plugin = load(stageRepo());

    const out = await call(plugin, {});

    expect(out.head).toEqual({ branch: "main" });

    expect(out.branches).toEqual([

      { name: "archive", id: SHA_B },

      { name: "main", id: SHA_A },

    ]);

    expect(out.log).toEqual([

      { id: SHA_A, at_ms: 1_700_000_100_000, message: "commit: keep\tgoing" },

      { id: SHA_B, at_ms: 1_700_000_000_000, message: "commit (initial): begin" },

    ]);

    const status = out.status!;

    expect(status.tracked).toBe(3);

    expect(status.changed_candidates.paths).toEqual(["drifted.txt"]);

    expect(status.untracked.paths).toEqual(["extra.txt"]);

    expect(status.missing.paths).toEqual(["gone.txt"]);

    expect(status.walk_truncated).toBe(false);

    expect(status.comparison).toBe("size_and_mtime_only");

  });

  it("reports only the facts asked for", async () => {

    const plugin = load(stageRepo());

    const out = await call(plugin, { facts: ["head", "log"], max_log: 1 });

    expect(out.head).toEqual({ branch: "main" });

    expect(out.log).toEqual([

      { id: SHA_A, at_ms: 1_700_000_100_000, message: "commit: keep\tgoing" },

    ]);

    expect(out.branches).toBeUndefined();

    expect(out.status).toBeUndefined();

  });

  it("refuses a workspace with no git repository at its root", async () => {

    const workspace = mkdtempSync(join(tmpdir(), "git-facts-bare-"));

    writeFileSync(join(workspace, "README.md"), "no repo here\n");

    const plugin = load(workspace);

    const envelope = await invoke(plugin, {});

    expect(envelope.ok).toBeUndefined();

    expect(envelope.refusal?.code).toBe("unsupported");

    expect(envelope.refusal?.reason).toContain("no git repository");

  });

});

/**

 * The knowledge base through the real boundary and onto the rail: the

 * checked-in `knowledge_base` plugin answers through the WASM sandbox from

 * its embedded corpus (no mounts, no hosts), and the harness-side note

 * builder turns those answers into the attached context a turn carries.

 * The ranking itself is unit-tested against the corpus in

 * `plugins/knowledge-base/src/tests.rs`; this file proves the loaded

 * artifact and the note agree end to end.

 */

import { fileURLToPath } from "node:url";

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

import {

  invokePlugin,

  isRefusal,

  loadPluginFromManifest,

  type LoadedPlugin,

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

import {

  KNOWLEDGE_ATTACH_FLOOR,

  knowledgeHits,

  knowledgeNote,

  type KnowledgeHit,

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

const MANIFEST = fileURLToPath(

  new URL("../../../plugins/knowledge-base/manifest.json", import.meta.url),

);

const load = (): LoadedPlugin => {

  const outcome = loadPluginFromManifest(MANIFEST);

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

  return outcome;

};

const ask = async (plugin: LoadedPlugin, input: Record<string, unknown>): Promise<unknown> => {

  const outcome = await invokePlugin(plugin, new TextEncoder().encode(JSON.stringify(input)));

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

  return JSON.parse(new TextDecoder().decode(outcome));

};

describe("the knowledge_base plugin through the sandbox", () => {

  it("answers the earning question with the parked-economy stance", async () => {

    const plugin = load();

    const envelope = await ask(plugin, { query: "How can I earn bitcoin with this system?" });

    const hits = knowledgeHits(envelope);

    const top = hits[0];

    expect(top?.kind).toBe("stance");

    expect(top?.title).toBe("Earning bitcoin or money on OpenAgents");

    expect(top?.state).toContain("parked");

    expect(top?.date).toBeDefined();

  });

  it("has nothing to say about an unrelated topic", async () => {

    const plugin = load();

    const envelope = await ask(plugin, { query: "quaternion spline interpolation" });

    expect(knowledgeHits(envelope)).toEqual([]);

  });

  it("refuses a query with no matchable words, inside the envelope", async () => {

    const plugin = load();

    const envelope = (await ask(plugin, { query: "a & b" })) as {

      refusal?: { code: string };

    };

    expect(envelope.refusal?.code).toBe("unsupported");

  });

});

describe("the knowledge note on the rail", () => {

  const stance: KnowledgeHit = {

    kind: "stance",

    title: "Earning bitcoin or money on OpenAgents",

    body: "Earning is real but parked.",

    state: "deliberately parked",

    sources: ["docs/economy.md"],

    date: "2026-08-25",

    score: 12,

  };

  it("attaches a strong stance with its state and review date", () => {

    const note = knowledgeNote([stance]);

    expect(note).toContain("knowledge base");

    expect(note).toContain("deliberately parked");

    expect(note).toContain("reviewed 2026-08-25");

    expect(note).toContain("Earning is real but parked.");

  });

  it("stays silent below the floor and on no hits", () => {

    expect(knowledgeNote([])).toBeUndefined();

    expect(

      knowledgeNote([{ ...stance, score: KNOWLEDGE_ATTACH_FLOOR - 1 }]),

    ).toBeUndefined();

  });

  it("carries at most two hits and clips a runaway body", () => {

    const long = { ...stance, body: "x".repeat(5000) };

    const note = knowledgeNote([long, stance, stance]);

    expect(note).toBeDefined();

    expect((note ?? "").length).toBeLessThan(2000);

    expect((note ?? "").split("\n- ").length - 1).toBeLessThanOrEqual(2);

  });

  it("end to end: the sandbox answer becomes an attachable note", async () => {

    const plugin = load();

    const envelope = await ask(plugin, { query: "How can I earn bitcoin with this system?" });

    const note = knowledgeNote(knowledgeHits(envelope));

    expect(note).toContain("Earning bitcoin or money on OpenAgents");

    expect(note).toContain("parked");

  });

});

/**

 * The patch checker through the real boundary: the checked-in

 * `patch_check` plugin loaded from its own manifest — pure computation, no

 * mounts, so no fixture staging or manifest rewriting — and invoked with

 * JSON packets. The placement logic is unit-tested in

 * `plugins/patch-check/src/tests.rs`; this file proves the same behavior

 * holds through the WASM sandbox: a clean apply, drift reporting, and the

 * refusal envelope for a malformed diff.

 */

import { fileURLToPath } from "node:url";

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

import {

  invokePlugin,

  isRefusal,

  loadPluginFromManifest,

  type LoadedPlugin,

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

const MANIFEST = fileURLToPath(

  new URL("../../../plugins/patch-check/manifest.json", import.meta.url),

);

const load = (): LoadedPlugin => {

  const outcome = loadPluginFromManifest(MANIFEST);

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

  return outcome;

};

type HunkReport = {

  index: number;

  applies: boolean;

  at_line?: number;

  drift_lines?: number;

  reason?: string;

  mismatch?: string;

};

type Output = {

  applies: boolean;

  hunks: HunkReport[];

  applied_hunks: number;

  failed_hunks: number;

  preview?: string;

  preview_truncated?: boolean;

};

/** The guest envelope: `ok` on success, `refusal` as a value otherwise. */

type Envelope = { ok?: Output; refusal?: { code: string; reason: string } };

const invoke = async (plugin: LoadedPlugin, input: Record<string, unknown>): Promise<Envelope> => {

  const packet = new TextEncoder().encode(JSON.stringify(input));

  const outcome = await invokePlugin(plugin, packet);

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

  return JSON.parse(new TextDecoder().decode(outcome)) as Envelope;

};

const call = async (plugin: LoadedPlugin, input: Record<string, unknown>): Promise<Output> => {

  const envelope = await invoke(plugin, input);

  if (envelope.ok === undefined) throw new Error(JSON.stringify(envelope.refusal));

  return envelope.ok;

};

const DIFF =

  "--- a/greeting.txt\n" +

  "+++ b/greeting.txt\n" +

  "@@ -2,3 +2,3 @@\n" +

  " beta\n" +

  "-gamma\n" +

  "+GAMMA\n" +

  " delta\n";

describe("the patch_check plugin through the sandbox", () => {

  it("confirms a clean apply and returns the preview", async () => {

    const plugin = load();

    const out = await call(plugin, {

      diff: DIFF,

      content: "alpha\nbeta\ngamma\ndelta\nepsilon\n",

      include_preview: true,

    });

    expect(out.applies).toBe(true);

    expect(out.applied_hunks).toBe(1);

    expect(out.failed_hunks).toBe(0);

    expect(out.hunks).toHaveLength(1);

    expect(out.hunks[0]).toMatchObject({ index: 0, applies: true, at_line: 2 });

    expect(out.hunks[0]?.drift_lines).toBeUndefined();

    expect(out.preview).toBe("alpha\nbeta\nGAMMA\ndelta\nepsilon\n");

    expect(out.preview_truncated).toBeUndefined();

  });

  it("finds a drifted hunk within fuzz and reports the signed offset", async () => {

    const plugin = load();

    const out = await call(plugin, {

      diff: DIFF,

      content: "extra one\nextra two\nextra three\nalpha\nbeta\ngamma\ndelta\nepsilon\n",

    });

    expect(out.applies).toBe(true);

    expect(out.hunks[0]).toMatchObject({ applies: true, at_line: 5, drift_lines: 3 });

  });

  it("reports a hunk whose context is gone without refusing", async () => {

    const plugin = load();

    const out = await call(plugin, {

      diff: DIFF,

      content: "the file\nwas rewritten\nentirely\n",

    });

    expect(out.applies).toBe(false);

    expect(out.applied_hunks).toBe(0);

    expect(out.failed_hunks).toBe(1);

    expect(out.hunks[0]?.reason).toBe("context_not_found");

    expect(out.hunks[0]?.mismatch).toBe("beta");

    expect(out.preview).toBeUndefined();

  });

  it("refuses a malformed diff with the refusal envelope, naming the shape", async () => {

    const plugin = load();

    const envelope = await invoke(plugin, {

      diff: "this is prose, not a patch",

      content: "alpha\n",

    });

    expect(envelope.ok).toBeUndefined();

    expect(envelope.refusal?.code).toBe("unsupported");

    expect(envelope.refusal?.reason).toContain("@@ -start,count +start,count @@");

  });

});

/**

 * The repository mapper through the real boundary: the checked-in

 * `repo_map` plugin against a staged polyglot fixture workspace. The

 * mapper's logic is unit-tested against a fake host in

 * `plugins/repo-map/src/tests.rs`; this file proves the same behavior

 * holds through the WASM sandbox — the heuristic outline, exact-name

 * definition lookup, and word-bounded reference counting, with the

 * `node_modules` skip list honored. The manifest's `${workspace}` mount

 * is rewritten to the fixture directory, as every sandbox test does; the

 * host-side `${workspace}` resolution is proven elsewhere.

 */

import { mkdirSync, mkdtempSync, copyFileSync, readFileSync, writeFileSync } from "node:fs";

import { tmpdir } from "node:os";

import { join } from "node:path";

import { fileURLToPath } from "node:url";

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

import {

  invokePlugin,

  isRefusal,

  loadPluginFromManifest,

  type LoadedPlugin,

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

const MANIFEST = fileURLToPath(

  new URL("../../../plugins/repo-map/manifest.json", import.meta.url),

);

const WASM = fileURLToPath(

  new URL("../../../plugins/repo-map/repo_map.wasm", import.meta.url),

);

const stage = (): { plugin: LoadedPlugin } => {

  const dir = mkdtempSync(join(tmpdir(), "repo-map-"));

  const workspace = join(dir, "workspace");

  mkdirSync(join(workspace, "src"), { recursive: true });

  mkdirSync(join(workspace, "lib"), { recursive: true });

  mkdirSync(join(workspace, "node_modules", "pkg"), { recursive: true });

  writeFileSync(

    join(workspace, "src", "main.py"),

    "class Greeter:\n    def greet(self):\n        return greet_all()\n\ndef greet_all():\n    pass\n",

  );

  writeFileSync(

    join(workspace, "src", "app.ts"),

    "export function greetAll(): void {}\nexport class App {}\nexport const run = () => greetAll();\n",

  );

  writeFileSync(

    join(workspace, "src", "map.rs"),

    "pub fn greet_all() -> u32 { 0 }\npub fn twice() -> u32 { greet_all() + greet_all() }\nfn greet_all_extra() {}\n",

  );

  writeFileSync(

    join(workspace, "lib", "demo.ex"),

    "defmodule Demo do\n  def greet_all do\n    :ok\n  end\nend\n",

  );

  writeFileSync(join(workspace, "node_modules", "pkg", "index.js"), "function hidden() {}\n");

  const manifest = JSON.parse(readFileSync(MANIFEST, "utf8")) as {

    capabilities: { mounts: Array<{ path: string; readonly: true }> };

  };

  manifest.capabilities.mounts = [{ path: workspace, readonly: true }];

  writeFileSync(join(dir, "manifest.json"), JSON.stringify(manifest));

  copyFileSync(WASM, join(dir, "repo_map.wasm"));

  const outcome = loadPluginFromManifest(join(dir, "manifest.json"));

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

  return { plugin: outcome };

};

type Symbol = { kind: string; name: string; line: number; parent?: string };

type Output = {

  files?: Array<{ path: string; language: string; symbols: Symbol[] | null }>;

  definitions?: Array<{ path: string; kind: string; line: number }>;

  references?: Array<{ path: string; count: number }>;

  total?: number;

  files_seen: number;

  files_parsed: number;

  oversized: number;

  unreadable: number;

  truncated: boolean;

};

/** The guest envelope: `ok` on success, `refusal` as a value otherwise. */

type Envelope = { ok?: Output; refusal?: { code: string; reason: string } };

const invoke = async (plugin: LoadedPlugin, input: Record<string, unknown>): Promise<Envelope> => {

  const packet = new TextEncoder().encode(JSON.stringify(input));

  const outcome = await invokePlugin(plugin, packet);

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

  return JSON.parse(new TextDecoder().decode(outcome)) as Envelope;

};

const call = async (plugin: LoadedPlugin, input: Record<string, unknown>): Promise<Output> => {

  const envelope = await invoke(plugin, input);

  if (envelope.ok === undefined) throw new Error(JSON.stringify(envelope.refusal));

  return envelope.ok;

};

describe("the repo_map plugin through the sandbox", () => {

  it("outlines the workspace per language and skips node_modules", async () => {

    const { plugin } = stage();

    const out = await call(plugin, {});

    const paths = (out.files ?? []).map((file) => file.path);

    expect(paths).toEqual(["lib/demo.ex", "src/app.ts", "src/main.py", "src/map.rs"]);

    expect(paths.some((path) => path.includes("node_modules"))).toBe(false);

    const byPath = new Map((out.files ?? []).map((file) => [file.path, file]));

    expect(byPath.get("src/main.py")?.language).toBe("python");

    expect(

      byPath.get("src/main.py")?.symbols?.map((s) => [s.kind, s.name, s.line]),

    ).toEqual([

      ["class", "Greeter", 1],

      ["method", "greet", 2],

      ["function", "greet_all", 5],

    ]);

    expect(byPath.get("src/main.py")?.symbols?.[1]?.parent).toBe("Greeter");

    expect(

      byPath.get("src/app.ts")?.symbols?.map((s) => [s.kind, s.name]),

    ).toEqual([

      ["function", "greetAll"],

      ["class", "App"],

      ["function", "run"],

    ]);

    expect(

      byPath.get("lib/demo.ex")?.symbols?.map((s) => [s.kind, s.name]),

    ).toEqual([

      ["module", "Demo"],

      ["function", "greet_all"],

    ]);

    expect(

      byPath.get("src/map.rs")?.symbols?.map((s) => s.name),

    ).toEqual(["greet_all", "twice", "greet_all_extra"]);

    expect(out.files_seen).toBe(4);

    expect(out.files_parsed).toBe(4);

    expect(out.oversized).toBe(0);

    expect(out.truncated).toBe(false);

  });

  it("looks a definition up by exact name across languages", async () => {

    const { plugin } = stage();

    const out = await call(plugin, { symbol: "greet_all" });

    expect(out.definitions).toEqual([

      { path: "lib/demo.ex", kind: "function", line: 2 },

      { path: "src/main.py", kind: "function", line: 5 },

      { path: "src/map.rs", kind: "function", line: 1 },

    ]);

  });

  it("counts whole-word references, skipping definition lines", async () => {

    const { plugin } = stage();

    const out = await call(plugin, { symbol: "greet_all", count_references: true });

    // map.rs: two calls in `twice`; main.py: one call in `greet`. The

    // definitions and `greet_all_extra` never count.

    expect(out.references).toEqual([

      { path: "src/map.rs", count: 2 },

      { path: "src/main.py", count: 1 },

    ]);

    expect(out.total).toBe(3);

  });

  it("refuses to count references without a symbol", async () => {

    const { plugin } = stage();

    const envelope = await invoke(plugin, { count_references: true });

    expect(envelope.ok).toBeUndefined();

    expect(envelope.refusal?.code).toBe("unsupported");

    expect(envelope.refusal?.reason).toContain("symbol");

  });

});

/**

 * The `repo_tree` plugin through the real boundary, plus the parameterized

 * workspace mount it rides on.