@agentxm/extension-lifecycle 0.28.12 → 0.28.13

package/dist/src/knowledge/install/plan.js

@@ -0,0 +1,128 @@
+/**
+ * Installing Open Knowledge Format bundles.
+ *
+ * A bundle becomes discoverable through the shared discovery region, so
+ * several bundles in one operation defer that render until every contributor
+ * has landed.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { KnowledgeManager, extensionRefLifecycleWarnings, extensionRefRegistryLifecycle, targetFromRef, toLabelWithCompanions, toStepKey, } from "@agentxm/extension-materialization";
+import { parseSourceQualifiedRegistrySourcePatternParts, } from "@agentxm/extension-model/unstable/extensions";
+import { SourceHostProviders, resolveSource } from "@agentxm/extension-sources";
+import { operationPresentation, } from "@agentxm/workspace-operations";
+import { applyPlannedProjections } from "@agentxm/workspace-projection";
+import { lifecycleStepFailure } from "../../step-failure.js";
+import { registryLoginSuggestions } from "../../install/registry-login-suggestion.js";
+import { installRefused, } from "../../install/vocabulary.js";
+/** Read the knowledge source grammar: which owner, which names, which range. */
+export const parseKnowledgeInstallRequest = Effect.fn("InstallExtensions.parseKnowledgeRequest")(function* (source) {
+    const input = source.trim();
+    const parsed = parseSourceQualifiedRegistrySourcePatternParts(input);
+    const resolved = yield* resolveSource(input).pipe(Effect.mapError((cause) => installRefused({
+        category: "validation",
+        detail: `Invalid knowledge source: ${cause.message}`,
+        cause,
+    })));
+    return {
+        source: resolved,
+        names: parsed?.type === "knowledge" && parsed.name !== undefined ? [parsed.name] : [],
+        owner: parsed?.type === "knowledge"
+            ? Option.some(parsed.owner)
+            : resolved.type === "registry"
+                ? resolved.owner
+                : Option.none(),
+        versionRange: resolved.type === "registry" && parsed?.type === "knowledge"
+            ? Option.fromUndefinedOr(parsed.versionRange)
+            : Option.none(),
+    };
+});
+/** Discover the knowledge bundles the parsed source offers. */
+export const discoverKnowledgeRefs = Effect.fn("InstallExtensions.discoverKnowledge")(function* (request) {
+    const sources = yield* SourceHostProviders;
+    return yield* sources
+        .find(request.source, {
+        names: request.names,
+        type: "knowledge",
+        owner: request.owner,
+        versionRange: request.versionRange,
+    })
+        .pipe(Effect.mapError((cause) => installRefused({
+        category: "network",
+        detail: "Knowledge bundles could not be discovered from the source",
+        cause,
+    })), Effect.map((refs) => refs.filter((ref) => ref.type === "knowledge")));
+});
+/** Settle which knowledge bundles this request installs, or refuse when none matched. */
+export const finalizeKnowledgeInstallIntent = Effect.fn("InstallExtensions.finalizeKnowledgeIntent")(function* (request, refs) {
+    if (refs.length === 0) {
+        const suggestions = request.source.type === "registry"
+            ? yield* registryLoginSuggestions([request.source.location.href])
+            : [];
+        return yield* installRefused({
+            category: "not_found",
+            detail: "No knowledge bundles found in source",
+            suggestions,
+        });
+    }
+    return {
+        refs: refs.map((ref) => ({
+            ref,
+            versionRange: ref.refType === "registry" ? request.versionRange : Option.none(),
+        })),
+    };
+});
+/** The closures a settled knowledge intent becomes. */
+export const planKnowledgeInstall = Effect.fn("InstallExtensions.planKnowledge")(function* (intent) {
+    const manager = yield* KnowledgeManager;
+    const deferProjections = intent.deferProjections === true || intent.refs.length > 1;
+    const memberSteps = intent.refs.map(({ ref, versionRange }) => {
+        const target = targetFromRef(ref);
+        const packages = ref.refType === "registry" ? ref.packages : [];
+        const base = {
+            key: toStepKey(target),
+            label: toLabelWithCompanions(target, packages),
+            run: manager.install({ ref, versionRange, deferProjection: deferProjections }).pipe(Effect.mapError(lifecycleStepFailure), Effect.as({
+                result: "success",
+                message: `Installed ${ref.knowledge.name}`,
+            })),
+        };
+        const warnings = extensionRefLifecycleWarnings(ref);
+        const registryLifecycle = extensionRefRegistryLifecycle(ref);
+        return warnings.length === 0
+            ? {
+                ...base,
+                readiness: "ready",
+                ...(registryLifecycle === undefined ? {} : { registryLifecycle }),
+            }
+            : {
+                ...base,
+                readiness: "warn",
+                warnMessage: warnings.join("; "),
+                ...(registryLifecycle === undefined ? {} : { registryLifecycle }),
+            };
+    });
+    const projectionSteps = deferProjections && intent.deferProjections !== true
+        ? [
+            {
+                key: "projection:knowledge:discovery-region",
+                label: "knowledge projection",
+                readiness: "ready",
+                run: applyPlannedProjections(manager).pipe(Effect.mapError(lifecycleStepFailure), Effect.as({
+                    result: "success",
+                    message: "Rendered installed Knowledge bundles from the complete contributor set",
+                })),
+            },
+        ]
+        : [];
+    return {
+        _tag: "Plan",
+        name: "Install knowledge",
+        description: Option.some("Install Open Knowledge Format bundle"),
+        presentation: operationPresentation({ imperative: "install", past: "Installed", gerund: "Installing" }, "knowledge"),
+        jobs: [{ concurrency: 1, steps: [...memberSteps, ...projectionSteps] }],
+    };
+});
+//# sourceMappingURL=plan.js.map

