@agentxm/extension-lifecycle 0.28.11 → 0.28.13

package/dist/src/install/registry-source-resolution.js

@@ -0,0 +1,216 @@
+/**
+ * Which configured registry supplies a skill or subagent named without one.
+ *
+ * A bare name or an unqualified `@owner/name` says nothing about which
+ * registry hosts it, so every configured host is probed in order and the
+ * first that answers wins. Each probe is recorded so the application can
+ * show, verbatim, which registries were consulted and what each one said.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { createRegistryClient } from "@agentxm/registry-client";
+import { resolveIdentifier, sourceResolutionFailureCategory, } from "@agentxm/extension-sources";
+import { WorkspaceMutations } from "@agentxm/workspace-state";
+import { registryLoginSuggestions } from "./registry-login-suggestion.js";
+import { installRefused } from "./vocabulary.js";
+/** How to declare a registry when none is configured for the requested owner. */
+export const ADD_REGISTRY_SOURCE = {
+    description: "Add a registry under `sources` in workspace settings",
+    cmd: "axm help settings",
+};
+/** The sentence a source-resolution failure carries, for probe evidence. */
+export const sourceFailureDetail = (error) => {
+    switch (error._tag) {
+        case "SourceSyntaxInvalid":
+        case "SourceHostNotConfigured":
+        case "SourceNotResolvable":
+        case "SourceNetworkFailure":
+        case "GitOperationFailed":
+        case "WorkspaceCatalogUnavailable":
+        case "AxmSkillGateUnavailable":
+            return error.detail;
+        case "RegistryProblem":
+            return error.detail ?? error.title ?? error.category;
+        case "RegistryRequestFailed":
+        case "RegistryOperationFailed":
+            return error.detail;
+    }
+};
+const summarizeLookupFailure = (error) => `${sourceFailureDetail(error)} (${sourceResolutionFailureCategory(error)})`;
+const extensionLabel = (type) => type === "skill" ? "Skill" : "Subagent";
+const qualifiedExtension = (type, owner, name) => `${owner}/${type === "skill" ? "skills" : "subagents"}/${name}`;
+const explicitSourceSuggestion = (type) => `Verify the owner/${type} name, or install with an explicit source like github:owner/repo`;
+/** Render one probe as the line the application prints under `--verbose`. */
+export const formatRegistryProbe = (probe) => {
+    switch (probe.outcome) {
+        case "matched":
+            return `${probe.location}: matched`;
+        case "not-found":
+            return `${probe.location}: no match`;
+        case "error":
+            return Option.match(probe.reason, {
+                onNone: () => `${probe.location}: error`,
+                onSome: (reason) => `${probe.location}: ${reason}`,
+            });
+    }
+};
+/** Probe every host configured under `sourceName` for the named extension. */
+export const resolveConfiguredRegistrySource = Effect.fn("InstallExtensions.resolveConfiguredRegistrySource")(function* (args) {
+    const workspace = yield* WorkspaceMutations;
+    const registrySources = (yield* workspace.getRegistrySourceHosts().pipe(Effect.mapError((cause) => installRefused({
+        category: "internal",
+        detail: `Failed to read configured registry sources for owner "${args.owner}"`,
+        recover: "Check that your workspace settings file is valid and accessible",
+        cause,
+    })))).filter((source) => source.name === args.sourceName);
+    if (registrySources.length === 0) {
+        return yield* installRefused({
+            category: "not_found",
+            detail: `No registry source is configured for owner "${args.owner}"`,
+            recover: `Add a registry source for owner "${args.owner}"`,
+            ...(ADD_REGISTRY_SOURCE.cmd === undefined ? {} : { cmd: ADD_REGISTRY_SOURCE.cmd }),
+        });
+    }
+    for (const registrySource of registrySources) {
+        const client = yield* createRegistryClient(registrySource.location.href).pipe(Effect.mapError((cause) => installRefused({
+            category: "network",
+            detail: `Registry ${registrySource.location.href} could not be reached`,
+            cause,
+        })));
+        const matchResult = yield* Option.match(args.extensionName, {
+            onNone: () => client.ownerExists(args.owner),
+            onSome: (name) => client.extensionExists({ owner: args.owner, type: args.extensionType, name }),
+        }).pipe(Effect.result);
+        if (matchResult._tag === "Failure") {
+            if (Option.isSome(args.options)) {
+                args.options.value.onRegistryProbe({
+                    location: registrySource.location.href,
+                    outcome: "error",
+                    reason: Option.some(summarizeLookupFailure(matchResult.failure)),
+                });
+            }
+            continue;
+        }
+        if (matchResult.success.exists) {
+            if (Option.isSome(args.options)) {
+                args.options.value.onRegistryProbe({
+                    location: registrySource.location.href,
+                    outcome: "matched",
+                    reason: Option.none(),
+                });
+            }
+            return {
+                type: "registry",
+                name: registrySource.name,
+                location: registrySource.location,
+                owner: Option.some(args.owner),
+            };
+        }
+        if (Option.isSome(args.options)) {
+            args.options.value.onRegistryProbe({
+                location: registrySource.location.href,
+                outcome: "not-found",
+                reason: Option.none(),
+            });
+        }
+    }
+    const loginSuggestions = yield* registryLoginSuggestions(registrySources.map((source) => source.location.href));
+    if (Option.isSome(args.extensionName)) {
+        return yield* installRefused({
+            category: "not_found",
+            detail: `${extensionLabel(args.extensionType)} "${qualifiedExtension(args.extensionType, args.owner, args.extensionName.value)}" was not found in configured registries`,
+            recover: explicitSourceSuggestion(args.extensionType),
+            suggestions: loginSuggestions,
+        });
+    }
+    return yield* installRefused({
+        category: "not_found",
+        detail: `None of the configured registry sources contain owner "${args.owner}"`,
+        recover: `Verify the owner name is correct, or add a registry that hosts "${args.owner}"`,
+        suggestions: loginSuggestions,
+    });
+});
+/** Resolve a bare name against the default `agentxm` registry and configured owner. */
+export const resolveDefaultRegistrySourceByName = Effect.fn("InstallExtensions.resolveDefaultRegistrySourceByName")(function* (args) {
+    const workspace = yield* WorkspaceMutations;
+    const label = extensionLabel(args.extensionType);
+    const registryHosts = (yield* workspace.getRegistrySourceHosts().pipe(Effect.mapError((cause) => installRefused({
+        category: "internal",
+        detail: "Configured registry sources could not be read",
+        cause,
+    })))).filter((source) => source.name === "agentxm");
+    if (registryHosts.length === 0) {
+        return yield* installRefused({
+            category: "not_found",
+            detail: `${label} "${args.name}" could not be looked up (no registry sources)`,
+            suggestions: [ADD_REGISTRY_SOURCE],
+        });
+    }
+    const maybeOwner = yield* workspace.getConfiguredOwner().pipe(Effect.mapError((cause) => installRefused({
+        category: "internal",
+        detail: "Configured workspace owner could not be read",
+        cause,
+    })));
+    const loginSuggestions = yield* registryLoginSuggestions(registryHosts.map((source) => source.location.href));
+    const resolved = yield* Effect.scoped(resolveIdentifier({
+        input: args.name,
+        resourceType: args.extensionType,
+        scope: "registry",
+        registrySourceName: "agentxm",
+    })).pipe(Effect.mapError((failure) => {
+        if (sourceResolutionFailureCategory(failure) !== "not_found") {
+            return installRefused({
+                category: "network",
+                detail: sourceFailureDetail(failure),
+                cause: failure,
+            });
+        }
+        const detail = Option.match(maybeOwner, {
+            onNone: () => `${label} "${args.name}" could not be looked up (no default owner)`,
+            onSome: (owner) => `${label} "${qualifiedExtension(args.extensionType, owner, args.name)}" was not found in configured registries`,
+        });
+        return installRefused({
+            category: "not_found",
+            detail,
+            suggestions: [
+                { description: explicitSourceSuggestion(args.extensionType) },
+                ...loginSuggestions,
+            ],
+            cause: failure,
+        });
+    }));
+    const resolvedOwner = Option.getOrUndefined(resolved.owner);
+    if (resolvedOwner === undefined) {
+        return yield* installRefused({
+            category: "not_found",
+            detail: `${label} "${args.name}" was not found in configured registries`,
+            suggestions: [
+                { description: explicitSourceSuggestion(args.extensionType) },
+                ...loginSuggestions,
+            ],
+        });
+    }
+    const defaultRegistry = registryHosts[0];
+    if (defaultRegistry === undefined) {
+        return yield* installRefused({
+            category: "not_found",
+            detail: `${label} "${args.name}" could not be looked up (no registry sources)`,
+        });
+    }
+    if (Option.isSome(args.options)) {
+        args.options.value.onRegistryProbe({
+            location: Option.getOrElse(Option.map(resolved.registryLocation, (location) => location.href), () => defaultRegistry.location.href),
+            outcome: "matched",
+            reason: Option.none(),
+        });
+    }
+    return {
+        type: "registry",
+        name: defaultRegistry.name,
+        location: Option.getOrElse(resolved.registryLocation, () => defaultRegistry.location),
+        owner: Option.some(resolvedOwner),
+    };
+});
+//# sourceMappingURL=registry-source-resolution.js.map

