@jini-ai/agent-plugins 0.4.6 → 0.4.8

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

package/dist/lifecycle/update-store.js

@@ -0,0 +1,150 @@
+import path from 'node:path';
+import { writeJsonFileAtomicAsync } from '@jini-ai/platform/fs';
+import { createPersistentStateModule } from './persistent-state.js';
+export class AgentPluginUpdateError extends Error {
+    code;
+    constructor(required, optional = {}) {
+        super(required.message, optional);
+        this.code = required.code;
+        this.name = 'AgentPluginUpdateError';
+    }
+}
+const DIGEST_PATTERN = /^[a-f0-9]{64}$/;
+const TRANSACTION_PATTERN = /^[a-zA-Z0-9-]{1,100}$/;
+const JOURNAL_STATES = ['pending', 'published', 'committed'];
+function invalidJournal(optional = {}) {
+    return new AgentPluginUpdateError({ code: 'UPDATE_JOURNAL_INVALID', message: 'Update recovery record is invalid.' }, optional);
+}
+function hasValidIdentity({ raw, pluginId }) {
+    return raw.schemaVersion === 1 && raw.pluginId === pluginId && typeof raw.actor === 'string' && typeof raw.enabled === 'boolean';
+}
+/** Digests become path segments in recovery; the grammar check is what keeps them segments. */
+function hasValidDigests({ raw }) {
+    const digests = [raw.fromDigest, raw.toDigest];
+    return raw.fromDigest !== raw.toDigest && digests.every(digest => typeof digest === 'string' && DIGEST_PATTERN.test(digest));
+}
+/** The transaction id names the history file, so it gets the same segment discipline. */
+function hasValidTransaction({ raw }) {
+    return JOURNAL_STATES.includes(raw.state) && typeof raw.transactionId === 'string'
+        && TRANSACTION_PATTERN.test(raw.transactionId) && typeof raw.startedAt === 'string';
+}
+/** Validates durable intent before using it; no journal field is ever accepted as a path.
+ * A damaged journal blocks mutations instead of discarding the only recovery record.
+ */
+function parseJournal({ value, pluginId }, _optional = {}) {
+    if (typeof value !== 'object' || value === null)
+        throw invalidJournal();
+    const raw = value;
+    if (!hasValidIdentity({ raw, pluginId }) || !hasValidDigests({ raw }) || !hasValidTransaction({ raw }))
+        throw invalidJournal();
+    return raw;
+}
+/** 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 function createAgentPluginUpdateStore({ ports, workspaceId, pluginId }, _optional = {}) {
+    const workspace = ports.layout.forWorkspace({ workspaceId });
+    const root = workspace.pluginRootDir({ pluginId });
+    const journalPath = path.join(root, 'update-journal.json');
+    const rollbackDir = path.join(root, 'rollback');
+    const persistent = createPersistentStateModule(ports);
+    async function contain({ entryPath }, _optional = {}) {
+        await persistent.assertOwnedPath({ workspaceRoot: workspace.root, entryPath: path.relative(workspace.root, entryPath) });
+    }
+    async function read(_required, _optional = {}) {
+        await contain({ entryPath: journalPath });
+        let text;
+        try {
+            text = await ports.filesystem.readFile(journalPath, 'utf8');
+        }
+        catch (error) {
+            if (!isMissing({ error }))
+                throw error;
+            return undefined;
+        }
+        let value;
+        try {
+            value = JSON.parse(text);
+        }
+        catch (cause) {
+            throw invalidJournal({ cause });
+        }
+        return parseJournal({ value, pluginId });
+    }
+    async function write({ journal, history = false }, _optional = {}) {
+        const filePath = history ? path.join(root, 'update-history', `${journal.transactionId}.json`) : journalPath;
+        await contain({ entryPath: filePath });
+        await writeJsonFileAtomicAsync({ filePath, data: journal }, { fs: ports.filesystem,
+            createParent: true, mode: 0o600, platform: ports.process.platform, tempName: () => ports.ids.newId() });
+    }
+    async function clear(_required, _optional = {}) {
+        await contain({ entryPath: journalPath });
+        await ports.filesystem.rm(journalPath, { force: true });
+    }
+    /** Audit first, then drop the active journal: a crash between the two leaves a finished journal
+     * that the next update or boot re-files (same transaction id, so the history write is idempotent). */
+    async function finish({ journal }, _optional = {}) {
+        await write({ journal, history: true });
+        await clear({});
+    }
+    async function prepare(_required, _optional = {}) {
+        await contain({ entryPath: rollbackDir });
+        await ports.filesystem.mkdir(rollbackDir, { recursive: true, mode: 0o700 });
+    }
+    /** Recovery chmods, renames and removes rollback and live roots, so each one must be a real
+     * directory inside this workspace's plugin state, never a symlink planted to redirect those calls
+     * (a symlink leaf fails `isDirectory()` under lstat; `contain` rejects symlinked ancestors).
+     * @returns false when the root is absent. */
+    async function realDirectoryExists({ root: target }, _optional = {}) {
+        let stats;
+        try {
+            stats = await ports.filesystem.lstat(target);
+        }
+        catch (error) {
+            if (!isMissing({ error }))
+                throw error;
+            return false;
+        }
+        if (!stats.isDirectory())
+            throw new AgentPluginUpdateError({ code: 'PLUGIN_UPDATE_PATH_UNSAFE', message: 'An update recovery path is not a real directory; repair it by hand.' });
+        await contain({ entryPath: target });
+        return true;
+    }
+    /** Retained rollback copies (digest-named directories only); other entries are never touched. */
+    async function listRollbackRoots(_required, _optional = {}) {
+        await contain({ entryPath: rollbackDir });
+        let entries;
+        try {
+            entries = await ports.filesystem.readdir(rollbackDir, { withFileTypes: true });
+        }
+        catch (error) {
+            if (!isMissing({ error }))
+                throw error;
+            return [];
+        }
+        return entries.filter(entry => entry.isDirectory() && DIGEST_PATTERN.test(entry.name)).map(entry => path.join(rollbackDir, entry.name));
+    }
+    return { read, write, clear, finish, prepare, listRollbackRoots, realDirectoryExists, rollbackDir,
+        rollbackRoot: ({ digest }, _optional = {}) => path.join(rollbackDir, digest),
+        liveRoot: ({ digest }, _optional = {}) => path.join(workspace.pluginPackagesDir({ pluginId }), digest) };
+}
+/** 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 async function settleAgentPluginUpdateJournal({ store }, _optional = {}) {
+    const outstanding = await store.read({});
+    if (!outstanding)
+        return;
+    if (outstanding.state !== 'committed')
+        throw new AgentPluginUpdateError({ code: 'PLUGIN_UPDATE_PENDING', message: 'Restart the host to recover the interrupted update.' });
+    await store.finish({ journal: outstanding });
+}
+export function isMissing({ error }, _optional = {}) {
+    return typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT';
+}
+//# sourceMappingURL=update-store.js.map

package/dist/lifecycle/update.d.ts

@@ -0,0 +1,55 @@
+import { type InstallAgentPluginOptional, type InstallAgentPluginRequired } from './install.js';
+import type { AgentPluginLifecyclePorts } from './ports.js';
+import type { InstalledAgentPlugin } from './types.js';
+export interface UpdateAgentPluginRequired extends InstallAgentPluginRequired {
+    readonly pluginId: string;
+    /** The digest the operator previewed; any other live revision refuses with PLUGIN_CHANGED. */
+    readonly expectedOldDigest: string;
+    /** The authenticated principal, recorded in the update audit. */
+    readonly actor: string;
+    /** Host owns settings schemas; archives never supply executable migrations or snapshot code.
+     * Return a NON-SECRET summary only: it is persisted (0600) in the journal and update history. */
+    readonly snapshotSettings: (required: {
+        workspaceId: string;
+        pluginId: string;
+    }, optional: Record<string, never>) => Promise<unknown>;
+}
+export interface UpdateAgentPluginResult {
+    readonly plugin: InstalledAgentPlugin;
+    readonly enabled: boolean;
+    readonly alreadyInstalled: boolean;
+    readonly warnings: readonly string[];
+}
+type InstallAgentPluginPort = (required: InstallAgentPluginRequired, optional: InstallAgentPluginOptional) => Promise<InstalledAgentPlugin>;
+/** Update transaction owner for operator-installed plugins (bundled ones stay seed-managed).
+ *
+ * Runs inside the installer's identity lock and per-plugin file lock (the publish guard), so it is
+ * serialized against enable/disable/uninstall, which take the same plugin lock. Nothing called in
+ * the guard re-takes that lock: activation writes use their own activations.json lock.
+ *
+ * Invariant: never two live digests. The old revision moves to a frozen rollback area outside
+ * `package/sha256` before the candidate is published; a per-plugin journal (pending -> published ->
+ * committed) lets boot reconciliation restore it if the process dies before commit.
+ *
+ * Documented behavior:
+ * - In-flight MCP calls against the old revision may fail once the roster is re-provisioned.
+ * - Running chats keep the skill text they already captured; new runs resolve the new revision.
+ * - Rollback bytes are retained after commit (a run may still read them) and collected by the next
+ *   boot's reconciliation, when no run can hold those paths.
+ * - Plugin data and memory directories carry over untouched. A rollback restores package bytes and
+ *   activation only; it does NOT revert data, memory or settings written while the candidate ran.
+ *   The settings snapshot is an audit record, not a restore source.
+ * - Caches: this package keeps no cache of skill prompt indexes or search ranking keyed by plugin
+ *   (search ranking is computed per call from the installed list; per-run automatic-use state is
+ *   per run; module imports are keyed by the digest path), so a switch has nothing to invalidate.
+ */
+export declare function createUpdateModule(ports: AgentPluginLifecyclePorts, optional?: {
+    installAgentPlugin?: InstallAgentPluginPort;
+}): {
+    updateAgentPlugin: (required: UpdateAgentPluginRequired, _optional?: Record<string, never>) => Promise<UpdateAgentPluginResult>;
+    reconcileAgentPluginUpdates: ({ workspaceId }: {
+        workspaceId: string;
+    }, _optional?: Record<string, never>) => Promise<void>;
+};
+export {};
+//# sourceMappingURL=update.d.ts.map