package/dist/src/knowledge/uninstall/plan.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Uninstalling a Knowledge bundle.
+ *
+ * Canonical Knowledge content that AXM never accepted ownership of belongs to
+ * whoever put it there. A removal that would delete such content is refused
+ * and says how to take ownership instead, so an unowned surface is preserved
+ * rather than silently destroyed.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import { KnowledgeManager } from "@agentxm/extension-materialization";
+import type { Plan } from "@agentxm/workspace-operations";
+import { ExtensionLifecycleFailed } from "../../errors.js";
+import { type InstallStepRequirements } from "../../install/vocabulary.js";
+import type { KnowledgeUninstallIntent } from "../../uninstall/vocabulary.js";
+/** Settle whether this Knowledge bundle has anything to remove. */
+export declare const parseKnowledgeUninstallRequest: (selector: string) => Effect.Effect<KnowledgeUninstallIntent, ExtensionLifecycleFailed, InstallStepRequirements | KnowledgeManager | FileSystem.FileSystem | Path.Path>;
+/** The closures a settled Knowledge removal becomes. */
+export declare const planKnowledgeUninstall: (intent: KnowledgeUninstallIntent) => Effect.Effect<Plan<InstallStepRequirements>, ExtensionLifecycleFailed, InstallStepRequirements | KnowledgeManager | FileSystem.FileSystem | Path.Path>;
+//# sourceMappingURL=plan.d.ts.map

package/dist/src/knowledge/uninstall/plan.js

