@jini-ai/agent-plugins 0.4.1 → 0.4.3

package/dist/lifecycle/search.d.ts

@@ -1,18 +1,83 @@
 /** Extracted from the host plugin lifecycle. Effects are supplied per host context. */
 import type { AgentPluginLifecyclePorts } from "./ports.js";
+/**
+ * @file Pure relevance ranking for `search_agent_plugin_local` — turns one workspace's already-
+ * resolved installed Agent Plugins into scored matches for a free-text query. No filesystem or
+ * network I/O; `tool-registrations.ts` is the caller that reads disk and hands this module already-
+ * resolved {@link AgentPluginSearchCandidate}s.
+ *
+ * ---------------------------------------------------------------------------
+ * Why field-weighted substring matching, not FTS5/BM25
+ * ---------------------------------------------------------------------------
+ * `assistant/tool-catalog-query.ts` (the `search_tools` index this tool itself is found through)
+ * seeds a real SQLite FTS5 table because its catalog is runtime-registered and can be large (170+
+ * tools, changing per boot/workspace). The catalog THIS function ranks over is different in kind:
+ * one workspace's own installed Agent Plugins, read fresh off disk on every call, realistically a
+ * handful of entries. `assistant/component-catalog-query.ts` (`search_components`) already
+ * establishes the house precedent for exactly this shape — "a handful of manifests doesn't warrant
+ * a database for substring matching" — and ranks with plain `haystack.includes(term)` scoring. This
+ * module reuses that same technique rather than inventing a second one, with one deliberate
+ * difference from that precedent: per-field WEIGHTS instead of one flat merged haystack.
+ *
+ * The weights are not decorative. `plugin.json` (agent-plugins.org) carries a `keywords` array
+ * that `component-catalog-query.ts`'s manifests have no equivalent of — author-curated discovery
+ * terms, the exact same "operator asks in different words than the code uses" gap
+ * `tool-search-keywords.ts`'s own header describes at length for native tools. A keyword hit is a
+ * stronger, more deliberate signal than an incidental word landing inside free-form prose, so it is
+ * scored higher. The id (`pluginId`) is scored highest of all: it is what a caller actually types
+ * back to `plugins_set_enabled`-shaped tools next, so an exact or near match on it (a caller typing
+ * "site-compliance" or "compliance") must win outright — mirroring `tool-catalog.ts`'s own
+ * documented "id weighted 6x description" ratio for the identical reason (id IS the thing quoted
+ * back). Skill name/summary text is weighted lowest: it is the broadest, noisiest vocabulary (every
+ * bundled skill's own frontmatter description folded in), valuable for recall on a query that names
+ * a capability rather than a plugin ("shadcn components") but not something that should let one
+ * verbose plugin outrank a plugin whose own id/keywords/description directly named the query.
+ * Plugin `description` sits in between: real author prose, but not curated tags and not the
+ * identity string itself.
+ *
+ * A plugin's own `version`, `enabled` state, and MCP server ids are carried through on every match
+ * for the caller to report, but are NOT scored — none of them are text a caller plausibly searches
+ * for ("find me the plugin on version 1.1.0" is not a real query), and an MCP server id is often an
+ * arbitrary machine-chosen string with no natural-language relationship to what an operator would
+ * type.
+ *
+ * @complexity `rankInstalledAgentPlugins` is O(c * t * f) — c candidates, t query terms, f fields
+ * (a fixed constant, 4) — so effectively O(c * t): linear in the installed-plugin count and query
+ * length, both small and locally bounded (there is no user-controlled upper bound on installed-
+ * plugin count today, matching the same unbounded-but-locally-small shape
+ * `loadInstalledAgentPluginToolSources` already accepts for the very same catalog).
+ */
+/** One installed plugin's skill, reduced to what search ranks and reports on — never the full
+ *  SKILL.md body (that stays behind `agent_plugin_<pluginId>`'s own tool, which a caller reaches
+ *  once search has told it which plugin to ask). */
 export interface AgentPluginSearchSkill {
     readonly name: string;
+    /** Plain-language explainer from the host extension namespace in `plugin.json`: `summary`, for the admin list
+     *  route only — not ranked, and the search tool's own response projection leaves it out. */
     readonly summary: string;
 }
