@agentxm/client-core 0.15.1 → 0.16.1

package/dist/src/unstable/agent-capabilities/schema.js

@@ -4,9 +4,8 @@
  * @experimental This API is unstable and may change without notice.
  */
 import * as Schema from "effect/Schema";
-import * as SchemaTransformation from "effect/SchemaTransformation";
 import { ExtensionTypeSchema } from "../extensions/common.js";
-import { DocLinkSchema, UrlSchema } from "../extension-types/schema.js";
+import { DocLinkSchema, LeafExtensionTypeSchema, UrlSchema, } from "../extension-types/schema.js";
 export { DocLinkSchema, LEAF_EXTENSION_TYPES, StandardSchema, UrlSchema, } from "../extension-types/schema.js";
 const AGENT_ID_PATTERN = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
 const ISO_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
@@ -39,41 +38,144 @@ export const ConventionSchema = Schema.Literals(["universal", "vendor"]).annotat
     examples: ["universal", "vendor"],
 });
 /** @experimental This API is unstable and may change without notice. */
-export const SUPPORTED_LIFECYCLE = "supported";
+export const ScopeSchema = Schema.Literals(["user", "project"]).annotate({
+    identifier: "Scope",
+    title: "Scope",
+    description: "Where a capability can be configured.",
+    examples: ["user", "project"],
+});
+const NonEmptyScopesSchema = Schema.NonEmptyArray(ScopeSchema).pipe(Schema.check(Schema.isUnique()));
+/** @experimental This API is unstable and may change without notice. */
+export const SUPPORTED_AXM_SUPPORT = "supported";
 /** @experimental This API is unstable and may change without notice. */
