@jini-ai/agent-plugins 0.4.1 → 0.4.2

package/dist/lifecycle/package-paths.d.ts

@@ -1,4 +1,6 @@
 import type { AgentPluginLifecyclePorts } from "./ports.js";
+/** Raised for any path a package entry (or a later read against an already-installed package) is
+ * not allowed to reach — lexically invalid, or resolving outside the package root. */
 export declare class PackagePathViolation extends Error {
     constructor({ message }: {
         readonly message: string;

package/dist/lifecycle/package-paths.js

@@ -1,10 +1,45 @@
+/**
+ * @file The one path-safety primitive every Agent Plugin package read goes through — extraction
+ * (`install.ts`) today, any future preview/read path tomorrow. One implementation, not two, so the
+ * containment guarantee cannot drift between "how a package is written" and "how it is later read".
+ *
+ * The rule is not invented here. The Agent Plugins spec (v1.0.0, "Path safety") states it as a MUST:
+ * "the filesystem-resolved path MUST remain within the filesystem-resolved plugin root... symlinks,
+ * junctions, reparse points, and equivalent filesystem mechanisms MAY resolve to targets within the
+ * plugin root, but clients MUST reject package paths that resolve outside it." The word
+ * "filesystem-resolved" is exactly what a lexical `../`-string check alone does not satisfy — a
+ * hostile archive can plant a symlinked directory at a lexically-clean path and let a later,
+ * innocent-looking entry walk through it (the two-step zip-slip vector; see `install.ts`'s header
+ * for the extraction-time mitigation, which is to refuse symlink ENTRIES outright rather than ever
+ * relying on this function to catch one after the fact).
+ *
+ * Architectural role:
+ * Pure path logic plus the minimum filesystem calls (`realpath`) the spec's own wording requires.
+ * No policy about what happens after containment is established — that is every caller's own job.
+ */
 /** Extracted from the host plugin lifecycle. Effects are supplied per host context. */
 import path from "node:path";
+/** Raised for any path a package entry (or a later read against an already-installed package) is
+ * not allowed to reach — lexically invalid, or resolving outside the package root. */
 export class PackagePathViolation extends Error {
     constructor({ message }, optional = {}) { super(message, optional); }
 }
 function buildModule(ports) {
     const realpath = ports.filesystem.realpath.bind(ports.filesystem);
+    /**
+   * Rejects an absolute path, a NUL byte, a Windows drive prefix, or a lexical `..`/`.` segment —
+   * BEFORE any filesystem call. This is the cheap majority of attempts; {@link assertContainedOnDisk}
+   * catches the rest (an entry that is lexically clean but is, or passes through, a symlink).
+   *
+   * Backslashes are normalized to `/` rather than rejected: the spec models paths as POSIX-style
+   * (`./`-prefixed), and an archive built on Windows may use them as its own separator without any
+   * hostile intent — the traversal segments that actually matter (`..`, an absolute prefix) are
+   * checked after normalization either way.
+   *
+   * @throws {PackagePathViolation} If the path is unsafe by construction, independent of any
+   * filesystem state.
+   * @complexity O(n) in the path's own length.
+   */
     function normalizePackageEntryPath(rawEntryPath) {
         if (rawEntryPath.includes("\0")) {
             throw new PackagePathViolation({ message: `package entry path contains a NUL byte: '${rawEntryPath}'` });
@@ -19,6 +54,30 @@ function buildModule(ports) {
         }
         return normalized;
     }
+    /**
+   * Resolves `entryPath` against `packageRoot` and asserts the REAL, symlink-resolved result is still
+   * inside the REAL, symlink-resolved root — the spec's "filesystem-resolved" requirement, not a
+   * string comparison.
+   *
+   * `packageRoot` is `realpath`'d fresh on every call rather than accepted pre-resolved from the
+   * caller, so a root whose own directory entry is later replaced by a symlink between two calls
+   * cannot smuggle a stale trusted root in.
+   *
+   * Handles the case extraction needs and a plain read doesn't: the target may not exist yet (mid-
+   * extraction, before this entry's own write), in which case the deepest EXISTING ancestor is
+   * `realpath`'d instead — so a symlinked PARENT directory planted by an earlier archive entry is
+   * still caught even though the leaf hasn't been created yet.
+   *
+   * @param packageRoot - Absolute path to the package root (extraction destination, or an already-
+   * installed package's root).
+   * @param entryPath - A package-relative path, as found in an archive entry name or a caller's own
+   * read request. Lexically validated internally via {@link normalizePackageEntryPath}.
+   * @returns The resolved (lexical, not yet realpath'd) absolute destination — safe for the caller to
+   * `open`/`mkdir`/`stat` against.
+   * @throws {PackagePathViolation} If the path is lexically unsafe, or the filesystem-resolved result
+   * (direct or via a symlinked ancestor) falls outside `packageRoot`.
+   * @complexity O(d) in path depth — one `realpath` per unresolved ancestor in the worst case.
+   */
     async function assertContainedOnDisk(packageRoot, entryPath) {
         const normalized = normalizePackageEntryPath(entryPath);
         const realRoot = await realpath(packageRoot);
@@ -42,6 +101,9 @@ function buildModule(ports) {
         const relative = path.relative(root, candidate);
         return relative === "" || (!path.isAbsolute(relative) && relative !== ".." && !relative.startsWith(`..${path.sep}`));
     }
+    /** Walks up from `candidate` until an existing ancestor is found, `realpath`s that ancestor, and
+   * reattaches the non-existent tail — so a symlinked ancestor is caught even for a path whose leaf
+   * (and possibly several parent segments) have not been created yet. */
     async function realpathDeepestExistingAncestor(candidate) {
         let current = path.dirname(candidate);
         const tail = [path.basename(candidate)];

package/dist/lifecycle/persistent-state.d.ts

@@ -9,7 +9,7 @@ export declare function createPersistentStateModule(ports: AgentPluginLifecycleP
     memory: (required: {
         workspaceRoot: string;
         pluginId: string;
-    }, optional?: {}) => import("../../persistent-state.js").PluginMemory;
+    }, optional?: {}) => import("../../core/persistent-state.js").PluginMemory;
     assertOwnedPath: (required: {
         workspaceRoot: string;
         entryPath: string;

package/dist/lifecycle/persistent-state.js

@@ -1,4 +1,4 @@
-import { createPluginMemory, migratePluginLayout, assertPluginStatePath, withPluginStateLock } from '../../persistent-state.js';
+import { createPluginMemory, migratePluginLayout, assertPluginStatePath, withPluginStateLock } from '../../core/persistent-state.js';
 import { withFileLock } from '@jini-ai/platform/fs/file-lock';
 import { createPackagePathsModule } from './package-paths.js';
 import { parseAgentPluginManifest } from './manifest.js';

package/dist/lifecycle/ports.d.ts

@@ -69,6 +69,18 @@ export interface AgentPluginLifecyclePorts {
     readonly layout: AgentPluginLayoutPort;
     readonly productName: string;
     readonly extensionNamespace: string;
+    /** Host boot policy may migrate every workspace before seeding the requested workspace.
+     * A failure refuses all publication; absent uses the owner's single-workspace migration. */
+    readonly migrateBeforeSeed?: ((required: {
+        readonly layout: AgentPluginLayoutPort;
+        readonly workspaceId: string;
+    }, optional: Record<string, never>) => Promise<{
+        readonly complete: boolean;
+    }>) | undefined;
+    /** Host-facing recovery instructions; the bundled refusal and its security gate remain owned here. */
+    readonly formatBundledUninstallRecovery?: ((required: {
+        readonly pluginId: string;
+    }, optional: Record<string, never>) => string) | undefined;
     readonly readServerMetadata?: AgentPluginServerMetadataReader | undefined;
     readonly deliveryMode: AgentPluginDeliveryMode;
     readonly mcpProvisioning: AgentPluginMcpProvisioningPort;
@@ -76,6 +88,6 @@ export interface AgentPluginLifecyclePorts {
     readonly outboundGuard: AgentPluginOutboundGuardPort;
 }
 /** Application policy/effects are required; observers and metadata translators are optional. */
-export type AgentPluginLifecycleRequired = Omit<AgentPluginLifecyclePorts, 'onEvent' | 'readServerMetadata'>;
-export type AgentPluginLifecycleOptional = Pick<AgentPluginLifecyclePorts, 'onEvent' | 'readServerMetadata'>;
+export type AgentPluginLifecycleRequired = Omit<AgentPluginLifecyclePorts, 'onEvent' | 'readServerMetadata' | 'migrateBeforeSeed' | 'formatBundledUninstallRecovery'>;
+export type AgentPluginLifecycleOptional = Pick<AgentPluginLifecyclePorts, 'onEvent' | 'readServerMetadata' | 'migrateBeforeSeed' | 'formatBundledUninstallRecovery'>;
 //# sourceMappingURL=ports.d.ts.map

package/dist/lifecycle/resolve-agent-plugin-refs.d.ts

@@ -1,4 +1,16 @@
-import type { AgentPluginDeliveryMode, InstalledAgentPlugin } from "./types.js";
+import type { /**
+ * How a pinned ref's content reaches the agent.
+ *
+ * - `inject` — the whole eponymous SKILL.md (~15KB for `ui-ux-design`) plus every other package file
+ *   listed by absolute path, in the run's prompt prefix. Today's shipped behaviour, and the default.
+ * - `pointer` — ~400 bytes naming the exact tool call that returns that SAME SKILL.md, and nothing
+ *   else. The content is identical; only the delivery differs, which is what makes the two a
+ *   controlled comparison rather than two different experiments.
+ *
+ * Selected per-process by the host-supplied `deliveryMode` port. This is a MEASUREMENT AFFORDANCE, not a
+ * migration flag: pointer and inject must coexist to compare delivery of identical content.
+ * Selecting an unconditional mode requires the measurement result.
+ */ AgentPluginDeliveryMode, InstalledAgentPlugin } from "./types.js";
 import type { AgentPluginWorkspaceLayout } from "./layout.js";
 import type { AgentPluginLifecyclePorts } from "./ports.js";
 export type { AgentPluginDeliveryMode } from "./types.js";

package/dist/lifecycle/resolve-agent-plugin-refs.js

@@ -1,10 +1,64 @@
+/**
+ * @file Resolves a run's pinned Agent Plugin refs (`pluginRefIds` — `run-start-context.ts`'s
+ * decoded `contextRef` field, itself sourced from the composer's `pluginRefId` chips,
+ * `composer-capabilities.ts`'s own doc) into the real prompt-prefix text `agent-daemon-server.ts`'s
+ * `onStarted` prepends to the run's prompt.
+ *
+ * ---------------------------------------------------------------------------
+ * The activation-record gap this function works around (KNOWN GAP, not silently papered over)
+ * ---------------------------------------------------------------------------
+ * `activation.ts` owns the per-workspace enabled decision; a disabled or undetermined ref is
+ * refused before resolution.
+ * What that record deliberately does NOT carry is which installed DIGEST is current for a plugin id.
+ * For a BUNDLED plugin, `bundled-digests.ts`'s ledger answers that: the boot seeder
+ * records which digest the running build published, so a workspace holding an upgraded plugin's old
+ * and new package is no longer ambiguous — the build's own record names the winner. For every other
+ * plugin id, closing this needs the operator-facing upgrade/pin flow (and, alongside it, the
+ * admission gate for MCP servers `capability-projection.ts`'s own header names) and remains a
+ * separate, later decision.
+ *
+ * So this function still scans every digest this workspace has ever installed under
+ * `packages/sha256/*` and matches on the installed `plugin.json`'s own `name` field, after dropping
+ * any digest of a bundled plugin the ledger records as superseded:
+ *
+ * - Exactly one match: resolves normally.
+ * - Zero matches: fails with a "not installed" reason — the operator pinned a chip for a plugin
+ *   that is not (or no longer) actually on disk for this workspace.
+ * - More than one match: fails with an explicit ambiguity reason naming every matching digest.
+ *   Silently picking one (e.g. the lexicographically-last, or "the newest") would be a WORSE
+ *   failure mode than an explicit error — a wrong plugin's content would reach the agent, and
+ *   nothing about the run would look wrong until someone noticed the agent's advice didn't match
+ *   what was supposedly pinned. An explicit error is loud and immediately actionable instead. That
+ *   refusal is UNCHANGED and still the default: the ledger narrows a plugin id only when the build
+ *   itself published one of the installed digests, which is authority rather than a guess, and it
+ *   has no say at all over packages an operator installed (`bundled-digests.ts`, consequence 1).
+ *
+ * ---------------------------------------------------------------------------
+ * What gets injected, and why not the whole 280K package
+ * ---------------------------------------------------------------------------
+ * Only the resolved plugin's own eponymous skill — `skills/<pluginRefId>/SKILL.md` (the skill
+ * folder whose name equals the plugin's own id; for `ui-ux-design` specifically, this is real,
+ * ~5.5KB content, not all seven of that plugin's skill folders). The reasoning mirrors
+ * `capability-projection.ts`'s own "Skills get a real executable binding" rule: a Skill's markdown
+ * IS the plugin's real, agent-facing content, while the rest of the package (references,
+ * examples, scripts) is supporting material a plugin's own SKILL.md is written to point an agent
+ * at when it needs more depth (the Agent Plugins spec's own convention every skill in this package
+ * follows). Injecting the FULL package indiscriminately would balloon every run's prompt with
+ * pages this specific task usually never needs. Every OTHER file in the resolved package is still
+ * listed by absolute path — genuinely `Read`-able by the spawned CLI agent, which runs with real
+ * filesystem access unlike a browser-facing preview — so nothing is unreachable, only deferred to
+ * an explicit follow-up read.
+ *
+ * Architectural role:
+ * Server-side only (reads `node:fs/promises`, imports `install.ts`'s `indexInstalledRoot`) — never
+ * imported into a browser bundle. Returns a discriminated result rather than throwing, so
+ * `agent-daemon-server.ts`'s `onStarted` gets one place to branch on success/failure without a
+ * second try/catch layer duplicating this module's own error classification.
+ */
 import { createPersistentStateModule } from "./persistent-state.js";
-/** Extracted from the host plugin lifecycle. Effects are supplied per host context. */
 import path from "node:path";
 import { createPackagePathsModule } from "./package-paths.js";
-import {} from "./activation.js";
 import { createActivationModule } from "./activation.js";
-import {} from "./bundled-digests.js";
 import { createBundledDigestsModule } from "./bundled-digests.js";
 import { createInstallModule } from "./install.js";
 import { createCapabilityProjectionModule } from "./capability-projection.js";
@@ -18,7 +72,35 @@ function buildModule(ports) {
     const { indexInstalledRoot } = createInstallModule(ports);
     const { readInstalledSkillMarkdown } = createCapabilityProjectionModule(ports);
     const SHA256_DIGEST_DIRNAME_PATTERN = /^[a-f0-9]{64}$/;
+    /** Reads the delivery mode for this process. An unset or unrecognised value is `inject` — an A/B
+   *  affordance must never be able to change production behaviour by typo. */
     function resolveAgentPluginDeliveryMode() { return ports.deliveryMode; }
+    /**
+   * Resolves every pinned `pluginRefId` into real on-disk text and joins the results into one
+   * prompt-prefix block, in the order the refs were pinned.
+   *
+   * @param pluginRefIds - This run's pinned Agent Plugin ids (`run-start-context.ts`'s decoded
+   *   `pluginRefIds` — already filtered to non-empty strings by that point). An empty array resolves
+   *   to an empty prefix with no filesystem access at all — the common case (no plugin pinned).
+   * @param workspaceLayout - This run's own workspace's Agent Plugin layout
+   *   (`resolveAgentPluginLayout().forWorkspace(workspaceId)`), never a shared/instance-level one —
+   *   see `layout.ts`'s own tenant-isolation header for why a workspace's installed packages must
+   *   never be resolved against another workspace's tree.
+   * @returns `{ ok: true, promptPrefix }` once every ref resolves, or the FIRST `{ ok: false, reason }`
+   *   encountered — a run pinning two refs where the second is ambiguous still fails clearly, rather
+   *   than partially augmenting the prompt with only the first ref's content.
+   * @complexity O(r * d) where r is `pluginRefIds.length` and d is the number of installed digests in
+   *   this workspace — each ref independently re-scans the (typically small) digest list, since a
+   *   different ref may resolve to a different digest.
+   */
+    // Read ONCE for the whole call, not per ref: it is one small file, and every ref resolves against
+    // the same workspace's ledger. See `bundled-digests.ts` for why this can only ever RESOLVE an
+    // ambiguity below, never create one.
+    // See activation.ts for the shared activation rule. One small file read per pinned ref; the
+    // fail-CLOSED `resolveAgentPluginActivation` (the same reader the per-call tool gate uses)
+    // refuses on a corrupt/unreadable file instead of reading it as "nothing recorded" — injecting a
+    // plugin's guidance SPENDS it exactly like a tool call, so this surface must refuse rather than
+    // read a fault as consent.
     async function resolveAgentPluginRefs(pluginRefIds, workspaceLayout, deliveryMode = resolveAgentPluginDeliveryMode()) {
         if (pluginRefIds.length === 0)
             return { ok: true, promptPrefix: "" };
@@ -35,6 +117,12 @@ function buildModule(ports) {
         }
         return { ok: true, promptPrefix: sections.join("\n\n") };
     }
+    /** The run-start refusal for one ref's activation verdict, or `undefined` when it may be injected.
+   *  @complexity O(1). */
+    // A distinct reason from "not installed", because the operator's remedy is different: the bytes
+    // ARE here and the fix is to enable the plugin, not to install it. Telling them to install
+    // something already present is the kind of wrong-but-plausible error message that costs an
+    // afternoon.
     function activationRefusal(pluginRefId, verdict) {
         if (verdict.verdict === "active")
             return undefined;
@@ -45,6 +133,19 @@ function buildModule(ports) {
         return (`Agent Plugin '${pluginRefId}' is installed in this workspace but is not enabled — it ships with ${ports.productName} and ` +
             "stays inactive until an operator turns it on. Enable it before pinning it to a run.");
     }
+    /** Every installed digest's `InstalledAgentPlugin`, indexed once per call to
+   *  {@link resolveAgentPluginRefs} — one `readdir` plus one `indexInstalledRoot` walk per digest.
+   *  Digest directory names that do not match the expected 64-hex-character shape are skipped rather
+   *  than passed to `indexInstalledRoot` — `packages/sha256/` is not asserted empty of anything else
+   *  a future tool might place there, and a non-digest entry is not this function's to interpret.
+   *
+   *  Exported for a second caller outside this module: `tool-registrations.ts`'s
+   *  `loadInstalledAgentPluginToolSources` needs the SAME per-digest walk (every installed digest,
+   *  whichever skills each one carries) to build one `agent_plugin_<pluginId>` tool per installed
+   *  plugin — the exact shape this function already builds, just consumed differently than
+   *  `resolveOnePluginRef`'s own "resolve one pinned ref" use below. Reusing this rather than
+   *  re-walking `packages/sha256/*` a second, less-validated way keeps the digest-directory-name check
+   *  and the per-digest failure isolation in exactly one place. */
     async function listInstalledPlugins(workspaceRoot) {
         let folders;
         try {
@@ -84,6 +185,28 @@ function buildModule(ports) {
         }
         return installed;
     }
+    /**
+   * Whether one installed archive digest still has its package directory under `packagesDir` — the
+   * cheap, per-call "is this still installed" signal `tool-registrations.ts`'s tool gate needs.
+   *
+   * Lives here, beside {@link listInstalledPlugins}, because it must agree with that walk about two
+   * things a second implementation would eventually get wrong: that an installed package root IS
+   * `<packagesDir>/<digest>` and nothing else, and that a directory name is only a digest when it
+   * matches the 64-hex shape. It deliberately does NOT re-index the package (`indexInstalledRoot`
+   * reads and validates a manifest, which is far too much per tool call): directory presence is
+   * exactly what `uninstall.ts` removes, and it removes it by `rename` BEFORE it touches the
+   * activation record, so the gate observes a removal at least as early as it observes the record's
+   * deletion, never later.
+   *
+   * Follows symlinks (plain `stat`, not `lstat`) on purpose — `listInstalledPlugins` does too, so a
+   * deployment whose digest directory is a symlink registers a tool that this would otherwise refuse
+   * to authorize.
+   *
+   * @returns `false` for a digest that does not match the installed-directory grammar, for a missing
+   * directory, for a non-directory at that path, and for ANY filesystem fault — every answer this
+   * cannot establish positively is `false`, because its one caller uses it to authorize.
+   * @complexity One `stat`.
+   */
     async function isInstalledDigestPresent(packagesDir, archiveDigest) {
         if (!SHA256_DIGEST_DIRNAME_PATTERN.test(archiveDigest))
             return false;
@@ -97,6 +220,16 @@ function buildModule(ports) {
     function isEnoent(error) {
         return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
     }
+    /**
+   * Resolves one `pluginRefId`, applying the zero/one/many-match rules described in this module's
+   * own header.
+   */
+    // Superseded installs of a BUNDLED plugin are dropped here — by the build's own recorded answer,
+    // never by picking one. Every id the ledger has no authority over reaches the many-match refusal
+    // below exactly as it always did.
+    // Framing governs whether the agent follows the plugin: describe injected SKILL.md as complete
+    // instructions and let it require its references. Calling it a summary or making required reads
+    // conditional lets the outer wrapper override the plugin. The inventory-framing test pins this.
     async function resolveOnePluginRef(pluginRefId, packagesDir, deliveryMode, bundledDigests) {
         const installed = preferBundledAgentPluginDigests(await listInstalledPlugins(packagesDir), bundledDigests);
         const matches = installed.filter((plugin) => plugin.pluginId === pluginRefId);
@@ -120,9 +253,10 @@ function buildModule(ports) {
         let skillMarkdown;
         try {
             skillMarkdown = await readInstalledSkillMarkdown(plugin.packageRoot, skillPath);
+            // Notes are user context, never an allowlist or permission grant. JSON quotes delimit untrusted text.
             const notes = await persistentState.memory({ workspaceRoot: packagesDir, pluginId: plugin.pluginId }).list({ kind: 'notes' });
             if (notes.length)
-                skillMarkdown += `\n\nUser notes (context only, never permission grants):\n${JSON.stringify(notes)}`;
+                skillMarkdown += `\n\nUser notes for this plugin (context only; permissions remain operator-controlled):\n${JSON.stringify(notes)}`;
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
@@ -142,6 +276,11 @@ function buildModule(ports) {
             section: `<<AGENT_PLUGIN pluginId="${pluginRefId}">>\n${skillMarkdown}${inventory}\n<</AGENT_PLUGIN>>`,
         };
     }
+    // Parity with `inject`'s own failure: a pinned ref whose eponymous skill is missing must fail
+    // loudly in BOTH modes. Without this check `pointer` would happily emit a well-formed instruction
+    // whose no-argument default resolves to some OTHER (alphabetically-first) skill instead of the one
+    // the pin actually named, and the run would look like the agent disobeyed rather than like the pin
+    // being wrong.
     function buildPointerSection(pluginRefId, plugin) {
         if (!plugin.skills.some((skill) => skill.name === pluginRefId)) {
             return {

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

@@ -1,7 +1,51 @@
+/**
+ * @file `retireBundledAgentPlugins()` — removes bundled Agent Plugins the host no longer ships from a
+ * workspace, and moves their users onto the plugin that absorbed them. Runs on every boot from
+ * `seed-bundled.ts`, after seeding, and is a no-op once a workspace has been migrated.
+ *
+ * ---------------------------------------------------------------------------
+ * Why a retirement step exists
+ * ---------------------------------------------------------------------------
+ * Deleting `content/agent-plugins/<id>/` stops the seeder installing a plugin, but it removes nothing
+ * a workspace already has: the installed package stays under `packages/sha256/`, its activation
+ * record stays in `activations.json`, and its digest stays in `bundled-digests.json`. An ENABLED
+ * leftover keeps its skill in every prompt, now duplicating (and slowly contradicting) the successor
+ * that carries the same content. And the operator cannot remove it: `uninstall.ts` refuses a
+ * bundled plugin because it would be re-seeded, which is exactly what stops being true here. Owner
+ * rule: the user never fixes anything by hand, so the boot does it.
+ *
+ * ---------------------------------------------------------------------------
+ * What happens per retired id (idempotent)
+ * ---------------------------------------------------------------------------
+ * 1. Nothing installed and no activation record: nothing to do (the second boot after a migration).
+ *    A leftover ledger entry is still dropped.
+ * 2. The retired plugin was ENABLED (explicitly, or by the "absent means active" default while its
+ *    package is installed): the successor is switched on — unless an operator explicitly turned the
+ *    successor off, which is left exactly as it is and reported in the outcome. No silent override.
+ * 3. The retired plugin's package(s) and activation record are removed through `uninstall.ts`
+ *    (`retiredBundled: true` skips only its bundled refusal). A record with no package left is
+ *    deleted directly.
+ * 4. The retired id is dropped from `bundled-digests.json`.
+ *
+ * A malformed or unreadable activation record for the retired id stops that id's retirement with a
+ * `failed` outcome and changes nothing: whether the operator had it enabled cannot be established,
+ * so neither enabling the successor nor deleting the record is safe. The next boot retries.
+ *
+ * Out of scope on purpose: nothing a retired plugin could own survives it. Agent Plugins have no
+ * per-plugin settings store (a workspace's `data/<pluginId>` directory has no production writer),
+ * and custom credentials (a saved `fly.io` token, say) belong to the workspace, not to a plugin.
+ *
+ * Architectural role:
+ * Composition over `activation.ts`, `uninstall.ts`, and `bundled-digests.ts`. Never throws: every
+ * failure is captured per id, exactly like `seed-bundled.ts`'s own outcomes, so one stuck retirement
+ * cannot stop a workspace from booting.
+ */
 /** Extracted from the host plugin lifecycle. Effects are supplied per host context. */
-import { type BundledAgentPluginEnableOutcome } from "./activation.js";
+import type { BundledAgentPluginEnableOutcome } from "./activation.js";
 import type { AgentPluginLayout } from "./layout.js";
 import type { AgentPluginLifecyclePorts } from "./ports.js";
+/** What happened to the successor. `not-needed`: the retired plugin was off, so the successor was
+ *  left as it was. The other three are {@link BundledAgentPluginEnableOutcome}. */
 export type RetiredAgentPluginSuccessorOutcome = BundledAgentPluginEnableOutcome | "not-needed";
 export type RetiredAgentPluginOutcome = {
     readonly pluginId: string;
@@ -11,9 +55,12 @@ export type RetiredAgentPluginOutcome = {
     readonly pluginId: string;
     readonly successorId: string;
     readonly status: "retired";
+    /** Every installed archive digest removed; empty when only a record or ledger entry was left. */
     readonly removedDigests: readonly string[];
     readonly activationRemoved: boolean;
     readonly ledgerEntryRemoved: boolean;
+    /** `left-disabled-by-operator` is the one case a caller should surface: the retired plugin was
+     *  on, its successor was explicitly turned off, and this step did not override that. */
     readonly successor: RetiredAgentPluginSuccessorOutcome;
 } | {
     readonly pluginId: string;
@@ -22,10 +69,12 @@ export type RetiredAgentPluginOutcome = {
     readonly reason: string;
 };
 export interface RetireBundledAgentPluginsRequired {
+    /** The INSTANCE-level layout, for the same reason `seed-bundled.ts` takes one. */
     readonly layout: AgentPluginLayout;
     readonly workspaceId: string;
 }
 export interface RetireBundledAgentPluginsOptional {
+    /** Defaults to {@link RETIRED_BUNDLED_AGENT_PLUGINS}; tests pass their own. */
     readonly retired?: (ReadonlyMap<string, string>) | undefined;
     readonly now?: ((required: Record<string, never>) => Date) | undefined;
 }

package/dist/lifecycle/retire-bundled.js

@@ -1,5 +1,3 @@
-/** Extracted from the host plugin lifecycle. Effects are supplied per host context. */
-import {} from "./activation.js";
 import { createActivationModule } from "./activation.js";
 import { createBundledDigestsModule } from "./bundled-digests.js";
 import { createResolveAgentPluginRefsModule } from "./resolve-agent-plugin-refs.js";
@@ -9,6 +7,13 @@ function buildModule(ports) {
     const { removeBundledAgentPluginDigest } = createBundledDigestsModule(ports);
     const { listInstalledPlugins } = createResolveAgentPluginRefsModule(ports);
     const { uninstallAgentPlugin } = createUninstallModule(ports);
+    /**
+   * Retires every id in `retired` from one workspace. See this file's header for the steps.
+   *
+   * @returns One outcome per retired id, in map order.
+   * @throws Nothing.
+   * @complexity O(r) retired ids, each one `listInstalledPlugins` walk plus a few small file writes.
+   */
     async function retireBundledAgentPlugins(required, optional = {}) {
         const outcomes = [];
         for (const [pluginId, successorId] of optional.retired ?? ports.retiredBundledPlugins) {
@@ -21,6 +26,8 @@ function buildModule(ports) {
         }
         return outcomes;
     }
+    // The successor first: if a later step fails, the operator keeps the capability, and the next boot
+    // (which finds this step already done) retries only what is left.
     async function retireOne(required, optional, pluginId, successorId) {
         const workspaceLayout = required.layout.forWorkspace({ workspaceId: required.workspaceId });
         const workspaceRoot = workspaceLayout.root;

package/dist/lifecycle/search.d.ts

@@ -1,18 +1,81 @@
 /** 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[];
+    /** 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,12 +4,18 @@ 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 },
@@ -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)