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

package/dist/src/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @agentxm/extension-materialization public API.
+ *
+ * The materialization capability: the per-extension-type manager contract and
+ * service tags, the per-type failure families, canonical package staging and
+ * swap, registry-backed acquisition, and the install, materialize, uninstall,
+ * and authored-package closure recipes that compose a manager into one plan
+ * step. Environment-backed manager layers live behind `./live`; in-memory
+ * managers for feature tests live behind `./testing`.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+export { NO_MATERIALIZATION_OBSERVATION, type ExtensionManager, type ManagerRequirements, type MaterializationFacts, type MaterializationObservation, } from "./manager-contract.js";
+export { ExtensionManagers, type ExtensionManagersService } from "./manager-registry.js";
+export { HookManager, KnowledgeManager, McpServerManager, PackManager, RuleManager, SkillManager, SubagentManager, type AcquiredContentFacts, type HookManagerService, type HookMaterializationFacts, type KnowledgeManagerService, type KnowledgeMaterializationFacts, type KnowledgeSyncResult, type McpServerMaterializationFacts, type PackMaterializationFacts, type RuleManagerService, type RuleMaterializationFacts, type SkillMaterializationFacts, type SubagentManagerService, type SubagentMaterializationFacts, } from "./managers.js";
+export type { ExtensionManagerFailure, ExtensionMaterializationError } from "./errors.js";
+export { ArchiveIntegrityMismatch, CanonicalPackageProbeFailed, CreateDestinationExists, LifecyclePostconditionViolated, PackageCopyFailed, PackageMaterializationFailed, ScaffoldedExtensionUnresolved, StagedPackageInvalid, type MaterializationError, } from "./extensions/errors.js";
+export { HookDefinitionInvalid, HookInstallStateMissing, type HookManagerError, } from "./hooks/errors.js";
+export { RuleDefinitionInvalid, RuleInstallStateMissing, type RuleManagerError, } from "./rules/errors.js";
+export { McpAgentSyncRefused, McpCanonicalPathUnsafe, McpInstallStateMissing, McpLocalNameConflict, McpRegistryOnlyInstall, McpRequiredInputsMissing, McpWorkspacePackageInvalid, type McpAgentSyncFault, type McpManagerError, type McpWorkspacePackageFault, } from "./mcps/errors.js";
+export { SubagentContentUnreadable, SubagentDefinitionInvalid, SubagentInstallStateMissing, type SubagentManagerError, } from "./subagents/errors.js";
+export { SkillDefinitionInvalid, SkillInstallStateMissing, SkillMaterializationFailed, type SkillManagerError, } from "./skills/errors.js";
+export { PackArchiveFetchFailed, PackDefinitionInvalid, PackInstallStateMissing, PackStagingFailed, type PackManagerError, } from "./packs/errors.js";
+export { KnowledgeDefinitionInvalid, KnowledgeDesiredStateUnreconcilable, KnowledgeInstallStateMissing, KnowledgeIoFailed, KnowledgeObservableContractViolated, KnowledgeResolutionMissing, KnowledgeUnavailable, type KnowledgeManagerError, } from "./knowledge/errors.js";
+export { collectSecretInputNames, deleteMcpSecrets, installMcpServer, readMcpServerManifest, type InstallMcpServerOperation, type InstallMcpServerOperationArgs, type McpSecretDeletionOutcome, type McpServerInstallRequirements, } from "./mcps/install-operation.js";
+export { materializeAuthoredMcpServer } from "./mcps/authored-materialization.js";
+export { NativeMcpEntryRetirementFailed, retireNativeMcpEntry, type NativeMcpEntryRef, } from "./mcps/native-entry.js";
+export { MCP_SECRET_SERVICE, McpSecretStore, mcpSecretAccount, type McpSecretEraseOutcome, type McpSecretIdentity, type McpSecretStoreService, type McpSecretWriteOutcome, } from "./mcps/secret-store.js";
+export { MCP_AGENT_CONFIG_SURFACE, agentConfigTarget, agentConfigTargets, mcpConfigSurface, mcpServerArtifact, mcpServerSourcePath, mcpServerVersion, mcpSettingsTarget, mcpSourceTarget, type AgentMcpConfigOutcome, } from "./mcps/artifact.js";
+export { buildSubagentLockEntry } from "./subagents/lock-entry-builder.js";
+export { artifactAgentIdsFromTargets, artifactTargetAgentIds, groupInstallTargetsByDirectory, skillArtifactFromTargets, type InstallableSkillTarget, type InstallableSkillTargetLocation, } from "./skills/skill-artifact.js";
+export { computeSkillSourceHash } from "./skills/source-hash.js";
+export { ensureSkillAgentArtifact, removeSkillAgentArtifact } from "./skills/materialization.js";
+export { copyExtensionDirectory, formatCopyExtensionDirectoryFailure, type CopyExtensionDirectoryFailureDetails, type CopyExtensionDirectoryOptions, } from "./extensions/copy-directory.js";
+export { shouldReuseCanonicalInstall } from "./extensions/canonical-reuse.js";
+export { configuredMcpServersToDiskRefs, configuredPacksToDiskRefs, configuredSkillsToDiskRefs, configuredSubagentsToDiskRefs, } from "./extensions/materializable-from-disk.js";
+export { canReuseExternalPackage, canReuseInstalledPackage, canonicalMaterializationPaths, createCanonicalDirectory, materializeExternalPackage, materializeExternalPackageWithTreeIntegrity, recoverCanonicalDirectory, replaceCanonicalDirectory, replaceCanonicalDirectoryWithInspection, type CanReuseExternalPackageArgs, type CanReuseInstalledPackageArgs, type CanonicalDirectoryInspection, type CanonicalDirectoryReplacementError, type CreateCanonicalDirectoryArgs, type MaterializeExternalPackageArgs, type MaterializedPackage, type RecoverCanonicalDirectoryArgs, type ReplaceCanonicalDirectoryArgs, type ReplaceCanonicalDirectoryWithInspectionArgs, } from "./extensions/canonical-directory.js";
+export { materializeRegistryPackage, materializeRegistryPackageWithTreeIntegrity, type MaterializeRegistryPackageArgs, type RegistryPackageMaterializationMessages, } from "./registry-materialization.js";
+export { buildAuthoredExtensionStep, buildInstallOperation, buildMaterializeOperation, buildNewExtensionStep, buildUninstallOperation, extensionRefLifecycleWarnings, extensionRefRegistryLifecycle, formatPackageUrlParts, targetFromRef, toLabel, toLabelWithCompanions, toStepKey, type AuthoredExtensionOperationArgs, type CallerStepFailure, type InstallOperationArgs, type MaterializeOperationArgs, type NewExtensionOperationArgs, type RecipeRequirements, type StepFailureAdapter, type UninstallOperationArgs, type UninstallRetentionPolicy, type UninstallSettlement, type UnreadablePackageRetirement, } from "./extensions/operations.js";
+export { RetainedContentUnusable } from "./desired-state/errors.js";
+export { collectRetainedMaterializeSteps, type RetainedMaterializeFailure, type RetainedMaterializeRequirements, type RetainedMaterializeSteps, type RunRetainedMcpServerInstall, } from "./desired-state/retained-materialization.js";
+export { projectionErrorToStepFailure } from "./projection-step-failure.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.js