package/dist/src/install/root-intent.d.ts

@@ -0,0 +1,19 @@
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import type { ExtensionLifecycleFailed } from "../errors.js";
+import { type InstallableExtensionType } from "@agentxm/extension-model/unstable/extensions/installable-types";
+export declare const rootInstallableTypeSegments: readonly ("knowledge" | "rules" | "hooks" | "mcps" | "skills" | "subagents" | "packs")[];
+export declare const RootInstallableTypeSegmentSchema: Schema.Literals<readonly ("knowledge" | "rules" | "hooks" | "mcps" | "skills" | "subagents" | "packs")[]>;
+export type RootInstallableTypeSegment = typeof RootInstallableTypeSegmentSchema.Type;
+export type RootInstallableType = InstallableExtensionType;
+export interface RootInstallIntent {
+    readonly source: string;
+    readonly type: RootInstallableType | "locator";
+}
+/**
+ * Which route a root install request takes: a registry FQN names its own
+ * type, while a locator is opened and whatever installable extensions it
+ * contains are discovered from it.
+ */
+export declare const resolveRootInstallIntent: (input: string) => Effect.Effect<RootInstallIntent, ExtensionLifecycleFailed>;
+//# sourceMappingURL=root-intent.d.ts.map

package/dist/src/install/root-intent.js

