@jini-ai/agent-plugins 0.4.7 → 0.4.8

package/dist/lifecycle/tools/projection.js

@@ -0,0 +1,283 @@
+/**
+ * @file Projects loaded Agent Plugin tools into the EXISTING plugin tool contribution contract
+ * (`@jini-ai/plugins/host`: `PluginContributionRegistry` → `attachPluginContributionTools`), so these
+ * tools reach the assistant through the same namespaced ids, enablement recheck, auth port, confirmation
+ * and revocable registry scope as every other plugin tool. Nothing here registers tools directly.
+ *
+ * Added at this seam, because only it knows a tool came from an Agent Plugin module:
+ * - schema validation of the input before the module runs (the registry passes schemas through);
+ * - per-call host capabilities, revoked when the plugin's tools are withdrawn;
+ * - the affected-resources disclosure the host shows before confirming a write/destructive call;
+ * - refusal of ambiguous ids (two plugins whose namespaced ids collide) and of write/destructive
+ *   tools that cannot disclose what they change.
+ */
+import { Validator } from '@cfworker/json-schema';
+import { requireInputRecord, ToolInputError } from '@jini-ai/core';
+import { openCapabilitySession, openCredentialScan, REVOKED_MESSAGE } from './capabilities.js';
+const MAX_RESOURCES = 50;
+const MAX_RESOURCE_LENGTH = 300;
+/** Agent Plugin tools have no site-plugin SDK; the contract's slot is filled with one that refuses. */
+const refuse = () => { throw new Error('Agent Plugin tools have no site-plugin SDK.'); };
+const INERT_SDK = Object.freeze({
+    content: Object.freeze({ read: refuse, extend: refuse }), addFilter: refuse, addAction: refuse, addContribution: refuse,
+    routes: Object.freeze({ add: refuse }), tools: Object.freeze({ add: refuse }), widgets: Object.freeze({ add: refuse }),
+});
+/** Compiles the declared schema, or says why it cannot be used. @complexity O(s) schema size. */
+function compileSchema(schema) {
+    try {
+        const validator = new Validator(schema, '2020-12', true);
+        // cfworker resolves references lazily; one probe surfaces a root-level unresolved $ref at load.
+        validator.validate({});
+        return validator;
+    }
+    catch (error) {
+        return `its input schema is invalid (${error instanceof Error ? error.message : String(error)})`;
+    }
+}
+/** Why a loaded tool cannot be projected, or its admitted form. @complexity O(s) schema size. */
+function admitOne(loaded, toolIdFor) {
+    const { descriptor, module } = loaded;
+    if (descriptor.effect !== 'read' && typeof module.describeAffectedResources !== 'function') {
+        return `a ${descriptor.effect} tool must export describeAffectedResources()`;
+    }
+    const validator = compileSchema(descriptor.inputSchema);
+    if (typeof validator === 'string')
+        return validator;
+    return { toolId: toolIdFor({ pluginId: loaded.pluginId, name: descriptor.name }), loaded, validator };
+}
+/** Admits each tool, then drops every id more than one plugin claims ("refusing to guess").
+ * @complexity O(t) tools plus schema compilation. */
+function admitAll(loaded, refusals, toolIdFor) {
+    const admitted = [];
+    for (const entry of loaded) {
+        const result = admitOne(entry, toolIdFor);
+        if (typeof result === 'string')
+            refusals.push(`agent tool '${entry.descriptor.name}' from '${entry.pluginId}' was not loaded: ${result}`);
+        else
+            admitted.push(result);
+    }
+    const claimants = new Map();
+    for (const tool of admitted)
+        claimants.set(tool.toolId, (claimants.get(tool.toolId) ?? new Set()).add(tool.loaded.pluginId));
+    for (const [toolId, owners] of claimants) {
+        if (owners.size > 1)
+            refusals.push(`agent tool '${toolId}' was not loaded: more than one plugin declares it (${[...owners].map(id => `'${id}'`).sort().join(', ')})`);
+    }
+    return admitted.filter(tool => claimants.get(tool.toolId).size === 1);
+}
+/** Validates input against the declared schema; the message names locations, never values.
+ * @complexity O(n) input size. */
+function validatedInput(tool, input) {
+    const record = requireInputRecord({ input });
+    let result;
+    // A schema fault reached only by some inputs (nested $ref, bad pattern) fails closed, not as bad input.
+    try {
+        result = tool.validator.validate(record);
+    }
+    catch (error) {
+        throw new Error(`Plugin tool '${tool.toolId}' has an unusable input schema; report it to the plugin author.`, { cause: error });
+    }
+    if (result.valid)
+        return record;
+    // cfworker roots every instanceLocation at '#' (validate()'s default, children append '/key'), so it
+    // is never empty; pinned by "input failing at the schema root is located at #" in projection.unit.test.ts.
+    const where = [...new Set(result.errors.map(unit => `${unit.instanceLocation} (${unit.keyword})`))].slice(0, 3).join(', ');
+    throw new ToolInputError({ message: `Input for '${tool.toolId}' does not match its schema at ${where}. Fix the input and retry.` });
+}
+/** True when both generations hold the same modules and declarations: no revocation needed. @complexity O(t). */
+function sameTools(previous, next, additional) {
+    if (!previous || previous.tools.length !== next.length || previous.additional.length !== additional.length
+        || !previous.additional.every((tool, index) => tool === additional[index]))
+        return false;
+    return previous.tools.every((tool, index) => tool.loaded.module === next[index].loaded.module
+        && JSON.stringify(tool.loaded.descriptor) === JSON.stringify(next[index].loaded.descriptor));
+}
+/**
+ * Checks a disclosure hook's answer. Its text reaches the confirmation prompt and the transcript,
+ * and module scope may still hold a token from an earlier call, so a list that mentions one is
+ * refused like a malformed one. @complexity O(r) resources plus the token scan.
+ */
+function checkedResources(toolId, value, scan) {
+    const valid = Array.isArray(value) && value.length <= MAX_RESOURCES
+        && value.every(item => typeof item === 'string' && item.length > 0 && item.length <= MAX_RESOURCE_LENGTH)
+        && !scan.mentionsToken({ value });
+    if (!valid)
+        throw new Error(`Plugin tool '${toolId}' returned an invalid affected-resources list; the call cannot be confirmed. Report it to the plugin author.`);
+    return Object.freeze([...value]);
+}
+/** Groups admitted tools and additional contributions in declaration order.
+ * Mutates only the local groups and appends admission failures to refusals. @complexity O(t) plus schema compilation. */
+function groupProjectionTools({ loaded, additionalTools, refusals, toolIdFor }, _options = {}) {
+    const grouped = new Map();
+    for (const tool of admitAll(loaded, refusals, toolIdFor)) {
+        const group = grouped.get(tool.loaded.pluginId);
+        if (group)
+            group.push(tool);
+        else
+            grouped.set(tool.loaded.pluginId, [tool]);
+    }
+    const additional = new Map();
+    for (const entry of additionalTools ?? []) {
+        const group = additional.get(entry.pluginId);
+        if (group)
+            group.push(entry);
+        else
+            additional.set(entry.pluginId, [entry]);
+        if (!grouped.has(entry.pluginId))
+            grouped.set(entry.pluginId, []);
+    }
+    return { grouped, additional };
+}
+/** Counts all declarations, including refused tools, and appends ambiguous-id refusals.
+ * @complexity O(t * (r + 1)) time and O(t) space for t declarations and r prior refusals. */
+function countProjectionClaims({ loaded, additionalTools, refusals, idFor }, _options = {}) {
+    // All claimants lose an ambiguous id, including collisions between executable and surface tools.
+    const counts = new Map();
+    const claimedIds = [...loaded.map(tool => idFor({ pluginId: tool.pluginId, name: tool.descriptor.name })),
+        ...(additionalTools ?? []).map(entry => idFor({ pluginId: entry.pluginId, name: entry.tool.name }))];
+    for (const id of claimedIds)
+        counts.set(id, (counts.get(id) ?? 0) + 1);
+    for (const [id, count] of counts) {
+        if (count <= 1)
+            continue;
+        // MOVE: Admission already reports executable collisions with their owners; preserve that diagnostic once.
+        if (refusals.some(reason => reason.startsWith(`agent tool '${id}' was not loaded:`)))
+            continue;
+        refusals.push(`agent tool '${id}' was not loaded: more than one contribution declares it`);
+    }
+    return counts;
+}
+/**
+ * Creates the projection for one dedicated contribution registry (keyed by plugin id, so it must not
+ * be shared with site plugins whose ids could match). Call `sync` after every load: on boot and on
+ * every activation change. A plugin missing from a load is detached: its tools disappear and its
+ * calls' capabilities are revoked.
+ * @param required.registry - Registry the host attached with `attachPluginContributionTools`.
+ * @param required.toolIdFor - The contract's namespacing rule (`pluginToolIdFor`), so ids match the registry's.
+ * @param required.capabilities - Host port building one call's capabilities.
+ * @param required.issuedTokens - Per-plugin token memory shared with the plugin's admin-surface handlers.
+ * @complexity sync is O(t) tools plus schema compilation; disclosure lookup is O(1).
+ */
+export function createAgentPluginToolProjection(required, _optional = {}) {
+    const { registry } = required;
+    let projected = new Map();
+    let additionalById = new Map();
+    let byToolId = new Map();
+    /** One contract tool whose handler validates, scopes capabilities and gates the result. */
+    function contractTool(tool, generationOf) {
+        const { isLive, issued } = generationOf;
+        const { descriptor, module } = tool.loaded;
+        const contribution = {
+            name: descriptor.name, description: descriptor.description, inputSchema: descriptor.inputSchema, effect: descriptor.effect,
+            async handler({ pluginId, auth, input, signal }) {
+                // Defense in depth: the registry rechecks enablement, but a retained handler must not run either.
+                if (!isLive())
+                    throw new Error(REVOKED_MESSAGE);
+                const checked = validatedInput(tool, input);
+                const host = required.capabilities({ pluginId, workspaceId: auth.workspaceId,
+                    ...(auth.principalId === undefined ? {} : { principalId: auth.principalId }), ...(signal === undefined ? {} : { signal }) });
+                const session = openCapabilitySession({ capabilities: host, isLive, issued });
+                try {
+                    const value = await module.invoke({ input: checked, capabilities: session.capabilities, ...(signal === undefined ? {} : { signal }) });
+                    return session.release({ value });
+                }
+                catch (error) {
+                    throw session.sanitize({ error });
+                }
+            },
+        };
+        return Object.freeze(contribution);
+    }
+    /** A fresh generation for one plugin; its tools are live only while the registry holds it. */
+    function generation(pluginId, tools, additional) {
+        let snapshot;
+        const isLive = () => snapshot !== undefined && registry.list({}).includes(snapshot);
+        const issued = required.issuedTokens.forPlugin({ pluginId });
+        snapshot = Object.freeze({ pluginId, sdk: INERT_SDK, routes: Object.freeze([]), widgets: Object.freeze([]),
+            tools: Object.freeze([...tools.map(tool => contractTool(tool, { isLive, issued })), ...additional.map(({ tool }) => Object.freeze({
+                    ...tool,
+                    handler(input) {
+                        if (!isLive())
+                            throw new Error(REVOKED_MESSAGE);
+                        return tool.handler(input);
+                    },
+                }))]) });
+        return { snapshot, tools, additional };
+    }
+    /** Replaces one plugin's generation unless it is unchanged; a refused replacement detaches it. */
+    function place(pluginId, tools, additional, refusals) {
+        const previous = projected.get(pluginId);
+        if (sameTools(previous, tools, additional))
+            return previous;
+        const next = generation(pluginId, tools, additional);
+        try {
+            registry.replace({ contributions: next.snapshot });
+            return next;
+        }
+        catch (error) {
+            registry.detach({ pluginId });
+            refusals.push(`agent tools from '${pluginId}' were not loaded: ${error instanceof Error ? error.message : String(error)}`);
+            return undefined;
+        }
+    }
+    return {
+        /** Projects one load result. @returns The loader's refusals plus this seam's own, in order. */
+        sync(input, _options = {}) {
+            const refusals = [...input.refusals];
+            const { grouped, additional } = groupProjectionTools({
+                loaded: input.loaded, additionalTools: input.additionalTools, refusals, toolIdFor: required.toolIdFor,
+            });
+            const idFor = required.toolIdFor;
+            const counts = countProjectionClaims({ loaded: input.loaded, additionalTools: input.additionalTools, refusals, idFor });
+            const nextProjected = new Map();
+            for (const [pluginId, tools] of grouped) {
+                const unique = tools.filter(tool => counts.get(tool.toolId) === 1);
+                const extras = (additional.get(pluginId) ?? []).filter(entry => counts.get(idFor({ pluginId, name: entry.tool.name })) === 1);
+                const placed = place(pluginId, unique, extras, refusals);
+                if (placed)
+                    nextProjected.set(pluginId, placed);
+            }
+            for (const pluginId of projected.keys())
+                if (!grouped.has(pluginId))
+                    registry.detach({ pluginId });
+            projected = nextProjected;
+            additionalById = new Map([...nextProjected.values()].flatMap(plugin => plugin.additional.map(entry => [idFor({ pluginId: entry.pluginId, name: entry.tool.name }), { entry, snapshot: plugin.snapshot }])));
+            byToolId = new Map([...nextProjected.values()].flatMap(plugin => plugin.tools.map(tool => [tool.toolId, { tool, snapshot: plugin.snapshot }])));
+            return { refusals };
+        },
+        /** What a call would change, for the confirmation prompt; null for an unknown or withdrawn tool.
+         * @throws ToolInputError for input that fails the schema; Error for an invalid hook answer. */
+        async describeAffectedResources(input, _options = {}) {
+            const extra = additionalById.get(input.toolId);
+            if (extra && registry.list({}).includes(extra.snapshot)) {
+                const scan = openCredentialScan({ issued: required.issuedTokens.forPlugin({ pluginId: extra.entry.pluginId }) });
+                try {
+                    const resources = await extra.entry.describeAffectedResources({ input: input.input });
+                    return { effect: extra.entry.tool.effect ?? 'write', resources: checkedResources(input.toolId, resources, scan) };
+                }
+                catch (error) {
+                    throw scan.sanitize({ error });
+                }
+            }
+            const entry = byToolId.get(input.toolId);
+            if (!entry || !registry.list({}).includes(entry.snapshot))
+                return null;
+            const { tool } = entry;
+            const checked = validatedInput(tool, input.input);
+            const describe = tool.loaded.module.describeAffectedResources;
+            if (!describe)
+                return { effect: tool.loaded.descriptor.effect, resources: [] };
+            // The same per-plugin token memory the plugin's calls feed: its answers and errors are scanned alike.
+            const scan = openCredentialScan({ issued: required.issuedTokens.forPlugin({ pluginId: tool.loaded.pluginId }) });
+            let answer;
+            try {
+                answer = await describe({ input: checked });
+            }
+            catch (error) {
+                throw scan.sanitize({ error });
+            }
+            return { effect: tool.loaded.descriptor.effect, resources: checkedResources(tool.toolId, answer, scan) };
+        },
+    };
+}
+//# sourceMappingURL=projection.js.map

