@agentxm/extension-materialization 0.28.14-preview.1789139351.5cd4595aa

package/dist/src/live.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Environment-backed layers of the materialization capability: the seven
+ * per-extension-type manager implementations behind their service tags, and
+ * their registration as `workspace-projection` participants. Only application
+ * composition roots import this module.
+ *
+ * @experimental All exports from this module are unstable and may change without notice.
+ * @packageDocumentation
+ */
+export { HookManagerLive } from "./hooks/manager.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 { McpSecretStoreLive } from "./mcps/secret-store-live.js";
+export { PackManagerLive } from "./packs/manager.js";
+export { KnowledgeManagerLive } from "./knowledge/manager.js";
+export { ProjectionParticipantsLive } from "./projection-participants-live.js";
+export { ExtensionManagersLive } from "./manager-registry-live.js";
+//# sourceMappingURL=live.d.ts.map

package/dist/src/live.js

@@ -0,0 +1,20 @@
+/**
+ * Environment-backed layers of the materialization capability: the seven
+ * per-extension-type manager implementations behind their service tags, and
+ * their registration as `workspace-projection` participants. Only application
+ * composition roots import this module.
+ *
+ * @experimental All exports from this module are unstable and may change without notice.
+ * @packageDocumentation
+ */
+export { HookManagerLive } from "./hooks/manager.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 { McpSecretStoreLive } from "./mcps/secret-store-live.js";
+export { PackManagerLive } from "./packs/manager.js";
+export { KnowledgeManagerLive } from "./knowledge/manager.js";
+export { ProjectionParticipantsLive } from "./projection-participants-live.js";
+export { ExtensionManagersLive } from "./manager-registry-live.js";
+//# sourceMappingURL=live.js.map

