@jini-ai/agent-plugins 0.4.0

package/dist/lifecycle/activation.d.ts

@@ -0,0 +1,177 @@
+import { type FileLockHolder } from "@jini-ai/platform/fs/file-lock";
+import type { AgentPluginLifecyclePorts } from "./ports.js";
+/**
+ * Where a workspace's activation record lives, relative to its own agent-plugin root.
+ */
+export declare const ACTIVATIONS_FILENAME = "activations.json";
+/**
+ * The cross-process lock every writer below takes before touching {@link ACTIVATIONS_FILENAME} —
+ *  see this file's header, "Concurrency", ACROSS processes.
+ */
+export declare const ACTIVATIONS_LOCK_FILENAME = "activations.json.lock";
+/**
+ * How a package came to be on disk. The whole reason the record is not just a boolean: it is what
+ *  lets an operator (and a future admin screen) tell "the host shipped this, you have not enabled it"
+ *  apart from "you installed this and then turned it off".
+ */
+export type AgentPluginOrigin = "bundled" | "operator-installed";
+export interface AgentPluginActivationRecord {
+    readonly enabled: boolean;
+    readonly origin: AgentPluginOrigin;
+    readonly updatedAt: string;
+    readonly updatedBy: string;
+}
+/**
+ * Who last changed it — an operator identifier, or `"system:seed"` for the seeder's own initial
+ *  disabled record. Audit breadcrumb; never used for authorization.
+ */
+export interface AgentPluginActivations {
+    readonly schemaVersion: 1;
+    readonly plugins: Readonly<Record<string, AgentPluginActivationRecord>>;
+}
+/**
+ * A WRITER (or the strict provenance read) found the activations file present but unreadable, and
+ *  refused rather than rewrite it — see this file's header, "Writers never rewrite what they could
+ *  not read". `message` names the host path: keep it in a server-side log, never in a model- or
+ *  user-facing payload.
+ */
+export declare class AgentPluginActivationsUnreadableError extends Error {
+    readonly filePath: string;
+    readonly reason: string;
+    constructor({ filePath, reason }: {
+        readonly filePath: string;
+        readonly reason: string;
+    });
+}
+/**
+ * A WRITER could not take (or lost) the cross-process write lock in time — see this file's header,
+ *  "Concurrency", ACROSS processes, and `exclusive-file-lock.ts`. `lost: true` means the lock WAS
+ *  acquired but was judged stale by another process before this writer's own rename; `lost: false`
+ *  means the initial acquisition itself timed out. Either way NOTHING was written. `message` names
+ *  the host lock path: keep it in a server-side log, never in a model- or user-facing payload.
+ */
+export declare class AgentPluginActivationsBusyError extends Error {
+    readonly lockPath: string;
+    readonly holder: FileLockHolder | undefined;
+    readonly lost: boolean;
+    constructor({ lockPath, holder, lost }: {
+        readonly lockPath: string;
+        readonly holder: FileLockHolder | undefined;
+        readonly lost: boolean;
+    });
+}
+/**
+ * One plugin's activation state, or the explicit third answer the other two readers cannot give:
+ *  the operator's decisions could not be established at all.
+ */
+export type AgentPluginActivationVerdict = {
+    readonly verdict: "active";
+} | {
+    readonly verdict: "inactive";
+} | {
+    readonly verdict: "undetermined";
+    readonly reason: string;
+};
+export interface SetAgentPluginActivationRequired {
+    readonly workspaceRoot: string;
+    readonly pluginId: string;
+    readonly enabled: boolean;
+    readonly actor: string;
+}
+/**
+ * Recorded as `updatedBy`. An operator identifier at a real call site.
+ */
+export interface SetAgentPluginActivationOptional {
+    readonly origin?: (AgentPluginOrigin) | undefined;
+    readonly now?: ((required: Record<string, never>) => Date) | undefined;
+}
+/**
+ * What {@link enableBundledAgentPluginUnlessOperatorDisabled} found and did.
+ */
+export type BundledAgentPluginEnableOutcome = "enabled" | "already-enabled" | "left-disabled-by-operator";
+export interface DeleteAgentPluginActivationRequired {
+    readonly workspaceRoot: string;
+    readonly pluginId: string;
+}
+type ActivationPorts = Pick<AgentPluginLifecyclePorts, "filesystem" | "clock" | "ids" | "process" | "onEvent">;
+/** Internal composition; one state/queue instance per injected host context. */
+export declare function createActivationModule(ports: ActivationPorts): {
+    isAgentPluginActive: (activations: AgentPluginActivations, pluginId: string) => boolean;
+    filterActiveAgentPlugins: <T>(activations: AgentPluginActivations, items: readonly T[], pluginIdOf: (item: T) => string) => readonly T[];
+    readAgentPluginActivations: (workspaceRoot: string) => Promise<AgentPluginActivations>;
+    assertAgentPluginActivationsWritable: (workspaceRoot: string) => Promise<void>;
+    isAgentPluginRecordedAsBundled: (workspaceRoot: string, pluginId: string) => Promise<boolean>;
+    resolveAgentPluginActivation: (workspaceRoot: string, pluginId: string) => Promise<AgentPluginActivationVerdict>;
+    normalizeActivations: (value: unknown) => AgentPluginActivations;
+    setAgentPluginActivation: (required: SetAgentPluginActivationRequired, optional?: SetAgentPluginActivationOptional) => Promise<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<BundledAgentPluginEnableOutcome>;
+    deleteAgentPluginActivation: (required: DeleteAgentPluginActivationRequired) => Promise<void>;
+};
+/** Bind activation effects once per host process. Required effects stay stable so every caller
+ * shares the same per-workspace write queue; discovery stays lenient, capability checks and writes
+ * refuse unreadable decisions. No network, package-layout or provisioning port is needed here.
+ * @complexity O(1) composition; reads/writes are O(p) in recorded plugins.
+ */
+export declare function createAgentPluginActivations(required: Omit<ActivationPorts, "onEvent">, optional?: Pick<ActivationPorts, "onEvent">): {
+    setAgentPluginActivation: (required: SetAgentPluginActivationRequired, optional?: SetAgentPluginActivationOptional) => Promise<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<BundledAgentPluginEnableOutcome>;
+    deleteAgentPluginActivation: (required: DeleteAgentPluginActivationRequired) => Promise<void>;
+    isAgentPluginActive: (input: {
+        readonly activations: AgentPluginActivations;
+        readonly pluginId: string;
+    }, _optional?: Record<string, never>) => boolean;
+    filterActiveAgentPlugins: <T>(input: {
+        readonly activations: AgentPluginActivations;
+        readonly items: readonly T[];
+        readonly pluginIdOf: (required: {
+            readonly item: T;
+        }) => string;
+    }, _optional?: Record<string, never>) => readonly T[];
+    readAgentPluginActivations: (input: {
+        readonly workspaceRoot: string;
+    }, _optional?: Record<string, never>) => Promise<AgentPluginActivations>;
+    assertAgentPluginActivationsWritable: (input: {
+        readonly workspaceRoot: string;
+    }, _optional?: Record<string, never>) => Promise<void>;
+    isAgentPluginRecordedAsBundled: (input: {
+        readonly workspaceRoot: string;
+        readonly pluginId: string;
+    }, _optional?: Record<string, never>) => Promise<boolean>;
+    resolveAgentPluginActivation: (input: {
+        readonly workspaceRoot: string;
+        readonly pluginId: string;
+    }, _optional?: Record<string, never>) => Promise<AgentPluginActivationVerdict>;
+    normalizeActivations: (input: {
+        readonly value: unknown;
+    }, _optional?: Record<string, never>) => AgentPluginActivations;
+};
+export {};
+//# sourceMappingURL=activation.d.ts.map