@@ -0,0 +1,140 @@
+/**
+ * Uninstalling a Knowledge bundle.
+ *
+ * Canonical Knowledge content that AXM never accepted ownership of belongs to
+ * whoever put it there. A removal that would delete such content is refused
+ * and says how to take ownership instead, so an unowned surface is preserved
+ * rather than silently destroyed.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import { KnowledgeManager, KnowledgeUnavailable, buildUninstallOperation, } from "@agentxm/extension-materialization";
+import { makeWorkspaceRelativePath } from "@agentxm/extension-model/unstable/path-types";
+import { resolveInstructionsConfig } from "@agentxm/workspace-projection";
+import { WorkspaceMutations, acceptedCanonicalObservation, computeExtensionPathsForLayout, extensionPathSourceFromLockEntry, } from "@agentxm/workspace-state";
+import { ExtensionLifecycleFailed } from "../../errors.js";
+import { lifecycleStepFailure } from "../../step-failure.js";
+import { installRefused } from "../../install/vocabulary.js";
+import { makeWorkspaceRetentionPolicy } from "../../uninstall/retention-policy.js";
+const lockCanonicalRoot = (path, layout, locked) => computeExtensionPathsForLayout(path.join, layout, extensionPathSourceFromLockEntry(locked), "knowledge", locked.workspaceName).canonicalPath;
+/** Settle whether this Knowledge bundle has anything to remove. */
+export const parseKnowledgeUninstallRequest = Effect.fn("UninstallExtensions.parseKnowledgeRequest")(function* (selector) {
+    const ws = yield* WorkspaceMutations;
+    const manager = yield* KnowledgeManager;
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const target = { type: "knowledge", name: selector.trim() };
+    return yield* Effect.gen(function* () {
+        const configured = manager.getConfiguredSource === undefined
+            ? Option.none()
+            : yield* manager.getConfiguredSource({ target });
+        const installed = yield* manager.isInstalled({ target });
+        const locked = yield* ws.getLockedKnowledgeEntry(target.name);
+        const authoredPackagePresent = ws.layout.scope === "project" &&
+            (yield* fs.exists(path.join(ws.layout.authoredRoot("knowledge"), target.name)));
+        if (Option.isNone(configured) && Option.isNone(locked) && authoredPackagePresent) {
+            return { targets: [] };
+        }
+        if (Option.isNone(configured) && Option.isNone(locked) && !installed) {
+            return { targets: [] };
+        }
+        return { targets: [target] };
+    }).pipe(Effect.mapError((cause) => installRefused({
+        category: "internal",
+        detail: `Knowledge bundle "${target.name}" declaration could not be read`,
+        cause,
+    })));
+});
+/**
+ * Whether AXM has an accepted ownership fact for the content it would delete,
+ * and whether the managed instructions target it would rewrite is inside the
+ * workspace at all.
+ */
+const inspectOwnership = Effect.fn("UninstallExtensions.inspectKnowledgeOwnership")(function* (target) {
+    const ws = yield* WorkspaceMutations;
+    const path = yield* Path.Path;
+    return yield* Effect.gen(function* () {
+        const configured = yield* ws.getConfiguredKnowledgeEntries();
+        const locked = yield* ws.getLockedKnowledgeEntry(target.name);
+        const graph = yield* ws.getDesiredStateGraph();
+        const desired = graph.nodes.find((node) => node.type === "knowledge" && node.name === target.name);
+        const acceptedObservation = desired === undefined
+            ? Option.none()
+            : yield* acceptedCanonicalObservation({
+                workspace: ws,
+                type: "knowledge",
+                name: target.name,
+            });
+        const expectedCanonicalPath = Option.match(acceptedObservation, {
+            onNone: () => Option.isSome(locked) ? lockCanonicalRoot(path, ws.layout, locked.value) : undefined,
+            onSome: (accepted) => accepted.observation.path,
+        });
+        const inventory = yield* ws.records.getExtensionInventory("knowledge", {});
+        const actualPaths = inventory.items
+            .filter((item) => item.name === target.name)
+            .flatMap((item) => item.paths.map((itemPath) => path.resolve(ws.baseDir, itemPath)));
+        const normalizedExpected = expectedCanonicalPath === undefined ? undefined : path.resolve(expectedCanonicalPath);
+        const workspaceOwned = desired?.identity.startsWith("workspace:") === true;
+        const hasAcceptedOwnership = workspaceOwned || Option.isSome(locked);
+        const settingsPresent = configured[target.name] !== undefined;
+        const instructionsConfig = yield* ws.getInstructionsConfig();
+        const resolvedInstructions = resolveInstructionsConfig(Option.match(instructionsConfig, {
+            onNone: () => undefined,
+            onSome: (value) => (value === false ? undefined : value),
+        }));
+        const instructionRelative = makeWorkspaceRelativePath(path, ws.baseDir, resolvedInstructions.fileName);
+        const ownershipBlocker = actualPaths.length === 0 || (hasAcceptedOwnership && normalizedExpected !== undefined)
+            ? undefined
+            : settingsPresent && !workspaceOwned
+                ? `Cannot uninstall Knowledge bundle "${target.name}": canonical Knowledge content is present, but its accepted resolution is missing. AXM will preserve the unowned canonical surface. Run \`axm adopt <extension>\` to transfer it into AXM ownership, or leave it for its current owner.`
+                : `Cannot uninstall Knowledge bundle "${target.name}": canonical Knowledge content has no accepted AXM ownership fact. AXM will preserve the unowned canonical surface. Run \`axm adopt <extension>\` to transfer it into AXM ownership, or leave it for its current owner.`;
+        const blocker = ownershipBlocker ??
+            (Option.isNone(instructionRelative)
+                ? `Cannot uninstall Knowledge bundle "${target.name}": the managed instructions target is outside the workspace. Configure a workspace-relative instructions target and retry.`
+                : undefined);
+        return { target, ...(blocker === undefined ? {} : { blocker }) };
+    }).pipe(Effect.mapError((cause) => installRefused({
+        category: "internal",
+        detail: `Knowledge ownership for "${target.name}" could not be inspected`,
+        cause,
+    })));
+});
+/** The closures a settled Knowledge removal becomes. */
+export const planKnowledgeUninstall = Effect.fn("UninstallExtensions.planKnowledge")(function* (intent) {
+    const ws = yield* WorkspaceMutations;
+    const manager = yield* KnowledgeManager;
+    const retentionPolicy = makeWorkspaceRetentionPolicy(ws);
+    /** The accepted ownership fact, not on-disk presence, decides removability. */
+    const isAcceptedTargetPresent = (target) => Effect.gen(function* () {
+        const graph = yield* ws.getDesiredStateGraph();
+        const desired = graph.nodes.find((node) => node.type === "knowledge" && node.name === target.name);
+        const locked = yield* ws.getLockedKnowledgeEntry(target.name);
+        return desired?.identity.startsWith("workspace:") === true || Option.isSome(locked);
+    }).pipe(Effect.mapError((cause) => new KnowledgeUnavailable({
+        detail: `Accepted ownership for Knowledge bundle "${target.name}" could not be read`,
+        cause,
+    })));
+    const ownership = yield* Effect.forEach(intent.targets, inspectOwnership);
+    const steps = ownership.map((entry) => {
+        if (entry.blocker !== undefined) {
+            return {
+                key: `knowledge:${entry.target.name}`,
+                readiness: "error",
+                label: entry.target.name,
+                errorMessage: entry.blocker,
+            };
+        }
+        return buildUninstallOperation({ ...manager, isInstalled: () => isAcceptedTargetPresent(entry.target) }, retentionPolicy, { target: entry.target, toStepFailure: lifecycleStepFailure });
+    });
+    return {
+        _tag: "Plan",
+        name: "Uninstall knowledge",
+        description: Option.some("Uninstall Open Knowledge Format bundle"),
+        jobs: [{ concurrency: 1, steps }],
+    };
+});
+//# sourceMappingURL=plan.js.map