+/** One installed plugin, already resolved into everything the ranker and the response need — no
+ *  `packageRoot`/`skillPath`/any other host-filesystem detail (see `tool-registrations.ts`'s own
+ *  SECURITY note for why: this candidate shape is what actually reaches the model). */
 export interface AgentPluginSearchCandidate {
     readonly pluginId: string;
     readonly version?: (string) | undefined;
+    /** Human-facing title from the host extension namespace in `plugin.json`: `displayName`, when the package set one. */
+    readonly displayName?: string | undefined;
+    readonly summary?: string | undefined;
     readonly description?: (string) | undefined;
     readonly keywords: readonly string[];
+    readonly id?: string | undefined;
+    readonly provides?: readonly string[] | undefined;
+    /** Whether this workspace currently has the plugin enabled — reflects `activation.ts`'s
+     *  absent-means-active default, same as everywhere else this codebase reads activation state. */
     readonly enabled: boolean;
     readonly skills: readonly AgentPluginSearchSkill[];
+    /** Server ids only, from the package's own `mcp.json` — never transport config (`command`/`args`/
+     *  `env` can carry secrets; see `capability-projection.ts`'s identical restraint). */
     readonly mcpServerIds: readonly string[];
 }
+/** One ranked result: a candidate plus the score it earned against a specific query. */
 export interface AgentPluginSearchMatch extends AgentPluginSearchCandidate {
     readonly score: number;
 }

package/dist/lifecycle/search.js