@@ -0,0 +1,122 @@
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import { installRefused } from "./vocabulary.js";
+import { installableExtensionTypePluralSegments, InstallableExtensionTypePluralSchema, isInstallableExtensionTypePlural, toInstallableExtensionType, } from "@agentxm/extension-model/unstable/extensions/installable-types";
+import { parseSourceQualifiedRegistrySourcePatternParts, RegistrySourceRefSchema, } from "@agentxm/extension-model/unstable/extensions";
+import { parseInputPattern } from "@agentxm/extension-model/unstable/sources/parser";
+import { perTypeInstallPluralSegments } from "./per-type-install.js";
+const decodeRegistrySourceRef = Schema.decodeUnknownEffect(RegistrySourceRefSchema);
+export const rootInstallableTypeSegments = installableExtensionTypePluralSegments;
+export const RootInstallableTypeSegmentSchema = InstallableExtensionTypePluralSchema;
+const rootInstallFqnGrammar = "@<handle>/<plural-type>/<name>[@<version>]";
+const supportedRootInstallTypes = rootInstallableTypeSegments.join(", ");
+const locatorDiscoveryTypes = "skills, MCP servers, subagents, rules, hooks, and knowledge";
+const rootInstallRegistryOnlyHowToFix = (source) => {
+    const parsed = parseInputPattern(source);
+    if (Option.isNone(parsed)) {
+        return "Use `axm install @<handle>/<plural-type>/<name>[@<version>]` or a path, URL, git, or provider shorthand source locator.";
+    }
+    switch (parsed.value.pattern.pattern) {
+        case "file-path-pattern":
+        case "url-input":
+        case "git-scp-address":
+        case "shorthand-input":
+        case "slash-pattern":
+            return `Use \`axm install ${source}\` to discover and install ${locatorDiscoveryTypes} from the source. MCP servers and packs require a registry FQN.`;
+        case "name-input":
+        case "glob-input":
+            return `Root install needs a registry FQN or source locator. For bare names, use the matching per-type command — for example \`axm skills install ${source}\`. Per-type install exists for ${perTypeInstallPluralSegments.join(", ")}.`;
+        case "registry-pattern-input":
+            return "Use `axm install @<handle>/<plural-type>/<name>[@<version>]`.";
+        case "workspace-pattern-input":
+            return "Workspace locators declare source authority in settings and cannot be installed over. Use sync or the matching enable command.";
+    }
+};
+/**
+ * Which route a root install request takes: a registry FQN names its own
+ * type, while a locator is opened and whatever installable extensions it
+ * contains are discovered from it.
+ */
+export const resolveRootInstallIntent = Effect.fn("InstallExtensions.resolveRootIntent")(function* (input) {
+    const source = input.trim();
+    const segments = source.split("/");
+    const pluralType = segments.length === 3 ? segments[1] : undefined;
+    const sourceQualifiedRegistry = parseSourceQualifiedRegistrySourcePatternParts(source);
+    if (!source.startsWith("@") && sourceQualifiedRegistry === undefined) {
+        const parsedInput = parseInputPattern(source);
+        if (Option.isSome(parsedInput)) {
+            switch (parsedInput.value.pattern.pattern) {
+                case "file-path-pattern":
+                case "url-input":
+                case "git-scp-address":
+                case "shorthand-input":
+                case "slash-pattern":
+                    return {
+                        source,
+                        type: "locator",
+                    };
+                case "name-input":
+                case "glob-input":
+                case "registry-pattern-input":
+                    break;
+            }
+        }
+        return yield* installRefused({
+            category: "usage",
+            detail: "Root install needs a registry FQN or source locator",
+            suggestions: [{ description: rootInstallRegistryOnlyHowToFix(source) }],
+        });
+    }
+    if (pluralType === "libraries") {
+        return yield* installRefused({
+            category: "usage",
+            detail: "Libraries are curated registry collections and cannot be installed",
+            suggestions: [
+                {
+                    description: "Open the Library in AgentXM, then install the individual extensions you want.",
+                },
+            ],
+        });
+    }
+    const parsed = yield* decodeRegistrySourceRef(source).pipe(Effect.mapError((error) => {
+        if (pluralType !== undefined && !isInstallableExtensionTypePlural(pluralType)) {
+            return installRefused({
+                category: "not_found",
+                detail: "Install source uses an unsupported plural type",
+                suggestions: [
+                    {
+                        description: `Use ${rootInstallFqnGrammar}. Supported plural types: ${supportedRootInstallTypes}.`,
+                    },
+                ],
+                cause: error,
+            });
+        }
+        return installRefused({
+            category: "validation",
+            detail: "Install source must be a registry FQN",
+            suggestions: [
+                {
+                    description: `Use ${rootInstallFqnGrammar} with one of: ${supportedRootInstallTypes}.`,
+                },
+            ],
+            cause: error,
+        });
+    }));
+    if (!isInstallableExtensionTypePlural(parsed.type)) {
+        return yield* installRefused({
+            category: "usage",
+            detail: "Root install does not support that extension type",
+            suggestions: [
+                {
+                    description: `Use ${rootInstallFqnGrammar}. Supported plural types: ${supportedRootInstallTypes}.`,
+                },
+            ],
+        });
+    }
+    return {
+        source,
+        type: toInstallableExtensionType(parsed.type),
+    };
+});
+//# sourceMappingURL=root-intent.js.map