package/dist/src/live.d.ts

@@ -1,18 +1,11 @@
 /**
- * Environment-backed layers of the extension-lifecycle feature: the seven
- * per-type manager implementations behind the extension-workspace manager
- * contracts, and the hook-backed configured-agent-outcomes provider. Only
- * application composition roots import this module.
+ * Environment-backed layers of the extension-lifecycle feature: the
+ * hook-backed configured-agent-outcomes provider. The per-extension-type
+ * manager implementations and their projection-participant registration live
+ * in `@agentxm/extension-materialization/live`.
  *
  * @experimental All exports from this module are unstable and may change without notice.
  * @packageDocumentation
  */
-export { HookManagerLive } from "./hooks/manager.js";
 export { HookConfiguredAgentOutcomesProviderLive } from "./hooks/configured-agent-outcomes-provider.js";
-export { RuleManagerLive } from "./rules/manager.js";
-export { SkillManagerLive } from "./skills/manager.js";
-export { SubagentManagerLive } from "./subagents/manager.js";
-export { McpServerManagerLive } from "./mcps/manager.js";
-export { PackManagerLive } from "./packs/manager.js";
-export { KnowledgeManagerLive } from "./knowledge/manager.js";
 //# sourceMappingURL=live.d.ts.map

package/dist/src/live.js

@@ -1,18 +1,11 @@
 /**
- * Environment-backed layers of the extension-lifecycle feature: the seven
- * per-type manager implementations behind the extension-workspace manager
- * contracts, and the hook-backed configured-agent-outcomes provider. Only
- * application composition roots import this module.
+ * Environment-backed layers of the extension-lifecycle feature: the
+ * hook-backed configured-agent-outcomes provider. The per-extension-type
+ * manager implementations and their projection-participant registration live
+ * in `@agentxm/extension-materialization/live`.
  *
  * @experimental All exports from this module are unstable and may change without notice.
  * @packageDocumentation
  */
-export { HookManagerLive } from "./hooks/manager.js";
 export { HookConfiguredAgentOutcomesProviderLive } from "./hooks/configured-agent-outcomes-provider.js";