@@ -4,16 +4,22 @@ function buildModule(ports) {
     const KEYWORD_FIELD_WEIGHT = 4;
     const DESCRIPTION_FIELD_WEIGHT = 2;
     const SKILL_FIELD_WEIGHT = 1;
+    /** Lowercase, whitespace-split query terms — mirrors `component-catalog-query.ts`'s identical
+   *  `query.toLowerCase().split(/\s+/).filter(Boolean)`, the house tokenizer for this "small local
+   *  catalog, plain string matching" shape. Empty/whitespace-only input yields no terms. */
     function tokenize(query) {
         return query
             .toLowerCase()
             .split(/\s+/)
             .filter((term) => term.length > 0);
     }
+    /** One candidate's scoreable text, one entry per weighted field — see this file's header for why
+   *  each weight is what it is. Split out of {@link scoreCandidate} so the field/weight pairing is a
+   *  plain, independently-readable list rather than interleaved with the scoring loop itself. */
     function fieldHaystacks(candidate) {
         return [
-            { text: candidate.pluginId.toLowerCase(), weight: ID_FIELD_WEIGHT },
-            { text: candidate.keywords.join(" ").toLowerCase(), weight: KEYWORD_FIELD_WEIGHT },
+            { text: `${candidate.pluginId} ${candidate.id ?? ""}`.toLowerCase(), weight: ID_FIELD_WEIGHT },
+            { text: [...candidate.keywords, ...(candidate.provides ?? [])].join(" ").toLowerCase(), weight: KEYWORD_FIELD_WEIGHT },
             { text: (candidate.description ?? "").toLowerCase(), weight: DESCRIPTION_FIELD_WEIGHT },
             {
                 text: candidate.skills.map((skill) => `${skill.name} ${skill.summary}`).join(" ").toLowerCase(),
@@ -21,10 +27,33 @@ function buildModule(ports) {
             },
         ];
     }
+    /** Sums, over every query term and every weighted field, the field's weight whenever that field's
+   *  text contains the term as a substring — the same `includes()` test `component-catalog-query.ts`
+   *  uses, just per-field instead of one merged haystack. A term can score against more than one field
+   *  (e.g. a keyword that is also echoed in the description) — that is intentional: a plugin whose
+   *  author reinforced a concept in both its keywords and its prose is a genuinely stronger match, not
+   *  a bug to dedupe away. */
     function scoreCandidate(candidate, terms) {
         const haystacks = fieldHaystacks(candidate);
         return terms.reduce((total, term) => total + haystacks.reduce((fieldTotal, haystack) => (haystack.text.includes(term) ? fieldTotal + haystack.weight : fieldTotal), 0), 0);
     }
+    /**
+   * Ranks already-resolved installed-plugin candidates against a free-text query.
+   *
+   * @param query - Free-text search phrase. An empty or whitespace-only query has no terms to match
+   * against and always returns no matches — this function never falls back to "return everything",
+   * matching `search_components`' own "no query, no hits" behavior rather than the different (and
+   * here wrong) choice of treating an empty query as "list all installed".
+   * @param candidates - One workspace's installed plugins, already resolved (disk already read).
+   * @param limit - Max matches to return, already clamped by the caller (mirrors
+   * `component-catalog-tool.ts`'s handler, which owns the clamp so this function can stay a pure
+   * "given these inputs, rank them" step with no knowledge of the tool's own schema bounds).
+   * @returns Matches with score > 0, sorted by score descending, truncated to `limit`. A candidate
+   * that scores 0 (no term matched anything) is dropped, not returned at the bottom — the caller's own
+   * "N installed, 0 matched" framing is what tells the model the workspace is not empty even when a
+   * query matches nothing.
+   * @complexity See this file's header.
+   */
     function rankInstalledAgentPlugins(query, candidates, limit) {
         const terms = tokenize(query);
         if (terms.length === 0)

package/dist/lifecycle/seed-bundled.d.ts

@@ -1,10 +1,13 @@
 import type { AgentPluginLayout } from "./layout.js";
-import { type RetiredAgentPluginOutcome } from "./retire-bundled.js";
+import type { RetiredAgentPluginOutcome } from "./retire-bundled.js";
 import type { AgentPluginLifecyclePorts } from "./ports.js";
 export type SeededAgentPluginOutcome = {
     readonly pluginId: string;
     readonly status: "seeded";
     readonly archiveDigest: string;
+    /** True when this boot wrote the initial record (disabled, or enabled for
+     *  {@link BUNDLED_AGENT_PLUGINS_SEEDED_ENABLED}); false when a decision already existed and was
+     *  preserved. */
     readonly activationRecorded: boolean;
 } | {
     readonly pluginId: string;
@@ -12,12 +15,26 @@ export type SeededAgentPluginOutcome = {
     readonly reason: string;
 };
 export interface SeedBundledAgentPluginsResult {
+    /** Directory holding one subdirectory per bundled plugin. `deps.ts`'s `bundledAgentPluginsDir()`
+     *  in production. */
     readonly sourceRoot: string;
     readonly outcomes: readonly SeededAgentPluginOutcome[];
+    /** Why this boot could not record which digest it published for each plugin
+     *  (`bundled-digests.ts`), or absent when it did. Reported rather than thrown, for the same
+     *  failure-isolation reason every per-plugin failure is: a workspace whose ledger cannot be
+     *  written still has every package installed and every activation decision intact — it only falls
+     *  back to refusing a multi-digest plugin id, which is exactly the behaviour that predates the
+     *  ledger. */
     readonly ledgerFailure?: (string) | undefined;
+    /** One outcome per retired bundled plugin (`retire-bundled.ts`), run after seeding and the ledger so
+     *  each successor's own record already exists. Empty when the activation pre-flight refused. */
     readonly retirements: readonly RetiredAgentPluginOutcome[];
 }
 export interface SeedBundledAgentPluginsRequired {
+    /** The INSTANCE-level layout (`resolveAgentPluginLayout()`), not a pre-resolved workspace one —
+     *  `installAgentPlugin` resolves `forWorkspace(workspaceId)` itself, atomically, and this
+     *  function passes both through unchanged so that guarantee is not weakened in transit. See
+     *  `install.ts`'s SECURITY note on `InstallAgentPluginRequired.layout`. */
     readonly layout: AgentPluginLayout;
     readonly workspaceId: string;
     readonly sourceRoot: string;

package/dist/lifecycle/seed-bundled.js

@@ -1,10 +1,88 @@
+/**
+ * @file `seedBundledAgentPlugins()` — installs the Agent Plugins that ship WITH the host into a
+ * workspace's own package store, and records each one INACTIVE until an operator says otherwise
+ * (except the few core paths depend on, `BUNDLED_AGENT_PLUGINS_SEEDED_ENABLED`, which seed active).
+ *
+ * ---------------------------------------------------------------------------
+ * "Bundled but inactive", concretely
+ * ---------------------------------------------------------------------------
+ * Bundled: the package's real files are tracked in this repository under `content/agent-plugins/<id>/`
+ * and copied into `dist/` by `npm run build`, exactly like `content/themes/`. A fresh install has them
+ * without downloading anything.
+ *
+ * Inactive: seeding writes `{ enabled: false, origin: "bundled" }` into the workspace's activation
+ * record (`activation.ts`) BEFORE the package can be read by anything, and the two places that
+ * consume installed plugins both consult that record:
+ *
+ * - `tool-registrations.ts` — will not register its `agent_plugin_<id>` tool;
+ * - `resolve-agent-plugin-refs.ts` — refuses to inject it even if a composer chip pins it by id.
+ *
+ * (A third surface, `capability-source.ts`'s `capability_search` discovery, was gated here too
+ * until that tool pair was removed 2026-08-26 — see
+ * `ADS-memory/knowledge/2026-08-26-removed-capability-search.md`.)
+ *
+ * So "inactive" means genuinely unexecutable, not merely unadvertised: its skills never reach a
+ * prompt, and its tools and MCP servers are never registered.
+ *
+ * It does NOT mean hidden from the operator. The admin Agent Plugins screen lists every installed
+ * plugin, with an inactive one's switch shown off, so a bundled plugin can be found and turned on
+ * there (owner decision, 2026-09-13; before it, that screen's default tab listed only active ones).
+ * Listing only READS the activation record, so the "absent means active" hazard described below is
+ * unaffected.
+ *
+ * ---------------------------------------------------------------------------
+ * Why it runs on every boot
+ * ---------------------------------------------------------------------------
+ * Seeding is idempotent twice over: `installAgentPlugin` short-circuits when the content digest is
+ * already published, and `recordBundledAgentPluginIfAbsent` never overwrites an existing decision.
+ * Re-running it therefore costs one directory walk and one hash, and buys two things a one-shot
+ * first-run seed would not:
+ *
+ * 1. A product upgrade that ships a NEW bundled plugin, or a NEW VERSION of one, reaches existing
+ *    workspaces without a migration step.
+ *
+ *    The second half of that claim was FALSE IN EFFECT until 2026-09-18, and the correction is the
+ *    reason `bundled-digests.ts` exists. The package store is content-addressed and nothing retires
+ *    an entry, so a revised bundled plugin installs ALONGSIDE its predecessor rather than replacing
+ *    it — after which both consumption surfaces refused the plugin outright as ambiguous
+ *    (`resolve-agent-plugin-refs.ts`'s "refusing to guess which one to use",
+ *    `tool-registrations.ts`'s `poisonedPluginIds`). An upgrade did reach the workspace; it also
+ *    silently broke the plugin. What makes the claim true now is the ledger this function writes
+ *    below: the seed RECORDS which digest this build published, so the read side has the build's own
+ *    answer to "which one" instead of a guess. The superseded bytes stay on disk — see
+ *    `bundled-digests.ts`'s header for why nothing is deleted, and this file's own report for what
+ *    an operator still has to prune by hand.
+ * 2. Deleting `activations.json` re-creates the bundled plugin's DISABLED record. Without the
+ *    re-run, deleting that file would silently promote every bundled plugin to active, because
+ *    `isAgentPluginActive`'s "absent means active" default is what keeps operator-installed plugins
+ *    working. The boot-time re-seed is what closes that direction.
+ *
+ *    A file that is PRESENT but unreadable is a different case from a deleted one, and is not
+ *    treated the same way (t91 F1.1, 2026-09-16): seeding refuses outright rather than install
+ *    around the fault, and every bundled plugin comes back `failed` with the recovery text
+ *    `activation.ts`'s `AgentPluginActivationsUnreadableError` gives — see this file's header,
+ *    "Failure isolation" below, and `activation.ts`'s own header, "Writers never rewrite what they
+ *    could not read".
+ *
+ * ---------------------------------------------------------------------------
+ * Failure isolation
+ * ---------------------------------------------------------------------------
+ * One unusable bundled package must never stop a workspace from booting or hide the others. Each is
+ * seeded independently and its failure is captured into the returned report, not thrown. The caller
+ * decides whether to log it; nothing here writes to the console, so this stays a pure-ish function
+ * a test can assert on directly.
+ *
+ * Architectural role:
+ * Composition over `bundled-source-archive.ts` (directory to archive), `install.ts`
+ * (`installAgentPlugin`, where every extraction guarantee lives), and `activation.ts` (the record).
+ * No guarantee of its own.
+ */
 import { createPersistentStateModule } from "./persistent-state.js";
 import path from "node:path";
 import { createActivationModule } from "./activation.js";
 import { createBundledDigestsModule } from "./bundled-digests.js";
 import { createBundledSourceArchiveModule } from "./bundled-source-archive.js";
 import { createInstallModule } from "./install.js";
-import {} from "./retire-bundled.js";
 import { createRetireBundledModule } from "./retire-bundled.js";
 function buildModule(ports) {
     const readdir = ports.filesystem.readdir.bind(ports.filesystem);
@@ -14,13 +92,38 @@ function buildModule(ports) {
     const { createBundledSourceArchiveReader, packAgentPluginDirectory } = createBundledSourceArchiveModule(ports);
     const { installAgentPlugin } = createInstallModule(ports);
     const { retireBundledAgentPlugins } = createRetireBundledModule(ports);
+    /**
+   * Installs every bundled Agent Plugin into one workspace and records each inactive-by-default,
+   * except {@link BUNDLED_AGENT_PLUGINS_SEEDED_ENABLED}.
+   *
+   * @returns A per-plugin report. An absent or unreadable `sourceRoot` yields an empty `outcomes`
+   * list rather than an error: a build that shipped no bundled plugins is a legitimate configuration,
+   * and a self-hosted operator who deleted the directory has made a choice this function should not
+   * override by crashing.
+   * @throws Nothing. Every per-plugin failure is captured into the report.
+   * @complexity O(p) plugins, each O(f) files and O(b) bytes — all bounded by
+   * `bundled-source-archive.ts`'s file cap and `install.ts`'s own byte caps.
+   */
+    // The migration must finish before new installs, including bundled packages, are published.
+    // Rejected legacy entries are preserved in quarantine and count as handled. An incomplete run
+    // means a move/quarantine failed; a held lock also refuses seeding until migration can finish.
+    // ONE strict pre-flight read BEFORE any install — so a bundled package never lands on disk
+    // without the activation record that would keep it inactive (this file's header). Every bundled
+    // plugin is reported failed with the SAME reason, rather than attempting each one and hitting the
+    // identical fault p times.
+    // AFTER every install, never before: the ledger names digests, and a digest is only worth naming
+    // once its bytes are actually on disk for this workspace.
+    // AFTER seeding and the ledger: a retired plugin's successor is itself bundled, so its record and
+    // its ledger entry exist by now, and the retirement only has to decide whether to switch it on.
     async function seedBundledAgentPlugins(required) {
         const { layout, workspaceId, sourceRoot } = required;
         const pluginDirNames = await listBundledPluginDirs(sourceRoot);
         try {
-            const migration = await createPersistentStateModule(ports).migrate({ workspaceRoot: layout.forWorkspace({ workspaceId }).root });
+            const migration = ports.migrateBeforeSeed
+                ? await ports.migrateBeforeSeed({ layout, workspaceId }, {})
+                : await createPersistentStateModule(ports).migrate({ workspaceRoot: layout.forWorkspace({ workspaceId }).root });
             if (!migration.complete)
-                throw new Error('Legacy plugin migration incomplete; see migration events');
+                throw new Error('Legacy plugin layout migration has unfinished filesystem moves; see boot log');
         }
         catch (error) {
             const reason = error instanceof Error ? error.message : String(error);
@@ -42,6 +145,11 @@ function buildModule(ports) {
         const retirements = await retireBundledAgentPlugins({ layout, workspaceId });
         return { sourceRoot, outcomes, retirements, ...(ledgerFailure !== undefined ? { ledgerFailure } : {}) };
     }
+    /** Records which digest this boot published for each plugin that seeded successfully, and returns
+   *  why it could not, rather than throwing — {@link seedBundledAgentPlugins}'s own contract is
+   *  "@throws Nothing", and a ledger this boot failed to write costs the workspace nothing it had
+   *  before the ledger existed.
+   *  @complexity One file read and one atomic write. */
     async function recordSeededDigests(workspaceRoot, outcomes) {
         try {
             await recordBundledAgentPluginDigests({
@@ -54,6 +162,11 @@ function buildModule(ports) {
             return error instanceof Error ? error.message : String(error);
         }
     }
+    /** Why nothing may be seeded into this workspace right now, or `undefined`. One strict read BEFORE
+   *  any install, so a bundled package never lands on disk without the record that keeps it inactive.
+   *  Catches everything (including `forWorkspace`'s own throw) to keep this function's own contract
+   *  "@throws Nothing", matching {@link seedBundledAgentPlugins}'s own guarantee.
+   *  @complexity One file read. */
     async function activationsRefusal(layout, workspaceId) {
         try {
             await assertAgentPluginActivationsWritable(layout.forWorkspace({ workspaceId }).root);
@@ -63,6 +176,9 @@ function buildModule(ports) {
             return error instanceof Error ? error.message : String(error);
         }
     }
+    // The plugin's OWN manifest name, not the directory name — `install.ts` reads the id from
+    // `plugin.json`, and every consumer keys activation off that same id. Using the folder name
+    // here would produce a record nothing ever consults if the two ever disagreed.
     async function seedOne(args) {
         try {
             const packed = await packAgentPluginDirectory(args.sourceDir);
@@ -89,6 +205,17 @@ function buildModule(ports) {
             };
         }
     }
+    /**
+   * Lists the subdirectories of `sourceRoot` that actually look like Agent Plugin packages (they hold
+   * a `plugin.json` at their own root, which is where `indexInstalledRoot` looks for it).
+   *
+   * Filtering here rather than letting the installer reject them keeps a stray `README.md` or an
+   * editor's scratch directory from showing up in the report as a failed plugin.
+   *
+   * @complexity O(d) in the subdirectory count.
+   */
+    // A retired id is never seeded, even from a stale build that still carries its directory —
+    // otherwise every boot would reinstall it only for `retire-bundled.ts` to remove it again.
     async function listBundledPluginDirs(sourceRoot) {
         let entries;
         try {
@@ -109,6 +236,7 @@ function buildModule(ports) {
                     dirs.push(entry.name);
             }
             catch {
+                // No plugin.json: not a package. Silently skipped — see this function's own doc.
             }
         }
         return dirs.sort();

package/dist/lifecycle/set-enabled.d.ts

@@ -1,4 +1,9 @@
 import type { AgentPluginLifecyclePorts } from "./ports.js";
+/**
+ * The id named is not installed in this workspace. A distinct class rather than a bare `Error` so
+ * each caller can map it to its own boundary's vocabulary — 404 `AGENT_PLUGIN_NOT_FOUND` at the
+ * admin route, `ToolInputError` at the tool — without either one string-matching a message.
+ */
 export declare class AgentPluginNotInstalledError extends Error {
     constructor({ pluginId }: {
         readonly pluginId: string;
@@ -8,10 +13,12 @@ export interface SetAgentPluginEnabledInput {
     readonly workspaceId: string;
     readonly pluginId: string;
     readonly enabled: boolean;
+    /** Recorded as the activation record's updatedBy. The authenticated principal, never a constant. */
     readonly actor: string;
 }
 export interface SetAgentPluginEnabledResult {
     readonly pluginId: string;
+    /** As actually written and read back, not as requested. */
     readonly enabled: boolean;
 }
 /** Internal composition; one state/queue instance per injected host context. */

package/dist/lifecycle/set-enabled.js

@@ -1,6 +1,11 @@
 /** Extracted from the host plugin lifecycle. Effects are supplied per host context. */
 import { createActivationModule } from "./activation.js";
 import { createResolveAgentPluginRefsModule } from "./resolve-agent-plugin-refs.js";
+/**
+ * The id named is not installed in this workspace. A distinct class rather than a bare `Error` so
+ * each caller can map it to its own boundary's vocabulary — 404 `AGENT_PLUGIN_NOT_FOUND` at the
+ * admin route, `ToolInputError` at the tool — without either one string-matching a message.
+ */
 export class AgentPluginNotInstalledError extends Error {
     constructor({ pluginId }) {
         super(`agent plugin '${pluginId}' is not installed in this workspace`);

package/dist/lifecycle/trusted-plugin-files.d.ts

@@ -1,18 +1,56 @@
 import type { AgentPluginLifecyclePorts } from "./ports.js";
+/**
+ * @file The shared trust gate for plugin-contributed files that core reads or runs: deploy targets
+ * (`features/deployments/deploy-targets/registry.ts`), deploy-config generators, credential
+ * scheme rules, mail adapters (`./mail-adapter-registry.ts`) and git-host providers
+ * (`features/source-control/provider-registry.ts`). One place decides which installed Agent Plugin packages core may take a contribution
+ * from, so every seam applies the same rules.
+ *
+ * A plugin opts in to a seam by shipping that seam's file at its package root (e.g.
+ * a host-supplied deploy-target descriptor filename). {@link findTrustedPluginPackages} judges each package that ships it
+ * against the gates:
+ * 1. ACTIVE by the fail-closed reader (`resolveAgentPluginActivation`) when the seam asks for it
+ *    (`requireActive`). An unreadable activation record refuses rather than reading as consent. A
+ *    data-only seam may skip this gate; its own file header must say why.
+ * 2. Its installed digest is the one `bundled-digests.json` records for it, the build's own seed.
+ *    An operator-installed package, or a tampered copy under a bundled id, never contributes
+ *    (owner decision 2026-09-29: third-party contributions come later). Always applied.
+ *
+ * {@link importContainedModule} is the third gate for seams that run code: the module path must
+ * resolve inside the package root on disk (`assertContainedOnDisk`) and end in `.mjs` (the caller's
+ * descriptor parser checks the extension), so no `package.json` above the install directory can make
+ * Node read it as CommonJS.
+ *
+ * Failure isolation: a refused package comes back as a refusal verdict, never thrown. Only a filesystem
+ * fault listing the workspace's package directory itself propagates.
+ *
+ * Architectural role: `features/agent-plugins` capability. Depends only on this feature's own
+ * install, activation and path modules; the seams depend on it, nothing here names one.
+ */
+/** A package a seam may read: whose it is and where its files live. */
 export interface TrustedPluginPackage {
     readonly pluginId: string;
     readonly packageRoot: string;
 }
 export interface TrustedPluginPackagesQuery {
     readonly workspaceId: string;
+    /** The file a plugin ships at its root to opt in to this seam. */
     readonly filename: string;
+    /** Plural noun for refusal text, e.g. `"deploy targets"`: "deploy targets from 'x' were not loaded: …". */
     readonly contribution: string;
+    /** Apply the activation gate (see this file's header, gate 1). */
     readonly requireActive: boolean;
+    /** Return verdicts sorted by plugin id instead of installed order. */
     readonly orderByPluginId?: (boolean) | undefined;
+    /** Hears each package the activation gate skips as switched off, e.g. to read its seam file as
+     *  data and name the plugin in a refusal. Never called without `requireActive`. */
     readonly onInactive?: ((required: {
         readonly plugin: TrustedPluginPackage;
     }) => Promise<void>) | undefined;
 }
+/** One installed package that ships the seam's file: trusted, or refused with the full refusal line.
+ *  Returned in installed order (or plugin-id order, see `orderByPluginId`) so a seam that interleaves its own per-package refusals keeps them in
+ *  the same order as the gate's. */
 export type TrustedPluginVerdict = {
     readonly trusted: TrustedPluginPackage;
 } | {

package/dist/lifecycle/trusted-plugin-files.js

@@ -12,6 +12,15 @@ function buildModule(ports) {
     const { preferBundledAgentPluginDigests, readBundledAgentPluginDigests } = createBundledDigestsModule(ports);
     const { assertContainedOnDisk } = createPackagePathsModule(ports);
     const { listInstalledPlugins } = createResolveAgentPluginRefsModule(ports);
+    /**
+   * A verdict for every installed package in this workspace that ships `query.filename`, in
+   * installed order (bundled digests preferred when a plugin has more than one installed digest).
+   * A switched-off plugin is skipped silently (only `onInactive` hears it); every other refusal is reported.
+   *
+   * @throws Nothing for a plugin-level fault; only a filesystem fault listing the workspace's package
+   * directory itself propagates.
+   * @complexity O(p) installed plugins, one activation read each for a plugin that ships the file.
+   */
     async function findTrustedPluginPackages(query) {
         const layout = ports.layout.forWorkspace({ workspaceId: query.workspaceId });
         const bundled = await readBundledAgentPluginDigests(layout.root);
@@ -32,6 +41,8 @@ function buildModule(ports) {
         }
         return verdicts;
     }
+    /** Why one installed package may not contribute (`"inactive"` = skip silently), or `null` when it may.
+   *  @complexity O(1) beyond one activation read. */
     async function trustRefusal(query, plugin, bundledDigest, workspaceRoot) {
         if (query.requireActive) {
             const activation = await resolveAgentPluginActivation(workspaceRoot, plugin.pluginId);
@@ -45,10 +56,17 @@ function buildModule(ports) {
         }
         return null;
     }
+    /** Reads one file at a trusted package's root as UTF-8. @complexity O(n) in the file size. */
     async function readTrustedPluginFile(plugin, filename) {
         const absolute = await assertContainedOnDisk(plugin.packageRoot, filename);
         return readFile(absolute, "utf8");
     }
+    /**
+   * Imports one module from a trusted package after the containment check. Returns the module's
+   * default export, or the refusal reason. The caller validates the export's shape.
+   *
+   * @complexity One `realpath` walk plus one dynamic import (cached by Node per file URL).
+   */
     async function importContainedModule(plugin, modulePath) {
         let resolved;
         try {

package/dist/lifecycle/types.d.ts

@@ -6,8 +6,22 @@ export interface InstalledAgentPluginSkill {
     readonly skillPath: string;
 }
 export interface InstalledAgentPlugin {
+    readonly id?: string | undefined;
+    readonly provides?: readonly string[] | undefined;
     readonly pluginId: string;
     readonly version?: (string) | undefined;
+    /** the host extension namespace in `plugin.json`: `displayName` — the human-facing title when the id alone reads
+     *  wrong ("deploy" shows as "Deploy Online"). Lives under the spec's host-extension namespace, not
+     *  a top-level field, because the spec has no title field and `name` is the stable id that
+     *  activations, tool ids and ledgers key on — renaming it would churn all of those. Absent means
+     *  callers title-case the id. */
+    readonly displayName?: string | undefined;
+    /** the host extension namespace in `plugin.json`: `summary` — a short plain-language explainer for the site owner,
+     *  shown in the admin in place of the spec `description`. That `description` stays the
+     *  agent-facing text (search ranks it and returns it to the model), so it can stay dense and
+     *  technical; this field is never ranked and never reaches the model. Blank lines separate
+     *  paragraphs. Absent means the admin shows the description. */
+    readonly summary?: string | undefined;
     readonly description?: (string) | undefined;
     readonly keywords?: (readonly string[]) | undefined;
     readonly author?: string | PluginManifestAuthor | undefined;

package/dist/lifecycle/uninstall.d.ts

@@ -1,15 +1,20 @@
 import type { AgentPluginLayout } from "./layout.js";
 import type { AgentPluginLifecyclePorts } from "./ports.js";
+/** The plugin id has no installed package on disk for this workspace. */
 export declare class AgentPluginNotFoundError extends Error {
     constructor({ message }: {
         readonly message: string;
     }, optional?: ErrorOptions);
 }
+/** The plugin is bundled with the host — see this file's header for why that is permanent, not merely
+ *  "nothing to remove". */
 export declare class AgentPluginNotUninstallableError extends Error {
     constructor({ message }: {
         readonly message: string;
     }, optional?: ErrorOptions);
 }
+/** The installed archives for this plugin id are no longer exactly the ones a confirmed preview listed —
+ *  see `UninstallAgentPluginOptional.confirmedPreview`. Nothing was removed. */
 export declare class AgentPluginChangedSincePreviewError extends Error {
     constructor({ message }: {
         readonly message: string;
@@ -21,22 +26,46 @@ export interface UninstallAgentPluginRequired {
     readonly pluginId: string;
 }
 export interface UninstallAgentPluginOptional {
+    /** The preview a human confirmed. When given, the uninstall refuses, removing nothing, unless the digests it
+     *  resolves now are exactly this preview's `archiveDigests`: a confirmation is consent to remove what was
+     *  resolved for the dialog, not whatever the id names by the time the answer arrives (t91 F2.2). */
     readonly confirmedPreview?: (AgentPluginUninstallPreview) | undefined;
+    /** Only the browser-confirmed choice may delete persistent state. Off by default. */
     readonly deleteMemory?: boolean | undefined;
+    /** INTERNAL — `retire-bundled.ts` only, never an agent tool or HTTP route. Skips the bundled refusal
+     *  (this file's header, item 2) and nothing else: that refusal exists because a bundled plugin is
+     *  re-seeded on every boot, which stops being true once the host no longer ships its source
+     *  (`RETIRED_BUNDLED_AGENT_PLUGINS`). The malformed-entry refusal still applies. */
     readonly retiredBundled?: (boolean) | undefined;
 }
 export interface UninstallAgentPluginResult {
     readonly pluginId: string;
+    /** Every installed archive digest removed for this plugin id — normally exactly one. All matching
+     *  digests are removed: uninstall's job is to make the plugin genuinely gone, so unlike the tool
+     *  loader, which must pick ONE to serve, there is no "which one" question here. */
     readonly removedDigests: readonly string[];
 }
+/** What an uninstall of one plugin would remove, in a form safe to show a human: no host path. */
 export interface AgentPluginUninstallPreview {
     readonly pluginId: string;
+    /** Distinct manifest versions across the matching digests; empty when none declares one. */
     readonly versions: readonly string[];
     readonly archiveDigests: readonly string[];
 }
+/** A reversible staged package and its original permissions; shared by uninstall and replacement. */
+/** One package root renamed aside, and what restoring it takes: the path it must go back to, and the
+ *  mode it carried before staging unfroze its root directory. */
+export interface StagedTree {
+    readonly quarantined: string;
+    readonly original: string;
+    readonly originalMode: number;
+}
 /** Internal composition; one state/queue instance per injected host context. */
 export declare function createUninstallModule(ports: AgentPluginLifecyclePorts): {
     previewAgentPluginUninstall: (required: UninstallAgentPluginRequired) => Promise<AgentPluginUninstallPreview>;
     uninstallAgentPlugin: (required: UninstallAgentPluginRequired, optional?: UninstallAgentPluginOptional) => Promise<UninstallAgentPluginResult>;
+    stageForRemoval: (packagesDir: string, packageRoot: string) => Promise<StagedTree>;
+    restoreStagedTrees: (staged: readonly StagedTree[], cause: unknown) => Promise<unknown>;
+    removeFrozenPackageTree: (root: string) => Promise<void>;
 };
 //# sourceMappingURL=uninstall.d.ts.map