-export const CapabilityLifecycleSchema = Schema.Literals([
-    SUPPORTED_LIFECYCLE,
+export const AxmSupportSchema = Schema.Literals([
+    SUPPORTED_AXM_SUPPORT,
     "planned",
     "unsupported",
     "unknown",
 ]).annotate({
-    identifier: "CapabilityLifecycle",
-    title: "Capability Lifecycle",
-    description: "State of AXM's integration with an agent capability.",
-    examples: [SUPPORTED_LIFECYCLE, "unsupported", "unknown"],
+    identifier: "AxmSupport",
+    title: "AXM Support",
+    description: "AXM install behavior and verification state for an agent capability.",
+    examples: [SUPPORTED_AXM_SUPPORT, "unsupported", "unknown"],
 });
 /** @experimental This API is unstable and may change without notice. */
-export const ActiveLifecycleSchema = Schema.Literals([SUPPORTED_LIFECYCLE, "planned"]).annotate({
-    identifier: "ActiveLifecycle",
-    title: "Active Lifecycle",
-    description: "Capability lifecycle values that carry a concrete capability claim.",
-    examples: [SUPPORTED_LIFECYCLE, "planned"],
+export const ActiveAxmSupportSchema = Schema.Literals([SUPPORTED_AXM_SUPPORT, "planned"]).annotate({
+    identifier: "ActiveAxmSupport",
+    title: "Active AXM Support",
+    description: "AXM support values that carry a concrete managed capability claim.",
+    examples: [SUPPORTED_AXM_SUPPORT, "planned"],
 });
 /** @experimental This API is unstable and may change without notice. */
-export const InactiveLifecycleSchema = Schema.Literals(["unsupported", "unknown"]).annotate({
-    identifier: "InactiveLifecycle",
-    title: "Inactive Lifecycle",
-    description: "Capability lifecycle values without active extension support.",
+export const InactiveAxmSupportSchema = Schema.Literals(["unsupported", "unknown"]).annotate({
+    identifier: "InactiveAxmSupport",
+    title: "Inactive AXM Support",
+    description: "AXM support values without an active managed extension writer.",
     examples: ["unsupported", "unknown"],
 });
 /** @experimental This API is unstable and may change without notice. */
-export const ScopeSchema = Schema.Literals(["user", "project"]).annotate({
-    identifier: "Scope",
-    title: "Scope",
-    description: "Where a capability can be configured.",
-    examples: ["user", "project"],
+export const PluginDistributionMechanismSchema = Schema.Literals([
+    "agent-native",
+    "npm",
+    "git",
+    "manual",
+]).annotate({
+    identifier: "PluginDistributionMechanism",
+    title: "Plugin Distribution Mechanism",
+    description: "How an agent-vendor plugin is distributed outside AXM.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const PluginDistributionSchema = Schema.Struct({
+    mechanism: PluginDistributionMechanismSchema,
+    installHint: Schema.NullOr(Schema.NonEmptyString),
+    packageRef: Schema.NullOr(Schema.NonEmptyString),
+}).annotate({
+    identifier: "PluginDistribution",
+    title: "Plugin Distribution",
+    description: "Descriptive install metadata that AXM may display but never executes.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const PluginDetectionPathSchema = Schema.Struct({
+    scope: ScopeSchema,
+    path: Schema.NonEmptyString,
+    kind: Schema.Literals(["dir", "file"]),
+}).annotate({
+    identifier: "PluginDetectionPath",
+    title: "Plugin Detection Path",
+    description: "Future scan marker for detecting an installed agent-vendor plugin.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const PluginDetectionConfigKeySchema = Schema.Struct({
+    scope: ScopeSchema,
+    file: Schema.NonEmptyString,
+    key: Schema.NonEmptyString,
+}).annotate({
+    identifier: "PluginDetectionConfigKey",
+    title: "Plugin Detection Config Key",
+    description: "Future config-key marker for detecting an installed agent-vendor plugin.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const PluginDetectionSchema = Schema.Struct({
+    paths: Schema.Array(PluginDetectionPathSchema),
+    configKeys: Schema.Array(PluginDetectionConfigKeySchema),
+}).annotate({
+    identifier: "PluginDetection",
+    title: "Plugin Detection",
+    description: "Descriptive plugin detection markers reserved for future workspace scans.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const PluginDescriptorSchema = Schema.Struct({
+    name: Schema.NonEmptyString,
+    homepage: UrlSchema,
+    author: Schema.NullOr(Schema.NonEmptyString),
+    distribution: PluginDistributionSchema,
+    detection: Schema.NullOr(PluginDetectionSchema),
+}).annotate({
+    identifier: "PluginDescriptor",
+    title: "Plugin Descriptor",
+    description: "Descriptive metadata for third-party or vendor plugins outside AXM management.",
+});
+/** @experimental This API is unstable and may change without notice. */
+const NativeAvailabilitySchema = Schema.Struct({ via: Schema.Literal("native") });
+const NoneAvailabilitySchema = Schema.Struct({ via: Schema.Literal("none") });
+const PluginAvailabilitySchema = Schema.Struct({
+    via: Schema.Literal("plugin"),
+    provider: Schema.Literals(["first-party", "third-party"]),
+    plugin: PluginDescriptorSchema,
+});
+const AvailableCapabilityAvailabilitySchema = Schema.Union([
+    NativeAvailabilitySchema,
+    PluginAvailabilitySchema,
+]);
+/** @experimental This API is unstable and may change without notice. */
+export const AvailabilitySchema = Schema.Union([
+    NativeAvailabilitySchema,
+    NoneAvailabilitySchema,
+    PluginAvailabilitySchema,
+]).annotate({
+    identifier: "Availability",
+    title: "Availability",
+    description: "Whether the agent capability surface is obtainable natively, via plugin, or not.",
+});
+const VendorStatusSinceSchema = Schema.NonEmptyString.pipe(Schema.check(Schema.isPattern(ISO_DATE_PATTERN, {
+    message: "Expected an ISO 8601 date in YYYY-MM-DD form.",
+})));
+const InactiveVendorStatusFields = {
+    since: Schema.NullOr(VendorStatusSinceSchema),
+    note: Schema.NullOr(Schema.NonEmptyString),
+    supersededByType: Schema.NullOr(LeafExtensionTypeSchema),
+};
+/** @experimental This API is unstable and may change without notice. */
+export const VendorStatusSchema = Schema.Union([
+    Schema.Struct({ state: Schema.Literal("active") }),
+    Schema.Struct({ state: Schema.Literal("maintenance"), ...InactiveVendorStatusFields }),
+    Schema.Struct({ state: Schema.Literal("deprecated"), ...InactiveVendorStatusFields }),
+    Schema.Struct({ state: Schema.Literal("removed"), ...InactiveVendorStatusFields }),
+]).annotate({
+    identifier: "VendorStatus",
+    title: "Vendor Status",
+    description: "Vendor or plugin health for the surface named by availability.",
 });
-const NonEmptyScopesSchema = Schema.NonEmptyArray(ScopeSchema).pipe(Schema.check(Schema.isUnique()));
 /** @experimental This API is unstable and may change without notice. */
 export const AgentInterfaceSchema = Schema.Literals(["cli", "ide-extension"]).annotate({
     identifier: "AgentInterface",
@@ -89,10 +191,6 @@ export const McpTransportSchema = Schema.Literals(["stdio", "http", "sse"]).anno
     examples: ["stdio", "http", "sse"],
 });
 const NonEmptyMcpTransportsSchema = Schema.NonEmptyArray(McpTransportSchema).pipe(Schema.check(Schema.isUnique()));
-const LegacyDetectionSchema = Schema.Struct({
-    projectDirs: Schema.Array(Schema.NonEmptyString).pipe(Schema.check(Schema.isUnique())),
-    userDirs: Schema.Array(Schema.NonEmptyString).pipe(Schema.check(Schema.isUnique())),
-});
 /** @experimental This API is unstable and may change without notice. */
 export const DetectionSignalSchema = Schema.Literals([
     "definitive",
@@ -148,26 +246,12 @@ export const ScopeDetectionSchema = Schema.Struct({
     title: "Scope Detection",
     description: "Detection markers for one configuration scope.",
 });
-const CurrentDetectionSchema = Schema.Struct({
+const DetectionStruct = Schema.Struct({
     project: ScopeDetectionSchema,
     user: ScopeDetectionSchema,
 });
-const markerFromLegacyDir = (path) => ({
-    kind: "dir",
-    path,
-    signal: "definitive",
-    note: null,
-});
 /** @experimental This API is unstable and may change without notice. */
-export const DetectionSchema = Schema.Union([CurrentDetectionSchema, LegacyDetectionSchema]).pipe(Schema.decodeTo(Schema.toType(CurrentDetectionSchema), SchemaTransformation.transform({
-    decode: (detection) => "projectDirs" in detection
-        ? {
-            project: { markers: detection.projectDirs.map(markerFromLegacyDir) },
-            user: { markers: detection.userDirs.map(markerFromLegacyDir) },
-        }
-        : detection,
-    encode: (detection) => detection,
-})), Schema.annotate({
+export const DetectionSchema = DetectionStruct.pipe(Schema.annotate({
     identifier: "Detection",
     title: "Detection",
     description: "Per-scope signals (marker dirs, files, CLI binaries) used to detect an installed agent.",
@@ -183,69 +267,90 @@ export const LastVerifiedDateSchema = Schema.NonEmptyString.pipe(Schema.check(Sc
 });
 const CapabilityNotesSchema = Schema.NullOr(Schema.NonEmptyString);
 const CapabilityDocsSchema = Schema.Array(DocLinkSchema);
-const ActiveSourcesSchema = Schema.NonEmptyArray(UrlSchema);
-const InactiveSourcesSchema = Schema.Array(UrlSchema);
-const InactiveCapabilitySchema = Schema.Struct({
-    lifecycle: InactiveLifecycleSchema,
+const CapabilitySourcesSchema = Schema.Array(UrlSchema);
+const UnavailableCanonicalCapabilityFields = {
+    availability: NoneAvailabilitySchema,
+    vendorStatus: VendorStatusSchema,
     notes: CapabilityNotesSchema,
     docs: CapabilityDocsSchema,
-    sources: InactiveSourcesSchema,
-}).annotate({
-    identifier: "InactiveCapability",
-    title: "Inactive Capability",
-    description: "Capability slot with no active extension support.",
-});
-const ActiveCapabilityBaseFields = {
-    lifecycle: ActiveLifecycleSchema,
+    sources: CapabilitySourcesSchema,
+};
+const AvailableCanonicalCapabilityBaseFields = {
+    availability: AvailableCapabilityAvailabilitySchema,
+    vendorStatus: VendorStatusSchema,
     notes: CapabilityNotesSchema,
     docs: CapabilityDocsSchema,
-    sources: ActiveSourcesSchema,
-    lastVerified: LastVerifiedDateSchema,
+    sources: CapabilitySourcesSchema,
     scopes: NonEmptyScopesSchema,
 };
 const SpecTrackedCapabilityFields = {
     standardsCompliance: StandardsComplianceSchema,
     convention: ConventionSchema,
 };
-/** @experimental This API is unstable and may change without notice. */
-export const CapabilityBaseSchema = Schema.Union([
-    Schema.Struct(ActiveCapabilityBaseFields),
-    InactiveCapabilitySchema,
-]).annotate({
-    identifier: "CapabilityBase",
-    title: "Capability Base",
-    description: "Fields shared by all agent capabilities.",
-});
-/** @experimental This API is unstable and may change without notice. */
-export const ScopedCapabilityBaseSchema = Schema.Struct(ActiveCapabilityBaseFields).annotate({
-    identifier: "ScopedCapabilityBase",
-    title: "Scoped Capability Base",
-    description: "Capability fields shared by extension-backed active capabilities.",
-});
-const ActiveSpecTrackedCapabilityFields = {
-    ...ActiveCapabilityBaseFields,
+const AvailableSpecTrackedCanonicalCapabilityFields = {
+    ...AvailableCanonicalCapabilityBaseFields,
     ...SpecTrackedCapabilityFields,
 };
-/** @experimental This API is unstable and may change without notice. */
-export const SkillsExtensionCapabilitySchema = Schema.Union([
+const NoWriterAxmCapabilityStateSchema = Schema.Union([
+    Schema.Struct({
+        support: ActiveAxmSupportSchema,
+        lastVerified: LastVerifiedDateSchema,
+        writer: Schema.Null,
+    }),
     Schema.Struct({
-        ...ActiveSpecTrackedCapabilityFields,
-        directory: Schema.NonEmptyString,
+        support: InactiveAxmSupportSchema,
+        writer: Schema.Null,
     }),
-    InactiveCapabilitySchema,
+]);
+const requireSourcesForActiveAxmSupport = (capability) => {
+    if ((capability.axm.support === SUPPORTED_AXM_SUPPORT || capability.axm.support === "planned") &&
+        capability.canonical.sources.length === 0) {
+        return {
+            path: ["canonical", "sources"],
+            issue: "Active AXM support claims require at least one canonical source.",
+        };
+    }
+    return undefined;
+};
+/** @experimental This API is unstable and may change without notice. */
+export const CanonicalCapabilityBaseSchema = Schema.Union([
+    Schema.Struct(AvailableCanonicalCapabilityBaseFields),
+    Schema.Struct(UnavailableCanonicalCapabilityFields),
 ]).annotate({
+    identifier: "CanonicalCapabilityBase",
+    title: "Canonical Capability Base",
+    description: "Vendor-sourced fields shared by all agent capabilities.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const SkillsExtensionCapabilitySchema = Schema.Struct({
+    canonical: Schema.Union([
+        Schema.Struct({
+            ...AvailableSpecTrackedCanonicalCapabilityFields,
+            directory: Schema.NonEmptyString,
+        }),
+        Schema.Struct(UnavailableCanonicalCapabilityFields),
+    ]),
+    axm: NoWriterAxmCapabilityStateSchema,
+})
+    .pipe(Schema.check(Schema.makeFilter(requireSourcesForActiveAxmSupport)))
+    .annotate({
     identifier: "SkillsExtensionCapability",
     title: "Skills Capability",
     description: "Agent support for Agent Skills-style extensions.",
 });
 /** @experimental This API is unstable and may change without notice. */
-export const CommandsExtensionCapabilitySchema = Schema.Union([
-    Schema.Struct({
-        ...ActiveCapabilityBaseFields,
-        directory: Schema.NonEmptyString,
-    }),
-    InactiveCapabilitySchema,
-]).annotate({
+export const CommandsExtensionCapabilitySchema = Schema.Struct({
+    canonical: Schema.Union([
+        Schema.Struct({
+            ...AvailableCanonicalCapabilityBaseFields,
+            directory: Schema.NonEmptyString,
+        }),
+        Schema.Struct(UnavailableCanonicalCapabilityFields),
+    ]),
+    axm: NoWriterAxmCapabilityStateSchema,
+})
+    .pipe(Schema.check(Schema.makeFilter(requireSourcesForActiveAxmSupport)))
+    .annotate({
     identifier: "CommandsExtensionCapability",
     title: "Commands Capability",
     description: "Agent support for command extensions.",
@@ -257,15 +362,26 @@ export const SubagentsLayoutSchema = Schema.Literals(["file", "directory"]).anno
     description: "Whether subagents live in a directory or a single opaque file path.",
     examples: ["directory", "file"],
 });
-/** @experimental This API is unstable and may change without notice. */
-export const SubagentsExtensionCapabilitySchema = Schema.Union([
-    Schema.Struct({
-        ...ActiveCapabilityBaseFields,
-        directory: Schema.NonEmptyString,
-        layout: SubagentsLayoutSchema,
-    }),
-    InactiveCapabilitySchema,
-]).annotate({
+const PluginSubagentsCanonicalCapabilitySchema = Schema.Struct({
+    ...AvailableCanonicalCapabilityBaseFields,
+    availability: PluginAvailabilitySchema,
+});
+/** @experimental This API is unstable and may change without notice. */
+export const SubagentsExtensionCapabilitySchema = Schema.Struct({
+    canonical: Schema.Union([
+        Schema.Struct({
+            ...AvailableCanonicalCapabilityBaseFields,
+            availability: NativeAvailabilitySchema,
+            directory: Schema.NonEmptyString,
+            layout: SubagentsLayoutSchema,
+        }),
+        PluginSubagentsCanonicalCapabilitySchema,
+        Schema.Struct(UnavailableCanonicalCapabilityFields),
+    ]),
+    axm: NoWriterAxmCapabilityStateSchema,
+})
+    .pipe(Schema.check(Schema.makeFilter(requireSourcesForActiveAxmSupport)))
+    .annotate({
     identifier: "SubagentsExtensionCapability",
     title: "Subagents Capability",
     description: "Agent support for subagent extensions.",
@@ -292,7 +408,7 @@ const OptionalRuleDirectoryField = {
     directory: Schema.optionalKey(Schema.NonEmptyString),
 };
 const AgentsMdRulesExtensionCapabilitySchema = Schema.Struct({
-    ...ActiveSpecTrackedCapabilityFields,
+    ...AvailableSpecTrackedCanonicalCapabilityFields,
     ...OptionalRuleDirectoryField,
     kind: Schema.Literal("agents-md"),
     files: Schema.Tuple([Schema.Literal("AGENTS.md")]),
@@ -300,7 +416,7 @@ const AgentsMdRulesExtensionCapabilitySchema = Schema.Struct({
     importSyntax: Schema.NullOr(RuleInstructionsImportSyntaxSchema),
 });
 const OwnFileRulesExtensionCapabilitySchema = Schema.Struct({
-    ...ActiveSpecTrackedCapabilityFields,
+    ...AvailableSpecTrackedCanonicalCapabilityFields,
     ...OptionalRuleDirectoryField,
     kind: Schema.Literal("own-file"),
     files: Schema.Tuple([Schema.NonEmptyString]),
@@ -308,7 +424,7 @@ const OwnFileRulesExtensionCapabilitySchema = Schema.Struct({
     importSyntax: Schema.NullOr(RuleInstructionsImportSyntaxSchema),
 });
 const RulesDirRulesExtensionCapabilitySchema = Schema.Struct({
-    ...ActiveSpecTrackedCapabilityFields,
+    ...AvailableSpecTrackedCanonicalCapabilityFields,
     kind: Schema.Literal("rules-dir"),
     files: Schema.Array(Schema.NonEmptyString).pipe(Schema.check(Schema.isUnique())),
     nestedDiscovery: Schema.Boolean,
@@ -316,26 +432,36 @@ const RulesDirRulesExtensionCapabilitySchema = Schema.Struct({
     directory: Schema.NonEmptyString,
 });
 /** @experimental This API is unstable and may change without notice. */
-export const RulesExtensionCapabilitySchema = Schema.Union([
-    AgentsMdRulesExtensionCapabilitySchema,
-    OwnFileRulesExtensionCapabilitySchema,
-    RulesDirRulesExtensionCapabilitySchema,
-    InactiveCapabilitySchema,
-]).annotate({
+export const RulesExtensionCapabilitySchema = Schema.Struct({
+    canonical: Schema.Union([
+        AgentsMdRulesExtensionCapabilitySchema,
+        OwnFileRulesExtensionCapabilitySchema,
+        RulesDirRulesExtensionCapabilitySchema,
+        Schema.Struct(UnavailableCanonicalCapabilityFields),
+    ]),
+    axm: NoWriterAxmCapabilityStateSchema,
+})
+    .pipe(Schema.check(Schema.makeFilter(requireSourcesForActiveAxmSupport)))
+    .annotate({
     identifier: "RulesExtensionCapability",
     title: "Rules Capability",
     description: "Agent support for behavior-governing instruction files and rule extensions.",
 });
 /** @experimental This API is unstable and may change without notice. */
-export const FilesExtensionCapabilitySchema = Schema.Union([
-    Schema.Struct({
-        ...ActiveCapabilityBaseFields,
-        directory: Schema.NonEmptyString,
-        files: Schema.Array(Schema.NonEmptyString).pipe(Schema.check(Schema.isUnique())),
-        naming: Schema.NullOr(Schema.NonEmptyString),
-    }),
-    InactiveCapabilitySchema,
-]).annotate({
+export const FilesExtensionCapabilitySchema = Schema.Struct({
+    canonical: Schema.Union([
+        Schema.Struct({
+            ...AvailableCanonicalCapabilityBaseFields,
+            directory: Schema.NonEmptyString,
+            files: Schema.Array(Schema.NonEmptyString).pipe(Schema.check(Schema.isUnique())),
+            naming: Schema.NullOr(Schema.NonEmptyString),
+        }),
+        Schema.Struct(UnavailableCanonicalCapabilityFields),
+    ]),
+    axm: NoWriterAxmCapabilityStateSchema,
+})
+    .pipe(Schema.check(Schema.makeFilter(requireSourcesForActiveAxmSupport)))
+    .annotate({
     identifier: "FilesExtensionCapability",
     title: "Files Capability",
     description: "Agent support for standalone context-file scaffolding.",
@@ -445,37 +571,70 @@ export const McpEnvExpansionSchema = Schema.Struct({
     title: "MCP Env Expansion",
     description: "Whether an agent expands MCP config environment references.",
 });
-const McpActiveCapabilityStruct = Schema.Struct({
-    ...ActiveSpecTrackedCapabilityFields,
+const McpUnavailableCapabilityStruct = Schema.Struct({
+    canonical: Schema.Struct(UnavailableCanonicalCapabilityFields),
+    axm: Schema.Union([
+        Schema.Struct({
+            support: ActiveAxmSupportSchema,
+            lastVerified: LastVerifiedDateSchema,
+            writer: Schema.NullOr(Schema.Struct({ config: McpConfigSchema })),
+        }),
+        Schema.Struct({
+            support: InactiveAxmSupportSchema,
+            writer: Schema.NullOr(Schema.Struct({ config: McpConfigSchema })),
+        }),
+    ]),
+});
+const McpCanonicalWithTransportsSchema = Schema.Struct({
+    ...AvailableSpecTrackedCanonicalCapabilityFields,
     transports: NonEmptyMcpTransportsSchema,
-    config: Schema.optionalKey(McpConfigSchema),
     mcpEnvExpansion: Schema.optionalKey(McpEnvExpansionSchema),
 });
-const McpActiveCapabilitySchema = McpActiveCapabilityStruct.pipe(Schema.check(Schema.makeFilter((capability) => {
+const McpAvailableCapabilityStruct = Schema.Struct({
+    canonical: McpCanonicalWithTransportsSchema,
+    axm: Schema.Union([
+        Schema.Struct({
+            support: ActiveAxmSupportSchema,
+            lastVerified: LastVerifiedDateSchema,
+            writer: Schema.NullOr(Schema.Struct({ config: McpConfigSchema })),
+        }),
+        Schema.Struct({
+            support: InactiveAxmSupportSchema,
+            writer: Schema.NullOr(Schema.Struct({ config: McpConfigSchema })),
+        }),
+    ]),
+});
+const McpExtensionCapabilityStruct = Schema.Union([
+    McpAvailableCapabilityStruct,
+    McpUnavailableCapabilityStruct,
+]);
+const McpExtensionCapabilitySchemaWithChecks = McpExtensionCapabilityStruct.pipe(Schema.check(Schema.makeFilter((capability) => {
     const issues = [];
-    const config = capability.config;
-    if (config === undefined)
+    const activeSourcesIssue = requireSourcesForActiveAxmSupport(capability);
+    if (activeSourcesIssue !== undefined)
+        issues.push(activeSourcesIssue);
+    const writer = capability.axm.writer;
+    if (writer === null || !("transports" in capability.canonical))
         return issues;
-    if (capability.transports.includes("stdio") && config.stdio === null) {
+    const config = writer.config;
+    if (capability.canonical.transports.includes("stdio") && config.stdio === null) {
         issues.push({
-            path: ["config", "stdio"],
+            path: ["axm", "writer", "config", "stdio"],
             issue: "MCP stdio config is required when stdio transport is supported.",
         });
     }
-    if ((capability.transports.includes("http") || capability.transports.includes("sse")) &&
+    if ((capability.canonical.transports.includes("http") ||
+        capability.canonical.transports.includes("sse")) &&
         config.remote === null) {
         issues.push({
-            path: ["config", "remote"],
+            path: ["axm", "writer", "config", "remote"],
             issue: "MCP remote config is required when http or sse transport is supported.",
         });
     }
     return issues;
 })));
 /** @experimental This API is unstable and may change without notice. */
-export const McpExtensionCapabilitySchema = Schema.Union([
-    McpActiveCapabilitySchema,
-    InactiveCapabilitySchema,
-]).annotate({
+export const McpExtensionCapabilitySchema = McpExtensionCapabilitySchemaWithChecks.annotate({
     identifier: "McpExtensionCapability",
     title: "MCP Capability",
     description: "Agent support for MCP server extensions.",
@@ -524,14 +683,28 @@ export const HooksSerializerSchema = Schema.Literals(["claude-code-settings"]).a
     examples: ["claude-code-settings"],
 });
 /** @experimental This API is unstable and may change without notice. */
-export const HooksExtensionCapabilitySchema = Schema.Union([
-    Schema.Struct({
-        ...ActiveCapabilityBaseFields,
-        configFiles: Schema.Array(ConfigFileLocationSchema),
-        serializer: HooksSerializerSchema,
-    }),
-    InactiveCapabilitySchema,
-]).annotate({
+export const HooksExtensionCapabilitySchema = Schema.Struct({
+    canonical: Schema.Union([
+        Schema.Struct({
+            ...AvailableCanonicalCapabilityBaseFields,
+            configFiles: Schema.Array(ConfigFileLocationSchema),
+        }),
+        Schema.Struct(UnavailableCanonicalCapabilityFields),
+    ]),
+    axm: Schema.Union([
+        Schema.Struct({
+            support: ActiveAxmSupportSchema,
+            lastVerified: LastVerifiedDateSchema,
+            writer: Schema.NullOr(Schema.Struct({ serializer: HooksSerializerSchema })),
+        }),
+        Schema.Struct({
+            support: InactiveAxmSupportSchema,
+            writer: Schema.NullOr(Schema.Struct({ serializer: HooksSerializerSchema })),
+        }),
+    ]),
+})
+    .pipe(Schema.check(Schema.makeFilter(requireSourcesForActiveAxmSupport)))
+    .annotate({
     identifier: "HooksExtensionCapability",
     title: "Hooks Capability",
     description: "Agent support for lifecycle hook extensions.",
@@ -580,18 +753,32 @@ export const PermissionGrantSchema = PermissionGrantStruct.pipe(Schema.check(Sch
     description: "Instruction to grant access for a named tool. Provide patch (JSON-ish merge) or template (raw text). Path and patch may interpolate ${tool} and ${workspaceRoot}.",
 });
 /** @experimental This API is unstable and may change without notice. */
-export const PermissionsExtensionCapabilitySchema = Schema.Union([
-    Schema.Struct({
-        ...ActiveCapabilityBaseFields,
-        mechanism: NonEmptyPermissionMechanismsSchema,
-        configFiles: Schema.Array(ConfigFileLocationSchema),
-        grammar: Schema.NullOr(PermissionGrammarSchema),
-        prerequisites: Schema.Array(PermissionPrerequisiteSchema),
-        cliFlags: Schema.Array(PermissionCliFlagSchema),
-        grants: Schema.Record(Schema.String, PermissionGrantSchema),
-    }),
-    InactiveCapabilitySchema,
-]).annotate({
+export const PermissionsExtensionCapabilitySchema = Schema.Struct({
+    canonical: Schema.Union([
+        Schema.Struct({
+            ...AvailableCanonicalCapabilityBaseFields,
+            mechanism: NonEmptyPermissionMechanismsSchema,
+            configFiles: Schema.Array(ConfigFileLocationSchema),
+            grammar: Schema.NullOr(PermissionGrammarSchema),
+            prerequisites: Schema.Array(PermissionPrerequisiteSchema),
+            cliFlags: Schema.Array(PermissionCliFlagSchema),
+        }),
+        Schema.Struct(UnavailableCanonicalCapabilityFields),
+    ]),
+    axm: Schema.Union([
+        Schema.Struct({
+            support: ActiveAxmSupportSchema,
+            lastVerified: LastVerifiedDateSchema,
+            writer: Schema.NullOr(Schema.Struct({ grants: Schema.Record(Schema.String, PermissionGrantSchema) })),
+        }),
+        Schema.Struct({
+            support: InactiveAxmSupportSchema,
+            writer: Schema.NullOr(Schema.Struct({ grants: Schema.Record(Schema.String, PermissionGrantSchema) })),
+        }),
+    ]),
+})
+    .pipe(Schema.check(Schema.makeFilter(requireSourcesForActiveAxmSupport)))
+    .annotate({
     identifier: "PermissionsExtensionCapability",
     title: "Permissions Capability",
     description: "How an agent grants tool execution and filesystem access without per-call prompts.",
@@ -611,6 +798,44 @@ export const AgentCapabilitiesSchema = Schema.Struct(LeafCapabilitySchemaByType)
     title: "Agent Capabilities",
     description: "Agent extension capabilities keyed by leaf extension type.",
 });
+/** @experimental This API is unstable and may change without notice. */
+export const AgentLifecycleStateSchema = Schema.Literals([
+    "active",
+    "deprecated",
+    "retired",
+]).annotate({
+    identifier: "AgentLifecycleState",
+    title: "Agent Lifecycle State",
+    description: "Support status of the coding agent product itself. Distinct from AxmSupport, which tracks AXM's integration with a single capability.",
+    examples: ["active", "deprecated", "retired"],
+});
+const AgentLifecycleSinceSchema = Schema.NonEmptyString.pipe(Schema.check(Schema.isPattern(ISO_DATE_PATTERN, {
+    message: "Expected an ISO 8601 date in YYYY-MM-DD form.",
+}))).annotate({
+    identifier: "AgentLifecycleSince",
+    title: "Agent Lifecycle Since",
+    description: "Date an agent entered its current lifecycle state.",
+    examples: ["2025-11-01"],
+});
+// Loose kebab id rather than the closed AgentIdSchema: that schema lives in
+// catalog.ts (which imports this module), so referencing it here would be a
+// cycle. Referential integrity (target exists, not self, no cycles) is enforced
+// by the catalog invariant test.
+const InactiveAgentLifecycleFields = {
+    since: Schema.NullOr(AgentLifecycleSinceSchema),
+    note: Schema.NullOr(Schema.NonEmptyString),
+    supersededBy: Schema.NullOr(AgentIdFromYamlSchema),
+};
+/** @experimental This API is unstable and may change without notice. */
+export const AgentLifecycleSchema = Schema.Union([
+    Schema.Struct({ state: Schema.Literal("active") }),
+    Schema.Struct({ state: Schema.Literal("deprecated"), ...InactiveAgentLifecycleFields }),
+    Schema.Struct({ state: Schema.Literal("retired"), ...InactiveAgentLifecycleFields }),
+]).annotate({
+    identifier: "AgentLifecycle",
+    title: "Agent Lifecycle",
+    description: "Whether a catalog agent is active, deprecated, or retired, and which agent supersedes it.",
+});
 const AgentStruct = Schema.Struct({
     id: AgentIdFromYamlSchema,
     name: Schema.NonEmptyString,
@@ -619,6 +844,7 @@ const AgentStruct = Schema.Struct({
     interfaces: Schema.NonEmptyArray(AgentInterfaceSchema).pipe(Schema.check(Schema.isUnique())),
     family: Schema.NullOr(Schema.NonEmptyString),
     rootDir: Schema.NullOr(Schema.NonEmptyString),
+    lifecycle: AgentLifecycleSchema,
     detection: DetectionSchema,
     docs: Schema.Array(DocLinkSchema),
     capabilities: AgentCapabilitiesSchema,
@@ -626,11 +852,11 @@ const AgentStruct = Schema.Struct({
 });
 /** @experimental This API is unstable and may change without notice. */
 export const AgentSchema = AgentStruct.pipe(Schema.check(Schema.makeFilter((agent) => {
-    if ("kind" in agent.capabilities.rule &&
-        agent.capabilities.rule.kind === "agents-md" &&
-        agent.capabilities.rule.files[0] !== "AGENTS.md") {
+    if ("kind" in agent.capabilities.rule.canonical &&
+        agent.capabilities.rule.canonical.kind === "agents-md" &&
+        agent.capabilities.rule.canonical.files[0] !== "AGENTS.md") {
         return {
-            path: ["capabilities", "rule", "files"],
+            path: ["capabilities", "rule", "canonical", "files"],
             issue: 'capabilities.rule.kind "agents-md" requires AGENTS.md.',
         };
     }