@jini-ai/agent-plugins 0.4.0

package/dist/lifecycle/index.d.ts

@@ -0,0 +1,174 @@
+import { maxAgentPluginArchiveBytes } from './fetch-archive.js';
+import type { FetchAgentPluginArchiveOptional } from './fetch-archive.js';
+import type { AgentPluginLifecycleRequired, AgentPluginLifecycleOptional } from './ports.js';
+import type { AgentPluginDeliveryMode } from './resolve-agent-plugin-refs.js';
+import type { InstalledDigestIdentity } from './bundled-digests.js';
+export type { SeededAgentPluginOutcome, SeedBundledAgentPluginsRequired, SeedBundledAgentPluginsResult } from './seed-bundled.js';
+export type { RetireBundledAgentPluginsRequired, RetireBundledAgentPluginsOptional, RetiredAgentPluginOutcome } from './retire-bundled.js';
+export * from './ports.js';
+export * from './layout.js';
+export * from './manifest.js';
+export * from './fetch-archive.js';
+export * from './mcp-provisioning.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';
+export { PackagePathViolation } from './package-paths.js';
+export { AgentPluginNotInstalledError } from './set-enabled.js';
+export { AgentPluginNotFoundError, AgentPluginNotUninstallableError, AgentPluginChangedSincePreviewError } from './uninstall.js';
+export type { AgentPluginOrigin, AgentPluginActivationRecord, AgentPluginActivations, AgentPluginActivationVerdict, SetAgentPluginActivationRequired, SetAgentPluginActivationOptional, BundledAgentPluginEnableOutcome, DeleteAgentPluginActivationRequired } from './activation.js';
+export type { BundledAgentPluginDigests, SeededBundledAgentPluginDigest, InstalledDigestIdentity } from './bundled-digests.js';
+export type { PackedAgentPluginArchive } from './bundled-source-archive.js';
+export type { AgentPluginArchiveEntry, AgentPluginArchiveReaderPort, AgentPluginArchiveReaderPort as ArchiveReaderPort, AgentPluginInstallErrorCode, InstalledAgentPluginSkill, InstalledAgentPlugin, InstallAgentPluginRequired, InstallAgentPluginOptional } from './install.js';
+export type { AgentPluginIntegrity, InstallAgentPluginFromUrlRequired, InstallAgentPluginFromUrlOptional, InstalledAgentPluginFromUrl } from './install-from-url.js';
+export type { AgentPluginDeliveryMode, ResolveAgentPluginRefsResult } from './resolve-agent-plugin-refs.js';
+export type { SetAgentPluginEnabledInput, SetAgentPluginEnabledResult } from './set-enabled.js';
+export type { UninstallAgentPluginRequired, UninstallAgentPluginOptional, UninstallAgentPluginResult, AgentPluginUninstallPreview } from './uninstall.js';
+export type { TrustedPluginPackage, TrustedPluginPackagesQuery, TrustedPluginVerdict } from './trusted-plugin-files.js';
+export type { AgentPluginSearchSkill, AgentPluginSearchCandidate, AgentPluginSearchMatch } from './search.js';
+/** One host context owns queues and effects. Keep this object and its ports stable for its lifetime.
+ * Installation/activation and MCP provisioning are separate operations: the host explicitly wires
+ * provisioning using the exported helpers, with its own retry/recovery policy. */
+export declare function createAgentPluginLifecycle(required: AgentPluginLifecycleRequired, optional?: AgentPluginLifecycleOptional): {
+    fetchAgentPluginArchive: (input: {
+        readonly url: string;
+    }, optional?: FetchAgentPluginArchiveOptional) => Promise<import("./fetch-archive.js").FetchedAgentPluginArchive>;
+    maxAgentPluginArchiveBytes: typeof maxAgentPluginArchiveBytes;
+    seedBundledAgentPlugins: (required: import("./seed-bundled.js").SeedBundledAgentPluginsRequired) => Promise<import("./seed-bundled.js").SeedBundledAgentPluginsResult>;
+    retireBundledAgentPlugins: (required: import("./retire-bundled.js").RetireBundledAgentPluginsRequired, optional?: import("./retire-bundled.js").RetireBundledAgentPluginsOptional) => Promise<readonly import("./retire-bundled.js").RetiredAgentPluginOutcome[]>;
+    setAgentPluginActivation: (required: import("./activation.js").SetAgentPluginActivationRequired, optional?: import("./activation.js").SetAgentPluginActivationOptional) => Promise<import("./activation.js").AgentPluginActivations>;
+    recordBundledAgentPluginIfAbsent: (required: {
+        readonly workspaceRoot: string;
+        readonly pluginId: string;
+    }, optional?: {
+        readonly now?: ((required: Record<string, never>) => Date) | undefined;
+        readonly enabled?: boolean;
+    }) => Promise<{
+        readonly recorded: boolean;
+    }>;
+    enableBundledAgentPluginUnlessOperatorDisabled: (required: {
+        readonly workspaceRoot: string;
+        readonly pluginId: string;
+        readonly actor: string;
+        readonly now?: ((required: Record<string, never>) => Date) | undefined;
+    }) => Promise<import("./activation.js").BundledAgentPluginEnableOutcome>;
+    deleteAgentPluginActivation: (required: import("./activation.js").DeleteAgentPluginActivationRequired) => Promise<void>;
+    recordBundledAgentPluginDigests: (input: {
+        readonly workspaceRoot: string;
+        readonly seeded: Parameters<(required: {
+            readonly workspaceRoot: string;
+            readonly seeded: readonly import("./bundled-digests.js").SeededBundledAgentPluginDigest[];
+            readonly now?: ((required: Record<string, never>) => Date) | undefined;
+        }) => Promise<void>>[0]["seeded"];
+    }, optional?: {
+        readonly now?: (required: Record<string, never>) => Date;
+    }) => Promise<void>;
+    removeBundledAgentPluginDigest: (required: {
+        readonly workspaceRoot: string;
+        readonly pluginId: string;
+    }) => Promise<boolean>;
+    installAgentPlugin: (required: import("./install.js").InstallAgentPluginRequired, _optional?: import("./install.js").InstallAgentPluginOptional) => Promise<import("./types.js").InstalledAgentPlugin>;
+    installAgentPluginFromUrl: (required: import("./install-from-url.js").InstallAgentPluginFromUrlRequired, optional?: import("./install-from-url.js").InstallAgentPluginFromUrlOptional) => Promise<import("./install-from-url.js").InstalledAgentPluginFromUrl>;
+    setAgentPluginEnabled: (input: import("./set-enabled.js").SetAgentPluginEnabledInput) => Promise<import("./set-enabled.js").SetAgentPluginEnabledResult>;
+    findTrustedPluginPackages: (input: Omit<Parameters<(query: import("./trusted-plugin-files.js").TrustedPluginPackagesQuery) => Promise<readonly import("./trusted-plugin-files.js").TrustedPluginVerdict[]>>[0], "orderByPluginId" | "onInactive">, optional?: Pick<Parameters<(query: import("./trusted-plugin-files.js").TrustedPluginPackagesQuery) => Promise<readonly import("./trusted-plugin-files.js").TrustedPluginVerdict[]>>[0], "orderByPluginId" | "onInactive">) => Promise<readonly import("./trusted-plugin-files.js").TrustedPluginVerdict[]>;
+    previewAgentPluginUninstall: (required: import("./uninstall.js").UninstallAgentPluginRequired) => Promise<import("./uninstall.js").AgentPluginUninstallPreview>;
+    uninstallAgentPlugin: (required: import("./uninstall.js").UninstallAgentPluginRequired, optional?: import("./uninstall.js").UninstallAgentPluginOptional) => Promise<import("./uninstall.js").UninstallAgentPluginResult>;
+    isAgentPluginActive: (input: {
+        readonly activations: Parameters<(activations: import("./activation.js").AgentPluginActivations, pluginId: string) => boolean>[0];
+        readonly pluginId: string;
+    }) => boolean;
+    filterActiveAgentPlugins: <T>(input: {
+        readonly activations: Parameters<(activations: import("./activation.js").AgentPluginActivations, pluginId: string) => boolean>[0];
+        readonly items: readonly T[];
+        readonly pluginIdOf: (required: {
+            readonly item: T;
+        }) => string;
+    }) => readonly T[];
+    readAgentPluginActivations: (input: {
+        readonly workspaceRoot: string;
+    }) => Promise<import("./activation.js").AgentPluginActivations>;
+    assertAgentPluginActivationsWritable: (input: {
+        readonly workspaceRoot: string;
+    }) => Promise<void>;
+    isAgentPluginRecordedAsBundled: (input: {
+        readonly workspaceRoot: string;
+        readonly pluginId: string;
+    }) => Promise<boolean>;
+    resolveAgentPluginActivation: (input: {
+        readonly workspaceRoot: string;
+        readonly pluginId: string;
+    }) => Promise<import("./activation.js").AgentPluginActivationVerdict>;
+    normalizeActivations: (input: {
+        readonly value: unknown;
+    }) => import("./activation.js").AgentPluginActivations;
+    readBundledAgentPluginDigests: (input: {
+        readonly workspaceRoot: string;
+    }) => Promise<import("./bundled-digests.js").BundledAgentPluginDigests>;
+    normalizeBundledDigests: (input: {
+        readonly value: unknown;
+    }) => import("./bundled-digests.js").BundledAgentPluginDigests;
+    preferBundledAgentPluginDigests: <T extends InstalledDigestIdentity>(input: {
+        readonly installed: readonly T[];
+        readonly bundled: Parameters<(<T_1 extends InstalledDigestIdentity>(installed: readonly T_1[], bundled: import("./bundled-digests.js").BundledAgentPluginDigests) => readonly T_1[])>[1];
+    }) => readonly T[];
+    normalizePackageEntryPath: (input: {
+        readonly rawEntryPath: string;
+    }) => string;
+    assertContainedOnDisk: (input: {
+        readonly packageRoot: string;
+        readonly entryPath: string;
+    }) => Promise<string>;
+    classifyAgentPluginMcpServerTrust: (input: {
+        readonly server: Parameters<(server: Pick<import("./manifest.js").McpServerConfig, "type">) => "auto-admit" | "requires-confirmation">[0];
+    }) => "auto-admit" | "requires-confirmation";
+    readInstalledSkillMarkdown: (input: {
+        readonly packageRoot: string;
+        readonly skillPath: string;
+    }) => Promise<string>;
+    readInstalledMcpServerIds: (input: {
+        readonly packageRoot: string;
+    }) => Promise<readonly string[]>;
+    readInstalledMcpServers: (input: {
+        readonly packageRoot: string;
+    }) => Promise<Readonly<Record<string, import("./manifest.js").McpServerConfig>>>;
+    resolveAgentPluginRefs: (input: {
+        readonly pluginRefIds: readonly string[];
+        readonly workspaceLayout: Parameters<(pluginRefIds: readonly string[], workspaceLayout: Pick<import("./layout.js").AgentPluginWorkspaceLayout, "packages" | "root">, deliveryMode?: AgentPluginDeliveryMode) => Promise<import("./resolve-agent-plugin-refs.js").ResolveAgentPluginRefsResult>>[1];
+    }, optional?: {
+        readonly deliveryMode?: AgentPluginDeliveryMode;
+    }) => Promise<import("./resolve-agent-plugin-refs.js").ResolveAgentPluginRefsResult>;
+    listInstalledPlugins: (input: {
+        readonly packagesDir: string;
+    }) => Promise<readonly import("./types.js").InstalledAgentPlugin[]>;
+    isInstalledDigestPresent: (input: {
+        readonly packagesDir: string;
+        readonly archiveDigest: string;
+    }) => Promise<boolean>;
+    rankInstalledAgentPlugins: (input: {
+        readonly query: string;
+        readonly candidates: Parameters<(query: string, candidates: readonly import("./search.js").AgentPluginSearchCandidate[], limit: number) => readonly import("./search.js").AgentPluginSearchMatch[]>[1];
+        readonly limit: number;
+    }) => readonly import("./search.js").AgentPluginSearchMatch[];
+    readTrustedPluginFile: (input: {
+        readonly plugin: Parameters<(plugin: import("./trusted-plugin-files.js").TrustedPluginPackage, filename: string) => Promise<string>>[0];
+        readonly filename: string;
+    }) => Promise<string>;
+    importContainedModule: (input: {
+        readonly plugin: Parameters<(plugin: import("./trusted-plugin-files.js").TrustedPluginPackage, modulePath: string) => Promise<{
+            readonly exported: unknown;
+        } | string>>[0];
+        readonly modulePath: string;
+    }) => Promise<string | {
+        readonly exported: unknown;
+    }>;
+    maxAgentPluginInstallArchiveBytes: (_input: Record<string, never>) => number;
+    indexInstalledRoot: (input: {
+        readonly packageRoot: string;
+        readonly archiveDigest: string;
+    }) => Promise<import("./types.js").InstalledAgentPlugin>;
+    packAgentPluginDirectory: (input: {
+        readonly sourceDir: string;
+    }) => Promise<import("./bundled-source-archive.js").PackedAgentPluginArchive>;
+    createBundledSourceArchiveReader: (_input: Record<string, never>) => import("./install.js").AgentPluginArchiveReaderPort;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/lifecycle/index.js

@@ -0,0 +1,94 @@
+import { fetchAgentPluginArchive, maxAgentPluginArchiveBytes } from './fetch-archive.js';
+import { createSeedBundledModule } from './seed-bundled.js';
+import { createRetireBundledModule } from './retire-bundled.js';
+import { createActivationModule } from './activation.js';
+import { createBundledDigestsModule } from './bundled-digests.js';
+import { createBundledSourceArchiveModule } from './bundled-source-archive.js';
+import { createCapabilityProjectionModule } from './capability-projection.js';
+import { createInstallModule } from './install.js';
+import { createInstallFromUrlModule } from './install-from-url.js';
+import { createPackagePathsModule } from './package-paths.js';
+import { createResolveAgentPluginRefsModule } from './resolve-agent-plugin-refs.js';
+import { createSearchModule } from './search.js';
+import { createSetEnabledModule } from './set-enabled.js';
+import { createTrustedPluginFilesModule } from './trusted-plugin-files.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 { createAgentPluginActivations, ACTIVATIONS_FILENAME, ACTIVATIONS_LOCK_FILENAME, AgentPluginActivationsBusyError, AgentPluginActivationsUnreadableError } from './activation.js';
+export { BUNDLED_DIGESTS_FILENAME } from './bundled-digests.js';
+export { AgentPluginInstallError } from './install.js';
+export { PackagePathViolation } from './package-paths.js';
+export { AgentPluginNotInstalledError } from './set-enabled.js';
+export { AgentPluginNotFoundError, AgentPluginNotUninstallableError, AgentPluginChangedSincePreviewError } from './uninstall.js';
+/** One host context owns queues and effects. Keep this object and its ports stable for its lifetime.
+ * Installation/activation and MCP provisioning are separate operations: the host explicitly wires
+ * provisioning using the exported helpers, with its own retry/recovery policy. */
+export function createAgentPluginLifecycle(required, optional = {}) {
+    const context = Object.keys(optional).length ? { ...required, ...optional } : required;
+    if (!context.productName.trim() || !context.extensionNamespace.trim() || !context.bundledArchiveMagic) {
+        throw new Error('productName, extensionNamespace and bundledArchiveMagic are required');
+    }
+    if (context.deliveryMode !== 'inject' && context.deliveryMode !== 'pointer')
+        throw new Error('Invalid deliveryMode');
+    const activation = createActivationModule(context);
+    const digests = createBundledDigestsModule(context);
+    const archive = createBundledSourceArchiveModule(context);
+    const capabilities = createCapabilityProjectionModule(context);
+    const install = createInstallModule(context);
+    const fromUrl = createInstallFromUrlModule(context);
+    const paths = createPackagePathsModule(context);
+    const refs = createResolveAgentPluginRefsModule(context);
+    const search = createSearchModule(context);
+    const enabled = createSetEnabledModule(context);
+    const trusted = createTrustedPluginFilesModule(context);
+    const uninstall = createUninstallModule(context);
+    return {
+        fetchAgentPluginArchive: (input, optional = {}) => fetchAgentPluginArchive({ ...input, fetch: context.fetch, outboundGuard: context.outboundGuard }, optional),
+        maxAgentPluginArchiveBytes,
+        seedBundledAgentPlugins: createSeedBundledModule(context).seedBundledAgentPlugins,
+        retireBundledAgentPlugins: createRetireBundledModule(context).retireBundledAgentPlugins,
+        setAgentPluginActivation: activation.setAgentPluginActivation,
+        recordBundledAgentPluginIfAbsent: activation.recordBundledAgentPluginIfAbsent,
+        enableBundledAgentPluginUnlessOperatorDisabled: activation.enableBundledAgentPluginUnlessOperatorDisabled,
+        deleteAgentPluginActivation: activation.deleteAgentPluginActivation,
+        recordBundledAgentPluginDigests: (input, optional = {}) => digests.recordBundledAgentPluginDigests({ ...input, ...optional }),
+        removeBundledAgentPluginDigest: digests.removeBundledAgentPluginDigest,
+        installAgentPlugin: install.installAgentPlugin,
+        installAgentPluginFromUrl: fromUrl.installAgentPluginFromUrl,
+        setAgentPluginEnabled: enabled.setAgentPluginEnabled,
+        findTrustedPluginPackages: (input, optional = {}) => trusted.findTrustedPluginPackages({ ...input, ...optional }),
+        previewAgentPluginUninstall: uninstall.previewAgentPluginUninstall,
+        uninstallAgentPlugin: uninstall.uninstallAgentPlugin,
+        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),
+        assertAgentPluginActivationsWritable: (input) => activation.assertAgentPluginActivationsWritable(input.workspaceRoot),
+        isAgentPluginRecordedAsBundled: (input) => activation.isAgentPluginRecordedAsBundled(input.workspaceRoot, input.pluginId),
+        resolveAgentPluginActivation: (input) => activation.resolveAgentPluginActivation(input.workspaceRoot, input.pluginId),
+        normalizeActivations: (input) => activation.normalizeActivations(input.value),
+        readBundledAgentPluginDigests: (input) => digests.readBundledAgentPluginDigests(input.workspaceRoot),
+        normalizeBundledDigests: (input) => digests.normalizeBundledDigests(input.value),
+        preferBundledAgentPluginDigests: (input) => digests.preferBundledAgentPluginDigests(input.installed, input.bundled),
+        normalizePackageEntryPath: (input) => paths.normalizePackageEntryPath(input.rawEntryPath),
+        assertContainedOnDisk: (input) => paths.assertContainedOnDisk(input.packageRoot, input.entryPath),
+        classifyAgentPluginMcpServerTrust: (input) => capabilities.classifyAgentPluginMcpServerTrust(input.server),
+        readInstalledSkillMarkdown: (input) => capabilities.readInstalledSkillMarkdown(input.packageRoot, input.skillPath),
+        readInstalledMcpServerIds: (input) => capabilities.readInstalledMcpServerIds(input.packageRoot),
+        readInstalledMcpServers: (input) => capabilities.readInstalledMcpServers(input.packageRoot),
+        resolveAgentPluginRefs: (input, optional = {}) => refs.resolveAgentPluginRefs(input.pluginRefIds, input.workspaceLayout, optional.deliveryMode ?? context.deliveryMode),
+        listInstalledPlugins: (input) => refs.listInstalledPlugins(input.packagesDir),
+        isInstalledDigestPresent: (input) => refs.isInstalledDigestPresent(input.packagesDir, input.archiveDigest),
+        rankInstalledAgentPlugins: (input) => search.rankInstalledAgentPlugins(input.query, input.candidates, input.limit),
+        readTrustedPluginFile: (input) => trusted.readTrustedPluginFile(input.plugin, input.filename),
+        importContainedModule: (input) => trusted.importContainedModule(input.plugin, input.modulePath),
+        maxAgentPluginInstallArchiveBytes: (_input) => install.maxAgentPluginInstallArchiveBytes(),
+        indexInstalledRoot: (input) => install.indexInstalledRoot(input.packageRoot, input.archiveDigest),
+        packAgentPluginDirectory: (input) => archive.packAgentPluginDirectory(input.sourceDir),
+        createBundledSourceArchiveReader: (_input) => archive.createBundledSourceArchiveReader(),
+    };
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,78 @@
+/**
+ * Historical lifecycle rationale, carried with the implementation during consumer adoption.
+ *
+ * Host command-line rationale retained when the unused URL-install CLI was removed:
+ * - 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
+ * manifest logic of its own — every one of those guarantees still comes from `install.ts`, reached
+ * with bytes instead of a URL.
+ *
+ * ---------------------------------------------------------------------------
+ * Why integrity is a tagged union and not an optional string
+ * ---------------------------------------------------------------------------
+ * `installAgentPlugin` requires `expectedSha256` and refuses to extract unverified bytes. That is
+ * its central security property. A download flow has an obvious temptation: hash whatever arrived
+ * and pass that in — which type-checks, always "passes", and silently converts digest verification
+ * into a no-op.
+ *
+ * So the choice is made explicit and greppable instead of implied by an absent argument:
+ * `{ kind: "pinned", sha256 }` verifies against a digest the caller obtained out-of-band (a
+ * registry's own metadata, a release note, a prior `--print-digest` run), and
+ * `{ kind: "trust-on-first-use" }` states in the call site itself that this install trusts the
+ * transport and the host, nothing more. Both reach the identical `installAgentPlugin` call; the
+ * difference is entirely in whether the digest came from somewhere other than the bytes.
+ */
+import { type FetchAgentPluginArchiveOptional } from "./fetch-archive.js";
+import { type AgentPluginArchiveReaderPort, type InstalledAgentPlugin } from "./install.js";
+import type { AgentPluginLifecyclePorts } from "./ports.js";
+import type { AgentPluginLayout } from "./layout.js";
+/**
+ * See this module's header for why this is a union rather than an optional `expectedSha256`.
+ */
+export type AgentPluginIntegrity = {
+    readonly kind: "pinned";
+    readonly sha256: string;
+} | {
+    readonly kind: "trust-on-first-use";
+};
+/**
+ * Lowercase hex SHA-256 obtained OUT-OF-BAND — never computed from the downloaded bytes.
+ */
+export interface InstallAgentPluginFromUrlRequired {
+    readonly url: string;
+    readonly integrity: AgentPluginIntegrity;
+    readonly layout: AgentPluginLayout;
+    readonly workspaceId: string;
+    readonly archiveReader: AgentPluginArchiveReaderPort;
+}
+/**
+ * The instance-level layout. Passed straight through to `installAgentPlugin`, which is the only
+ * thing that may call `forWorkspace` — see its own SECURITY note.
+ */
+export interface InstallAgentPluginFromUrlOptional {
+    readonly fetch?: (FetchAgentPluginArchiveOptional) | undefined;
+}
+/**
+ * Defaults to {@link yauzlAgentPluginArchiveReader} — the only real reader in the tree.
+ */
+export interface InstalledAgentPluginFromUrl {
+    readonly installed: InstalledAgentPlugin;
+    readonly resolvedUrl: string;
+    readonly sha256: string;
+    readonly digestWasPinned: boolean;
+}
+export declare function createInstallFromUrlModule(ports: AgentPluginLifecyclePorts): {
+    installAgentPluginFromUrl: (required: InstallAgentPluginFromUrlRequired, optional?: InstallAgentPluginFromUrlOptional) => Promise<InstalledAgentPluginFromUrl>;
+};
+//# sourceMappingURL=install-from-url.d.ts.map

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

@@ -0,0 +1,73 @@
+/**
+ * Historical lifecycle rationale, carried with the implementation during consumer adoption.
+ *
+ * Host command-line rationale retained when the unused URL-install CLI was removed:
+ * - 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
+ * manifest logic of its own — every one of those guarantees still comes from `install.ts`, reached
+ * with bytes instead of a URL.
+ *
+ * ---------------------------------------------------------------------------
+ * Why integrity is a tagged union and not an optional string
+ * ---------------------------------------------------------------------------
+ * `installAgentPlugin` requires `expectedSha256` and refuses to extract unverified bytes. That is
+ * its central security property. A download flow has an obvious temptation: hash whatever arrived
+ * and pass that in — which type-checks, always "passes", and silently converts digest verification
+ * into a no-op.
+ *
+ * So the choice is made explicit and greppable instead of implied by an absent argument:
+ * `{ kind: "pinned", sha256 }` verifies against a digest the caller obtained out-of-band (a
+ * registry's own metadata, a release note, a prior `--print-digest` run), and
+ * `{ kind: "trust-on-first-use" }` states in the call site itself that this install trusts the
+ * transport and the host, nothing more. Both reach the identical `installAgentPlugin` call; the
+ * difference is entirely in whether the digest came from somewhere other than the bytes.
+ */
+import { fetchAgentPluginArchive } from "./fetch-archive.js";
+import { createInstallModule } from "./install.js";
+export function createInstallFromUrlModule(ports) {
+    const { installAgentPlugin } = createInstallModule(ports);
+    /**
+     * The URL the bytes actually came from, after redirects.
+     *
+     * Echoed so a `trust-on-first-use` caller can print the digest to pin on the next install.
+     *
+     * True when the digest was supplied out-of-band and verified, false for trust-on-first-use.
+     * Callers surface this so an unpinned install is never mistaken for a verified one.
+     *
+     * Downloads a plugin archive and installs it into this workspace's own on-disk package store.
+     *
+     * @throws {AgentPluginFetchError} For a download failure — bad URL, HTTP error, oversized body.
+     * @throws {AgentPluginInstallError} For everything after the bytes arrive — digest mismatch,
+     * hostile archive, invalid manifest. Both are thrown unchanged, so a caller can branch on `code`.
+     * @complexity O(b) in archive bytes; extraction cost is bounded by `install.ts`'s own `LIMITS`.
+     *
+     * For "pinned", this is the caller's out-of-band digest and `installAgentPlugin` genuinely
+     * verifies it. For "trust-on-first-use", it is the digest of the download itself, so that check
+     * is a tautology — which is exactly what the union's name says out loud at the call site.
+     */
+    async function installAgentPluginFromUrl(required, optional = {}) {
+        const { archive, sha256, resolvedUrl } = await fetchAgentPluginArchive({ url: required.url, fetch: ports.fetch, outboundGuard: ports.outboundGuard }, optional.fetch);
+        const expectedSha256 = required.integrity.kind === "pinned" ? required.integrity.sha256 : sha256;
+        const installed = await installAgentPlugin({
+            archive,
+            expectedSha256,
+            archiveReader: required.archiveReader,
+            layout: required.layout,
+            workspaceId: required.workspaceId,
+        });
+        return { installed, resolvedUrl, sha256, digestWasPinned: required.integrity.kind === "pinned" };
+    }
+    return { installAgentPluginFromUrl };
+}
+//# sourceMappingURL=install-from-url.js.map

package/dist/lifecycle/install.d.ts

@@ -0,0 +1,52 @@
+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";
+export declare class AgentPluginInstallError extends Error {
+    readonly code: AgentPluginInstallErrorCode;
+    constructor({ code, message }: {
+        readonly code: AgentPluginInstallErrorCode;
+        readonly message: string;
+    }, options?: {
+        cause?: unknown;
+    });
+}
+export type AgentPluginArchiveEntry = {
+    readonly kind: "file";
+    readonly entryPath: string;
+    readonly declaredSize?: (number) | undefined;
+    readonly executable?: (boolean) | undefined;
+    readonly openReadStream: (required: Record<string, never>) => AsyncIterable<Uint8Array>;
+} | {
+    readonly kind: "directory";
+    readonly entryPath: string;
+} | {
+    readonly kind: "symlink" | "hardlink" | "device" | "fifo";
+    readonly entryPath: string;
+    readonly linkTarget?: string | undefined;
+};
+/**
+ * `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.
+ */
+export interface AgentPluginArchiveReaderPort {
+    entries(required: {
+        readonly archive: Uint8Array;
+    }): AsyncIterable<AgentPluginArchiveEntry>;
+}
+export interface InstallAgentPluginRequired {
+    readonly archive: Uint8Array;
+    readonly expectedSha256: string;
+    readonly archiveReader: AgentPluginArchiveReaderPort;
+    readonly layout: AgentPluginLayout;
+    readonly workspaceId: string;
+}
+export type InstallAgentPluginOptional = {};
+/** 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>;
+    indexInstalledRoot: (packageRoot: string, archiveDigest: string) => Promise<InstalledAgentPlugin>;
+};
+//# sourceMappingURL=install.d.ts.map