@@ -0,0 +1,56 @@
+/**
+ * @agentxm/extension-materialization public API.
+ *
+ * The materialization capability: the per-extension-type manager contract and
+ * service tags, the per-type failure families, canonical package staging and
+ * swap, registry-backed acquisition, and the install, materialize, uninstall,
+ * and authored-package closure recipes that compose a manager into one plan
+ * step. Environment-backed manager layers live behind `./live`; in-memory
+ * managers for feature tests live behind `./testing`.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+// Manager contract
+export { NO_MATERIALIZATION_OBSERVATION, } from "./manager-contract.js";
+// The seven managers under one lookup, for use cases that decide the
+// extension type at runtime.
+export { ExtensionManagers } from "./manager-registry.js";
+// Manager service tags and the facts each manager reports
+export { HookManager, KnowledgeManager, McpServerManager, PackManager, RuleManager, SkillManager, SubagentManager, } from "./managers.js";
+export { ArchiveIntegrityMismatch, CanonicalPackageProbeFailed, CreateDestinationExists, LifecyclePostconditionViolated, PackageCopyFailed, PackageMaterializationFailed, ScaffoldedExtensionUnresolved, StagedPackageInvalid, } from "./extensions/errors.js";
+export { HookDefinitionInvalid, HookInstallStateMissing, } from "./hooks/errors.js";
+export { RuleDefinitionInvalid, RuleInstallStateMissing, } from "./rules/errors.js";
+export { McpAgentSyncRefused, McpCanonicalPathUnsafe, McpInstallStateMissing, McpLocalNameConflict, McpRegistryOnlyInstall, McpRequiredInputsMissing, McpWorkspacePackageInvalid, } from "./mcps/errors.js";
+export { SubagentContentUnreadable, SubagentDefinitionInvalid, SubagentInstallStateMissing, } from "./subagents/errors.js";
+export { SkillDefinitionInvalid, SkillInstallStateMissing, SkillMaterializationFailed, } from "./skills/errors.js";
+export { PackArchiveFetchFailed, PackDefinitionInvalid, PackInstallStateMissing, PackStagingFailed, } from "./packs/errors.js";
+export { KnowledgeDefinitionInvalid, KnowledgeDesiredStateUnreconcilable, KnowledgeInstallStateMissing, KnowledgeIoFailed, KnowledgeObservableContractViolated, KnowledgeResolutionMissing, KnowledgeUnavailable, } from "./knowledge/errors.js";
+// MCP server installation: the operation four surfaces share, its credential
+// port, and the artifact/target vocabulary the plan step reports.
+export { collectSecretInputNames, deleteMcpSecrets, installMcpServer, readMcpServerManifest, } from "./mcps/install-operation.js";
+export { materializeAuthoredMcpServer } from "./mcps/authored-materialization.js";
+export { NativeMcpEntryRetirementFailed, retireNativeMcpEntry, } from "./mcps/native-entry.js";
+export { MCP_SECRET_SERVICE, McpSecretStore, mcpSecretAccount, } from "./mcps/secret-store.js";
+export { MCP_AGENT_CONFIG_SURFACE, agentConfigTarget, agentConfigTargets, mcpConfigSurface, mcpServerArtifact, mcpServerSourcePath, mcpServerVersion, mcpSettingsTarget, mcpSourceTarget, } from "./mcps/artifact.js";
+// Per-type materialization vocabulary
+export { buildSubagentLockEntry } from "./subagents/lock-entry-builder.js";
+export { artifactAgentIdsFromTargets, artifactTargetAgentIds, groupInstallTargetsByDirectory, skillArtifactFromTargets, } from "./skills/skill-artifact.js";
+export { computeSkillSourceHash } from "./skills/source-hash.js";
+export { ensureSkillAgentArtifact, removeSkillAgentArtifact } from "./skills/materialization.js";
+// Canonical package staging, copy, reuse, and on-disk materializability
+export { copyExtensionDirectory, formatCopyExtensionDirectoryFailure, } from "./extensions/copy-directory.js";
+export { shouldReuseCanonicalInstall } from "./extensions/canonical-reuse.js";
+export { configuredMcpServersToDiskRefs, configuredPacksToDiskRefs, configuredSkillsToDiskRefs, configuredSubagentsToDiskRefs, } from "./extensions/materializable-from-disk.js";
+export { canReuseExternalPackage, canReuseInstalledPackage, canonicalMaterializationPaths, createCanonicalDirectory, materializeExternalPackage, materializeExternalPackageWithTreeIntegrity, recoverCanonicalDirectory, replaceCanonicalDirectory, replaceCanonicalDirectoryWithInspection, } from "./extensions/canonical-directory.js";
+// Registry-backed acquisition
+export { materializeRegistryPackage, materializeRegistryPackageWithTreeIntegrity, } from "./registry-materialization.js";
+// Closure recipes
+export { buildAuthoredExtensionStep, buildInstallOperation, buildMaterializeOperation, buildNewExtensionStep, buildUninstallOperation, extensionRefLifecycleWarnings, extensionRefRegistryLifecycle, formatPackageUrlParts, targetFromRef, toLabel, toLabelWithCompanions, toStepKey, } from "./extensions/operations.js";
+// Re-materializing content the workspace already accepted. Both the sync
+// sweep and Pack activation restore retained members, and neither feature may
+// import the other.
+export { RetainedContentUnusable } from "./desired-state/errors.js";
+export { collectRetainedMaterializeSteps, } from "./desired-state/retained-materialization.js";
+export { projectionErrorToStepFailure } from "./projection-step-failure.js";
+//# sourceMappingURL=index.js.map

package/dist/src/knowledge/errors.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Typed failure family for the Knowledge manager, discovery, and package
+ * inspection. Fields are domain facts; the application error boundary owns
+ * rendering, codes, and suggestions.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+declare const KnowledgeDefinitionInvalid_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: "KnowledgeDefinitionInvalid";
+} & Readonly<A>;
+/**
+ * A Knowledge bundle source, manifest, or discovery input did not validate.
+ * `detail` carries the site's fact sentence verbatim.
+ */
+export declare class KnowledgeDefinitionInvalid extends KnowledgeDefinitionInvalid_base<{
+    readonly detail: string;
+    readonly cause?: unknown;
+}> {
+}
+declare const KnowledgeIoFailed_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: "KnowledgeIoFailed";
+} & Readonly<A>;
+/** A Knowledge filesystem step failed; `detail` carries the site's fact sentence. */
+export declare class KnowledgeIoFailed extends KnowledgeIoFailed_base<{
+    readonly detail: string;
+    readonly cause: unknown;
+}> {
+}
+declare const KnowledgeInstallStateMissing_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: "KnowledgeInstallStateMissing";
+} & Readonly<A>;
+/** A lock entry was requested before install recorded the package state. */
+export declare class KnowledgeInstallStateMissing extends KnowledgeInstallStateMissing_base<{
+    readonly name: string;
+    readonly kind: "tree-integrity" | "content-identity" | "staged-tree-integrity";
+}> {
+}
+declare const KnowledgeResolutionMissing_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: "KnowledgeResolutionMissing";
+} & Readonly<A>;
+/** An active external Knowledge bundle has no accepted lock resolution. */
+export declare class KnowledgeResolutionMissing extends KnowledgeResolutionMissing_base<{
+    readonly name: string;
+}> {
+}
+declare const KnowledgeDesiredStateUnreconcilable_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: "KnowledgeDesiredStateUnreconcilable";
+} & Readonly<A>;
+/** Knowledge desired state cannot be reconciled from an incomplete graph. */
+export declare class KnowledgeDesiredStateUnreconcilable extends KnowledgeDesiredStateUnreconcilable_base {
+}
+declare const KnowledgeUnavailable_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: "KnowledgeUnavailable";
+} & Readonly<A>;
+/**
+ * Locked Knowledge content cannot be restored from its source. `detail`
+ * carries the site's fact sentence verbatim.
+ */
+export declare class KnowledgeUnavailable extends KnowledgeUnavailable_base<{
+    readonly detail: string;
+    readonly cause?: unknown;
+}> {
+}
+declare const KnowledgeObservableContractViolated_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: "KnowledgeObservableContractViolated";
+} & Readonly<A>;
+/** An installed Knowledge bundle failed its observable postcondition. */
+export declare class KnowledgeObservableContractViolated extends KnowledgeObservableContractViolated_base<{
+    readonly name: string;
+}> {
+}
+/** Every failure the Knowledge module constructs. */
+export type KnowledgeManagerError = KnowledgeDefinitionInvalid | KnowledgeIoFailed | KnowledgeInstallStateMissing | KnowledgeResolutionMissing | KnowledgeDesiredStateUnreconcilable | KnowledgeUnavailable | KnowledgeObservableContractViolated;
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/src/knowledge/errors.js