package/dist/src/install/selection-interaction.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Choosing among the extensions a source offers.
+ *
+ * When a source contains several skills or subagents and the request named
+ * none of them, someone has to choose. Which candidates are offered and what
+ * a choice means is this feature's; how the choice is asked for — a terminal
+ * multiselect, a test double, nothing at all — is the application's.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import type * as Array from "effect/Array";
+import * as ServiceMap from "effect/Context";
+import type * as Effect from "effect/Effect";
+import type { SkillExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/skill";
+import type { SubagentExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/subagent";
+import type { ExtensionLifecycleFailed } from "../errors.js";
+declare const ExtensionSelectionCancelled_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "ExtensionSelectionCancelled";
+} & Readonly<A>;
+/**
+ * The person was asked which extensions to install and declined to answer.
+ * Nothing was written and nothing is pending, so the application reports a
+ * cancelled invocation rather than a failure.
+ */
+export declare class ExtensionSelectionCancelled extends ExtensionSelectionCancelled_base<{
+    readonly message: string;
+}> {
+}
+/**
+ * A surface that cannot open the choice refuses with the feature's own typed
+ * failure rather than reporting a cancellation nobody made: declining is a
+ * clean exit, being unable to ask is a refusal the operator must act on. Both
+ * callers already carry the pair, so naming it here narrows nothing.
+ */
+export type ExtensionSelectionFailure = ExtensionSelectionCancelled | ExtensionLifecycleFailed;
+export interface ExtensionSelectionInteractionService {
+    /** Choose which of the discovered skills to install; at least one. */
+    readonly selectSkills: (candidates: Array.NonEmptyReadonlyArray<SkillExtensionRef>) => Effect.Effect<ReadonlyArray<SkillExtensionRef>, ExtensionSelectionFailure>;
+    /** Choose which of the discovered subagents to install; at least one. */
+    readonly selectSubagents: (candidates: Array.NonEmptyReadonlyArray<SubagentExtensionRef>) => Effect.Effect<ReadonlyArray<SubagentExtensionRef>, ExtensionSelectionFailure>;
+}
+declare const ExtensionSelectionInteraction_base: ServiceMap.ServiceClass<ExtensionSelectionInteraction, "@agentxm/extension-lifecycle/install/ExtensionSelectionInteraction", ExtensionSelectionInteractionService>;
+export declare class ExtensionSelectionInteraction extends ExtensionSelectionInteraction_base {
+}
+export {};
+//# sourceMappingURL=selection-interaction.d.ts.map

package/dist/src/install/selection-interaction.js

@@ -0,0 +1,22 @@
+/**
+ * Choosing among the extensions a source offers.
+ *
+ * When a source contains several skills or subagents and the request named
+ * none of them, someone has to choose. Which candidates are offered and what
+ * a choice means is this feature's; how the choice is asked for — a terminal
+ * multiselect, a test double, nothing at all — is the application's.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as ServiceMap from "effect/Context";
+import * as Data from "effect/Data";
+/**
+ * The person was asked which extensions to install and declined to answer.
+ * Nothing was written and nothing is pending, so the application reports a
+ * cancelled invocation rather than a failure.
+ */
+export class ExtensionSelectionCancelled extends Data.TaggedError("ExtensionSelectionCancelled") {
+}
+export class ExtensionSelectionInteraction extends ServiceMap.Service()("@agentxm/extension-lifecycle/install/ExtensionSelectionInteraction") {
+}
+//# sourceMappingURL=selection-interaction.js.map

package/dist/src/install/vocabulary.d.ts

@@ -0,0 +1,143 @@
+/**
+ * The vocabulary every install route shares.
+ *
+ * Root install, the seven per-type installs, and the configured-entry sweep
+ * are one use case with the type either fixed by the command or detected from
+ * what the source offers. They therefore share one request, one requirement
+ * set, one per-type resolved intent, and one failure vocabulary; only the
+ * grammar that produced the request differs.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import type * as FileSystem from "effect/FileSystem";
+import type * as Option from "effect/Option";
+import type * as Path from "effect/Path";
+import type * as Scope from "effect/Scope";
+import type * as HttpClient from "effect/unstable/http/HttpClient";
+import type { NativeWriteAuthority } from "@agentxm/agent-integration";
+import type { ManagerRequirements, McpSecretStore, RecipeRequirements } from "@agentxm/extension-materialization";
+import type { ExtensionName } from "@agentxm/extension-model/unstable/extensions";
+import type { HookExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/hook";
+import type { KnowledgeExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/knowledge";
+import type { McpServerExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/mcp-server";
+import type { PackRef } from "@agentxm/extension-model/unstable/extensions/refs/pack";
+import type { RuleExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/rule";
+import type { SkillExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/skill";
+import type { SubagentExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/subagent";
+import type { ReleaseAgeEvaluation } from "@agentxm/extension-model/unstable/extensions/release-age";
+import type { VersionRange } from "@agentxm/extension-model/unstable/version-constraints";
+import type { ExtensionResolutionFailed, PackDependencyRefResolver } from "@agentxm/extension-resolution";
+import type { SourceHostProviders, WorkspaceCatalog } from "@agentxm/extension-sources";
+import type { ApprovalRecoveryMissing, CandidateFingerprintFailed, OperationJournal, PlanInteractionFailed, ResolvePlanInteraction } from "@agentxm/workspace-operations";
+import type { CodingAgentRepository } from "@agentxm/workspace-projection";
+import type { AcceptedCanonicalRefError, ConfiguredAgentOutcomesProvider, LockfileValidationError, WorkspaceMutations, WorkspaceSettingsReadFailure, WorkspaceStateReadFailure } from "@agentxm/workspace-state";
+import type { FootprintRecorder, WorkspaceTransactionScope, WorkspaceTransitionAcquireFailure } from "@agentxm/workspace-transactions";
+import { ExtensionLifecycleFailed } from "../errors.js";
+/**
+ * What an install or uninstall plan step declares at execution time: the
+ * manager's own requirements, the transaction scope its closure opens, the
+ * keychain an MCP connection reads, and the workspace facade and agent
+ * repository its artifact observes. These travel with the step and are
+ * composed once at the application's runtime boundary; nothing is captured
+ * into a step's closure on the way, and no failure adapter is among them.
+ */
+export type InstallStepRequirements = ManagerRequirements | RecipeRequirements | McpSecretStore | CodingAgentRepository | WorkspaceMutations | NativeWriteAuthority;
+/**
+ * What routing a source locator, probing configured registries, and reading
+ * what a source contains all need.
+ */
+export type ResolveInstallRequirements = FileSystem.FileSystem | Path.Path | HttpClient.HttpClient | Scope.Scope | SourceHostProviders | WorkspaceCatalog | WorkspaceMutations;
+/**
+ * Every failure resolving a settled install or removal can surface: the
+ * approval and interaction refusals, the candidate revalidation, and the
+ * transition an apply could not acquire. Step failures travel inside the
+ * resolution rather than being raised, so the operator still sees what each
+ * closure settled.
+ */
+export type InstallExecutionFailure = ApprovalRecoveryMissing | CandidateFingerprintFailed | LockfileValidationError | PlanInteractionFailed | WorkspaceSettingsReadFailure | WorkspaceStateReadFailure | WorkspaceTransitionAcquireFailure;
+/**
+ * Everything settling an install reads, and everything resolving the settled
+ * candidate writes through: the sources it resolves against, the workspace
+ * facade and agent outcomes it reads, the journal and footprint the operation
+ * records into, and the interaction that presents and confirms it.
+ */
+export type PrepareInstallRequirements = InstallStepRequirements | ResolveInstallRequirements | ConfiguredAgentOutcomesProvider | FootprintRecorder | OperationJournal | ResolvePlanInteraction | WorkspaceTransactionScope;
+/**
+ * Refuse an install or uninstall with the category, wording, and recovery the
+ * feature decided. The application converts the carried fields into its error
+ * envelope verbatim, so the producer owns the refusal rather than the shell.
+ */
+export declare const installRefused: (fields: {
+    readonly category: ExtensionLifecycleFailed["category"];
+    readonly detail: string;
+    readonly recover?: string;
+    readonly cmd?: string;
+    readonly suggestions?: ExtensionLifecycleFailed["suggestions"];
+    readonly cause?: unknown;
+}) => ExtensionLifecycleFailed;
+/** One discovered package and the constraint the request placed on it. */
+export interface ResolvedInstallRef<TRef> {
+    readonly ref: TRef;
+    readonly versionRange: Option.Option<VersionRange>;
+}
+/** Skills the request selected, and whether to re-materialize regardless. */
+export interface SkillInstallIntent {
+    readonly skillsToInstall: ReadonlyArray<ResolvedInstallRef<SkillExtensionRef>>;
+    readonly force?: boolean;
+}
+/** Subagents the request selected. */
+export interface SubagentInstallIntent {
+    readonly subagentsToInstall: ReadonlyArray<ResolvedInstallRef<SubagentExtensionRef>>;
+}
+/** Rules the request selected. */
+export interface RuleInstallIntent {
+    /** The enclosing semantic closure owns the trailing aggregate projection. */
+    readonly deferProjections?: boolean;
+    readonly refs: ReadonlyArray<ResolvedInstallRef<RuleExtensionRef>>;
+}
+/** Hooks packages the request selected. */
+export interface HookInstallIntent {
+    /** The enclosing semantic closure owns the trailing aggregate projection. */
+    readonly deferProjections?: boolean;
+    readonly refs: ReadonlyArray<ResolvedInstallRef<HookExtensionRef>>;
+}
+/** Knowledge bundles the request selected. */
+export interface KnowledgeInstallIntent {
+    /** The enclosing semantic closure owns the trailing aggregate projection. */
+    readonly deferProjections?: boolean;
+    readonly refs: ReadonlyArray<ResolvedInstallRef<KnowledgeExtensionRef>>;
+}
+/** One MCP connection, its local name, and the inputs the request supplied. */
+export interface McpServerInstallIntent {
+    readonly ref: McpServerExtensionRef;
+    readonly localName: ExtensionName;
+    readonly versionRange: Option.Option<string>;
+    readonly force: boolean;
+    readonly nonInteractive: boolean;
+    readonly env?: Readonly<Record<string, string>>;
+}
+/**
+ * The authority a recovery uses instead of re-selecting members: every member
+ * ref comes from the accepted resolution already recorded for it.
+ */
+export type PackRecoveryDependencyResolver = PackDependencyRefResolver<AcceptedCanonicalRefError | ExtensionResolutionFailed, WorkspaceMutations | FileSystem.FileSystem | Path.Path>;
+/** One pack graph transition and the policy that governs it. */
+export interface PackInstallIntent {
+    readonly packToInstall: PackRef;
+    readonly versionRange: Option.Option<VersionRange>;
+    readonly unattended?: boolean;
+    readonly nonInteractive: boolean;
+    readonly releaseAgeEvaluation?: ReleaseAgeEvaluation;
+    readonly releaseAgeHoldbackBehavior?: "continue" | "preserve-or-block";
+    /** Immutable dependency authority a deterministic recovery workflow supplies. */
+    readonly dependencyResolver?: PackRecoveryDependencyResolver;
+    /** Render shared aggregate projections after a larger enclosing transition. */
+    readonly deferProjections?: boolean;
+    /**
+     * Reacquire the Pack's canonical content instead of reusing the installed
+     * tree. Recovery sets this because the observed tree already diverged from
+     * the accepted resolution, so reusing it would preserve the divergence.
+     */
+    readonly forceCanonical?: boolean;
+}
+//# sourceMappingURL=vocabulary.d.ts.map

package/dist/src/install/vocabulary.js

@@ -0,0 +1,29 @@
+/**
+ * The vocabulary every install route shares.
+ *
+ * Root install, the seven per-type installs, and the configured-entry sweep
+ * are one use case with the type either fixed by the command or detected from
+ * what the source offers. They therefore share one request, one requirement
+ * set, one per-type resolved intent, and one failure vocabulary; only the
+ * grammar that produced the request differs.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import { ExtensionLifecycleFailed } from "../errors.js";
+// -----------------------------------------------------------------------------
+// Failures
+// -----------------------------------------------------------------------------
+/**
+ * Refuse an install or uninstall with the category, wording, and recovery the
+ * feature decided. The application converts the carried fields into its error
+ * envelope verbatim, so the producer owns the refusal rather than the shell.
+ */
+export const installRefused = (fields) => new ExtensionLifecycleFailed({
+    category: fields.category,
+    detail: fields.detail,
+    ...(fields.recover === undefined ? {} : { recover: fields.recover }),
+    ...(fields.cmd === undefined ? {} : { cmd: fields.cmd }),
+    ...(fields.suggestions === undefined ? {} : { suggestions: fields.suggestions }),
+    ...(fields.cause === undefined ? {} : { cause: fields.cause }),
+});
+//# sourceMappingURL=vocabulary.js.map

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

@@ -0,0 +1,35 @@
+/**
+ * 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 } from "@agentxm/extension-materialization";
+import { type Handle } from "@agentxm/extension-model/unstable/extensions";
+import type { KnowledgeExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/knowledge";
+import type { Source } from "@agentxm/extension-model/unstable/sources/types";
+import type { VersionRange } from "@agentxm/extension-model/unstable/version-constraints";
+import { type Plan } from "@agentxm/workspace-operations";
+import type { ExtensionLifecycleFailed } from "../../errors.js";
+import { type InstallStepRequirements, type KnowledgeInstallIntent, type ResolveInstallRequirements } from "../../install/vocabulary.js";
+/** A knowledge source after grammar parsing, before anything is discovered. */
+export interface ParsedKnowledgeInstallRequest {
+    readonly source: Source;
+    readonly names: ReadonlyArray<string>;
+    readonly owner: Option.Option<Handle>;
+    readonly versionRange: Option.Option<VersionRange>;
+}
+/** Read the knowledge source grammar: which owner, which names, which range. */
+export declare const parseKnowledgeInstallRequest: (source: string) => Effect.Effect<ParsedKnowledgeInstallRequest, ExtensionLifecycleFailed, ResolveInstallRequirements>;
+/** Discover the knowledge bundles the parsed source offers. */
+export declare const discoverKnowledgeRefs: (request: ParsedKnowledgeInstallRequest) => Effect.Effect<ReadonlyArray<KnowledgeExtensionRef>, ExtensionLifecycleFailed, ResolveInstallRequirements>;
+/** Settle which knowledge bundles this request installs, or refuse when none matched. */
+export declare const finalizeKnowledgeInstallIntent: (request: ParsedKnowledgeInstallRequest, refs: ReadonlyArray<KnowledgeExtensionRef>) => Effect.Effect<KnowledgeInstallIntent, ExtensionLifecycleFailed>;
+/** The closures a settled knowledge intent becomes. */
+export declare const planKnowledgeInstall: (intent: KnowledgeInstallIntent) => Effect.Effect<Plan<InstallStepRequirements>, ExtensionLifecycleFailed, InstallStepRequirements | KnowledgeManager>;
+//# sourceMappingURL=plan.d.ts.map