-export { RuleManagerLive } from "./rules/manager.js";
-export { SkillManagerLive } from "./skills/manager.js";
-export { SubagentManagerLive } from "./subagents/manager.js";
-export { McpServerManagerLive } from "./mcps/manager.js";
-export { PackManagerLive } from "./packs/manager.js";
-export { KnowledgeManagerLive } from "./knowledge/manager.js";
 //# sourceMappingURL=live.js.map

package/dist/src/mcps/install/plan.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Installing an MCP connection from the registry.
+ *
+ * An MCP server is acquired once and referenced by a local connection name, so
+ * this decides who owns that name, which version constraint every origin
+ * referencing the same server agrees on, and whether the selected workspace
+ * scope can hold an MCP configuration at all.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { type ExtensionName, type Handle } from "@agentxm/extension-model/unstable/extensions";
+import type { McpServerExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/mcp-server";
+import type { RegistrySource } from "@agentxm/extension-model/unstable/sources/types";
+import { type Plan } from "@agentxm/workspace-operations";
+import type { ExtensionLifecycleFailed } from "../../errors.js";
+import { type InstallStepRequirements, type McpServerInstallIntent, type ResolveInstallRequirements } from "../../install/vocabulary.js";
+/** An MCP install request after grammar parsing, before anything is discovered. */
+export interface ParsedMcpServerInstallRequest {
+    readonly owner: Handle;
+    readonly serverName: ExtensionName;
+    readonly localName: ExtensionName;
+    readonly versionRange: Option.Option<string>;
+    readonly resolvedInput: string;
+    readonly force: boolean;
+    readonly nonInteractive: boolean;
+    readonly env: Readonly<Record<string, string>>;
+}
+/** One MCP registry lookup, with the constraint every origin agrees on. */
+export interface McpServerInstallSourceRequest {
+    readonly source: RegistrySource;
+    readonly owner: Handle;
+    readonly serverName: ExtensionName;
+    readonly versionRange: Option.Option<string>;
+}
+/**
+ * Decode repeated `--env KEY=VALUE` inputs into a record. Later occurrences of
+ * the same key win. Registry installs resolve declared inputs by name, so a
+ * bare `KEY` (passthrough from the ambient environment, as `axm mcps add`
+ * allows) is refused here rather than silently resolving to nothing.
+ */
+export declare const parseMcpEnvInputs: (env: ReadonlyArray<string>) => Effect.Effect<Readonly<Record<string, string>>, ExtensionLifecycleFailed>;
+/** What an MCP install command supplies before anything is parsed. */
+export interface McpServerInstallArgs {
+    readonly source: string;
+    readonly localName: Option.Option<string>;
+    readonly env: ReadonlyArray<string>;
+    readonly force: boolean;
+    readonly nonInteractive: boolean;
+}
+/** Read the MCP source grammar and settle the local connection name. */
+export declare const parseMcpServerInstallRequest: (args: McpServerInstallArgs) => Effect.Effect<ParsedMcpServerInstallRequest, ExtensionLifecycleFailed, ResolveInstallRequirements>;
+/**
+ * Decide which local name may own the connection and which version constraint
+ * every origin referencing the same registry server can agree on.
+ */
+export declare const resolveMcpServerSourceRequest: (request: ParsedMcpServerInstallRequest) => Effect.Effect<McpServerInstallSourceRequest, ExtensionLifecycleFailed, ResolveInstallRequirements>;
+/** Discover the MCP server the resolved request names. */
+export declare const discoverMcpServerRefs: (request: McpServerInstallSourceRequest) => Effect.Effect<ReadonlyArray<McpServerExtensionRef>, ExtensionLifecycleFailed, ResolveInstallRequirements>;
+/** Settle the connection this request installs, or refuse when nothing matched. */
+export declare const finalizeMcpServerInstallIntent: (request: ParsedMcpServerInstallRequest, refs: ReadonlyArray<McpServerExtensionRef>) => Effect.Effect<McpServerInstallIntent, ExtensionLifecycleFailed, ResolveInstallRequirements>;
+/** The closure a settled MCP intent becomes. */
+export declare const planMcpServerInstall: (intent: McpServerInstallIntent) => Effect.Effect<Plan<InstallStepRequirements>, ExtensionLifecycleFailed, InstallStepRequirements>;
+//# sourceMappingURL=plan.d.ts.map