@jini-ai/agent-plugins 0.4.1 → 0.4.3

package/dist/lifecycle/index.js

@@ -13,12 +13,14 @@ import { createResolveAgentPluginRefsModule } from './resolve-agent-plugin-refs.
 import { createSearchModule } from './search.js';
 import { createSetEnabledModule } from './set-enabled.js';
 import { createTrustedPluginFilesModule } from './trusted-plugin-files.js';
+import { createPluginContributionLoader } from './contribution-loader.js';
 import { createUninstallModule } from './uninstall.js';
 export * from './ports.js';
 export * from './layout.js';
 export * from './manifest.js';
 export * from './fetch-archive.js';
 export * from './mcp-provisioning.js';
+export * from './contribution-loader.js';
 export { createAgentPluginActivations, ACTIVATIONS_FILENAME, ACTIVATIONS_LOCK_FILENAME, AgentPluginActivationsBusyError, AgentPluginActivationsUnreadableError } from './activation.js';
 export { BUNDLED_DIGESTS_FILENAME } from './bundled-digests.js';
 export { AgentPluginInstallError } from './install.js';
@@ -46,8 +48,14 @@ export function createAgentPluginLifecycle(required, optional = {}) {
     const search = createSearchModule(context);
     const enabled = createSetEnabledModule(context);
     const trusted = createTrustedPluginFilesModule(context);
+    const contributions = createPluginContributionLoader({
+        findPackages: input => trusted.findTrustedPluginPackages(input),
+        readFile: ({ plugin, filename }) => trusted.readTrustedPluginFile(plugin, filename),
+        importModule: ({ plugin, modulePath }) => trusted.importContainedModule(plugin, modulePath),
+    });
     const uninstall = createUninstallModule(context);
     return {
+        ...contributions,
         fetchAgentPluginArchive: (input, optional = {}) => fetchAgentPluginArchive({ ...input, fetch: context.fetch, outboundGuard: context.outboundGuard }, optional),
         maxAgentPluginArchiveBytes,
         seedBundledAgentPlugins: createSeedBundledModule(context).seedBundledAgentPlugins,
@@ -64,6 +72,9 @@ export function createAgentPluginLifecycle(required, optional = {}) {
         findTrustedPluginPackages: (input, optional = {}) => trusted.findTrustedPluginPackages({ ...input, ...optional }),
         previewAgentPluginUninstall: uninstall.previewAgentPluginUninstall,
         uninstallAgentPlugin: uninstall.uninstallAgentPlugin,
+        stageForRemoval: (input, _optional = {}) => uninstall.stageForRemoval(input.packagesDir, input.packageRoot),
+        restoreStagedTrees: (input, _optional = {}) => uninstall.restoreStagedTrees(input.staged, input.cause),
+        removeFrozenPackageTree: (input, _optional = {}) => uninstall.removeFrozenPackageTree(input.root),
         isAgentPluginActive: (input) => activation.isAgentPluginActive(input.activations, input.pluginId),
         filterActiveAgentPlugins: (input) => activation.filterActiveAgentPlugins(input.activations, input.items, item => input.pluginIdOf({ item })),
         readAgentPluginActivations: (input) => activation.readAgentPluginActivations(input.workspaceRoot),

package/dist/lifecycle/install-from-url.d.ts

@@ -1,20 +1,17 @@
 /**
- * Historical lifecycle rationale, carried with the implementation during consumer adoption.
  *
- * Host command-line rationale retained when the unused URL-install CLI was removed:
+ * Caller integrity constraints:
  * - A digest-only preview downloads and reports SHA-256 without installing. Hashing those bytes
  *   does not establish provenance; the host must make that distinction visible to the operator.
  * - A real install requires exactly one explicit integrity decision: an independent pinned digest
  *   or trust-on-first-use. Missing or conflicting choices must be refused before execution, with
  *   diagnostics naming the choice the operator needs to supply.
- * - Keep pure token classification separate from argument validation and exit/reporting effects,
- *   so both parsing and legal combinations are directly testable without a network or process exit.
  * - The CLI composes shared download/extraction operations; digest verification, expansion bounds,
  *   path containment and tenant isolation belong in those operations rather than a CLI-only guard.
  * @file The one composition step that turns "here is an address" into "the plugin is on this
  * machine": {@link fetchAgentPluginArchive} -> `installAgentPlugin`.
  *
- * This is the caller `install.ts` was written for and never had. It adds no extraction, path, or
+ * It adds no extraction, path, or
  * manifest logic of its own — every one of those guarantees still comes from `install.ts`, reached
  * with bytes instead of a URL.
  *

package/dist/lifecycle/install-from-url.js

@@ -1,20 +1,17 @@
 /**
- * Historical lifecycle rationale, carried with the implementation during consumer adoption.
  *
- * Host command-line rationale retained when the unused URL-install CLI was removed:
+ * Caller integrity constraints:
  * - A digest-only preview downloads and reports SHA-256 without installing. Hashing those bytes
  *   does not establish provenance; the host must make that distinction visible to the operator.
  * - A real install requires exactly one explicit integrity decision: an independent pinned digest
  *   or trust-on-first-use. Missing or conflicting choices must be refused before execution, with
  *   diagnostics naming the choice the operator needs to supply.
- * - Keep pure token classification separate from argument validation and exit/reporting effects,
- *   so both parsing and legal combinations are directly testable without a network or process exit.
  * - The CLI composes shared download/extraction operations; digest verification, expansion bounds,
  *   path containment and tenant isolation belong in those operations rather than a CLI-only guard.
  * @file The one composition step that turns "here is an address" into "the plugin is on this
  * machine": {@link fetchAgentPluginArchive} -> `installAgentPlugin`.
  *
- * This is the caller `install.ts` was written for and never had. It adds no extraction, path, or
+ * It adds no extraction, path, or
  * manifest logic of its own — every one of those guarantees still comes from `install.ts`, reached
  * with bytes instead of a URL.
  *

package/dist/lifecycle/install.d.ts

@@ -2,7 +2,10 @@ import type { AgentPluginLayout } from "./layout.js";
 import type { AgentPluginLifecyclePorts } from "./ports.js";
 import type { InstalledAgentPlugin } from "./types.js";
 export type { InstalledAgentPlugin, InstalledAgentPluginSkill } from "./types.js";
-export type AgentPluginInstallErrorCode = "ARCHIVE_TOO_LARGE" | "DIGEST_MISMATCH" | "TOO_MANY_ENTRIES" | "UNSAFE_ENTRY_PATH" | "SYMLINK_ENTRY_REJECTED" | "UNSUPPORTED_ENTRY_KIND" | "DUPLICATE_ENTRY" | "FILE_TOO_LARGE" | "DECOMPRESSION_BOMB" | "TOTAL_SIZE_EXCEEDED" | "MANIFEST_MISSING" | "MANIFEST_INVALID" | "PUBLISH_FAILED";
+/** One extraction/install failure reason. A caller (an admin route, a future marketplace installer)
+ * branches on `code` rather than parsing `message` — this codebase's own convention
+ * (`PluginLoadError.reason` in `plugin-runtime/loader.ts` is the direct precedent). */
+export type AgentPluginInstallErrorCode = "PLUGIN_ID_CONFLICT" | "ARCHIVE_TOO_LARGE" | "DIGEST_MISMATCH" | "TOO_MANY_ENTRIES" | "UNSAFE_ENTRY_PATH" | "SYMLINK_ENTRY_REJECTED" | "UNSUPPORTED_ENTRY_KIND" | "DUPLICATE_ENTRY" | "FILE_TOO_LARGE" | "DECOMPRESSION_BOMB" | "TOTAL_SIZE_EXCEEDED" | "MANIFEST_MISSING" | "MANIFEST_INVALID" | "PUBLISH_FAILED";
 export declare class AgentPluginInstallError extends Error {
     readonly code: AgentPluginInstallErrorCode;
     constructor({ code, message }: {
@@ -12,9 +15,14 @@ export declare class AgentPluginInstallError extends Error {
         cause?: unknown;
     });
 }
+/** One archive entry. A symlink is modeled as its OWN kind rather than folded into "file" — the
+ * zip-slip research this module's header cites is explicit that the symlink-entry vector is
+ * distinct from the lexical-traversal one, and the two need independent tests and independent
+ * handling (see the "symlink entries are rejected outright" rule below). */
 export type AgentPluginArchiveEntry = {
     readonly kind: "file";
     readonly entryPath: string;
+    /** The archive format's own claimed size. Never trusted alone — see `DECOMPRESSION_BOMB`. */
     readonly declaredSize?: (number) | undefined;
     readonly executable?: (boolean) | undefined;
     readonly openReadStream: (required: Record<string, never>) => AsyncIterable<Uint8Array>;
@@ -30,6 +38,7 @@ export type AgentPluginArchiveEntry = {
  * `entries` must be a pure function of the archive bytes: an install iterates it twice, once to
  * check entry-count limits from metadata alone and once to extract.
  */
+/** `entries` is a pure function of archive bytes: metadata preflight and extraction iterate it twice. */
 export interface AgentPluginArchiveReaderPort {
     entries(required: {
         readonly archive: Uint8Array;
@@ -37,16 +46,62 @@ export interface AgentPluginArchiveReaderPort {
 }
 export interface InstallAgentPluginRequired {
     readonly archive: Uint8Array;
+    /** Lowercase hex SHA-256 the caller expects `archive` to hash to — a real marketplace flow would
+     * supply this from the server's own metadata; verified here, never trusted from the archive
+     * itself. */
     readonly expectedSha256: string;
     readonly archiveReader: AgentPluginArchiveReaderPort;
+    /**
+     * SECURITY (2026-08-13, security pass Finding 2 — tenant isolation, `ADS-memory/reports/security/
+     * 2026-08-13-post-session-security-pass.md`): this field used to be an already-resolved
+     * `AgentPluginWorkspaceLayout` (`{ root, packages, staging, pluginDataDir }`) — a plain interface
+     * of four independently-typed string/function fields with no tag identifying which workspace it
+     * came from. Nothing stopped a caller from hand-assembling one from two DIFFERENT real
+     * `forWorkspace()` results (wrong variable capture, a stale cached layout, a future code path that
+     * builds one by hand instead of calling `forWorkspace`) — such a value type-checked identically to
+     * a correctly-resolved one, and `installAgentPlugin` published into whatever `packages`/`staging`
+     * it was handed with no consistency check. Proven at the unit level in `install.unit.test.ts`
+     * (a layout stitching workspace A's `root`/`pluginDataDir` onto workspace B's real `packages`/
+     * `staging` published into workspace B's real, on-disk store with no error).
+     *
+     * The fix: `installAgentPlugin` no longer accepts a pre-resolved workspace layout as input AT ALL.
+     * It takes the RAW MATERIALS instead — the INSTANCE-level layout (`resolveAgentPluginLayout()`,
+     * carries no workspace-scoped path of its own) plus one `workspaceId` — and calls
+     * `layout.forWorkspace(workspaceId)` itself, exactly once, internally. There is no longer any
+     * `AgentPluginWorkspaceLayout`-shaped parameter here for a caller to stitch fields into: the one
+     * and only path from these two inputs to `packages`/`staging`/`pluginDataDir` is the real
+     * `forWorkspace()` closure, called atomically, so the four resulting paths can never disagree with
+     * each other about which workspace they belong to. Passing a hand-built `{ packages, staging, ... }`
+     * literal where this field is expected is now a compile-time type error, not a runtime hazard.
+     *
+     * `workspaceId` must still come from the authenticated principal's own request context, never
+     * derived from `layout` itself (a hand-built or malicious `AgentPluginLayout` could fake a
+     * `forWorkspace` implementation identically) — that half of the guarantee is a caller obligation
+     * this type cannot enforce, the same way `archiveReader` above is a fully caller-trusted port. What
+     * IS closed is the specific, demonstrated bug class: stitching or hand-assembling an
+     * already-resolved workspace layout from parts.
+     */
     readonly layout: AgentPluginLayout;
+    /** The workspace this install is for. Combined with {@link layout} via `layout.forWorkspace(workspaceId)`
+     * — see the SECURITY note on {@link layout} above. */
     readonly workspaceId: string;
 }
-export type InstallAgentPluginOptional = {};
+export interface InstallAgentPluginOptional {
+    /** Full bounded extraction/validation in staging, with no package or memory publication. */
+    readonly previewOnly?: boolean;
+    /** Host policy transaction inside the per-plugin lock after validation. Call publish exactly
+     * once to install; returning an existing package without calling it is a deduplicated no-op. */
+    /** Host policy transaction, called inside the existing per-plugin lock after validation.
+     * It must invoke publish exactly once to install. Shared lifecycle counterpart is in chat-tools.jini.patch. */
+    readonly publishGuard?: (required: {
+        readonly plugin: InstalledAgentPlugin;
+        readonly publish: () => Promise<InstalledAgentPlugin>;
+    }, optional: Record<string, never>) => Promise<InstalledAgentPlugin>;
+}
 /** Internal composition; one state/queue instance per injected host context. */
 export declare function createInstallModule(ports: AgentPluginLifecyclePorts): {
     maxAgentPluginInstallArchiveBytes: () => number;
-    installAgentPlugin: (required: InstallAgentPluginRequired, _optional?: InstallAgentPluginOptional) => Promise<InstalledAgentPlugin>;
+    installAgentPlugin: (required: InstallAgentPluginRequired, optional?: InstallAgentPluginOptional) => Promise<InstalledAgentPlugin>;
     indexInstalledRoot: (packageRoot: string, archiveDigest: string) => Promise<InstalledAgentPlugin>;
 };
 //# sourceMappingURL=install.d.ts.map