@@ -0,0 +1,36 @@
+/**
+ * Typed failure family for the Knowledge manager, discovery, and package
+ * inspection. Fields are domain facts; the application error boundary owns
+ * rendering, codes, and suggestions.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Data from "effect/Data";
+/**
+ * A Knowledge bundle source, manifest, or discovery input did not validate.
+ * `detail` carries the site's fact sentence verbatim.
+ */
+export class KnowledgeDefinitionInvalid extends Data.TaggedError("KnowledgeDefinitionInvalid") {
+}
+/** A Knowledge filesystem step failed; `detail` carries the site's fact sentence. */
+export class KnowledgeIoFailed extends Data.TaggedError("KnowledgeIoFailed") {
+}
+/** A lock entry was requested before install recorded the package state. */
+export class KnowledgeInstallStateMissing extends Data.TaggedError("KnowledgeInstallStateMissing") {
+}
+/** An active external Knowledge bundle has no accepted lock resolution. */
+export class KnowledgeResolutionMissing extends Data.TaggedError("KnowledgeResolutionMissing") {
+}
+/** Knowledge desired state cannot be reconciled from an incomplete graph. */
+export class KnowledgeDesiredStateUnreconcilable extends Data.TaggedError("KnowledgeDesiredStateUnreconcilable") {
+}
+/**
+ * Locked Knowledge content cannot be restored from its source. `detail`
+ * carries the site's fact sentence verbatim.
+ */
+export class KnowledgeUnavailable extends Data.TaggedError("KnowledgeUnavailable") {
+}
+/** An installed Knowledge bundle failed its observable postcondition. */
+export class KnowledgeObservableContractViolated extends Data.TaggedError("KnowledgeObservableContractViolated") {
+}
+//# sourceMappingURL=errors.js.map

package/dist/src/knowledge/manager.d.ts

@@ -0,0 +1,9 @@
+/** Lifecycle manager for isolated Open Knowledge Format bundles. */
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
+import { SourceHostProviders, WorkspaceCatalog } from "@agentxm/extension-sources";
+import { KnowledgeManager } from "../managers.js";
+import { WorkspaceMutations } from "@agentxm/workspace-state";
+export declare const KnowledgeManagerLive: Layer.Layer<KnowledgeManager, never, FileSystem.FileSystem | Path.Path | WorkspaceMutations | SourceHostProviders | WorkspaceCatalog>;
+//# sourceMappingURL=manager.d.ts.map