package/dist/lifecycle/types.d.ts

@@ -8,6 +8,8 @@ export interface InstalledAgentPluginSkill {
 export interface InstalledAgentPlugin {
     readonly id?: string | undefined;
     readonly provides?: readonly string[] | undefined;
+    readonly requires?: readonly string[] | undefined;
+    readonly hostRange?: 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

package/dist/lifecycle/uninstall.d.ts

@@ -64,7 +64,9 @@ export interface StagedTree {
 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>;
+    stageForRemoval: (packagesDir: string, packageRoot: string, optional?: {
+        quarantined?: string;
+    }) => Promise<StagedTree>;
     restoreStagedTrees: (staged: readonly StagedTree[], cause: unknown) => Promise<unknown>;
     removeFrozenPackageTree: (root: string) => Promise<void>;
 };

package/dist/lifecycle/uninstall.js

@@ -112,6 +112,7 @@ import path from "node:path";
 import { createPackagePathsModule } from "./package-paths.js";
 import { createActivationModule } from "./activation.js";
 import { createResolveAgentPluginRefsModule } from "./resolve-agent-plugin-refs.js";
+import { createAgentPluginUpdateStore, settleAgentPluginUpdateJournal } from "./update-store.js";
 /** The plugin id has no installed package on disk for this workspace. */
 export class AgentPluginNotFoundError extends Error {
     constructor({ message }, optional = {}) { super(message, optional); }
@@ -174,50 +175,71 @@ function buildModule(ports) {
         return createPersistentStateModule(ports).withPluginLock({ workspaceRoot, pluginId: required.pluginId,
             run: () => uninstallAgentPluginUnlocked(required, optional) });
     }
-    // Reversible work first — see this file's header, "Why removal stages first". Nothing on this
-    // side of the try is destructive: every step up to and including the activation-record delete can
-    // be undone by renaming the staged trees back where they came from.
-    // Past this point the live state is already settled: the packages are no longer reachable under
-    // any installed-digest name and the activation record is gone. These removes are the only
-    // irreversible step, and nothing observable depends on them finishing.
-    // Remove only empty package ancestors: a concurrently-installed digest must never be deleted.
-    // No package may have appeared since this uninstall's preview. Preserve it on a race.
     async function uninstallAgentPluginUnlocked(required, optional = {}) {
         const { workspaceRoot, packagesDir, matches } = await resolveUninstallTargets(required, optional.retiredBundled === true);
         assertUnchangedSincePreview(required.pluginId, optional.confirmedPreview, matches);
-        if (optional.deleteMemory && (!optional.confirmedPreview || optional.confirmedPreview.pluginId !== required.pluginId)) {
+        assertMemoryDeletionConfirmed(required, optional);
+        // An unfinished update journal would make boot recovery resurrect the old revision over this
+        // uninstall, so it refuses (PLUGIN_UPDATE_PENDING) until a boot recovers it. The store resolves
+        // paths from this call's own layout, like every other path here.
+        const updates = createAgentPluginUpdateStore({ ports: { ...ports, layout: required.layout }, workspaceId: required.workspaceId, pluginId: required.pluginId });
+        await settleAgentPluginUpdateJournal({ store: updates });
+        const staged = await stageAndDeleteActivation({ workspaceRoot, packagesDir, pluginId: required.pluginId, matches });
+        // Past this point the live state is already settled: the packages are no longer reachable under
+        // any installed-digest name and the activation record is gone. These removes are the only
+        // irreversible step, and nothing observable depends on them finishing.
+        for (const tree of staged) {
+            await removeFrozenPackageTree(tree.quarantined);
+        }
+        await removeEmptyPackageAncestors({ packagesDir });
+        if (optional.deleteMemory)
+            await deletePersistentMemory({ ...required, workspaceRoot });
+        return { pluginId: required.pluginId, removedDigests: matches.map((plugin) => plugin.archiveDigest) };
+    }
+    function assertMemoryDeletionConfirmed(required, optional) {
+        if (optional.deleteMemory && optional.confirmedPreview?.pluginId !== required.pluginId) {
             throw new Error('Deleting plugin memory requires a confirmed preview for this plugin');
         }
+    }
+    /** Reversible work first — see this file's header, "Why removal stages first". Nothing in here is
+     *  destructive: every step up to and including the activation-record delete can be undone by
+     *  renaming the staged trees back where they came from. */
+    async function stageAndDeleteActivation(required) {
         const staged = [];
         try {
-            for (const plugin of matches) {
-                staged.push(await stageForRemoval(packagesDir, plugin.packageRoot));
+            for (const plugin of required.matches) {
+                staged.push(await stageForRemoval(required.packagesDir, plugin.packageRoot));
             }
-            await deleteAgentPluginActivation({ workspaceRoot, pluginId: required.pluginId });
+            await deleteAgentPluginActivation({ workspaceRoot: required.workspaceRoot, pluginId: required.pluginId });
         }
         catch (error) {
             throw await restoreStagedTrees(staged, error);
         }
-        for (const tree of staged) {
-            await removeFrozenPackageTree(tree.quarantined);
-        }
-        for (const directory of [packagesDir, path.dirname(packagesDir)]) {
+        return staged;
+    }
+    /** Remove only empty package ancestors: a concurrently-installed digest must never be deleted. */
+    async function removeEmptyPackageAncestors(required) {
+        for (const directory of [required.packagesDir, path.dirname(required.packagesDir)]) {
             try {
                 await rmdir(directory);
             }
             catch (error) {
-                if (!error || typeof error !== 'object' || !('code' in error) || !['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes(String(error.code)))
+                if (!isAncestorStillInUse(error))
                     throw error;
             }
         }
-        if (optional.deleteMemory) {
-            const pluginRoot = required.layout.forWorkspace({ workspaceId: required.workspaceId }).pluginRootDir({ pluginId: required.pluginId });
-            await assertContainedOnDisk(workspaceRoot, path.relative(workspaceRoot, pluginRoot));
-            if ((await listInstalledPlugins(workspaceRoot)).some(plugin => plugin.pluginId === required.pluginId))
-                throw new Error('Plugin was reinstalled during uninstall; persistent memory was kept');
-            await rm(pluginRoot, { recursive: true, force: true });
-        }
-        return { pluginId: required.pluginId, removedDigests: matches.map((plugin) => plugin.archiveDigest) };
+    }
+    function isAncestorStillInUse(error) {
+        return typeof error === 'object' && error !== null && 'code' in error && ['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes(String(error.code));
+    }
+    /** No package may have appeared since this uninstall's preview. Preserve it on a race. */
+    async function deletePersistentMemory(required) {
+        const { workspaceRoot, pluginId } = required;
+        const pluginRoot = required.layout.forWorkspace({ workspaceId: required.workspaceId }).pluginRootDir({ pluginId });
+        await assertContainedOnDisk(workspaceRoot, path.relative(workspaceRoot, pluginRoot));
+        if ((await listInstalledPlugins(workspaceRoot)).some(plugin => plugin.pluginId === pluginId))
+            throw new Error('Plugin was reinstalled during uninstall; persistent memory was kept');
+        await rm(pluginRoot, { recursive: true, force: true });
     }
     /**
    * Refuses when the digests resolved now are not exactly the set a confirmed preview listed — an archive added
@@ -245,8 +267,10 @@ function buildModule(ports) {
    *
    * @complexity One `stat`, one or two `chmod`s, one `rename`.
    */
-    async function stageForRemoval(packagesDir, packageRoot) {
-        const quarantined = path.join(packagesDir, `${STAGED_DIRNAME_PREFIX}${randomUUID()}`);
+    async function stageForRemoval(packagesDir, packageRoot, optional = {}) {
+        // Updates choose a journaled destination outside packages/sha256; uninstall keeps its sibling
+        // destination and same-filesystem guarantee documented above. Both retain the same move owner.
+        const quarantined = optional.quarantined ?? path.join(packagesDir, `${STAGED_DIRNAME_PREFIX}${randomUUID()}`);
         const originalMode = (await stat(packageRoot)).mode & 0o777;
         await chmod(packageRoot, originalMode | 0o700);
         try {

package/dist/lifecycle/update-plan.d.ts

@@ -0,0 +1,18 @@
+import type { InstalledAgentPlugin } from './types.js';
+type Revision = Pick<InstalledAgentPlugin, 'pluginId' | 'archiveDigest' | 'version'> & {
+    readonly enabled?: boolean;
+};
+export interface AgentPluginUpdatePlan {
+    readonly action: 'none' | 'update' | 'downgrade-refused' | 'id-mismatch';
+    readonly enabled: boolean;
+    readonly warnings: readonly string[];
+}
+/** Manifest semver orders releases; digest identifies bytes. Unknown or equal versions require
+ * an explicit replacement; automatic rollback bypasses planning. @complexity O(v) version length.
+ */
+export declare function planAgentPluginUpdate({ installed, candidate }: {
+    readonly installed: Revision;
+    readonly candidate: Revision;
+}, _optional?: Record<string, never>): AgentPluginUpdatePlan;
+export {};
+//# sourceMappingURL=update-plan.d.ts.map

package/dist/lifecycle/update-plan.js

@@ -0,0 +1,22 @@
+import * as semver from 'semver';
+/** Manifest semver orders releases; digest identifies bytes. Unknown or equal versions require
+ * an explicit replacement; automatic rollback bypasses planning. @complexity O(v) version length.
+ */
+export function planAgentPluginUpdate({ installed, candidate }, _optional = {}) {
+    const enabled = installed.enabled === true;
+    if (installed.pluginId !== candidate.pluginId)
+        return { action: 'id-mismatch', enabled, warnings: [] };
+    if (installed.archiveDigest === candidate.archiveDigest)
+        return { action: 'none', enabled, warnings: [] };
+    // `semver.valid` returns null for an absent version as well as a malformed one.
+    const from = semver.valid(installed.version);
+    const to = semver.valid(candidate.version);
+    if (!from || !to) {
+        return { action: 'update', enabled, warnings: ['Unknown release version; explicit replacement required.'] };
+    }
+    const order = semver.compare(to, from);
+    if (order < 0)
+        return { action: 'downgrade-refused', enabled, warnings: [] };
+    return { action: 'update', enabled, warnings: order === 0 ? ['Same version with different bytes; explicit replacement required.'] : [] };
+}
+//# sourceMappingURL=update-plan.js.map

package/dist/lifecycle/update-store.d.ts

@@ -0,0 +1,71 @@
+import type { AgentPluginLifecyclePorts } from './ports.js';
+/** One update transaction's durable intent and, once finished, its audit record (`result`).
+ * `settingsSnapshot` is the host's NON-SECRET settings summary; hosts must never put secret values
+ * in it, because it is retained in the update history after the transaction ends. */
+export interface AgentPluginUpdateJournal {
+    readonly schemaVersion: 1;
+    readonly state: 'pending' | 'published' | 'committed';
+    readonly transactionId: string;
+    readonly pluginId: string;
+    readonly actor: string;
+    readonly enabled: boolean;
+    readonly fromDigest: string;
+    readonly toDigest: string;
+    readonly fromVersion?: string | undefined;
+    readonly toVersion?: string | undefined;
+    readonly settingsSnapshot: unknown;
+    readonly startedAt: string;
+    readonly result?: 'updated' | 'rolled-back';
+}
+export declare class AgentPluginUpdateError extends Error {
+    readonly code: string;
+    constructor(required: {
+        code: string;
+        message: string;
+    }, optional?: ErrorOptions);
+}
+/** Durable per-plugin journal, audit history and frozen rollback area, all under the plugin's own
+ * state root (never under `package/sha256`, so a rollback copy is never a live digest). Files use
+ * the existing platform atomic writer. Settings snapshots are private (0600) and never returned to
+ * tools or HTTP callers.
+ * @complexity O(s) serialization of the host's settings slice.
+ */
+export declare function createAgentPluginUpdateStore({ ports, workspaceId, pluginId }: {
+    ports: AgentPluginLifecyclePorts;
+    workspaceId: string;
+    pluginId: string;
+}, _optional?: Record<string, never>): {
+    read: (_required: Record<string, never>, _optional?: {}) => Promise<AgentPluginUpdateJournal | undefined>;
+    write: ({ journal, history }: {
+        journal: AgentPluginUpdateJournal;
+        history?: boolean;
+    }, _optional?: {}) => Promise<void>;
+    clear: (_required: Record<string, never>, _optional?: {}) => Promise<void>;
+    finish: ({ journal }: {
+        journal: AgentPluginUpdateJournal;
+    }, _optional?: {}) => Promise<void>;
+    prepare: (_required: Record<string, never>, _optional?: {}) => Promise<void>;
+    listRollbackRoots: (_required: Record<string, never>, _optional?: {}) => Promise<string[]>;
+    realDirectoryExists: ({ root: target }: {
+        root: string;
+    }, _optional?: {}) => Promise<boolean>;
+    rollbackDir: string;
+    rollbackRoot: ({ digest }: {
+        digest: string;
+    }, _optional?: {}) => string;
+    liveRoot: ({ digest }: {
+        digest: string;
+    }, _optional?: {}) => string;
+};
+/** Every mutation of a plugin (update, enable/disable, uninstall) runs this under the plugin lock
+ * first. An unfinished journal refuses it: boot recovery would otherwise resurrect the old revision
+ * over an uninstall or overwrite an operator's newer decision. A committed journal whose audit filing
+ * was interrupted is filed now.
+ * @throws AgentPluginUpdateError PLUGIN_UPDATE_PENDING, UPDATE_JOURNAL_INVALID. */
+export declare function settleAgentPluginUpdateJournal({ store }: {
+    store: Pick<ReturnType<typeof createAgentPluginUpdateStore>, 'read' | 'finish'>;
+}, _optional?: {}): Promise<void>;
+export declare function isMissing({ error }: {
+    error: unknown;
+}, _optional?: {}): boolean;
+//# sourceMappingURL=update-store.d.ts.map