package/dist/src/manager-contract.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Per-extension-type materialization manager contract.
+ *
+ * Implemented by the seven extension-type managers and consumed by the closure
+ * recipes in `extensions/operations.ts`. Requirements stay explicit in `R`: a
+ * manager never captures the platform into its members, and the command
+ * boundary composes them once. Materialization facts travel forward as return
+ * values, so a later settings or lockfile write reads what the materialization
+ * observed instead of a mutable map the layer kept alive between calls.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import type * as Effect from "effect/Effect";
+import type * as FileSystem from "effect/FileSystem";
+import type * as Option from "effect/Option";
+import type * as Path from "effect/Path";
+import type * as HttpClient from "effect/unstable/http/HttpClient";
+import type { ExtensionManagerFailure } from "./errors.js";
+import type { NativeWriteAuthority } from "@agentxm/agent-integration";
+import type { ProjectionPlan } from "@agentxm/workspace-projection";
+import type { ExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/extension-ref";
+import type { ExtensionTarget, ExtensionTargetFor } from "@agentxm/workspace-state";
+/**
+ * The services every manager keeps in `R`: the platform it reads and writes
+ * through, the registry transport its acquisition steps use, and the authority
+ * that admits a native write. Uniform across the seven managers so a recipe
+ * composes one requirement set, and identical to what a projection participant
+ * declares so a manager registers as one without providing anything at a leaf.
+ * The transaction scope belongs to the closure recipe, not to a manager: every
+ * manager member runs inside a transition the recipe opened.
+ */
+export type ManagerRequirements = FileSystem.FileSystem | Path.Path | HttpClient.HttpClient | NativeWriteAuthority;
+/**
+ * Machine-local effects observed during the most recent materialization.
+ *
+ * This data is intentionally ephemeral. It supports operation output without
+ * making agent-specific paths part of the shared lockfile contract.
+ */
+export interface MaterializationObservation {
+    readonly agents: ReadonlyArray<string>;
+    readonly targets: ReadonlyArray<{
+        readonly path: string;
+        readonly agentIds?: ReadonlyArray<string>;
+    }>;
+}
+/** An empty observation, for transitions that projected nothing. */
+export declare const NO_MATERIALIZATION_OBSERVATION: MaterializationObservation;
+/**
+ * What one materialization observed. Each manager extends this with the
+ * content identity its own settings and lockfile writes need; the closure
+ * recipes carry the value from `materializeInstall` to those writes and to the
+ * step's artifact without inspecting the extension.
+ */
+export interface MaterializationFacts {
+    readonly observation: MaterializationObservation;
+}
+/**
+ * Per-extension-type materialization manager contract.
+ *
+ * `TMaterialization` is what this manager's `materializeInstall` observed and
+ * its entry writes consume; `R` is the requirement set its members declare.
+ */
+export interface ExtensionManager<TRef extends ExtensionRef, TMaterialization extends MaterializationFacts = MaterializationFacts, R = ManagerRequirements> {
+    readonly type: TRef["type"];
+    readonly isInstalled: (args: {
+        readonly target: ExtensionTarget;
+    }) => Effect.Effect<boolean, ExtensionManagerFailure, R>;
+    /** Acquire canonical content and project it, reporting what it observed. */
+    readonly materializeInstall: (args: {
+        readonly ref: TRef;
+        /** When true, re-materialize unconditionally instead of reusing an existing canonical tree. */
+        readonly force?: boolean;
+    }) => Effect.Effect<TMaterialization, ExtensionManagerFailure, R>;
+    /**
+     * Capture cleanup for the currently accepted canonical package before a
+     * replacement writes its new lock entry. The returned effect runs only
+     * after the replacement resolution has been committed inside the same
+     * workspace transaction.
+     */
+    readonly prepareSourceTransition?: (args: {
+        readonly ref: TRef;
+    }) => Effect.Effect<Effect.Effect<void, ExtensionManagerFailure, R>, ExtensionManagerFailure, R>;
+    /**
+     * What this manager's shared aggregate units projected in this invocation.
+     * Aggregate units render after desired state commits — later than
+     * `materializeInstall` returns — so a closure reads the observation back
+     * here instead of receiving it with the materialization facts. Managers
+     * whose units are singletons report their targets in the facts instead and
+     * do not implement this.
+     */
+    readonly aggregateProjectionObservation?: Effect.Effect<MaterializationObservation, ExtensionManagerFailure, R>;
+    /** Build opaque projection plans after desired state and canonical content commit. */
+    readonly projectionPlans?: () => Effect.Effect<ReadonlyArray<ProjectionPlan<void, ExtensionManagerFailure, R>>, ExtensionManagerFailure, R>;
+    readonly getConfiguredSource?: (args: {
+        readonly target: ExtensionTarget;
+    }) => Effect.Effect<Option.Option<string>, ExtensionManagerFailure, R>;
+    /**
+     * Observe whether desired state declares the target independently of whether
+     * that declaration points at a package source.
+     */
+    readonly isConfigured?: (args: {
+        readonly target: ExtensionTarget;
+    }) => Effect.Effect<boolean, ExtensionManagerFailure, R>;
+    readonly listMaterializable: () => Effect.Effect<ReadonlyArray<TRef>, ExtensionManagerFailure, R>;
+    /** Remove projections and canonical content, reporting what it withdrew. */
+    readonly materializeUninstall: (args: {
+        readonly target: ExtensionTargetFor<TRef>;
+    }) => Effect.Effect<TMaterialization, ExtensionManagerFailure, R>;
+    /** Remove active projections while retaining canonical managed content. */
+    readonly materializeDeactivate: (args: {
+        readonly target: ExtensionTargetFor<TRef>;
+    }) => Effect.Effect<TMaterialization, ExtensionManagerFailure, R>;
+    readonly upsertSettingsEntry: (args: {
+        readonly ref: TRef;
+        readonly versionRange: Option.Option<string>;
+        /** What `materializeInstall` observed in this closure, when it ran. */
+        readonly materialization: Option.Option<TMaterialization>;
+    }) => Effect.Effect<void, ExtensionManagerFailure, R>;
+    readonly removeSettingsEntry: (args: {
+        readonly target: ExtensionTargetFor<TRef>;
+        /** What the withdrawal in this closure observed, when one ran. */
+        readonly materialization: Option.Option<TMaterialization>;
+    }) => Effect.Effect<void, ExtensionManagerFailure, R>;
+    readonly upsertLockfileEntry: (args: {
+        readonly ref: TRef;
+        /** What `materializeInstall` observed in this closure, when it ran. */
+        readonly materialization: Option.Option<TMaterialization>;
+    }) => Effect.Effect<void, ExtensionManagerFailure, R>;
+    readonly removeLockfileEntry: (args: {
+        readonly target: ExtensionTargetFor<TRef>;
+        /** What the withdrawal in this closure observed, when one ran. */
+        readonly materialization: Option.Option<TMaterialization>;
+    }) => Effect.Effect<void, ExtensionManagerFailure, R>;
+}
+//# sourceMappingURL=manager-contract.d.ts.map

package/dist/src/manager-contract.js

@@ -0,0 +1,19 @@
+/**
+ * Per-extension-type materialization manager contract.
+ *
+ * Implemented by the seven extension-type managers and consumed by the closure
+ * recipes in `extensions/operations.ts`. Requirements stay explicit in `R`: a
+ * manager never captures the platform into its members, and the command
+ * boundary composes them once. Materialization facts travel forward as return
+ * values, so a later settings or lockfile write reads what the materialization
+ * observed instead of a mutable map the layer kept alive between calls.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+/** An empty observation, for transitions that projected nothing. */
+export const NO_MATERIALIZATION_OBSERVATION = {
+    agents: [],
+    targets: [],
+};
+//# sourceMappingURL=manager-contract.js.map

package/dist/src/manager-registry-live.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The manager registry composed from the seven individual manager tags.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Layer from "effect/Layer";
+import { ExtensionManagers } from "./manager-registry.js";
+import { HookManager, KnowledgeManager, McpServerManager, PackManager, RuleManager, SkillManager, SubagentManager } from "./managers.js";
+/** Resolve every per-type manager once and publish them as one lookup. */
+export declare const ExtensionManagersLive: Layer.Layer<ExtensionManagers, never, SkillManager | SubagentManager | RuleManager | HookManager | KnowledgeManager | McpServerManager | PackManager>;
+//# sourceMappingURL=manager-registry-live.d.ts.map

package/dist/src/manager-registry-live.js

@@ -0,0 +1,23 @@
+/**
+ * The manager registry composed from the seven individual manager tags.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { ExtensionManagers } from "./manager-registry.js";
+import { HookManager, KnowledgeManager, McpServerManager, PackManager, RuleManager, SkillManager, SubagentManager, } from "./managers.js";
+/** Resolve every per-type manager once and publish them as one lookup. */
+export const ExtensionManagersLive = Layer.effect(ExtensionManagers, Effect.gen(function* () {
+    const managers = {
+        skill: yield* SkillManager,
+        subagent: yield* SubagentManager,
+        rule: yield* RuleManager,
+        hook: yield* HookManager,
+        knowledge: yield* KnowledgeManager,
+        "mcp-server": yield* McpServerManager,
+        pack: yield* PackManager,
+    };
+    return managers;
+}));
+//# sourceMappingURL=manager-registry-live.js.map

package/dist/src/manager-registry.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Every per-extension-type manager under one lookup.
+ *
+ * A use case that decides the extension type at runtime — creating, forking,
+ * adopting, importing, or re-versioning an authored package — needs the
+ * manager for the type it decided, not a manager it named at compile time.
+ * Without this, each such use case re-derives the same seven-way switch over
+ * `ExtensionType`. The registry keeps every entry at its own precise manager
+ * type, so narrowing the type narrows the manager with it.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as ServiceMap from "effect/Context";
+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 { SkillExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/skill";
+import type { ExtensionManager, ManagerRequirements } from "./manager-contract.js";
+import type { HookManagerService, KnowledgeManagerService, McpServerMaterializationFacts, PackMaterializationFacts, RuleManagerService, SkillMaterializationFacts, SubagentManagerService } from "./managers.js";
+/** The manager each extension type is materialized through. */
+export interface ExtensionManagersService {
+    readonly skill: ExtensionManager<SkillExtensionRef, SkillMaterializationFacts, ManagerRequirements>;
+    readonly subagent: SubagentManagerService;
+    readonly rule: RuleManagerService;
+    readonly hook: HookManagerService;
+    readonly knowledge: KnowledgeManagerService;
+    readonly "mcp-server": ExtensionManager<McpServerExtensionRef, McpServerMaterializationFacts, ManagerRequirements>;
+    readonly pack: ExtensionManager<PackRef, PackMaterializationFacts, ManagerRequirements>;
+}
+declare const ExtensionManagers_base: ServiceMap.ServiceClass<ExtensionManagers, "@agentxm/extension-materialization/ExtensionManagers", ExtensionManagersService>;
+/**
+ * The seven managers as one service. The application composes it once from
+ * the individual manager tags; `./live` carries that composition.
+ */
+export declare class ExtensionManagers extends ExtensionManagers_base {
+}
+export {};
+//# sourceMappingURL=manager-registry.d.ts.map

package/dist/src/manager-registry.js

@@ -0,0 +1,22 @@
+/**
+ * Every per-extension-type manager under one lookup.
+ *
+ * A use case that decides the extension type at runtime — creating, forking,
+ * adopting, importing, or re-versioning an authored package — needs the
+ * manager for the type it decided, not a manager it named at compile time.
+ * Without this, each such use case re-derives the same seven-way switch over
+ * `ExtensionType`. The registry keeps every entry at its own precise manager
+ * type, so narrowing the type narrows the manager with it.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as ServiceMap from "effect/Context";
+const _managersCoverEveryType = true;
+void _managersCoverEveryType;
+/**
+ * The seven managers as one service. The application composes it once from
+ * the individual manager tags; `./live` carries that composition.
+ */
+export class ExtensionManagers extends ServiceMap.Service()("@agentxm/extension-materialization/ExtensionManagers") {
+}
+//# sourceMappingURL=manager-registry.js.map

package/dist/src/managers.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Per-extension-type manager service tags and the materialization facts each
+ * manager reports.
+ *
+ * Plan-building features require a manager through its tag without depending
+ * on the module that implements it. Every tag pins the facts type its manager
+ * carries from a materialization to the settings and lockfile writes that
+ * follow it in the same closure, so nothing travels through state the layer
+ * keeps alive between calls.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import type * as Effect from "effect/Effect";
+import type * as Option from "effect/Option";
+import * as ServiceMap from "effect/Context";
+import type { ExtensionManager, ManagerRequirements, MaterializationFacts, MaterializationObservation } from "./manager-contract.js";
+import type { ExtensionManagerFailure } from "./errors.js";
+import type { ProjectionPlan } from "@agentxm/workspace-projection";
+import type { ConfiguredAgentOutcome } from "@agentxm/workspace-state";
+import type { WorkspaceTransactionScope } from "@agentxm/workspace-transactions";
+import type { SourceHash } from "@agentxm/extension-model/unstable/sources/source-hash";
+import type { TreeIntegrity } from "@agentxm/workspace-state";
+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 { VersionRange } from "@agentxm/extension-model/unstable/version-constraints";
+/** The content identity a canonical acquisition established, when it ran. */
+export interface AcquiredContentFacts extends MaterializationFacts {
+    /** Absent for workspace-authored packages, which carry no accepted tree. */
+    readonly treeIntegrity: Option.Option<TreeIntegrity>;
+}
+/** What a skill materialization observed. */
+export interface SkillMaterializationFacts extends AcquiredContentFacts {
+    readonly sourceHash: Option.Option<SourceHash>;
+}
+/** What a subagent materialization observed. */
+export interface SubagentMaterializationFacts extends AcquiredContentFacts {
+    readonly sourceHash: Option.Option<SourceHash>;
+}
+/** What a rule materialization observed, including the ref it accepted. */
+export interface RuleMaterializationFacts extends AcquiredContentFacts {
+    readonly acquired: Option.Option<{
+        readonly ref: RuleExtensionRef;
+        readonly workspaceRelativeLocalSourcePath: Option.Option<string>;
+        readonly sourceHash: SourceHash;
+        readonly treeIntegrity: TreeIntegrity;
+    }>;
+}
+/** What a hook materialization observed, including the ref it accepted. */
+export interface HookMaterializationFacts extends AcquiredContentFacts {
+    readonly acquired: Option.Option<{
+        readonly ref: HookExtensionRef;
+        readonly workspaceRelativeLocalSourcePath: Option.Option<string>;
+        readonly sourceHash: SourceHash;
+        readonly treeIntegrity: TreeIntegrity;
+    }>;
+}
+/** What a Knowledge materialization observed. */
+export interface KnowledgeMaterializationFacts extends MaterializationFacts {
+    readonly acquired: Option.Option<{
+        readonly relativeLocalSource: Option.Option<string>;
+        readonly sourceHash: SourceHash;
+        readonly treeIntegrity?: TreeIntegrity;
+    }>;
+}
+/**
+ * What an MCP server materialization observed. A withdrawal also reports which
+ * shared registry resolution its lockfile entry may release.
+ */
+export interface McpServerMaterializationFacts extends AcquiredContentFacts {
+    readonly removal: Option.Option<{
+        readonly resolutionKey: Option.Option<string>;
+        readonly retainShared: boolean;
+    }>;
+}
+/** What a Pack materialization observed: the acquired content identity alone. */
+export type PackMaterializationFacts = AcquiredContentFacts;
+declare const SkillManager_base: ServiceMap.ServiceClass<SkillManager, "@agentxm/extension-materialization/managers/SkillManager", ExtensionManager<SkillExtensionRef, SkillMaterializationFacts, ManagerRequirements>>;
+export declare class SkillManager extends SkillManager_base {
+}
+declare const McpServerManager_base: ServiceMap.ServiceClass<McpServerManager, "@agentxm/extension-materialization/managers/McpServerManager", ExtensionManager<McpServerExtensionRef, McpServerMaterializationFacts, ManagerRequirements>>;
+export declare class McpServerManager extends McpServerManager_base {
+}
+export interface SubagentManagerService extends ExtensionManager<SubagentExtensionRef, SubagentMaterializationFacts, ManagerRequirements> {
+    readonly projectionObservation: (ref: SubagentExtensionRef) => Effect.Effect<{
+        readonly present: boolean;
+        readonly current: boolean;
+    }, ExtensionManagerFailure, ManagerRequirements>;
+}
+declare const SubagentManager_base: ServiceMap.ServiceClass<SubagentManager, "@agentxm/extension-materialization/managers/SubagentManager", SubagentManagerService>;
+export declare class SubagentManager extends SubagentManager_base {
+}
+export interface RuleManagerService extends ExtensionManager<RuleExtensionRef, RuleMaterializationFacts, ManagerRequirements> {
+    readonly aggregateProjectionObservation: Effect.Effect<MaterializationObservation, ExtensionManagerFailure, ManagerRequirements>;
+    readonly projectionPlans: () => Effect.Effect<ReadonlyArray<ProjectionPlan<void, ExtensionManagerFailure, ManagerRequirements>>, ExtensionManagerFailure, ManagerRequirements>;
+}
+declare const RuleManager_base: ServiceMap.ServiceClass<RuleManager, "@agentxm/extension-materialization/managers/RuleManager", RuleManagerService>;
+export declare class RuleManager extends RuleManager_base {
+}
+export interface HookManagerService extends ExtensionManager<HookExtensionRef, HookMaterializationFacts, ManagerRequirements> {
+    readonly aggregateProjectionObservation: Effect.Effect<MaterializationObservation, ExtensionManagerFailure, ManagerRequirements>;
+    readonly projectionPlans: () => Effect.Effect<ReadonlyArray<ProjectionPlan<void, ExtensionManagerFailure, ManagerRequirements>>, ExtensionManagerFailure, ManagerRequirements>;
+    readonly configuredAgentOutcomes?: (state: "projected" | "current") => Effect.Effect<ReadonlyArray<ConfiguredAgentOutcome>, ExtensionManagerFailure, ManagerRequirements>;
+    readonly configuredAgentOutcomesForRef?: (ref: HookExtensionRef, state: "projected" | "current") => Effect.Effect<ReadonlyArray<ConfiguredAgentOutcome>, ExtensionManagerFailure, ManagerRequirements>;
+}
+declare const HookManager_base: ServiceMap.ServiceClass<HookManager, "@agentxm/extension-materialization/managers/HookManager", HookManagerService>;
+export declare class HookManager extends HookManager_base {
+}
+export interface KnowledgeSyncResult {
+    readonly changed: boolean;
+    readonly warnings: ReadonlyArray<string>;
+    readonly artifacts: ReadonlyArray<{
+        readonly path: string;
+        readonly change: "created" | "updated" | "removed" | "unchanged";
+        readonly mechanism?: "symlink" | "copy";
+    }>;
+}
+export interface KnowledgeManagerService extends ExtensionManager<KnowledgeExtensionRef, KnowledgeMaterializationFacts, ManagerRequirements> {
+    readonly projectionPlans: () => Effect.Effect<ReadonlyArray<ProjectionPlan<void, ExtensionManagerFailure, ManagerRequirements>>, ExtensionManagerFailure, ManagerRequirements>;
+    /**
+     * Catalog refresh, sync, and the atomic install open their own workspace
+     * transaction, so they name the transaction scope alongside the manager's
+     * own requirements.
+     */
+    readonly refreshCatalog: () => Effect.Effect<void, ExtensionManagerFailure, ManagerRequirements | WorkspaceTransactionScope>;
+    readonly sync: (options: {
+        readonly dryRun: boolean;
+    }) => Effect.Effect<KnowledgeSyncResult, ExtensionManagerFailure, ManagerRequirements | WorkspaceTransactionScope>;
+    readonly install: (args: {
+        readonly ref: KnowledgeExtensionRef;
+        readonly versionRange: Option.Option<VersionRange>;
+        readonly deferProjection?: boolean;
+    }) => Effect.Effect<void, ExtensionManagerFailure, ManagerRequirements | WorkspaceTransactionScope>;
+}
+declare const KnowledgeManager_base: ServiceMap.ServiceClass<KnowledgeManager, "@agentxm/extension-materialization/managers/KnowledgeManager", KnowledgeManagerService>;
+export declare class KnowledgeManager extends KnowledgeManager_base {
+}
+declare const PackManager_base: ServiceMap.ServiceClass<PackManager, "@agentxm/extension-materialization/managers/PackManager", ExtensionManager<PackRef, AcquiredContentFacts, ManagerRequirements>>;
+export declare class PackManager extends PackManager_base {
+}
+export {};
+//# sourceMappingURL=managers.d.ts.map

package/dist/src/managers.js

@@ -0,0 +1,32 @@
+/**
+ * Per-extension-type manager service tags and the materialization facts each
+ * manager reports.
+ *
+ * Plan-building features require a manager through its tag without depending
+ * on the module that implements it. Every tag pins the facts type its manager
+ * carries from a materialization to the settings and lockfile writes that
+ * follow it in the same closure, so nothing travels through state the layer
+ * keeps alive between calls.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as ServiceMap from "effect/Context";
+// -----------------------------------------------------------------------------
+// Service tags
+// -----------------------------------------------------------------------------
+export class SkillManager extends ServiceMap.Service()("@agentxm/extension-materialization/managers/SkillManager") {
+}
+export class McpServerManager extends ServiceMap.Service()("@agentxm/extension-materialization/managers/McpServerManager") {
+}
+export class SubagentManager extends ServiceMap.Service()("@agentxm/extension-materialization/managers/SubagentManager") {
+}
+export class RuleManager extends ServiceMap.Service()("@agentxm/extension-materialization/managers/RuleManager") {
+}
+export class HookManager extends ServiceMap.Service()("@agentxm/extension-materialization/managers/HookManager") {
+}
+export class KnowledgeManager extends ServiceMap.Service()("@agentxm/extension-materialization/managers/KnowledgeManager") {
+}
+export class PackManager extends ServiceMap.Service()("@agentxm/extension-materialization/managers/PackManager") {
+}
+//# sourceMappingURL=managers.js.map

package/dist/src/mcps/artifact.d.ts

@@ -0,0 +1,24 @@
+import type { AgentId } from "@agentxm/extension-model/unstable/agents/types";
+import type { McpServerLockEntry } from "@agentxm/workspace-state";
+import type { JobStepArtifact, JobStepArtifactTarget } from "@agentxm/workspace-operations";
+import type { WorkspaceScope } from "@agentxm/extension-model/unstable/workspace-scope";
+export declare const mcpConfigSurface: (scope: WorkspaceScope) => string;
+export declare const MCP_AGENT_CONFIG_SURFACE = ".mcp.json";
+export declare const mcpServerVersion: (entry: McpServerLockEntry) => string | undefined;
+export declare const mcpServerSourcePath: (scope: WorkspaceScope, entry: McpServerLockEntry) => string;
+export declare const agentConfigTarget: (change: JobStepArtifactTarget["change"], agentIds: ReadonlyArray<AgentId>) => JobStepArtifactTarget | undefined;
+export interface AgentMcpConfigOutcome {
+    readonly agentId: string;
+    readonly targets?: ReadonlyArray<JobStepArtifactTarget>;
+}
+export declare const agentConfigTargets: (outcomes: ReadonlyArray<AgentMcpConfigOutcome>) => ReadonlyArray<JobStepArtifactTarget>;
+export declare const mcpSettingsTarget: (scope: WorkspaceScope, change: JobStepArtifactTarget["change"]) => JobStepArtifactTarget;
+export declare const mcpSourceTarget: (scope: WorkspaceScope, entry: McpServerLockEntry, change: JobStepArtifactTarget["change"]) => JobStepArtifactTarget;
+export declare const mcpServerArtifact: (args: {
+    readonly lockEntry: McpServerLockEntry | undefined;
+    readonly scope: JobStepArtifact["scope"];
+    readonly change: JobStepArtifact["change"];
+    readonly targets: ReadonlyArray<JobStepArtifactTarget>;
+    readonly agents?: ReadonlyArray<string>;
+}) => JobStepArtifact;
+//# sourceMappingURL=artifact.d.ts.map

package/dist/src/mcps/artifact.js

@@ -0,0 +1,74 @@
+import { ACQUIRED_EXTENSIONS_DIR } from "@agentxm/workspace-state";
+import { acquiredExtensionDisplayPathFromLockEntry } from "@agentxm/workspace-state";
+export const mcpConfigSurface = (scope) => scope === "project"
+    ? "axm.json / axm-lock.yaml"
+    : ".axm/workspace/axm.json / .axm/workspace/axm-lock.yaml";
+export const MCP_AGENT_CONFIG_SURFACE = ".mcp.json";
+export const mcpServerVersion = (entry) => entry.type === "registry" ? entry.resolvedVersion : undefined;
+export const mcpServerSourcePath = (scope, entry) => acquiredExtensionDisplayPathFromLockEntry(scope === "project" ? ACQUIRED_EXTENSIONS_DIR : ".axm/workspace/agent_extensions", entry, "mcps", entry.workspaceName);
+export const agentConfigTarget = (change, agentIds) => agentIds.length === 0
+    ? undefined
+    : {
+        path: MCP_AGENT_CONFIG_SURFACE,
+        change,
+        agentIds,
+    };
+const mergeTargetChange = (current, next) => {
+    if (current === "created" || next === "created")
+        return "created";
+    if (current === "updated" || next === "updated")
+        return "updated";
+    if (current === "removed" || next === "removed")
+        return "removed";
+    return "unchanged";
+};
+export const agentConfigTargets = (outcomes) => {
+    const grouped = new Map();
+    for (const outcome of outcomes) {
+        for (const target of outcome.targets ?? []) {
+            const existing = grouped.get(target.path);
+            if (existing === undefined) {
+                grouped.set(target.path, {
+                    path: target.path,
+                    change: target.change,
+                    agentIds: [outcome.agentId],
+                });
+                continue;
+            }
+            existing.change = mergeTargetChange(existing.change, target.change);
+            existing.agentIds.push(outcome.agentId);
+        }
+    }
+    return Array.from(grouped.values()).map((target) => ({
+        path: target.path,
+        change: target.change,
+        agentIds: target.agentIds,
+    }));
+};
+export const mcpSettingsTarget = (scope, change) => ({
+    path: scope === "project" ? "axm.json" : ".axm/workspace/axm.json",
+    change,
+});
+export const mcpSourceTarget = (scope, entry, change) => ({
+    path: mcpServerSourcePath(scope, entry),
+    change,
+});
+export const mcpServerArtifact = (args) => {
+    const version = args.lockEntry === undefined ? undefined : mcpServerVersion(args.lockEntry);
+    return {
+        path: args.lockEntry === undefined
+            ? mcpConfigSurface(args.scope)
+            : mcpServerSourcePath(args.scope, args.lockEntry),
+        scope: args.scope,
+        change: args.change,
+        ...(args.agents === undefined ? {} : { agents: args.agents }),
+        ...(version === undefined ? {} : { version }),
+        ...(args.targets.length === 0
+            ? {}
+            : {
+                fileCount: args.targets.length,
+                targets: args.targets,
+            }),
+    };
+};
+//# sourceMappingURL=artifact.js.map

package/dist/src/mcps/authored-materialization.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Materializing an authored MCP server package during create, fork, adopt, and
+ * native import.
+ *
+ * The authored closure recipe accepts a type-specific materialization because
+ * an MCP server's canonical content is realized by the install operation
+ * rather than by its manager. Both live in this capability, so every authoring
+ * route reaches the same realization without importing a peer feature.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import type { McpServerExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/mcp-server";
+import type { McpServerMaterializationFacts } from "../managers.js";
+import type { ExtensionManagerFailure } from "../errors.js";
+import { type McpServerInstallRequirements } from "./install-operation.js";
+/**
+ * Realize the authored package's canonical content and native projections
+ * without touching workspace state: the authored closure commits desired state
+ * itself. Reports no acquisition facts — an authored package has no accepted
+ * registry resolution for the entry writers to record.
+ */
+export declare const materializeAuthoredMcpServer: (args: {
+    readonly ref: McpServerExtensionRef;
+    readonly nonInteractive: boolean;
+}) => Effect.Effect<Option.Option<McpServerMaterializationFacts>, ExtensionManagerFailure, McpServerInstallRequirements>;
+//# sourceMappingURL=authored-materialization.d.ts.map

package/dist/src/mcps/authored-materialization.js

@@ -0,0 +1,34 @@
+/**
+ * Materializing an authored MCP server package during create, fork, adopt, and
+ * native import.
+ *
+ * The authored closure recipe accepts a type-specific materialization because
+ * an MCP server's canonical content is realized by the install operation
+ * rather than by its manager. Both live in this capability, so every authoring
+ * route reaches the same realization without importing a peer feature.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { installMcpServer } from "./install-operation.js";
+/**
+ * Realize the authored package's canonical content and native projections
+ * without touching workspace state: the authored closure commits desired state
+ * itself. Reports no acquisition facts — an authored package has no accepted
+ * registry resolution for the entry writers to record.
+ */
+export const materializeAuthoredMcpServer = (args) => installMcpServer({
+    name: "install-mcp-server",
+    args: {
+        ref: args.ref,
+        nonInteractive: args.nonInteractive,
+        force: false,
+        allowWorkspaceSourceTransition: true,
+        versionRange: Option.none(),
+        skipSettings: Option.none(),
+        skipStateWrites: true,
+        env: Option.none(),
+    },
+}).pipe(Effect.as(Option.none()));
+//# sourceMappingURL=authored-materialization.js.map