@agentxm/extension-model 0.28.4-bootstrap.0

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

@@ -0,0 +1,1218 @@
+/**
+ * Agent capability catalog schemas.
+ *
+ * Sourcing namespaces:
+ *
+ * - `native` is the vendor-authoritative fact layer: whether the agent exposes
+ *   the surface, which standard or convention it follows, where config lives,
+ *   and the source URLs used to verify that claim.
+ * - `axm` is AXM integration state: whether AXM has modeled support, whether a
+ *   writer exists, the writer metadata needed by AXM, and AXM-owned backlog or
+ *   unsupported reasons. These fields are not vendor facts.
+ * - `canonical` is a derived, vendor-neutral vocabulary. Hook event/tool
+ *   mappings store canonical IDs beside native names, but the catalog does not
+ *   store a per-agent canonical capability block.
+ *
+ * Status axes:
+ *
+ * - `AgentLifecycle` describes the coding agent product itself.
+ * - `VendorStatus` describes the vendor or plugin surface named by
+ *   `Availability`.
+ * - `Availability` describes whether the surface is native, plugin-backed, or
+ *   absent.
+ * - AXM support/writer state lives under `axm.status` and `axm.writer`;
+ *   `axm.writer !== null` means AXM has verified write mechanics for that
+ *   capability.
+ *
+ * `capabilities` is keyed on the placement axis: exactly the extension types
+ * `EXTENSION_TYPE_TABLE` marks `placement: "per-agent"`, because only those
+ * render into a directory the agent owns. Two sibling fields sit beside it
+ * rather than inside it:
+ *
+ * - `instructions` carries the `rule` capability. Rules are `placement:
+ *   "workspace"` — they live in shared instruction files that every configured
+ *   agent reads — so the catalog records how each agent consumes that shared
+ *   file, not an agent-owned slot. The field name is the type's
+ *   `workspaceCapability` axis value.
+ * - `permissions` models AXM grant/write mechanics for an agent's permission
+ *   system. It is not a publishable extension type at all.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { DocLinkSchema, LeafExtensionTypeSchema, UrlSchema, } from "../extension-types/schema.js";
+import {} from "../extensions/common.js";
+export { DocLinkSchema, LEAF_EXTENSION_TYPES, StandardSchema, UrlSchema, } from "../extension-types/schema.js";
+export {} from "../extensions/common.js";
+const AGENT_ID_PATTERN = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+const ISO_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+/** @experimental This API is unstable and may change without notice. */
+export const AgentIdFromYamlSchema = Schema.NonEmptyString.pipe(Schema.check(Schema.isPattern(AGENT_ID_PATTERN, {
+    message: "Expected a lowercase kebab-case agent id.",
+}))).annotate({
+    identifier: "AgentId",
+    title: "Agent ID",
+    description: "Lowercase kebab-case coding agent identifier.",
+    examples: ["claude-code", "codex", "cursor"],
+});
+/** @experimental This API is unstable and may change without notice. */
+export const StandardsComplianceSchema = Schema.Literals([
+    "full",
+    "parity",
+    "partial",
+    "none",
+]).annotate({
+    identifier: "StandardsCompliance",
+    title: "Standards Compliance",
+    description: "How well a spec-tracked capability's native format matches the named spec.",
+    examples: ["full", "parity", "partial"],
+});
+/** @experimental This API is unstable and may change without notice. */
+export const ConventionSchema = Schema.Literals(["universal", "vendor", "hosted"]).annotate({
+    identifier: "Convention",
+    title: "Convention",
+    description: "Whether a spec-tracked capability uses a standard, vendor-specific, or hosted location.",
+    examples: ["universal", "vendor", "hosted"],
+});
+/** @experimental This API is unstable and may change without notice. */
+export const SkillReadPathStatusSchema = Schema.Literals([
+    "canonical",
+    "compat",
+    "deprecated",
+]).annotate({
+    identifier: "SkillReadPathStatus",
+    title: "Skill Read Path Status",
+    description: "How an additional native Skill directory relates to the agent's primary path.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const SkillReadPathSchema = Schema.Struct({
+    path: Schema.NonEmptyString,
+    status: SkillReadPathStatusSchema,
+}).annotate({
+    identifier: "SkillReadPath",
+    title: "Skill Read Path",
+    description: "An additional directory an agent reads for Skill discovery but AXM never writes.",
+});
+/** @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"],
+});
+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 AxmSupportSchema = Schema.Literals([
+    SUPPORTED_AXM_SUPPORT,
+    "planned",
+    "unsupported",
+    "unknown",
+]).annotate({
+    identifier: "AxmSupport",
+    title: "AXM Support",
+    description: "AXM-owned integration status for an agent capability. This is not a vendor fact.",
+    examples: [SUPPORTED_AXM_SUPPORT, "unsupported", "unknown"],
+});
+/** @experimental This API is unstable and may change without notice. */
+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 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 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.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const AgentInterfaceSchema = Schema.Literals([
+    "cli",
+    "ide-extension",
+    "chat",
+    "hosted-agent",
+]).annotate({
+    identifier: "AgentInterface",
+    title: "Agent Interface",
+    description: "Primary product interface where the agent runs.",
+    examples: ["cli", "ide-extension", "chat", "hosted-agent"],
+});
+/** @experimental This API is unstable and may change without notice. */
+export const McpTransportSchema = Schema.Literals(["stdio", "http", "sse"]).annotate({
+    identifier: "McpTransport",
+    title: "MCP Transport",
+    description: "MCP transport supported by an agent.",
+    examples: ["stdio", "http", "sse"],
+});
+const NonEmptyMcpTransportsSchema = Schema.NonEmptyArray(McpTransportSchema).pipe(Schema.check(Schema.isUnique()));
+/** @experimental This API is unstable and may change without notice. */
+export const DetectionSignalSchema = Schema.Literals([
+    "definitive",
+    "supporting",
+    "ambiguous",
+]).annotate({
+    identifier: "DetectionSignal",
+    title: "Detection Signal",
+    description: "How strongly a resolved marker identifies a specific coding agent.",
+    examples: ["definitive", "supporting", "ambiguous"],
+});
+const DetectionMarkerBaseFields = {
+    signal: DetectionSignalSchema,
+    note: Schema.NullOr(Schema.NonEmptyString),
+};
+/** @experimental This API is unstable and may change without notice. */
+export const DetectionMarkerSchema = Schema.Union([
+    Schema.Struct({
+        kind: Schema.Literal("dir"),
+        path: Schema.NonEmptyString,
+        ...DetectionMarkerBaseFields,
+    }),
+    Schema.Struct({
+        kind: Schema.Literal("file"),
+        path: Schema.NonEmptyString,
+        ...DetectionMarkerBaseFields,
+    }),
+    Schema.Struct({
+        kind: Schema.Literal("executable"),
+        name: Schema.NonEmptyString,
+        ...DetectionMarkerBaseFields,
+    }),
+]).annotate({
+    identifier: "DetectionMarker",
+    title: "Detection Marker",
+    description: "Typed marker used to detect an installed or configured coding agent.",
+});
+const detectionMarkerKey = (marker) => marker.kind === "executable" ? `executable:${marker.name}` : `${marker.kind}:${marker.path}`;
+/** @experimental This API is unstable and may change without notice. */
+export const ScopeDetectionSchema = Schema.Struct({
+    markers: Schema.Array(DetectionMarkerSchema).pipe(Schema.check(Schema.makeFilter((markers) => {
+        const seen = new Set();
+        for (const marker of markers) {
+            const key = detectionMarkerKey(marker);
+            if (seen.has(key))
+                return "Detection markers must be unique by kind and path/name.";
+            seen.add(key);
+        }
+        return undefined;
+    }))),
+}).annotate({
+    identifier: "ScopeDetection",
+    title: "Scope Detection",
+    description: "Detection markers for one configuration scope.",
+});
+const DetectionStruct = Schema.Struct({
+    project: ScopeDetectionSchema,
+    user: ScopeDetectionSchema,
+});
+/** @experimental This API is unstable and may change without notice. */
+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.",
+}));
+/** @experimental This API is unstable and may change without notice. */
+export const LastVerifiedDateSchema = Schema.NonEmptyString.pipe(Schema.check(Schema.isPattern(ISO_DATE_PATTERN, {
+    message: "Expected an ISO 8601 date in YYYY-MM-DD form.",
+}))).annotate({
+    identifier: "LastVerifiedDate",
+    title: "Last Verified Date",
+    description: "Date a capability claim was last verified.",
+    examples: ["2026-05-16"],
+});
+const CapabilityNotesSchema = Schema.NullOr(Schema.NonEmptyString);
+const CapabilityDocsSchema = Schema.Array(DocLinkSchema);
+const CapabilitySourcesSchema = Schema.Array(UrlSchema);
+const provenanceFields = (sources, lastVerified) => ({
+    sources,
+    lastVerified,
+});
+const NullableProvenanceFields = provenanceFields(CapabilitySourcesSchema, Schema.NullOr(LastVerifiedDateSchema));
+const VerifiedProvenanceFields = provenanceFields(Schema.NonEmptyArray(UrlSchema), LastVerifiedDateSchema);
+/** @experimental This API is unstable and may change without notice. */
+export const ProvenanceSchema = Schema.Struct(NullableProvenanceFields).annotate({
+    identifier: "Provenance",
+    title: "Provenance",
+    description: "Source URLs and verification date for a catalog capability claim.",
+});
+const UnavailableNativeCapabilityFields = {
+    availability: NoneAvailabilitySchema,
+    vendorStatus: VendorStatusSchema,
+    notes: CapabilityNotesSchema,
+    docs: CapabilityDocsSchema,
+    sources: CapabilitySourcesSchema,
+};
+const AvailableNativeCapabilityBaseFields = {
+    availability: AvailableCapabilityAvailabilitySchema,
+    vendorStatus: VendorStatusSchema,
+    notes: CapabilityNotesSchema,
+    docs: CapabilityDocsSchema,
+    sources: CapabilitySourcesSchema,
+    scopes: NonEmptyScopesSchema,
+};
+const SpecTrackedCapabilityFields = {
+    standardsCompliance: StandardsComplianceSchema,
+    convention: ConventionSchema,
+};
+const AvailableSpecTrackedNativeCapabilityFields = {
+    ...AvailableNativeCapabilityBaseFields,
+    ...SpecTrackedCapabilityFields,
+};
+const axmCapabilityStateDescription = "AXM integration state for this capability: AXM support status, AXM verification date, optional writer metadata, and AXM-owned rationale. This is not a vendor fact.";
+const axmCapabilityStateSchema = (writerSchema, identifier) => Schema.Struct({
+    status: AxmSupportSchema,
+    lastVerified: Schema.NullOr(LastVerifiedDateSchema),
+    reason: Schema.optionalKey(Schema.NonEmptyString),
+    writer: Schema.NullOr(writerSchema),
+}).annotate({
+    identifier,
+    title: "AXM Capability State",
+    description: axmCapabilityStateDescription,
+});
+const NoWriterAxmCapabilityStateSchema = axmCapabilityStateSchema(Schema.Never, "NoWriterAxmCapabilityState");
+const requireSourcesForActiveAxmSupport = (capability) => {
+    if ((capability.axm.status === SUPPORTED_AXM_SUPPORT || capability.axm.status === "planned") &&
+        capability.native.sources.length === 0) {
+        return {
+            path: ["native", "sources"],
+            issue: "Active AXM support claims require at least one native source.",
+        };
+    }
+    return undefined;
+};
+/** @experimental This API is unstable and may change without notice. */
+export const NativeCapabilityBaseSchema = Schema.Union([
+    Schema.Struct(AvailableNativeCapabilityBaseFields),
+    Schema.Struct(UnavailableNativeCapabilityFields),
+]).annotate({
+    identifier: "NativeCapabilityBase",
+    title: "Native 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({
+    native: Schema.Union([
+        Schema.Struct({
+            ...AvailableSpecTrackedNativeCapabilityFields,
+            convention: Schema.Literals(["universal", "vendor"]),
+            directory: Schema.NonEmptyString,
+            additionalReadPaths: Schema.Array(SkillReadPathSchema).pipe(Schema.withDecodingDefaultKey(Effect.succeed([])), Schema.optionalKey),
+        }),
+        Schema.Struct({
+            ...AvailableSpecTrackedNativeCapabilityFields,
+            convention: Schema.Literal("hosted"),
+        }),
+        Schema.Struct(UnavailableNativeCapabilityFields),
+    ]),
+    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. */
+/** @experimental This API is unstable and may change without notice. */
+export const SubagentsLayoutSchema = Schema.Literals(["file", "directory"]).annotate({
+    identifier: "SubagentsLayout",
+    title: "Subagents Layout",
+    description: "Whether subagents live in a directory or a single opaque file path.",
+    examples: ["directory", "file"],
+});
+const PluginSubagentsNativeCapabilitySchema = Schema.Struct({
+    ...AvailableNativeCapabilityBaseFields,
+    availability: PluginAvailabilitySchema,
+});
+/** @experimental This API is unstable and may change without notice. */
+export const SubagentsExtensionCapabilitySchema = Schema.Struct({
+    native: Schema.Union([
+        Schema.Struct({
+            ...AvailableNativeCapabilityBaseFields,
+            availability: NativeAvailabilitySchema,
+            directory: Schema.NonEmptyString,
+            layout: SubagentsLayoutSchema,
+        }),
+        PluginSubagentsNativeCapabilitySchema,
+        Schema.Struct(UnavailableNativeCapabilityFields),
+    ]),
+    axm: NoWriterAxmCapabilityStateSchema,
+})
+    .pipe(Schema.check(Schema.makeFilter(requireSourcesForActiveAxmSupport)))
+    .annotate({
+    identifier: "SubagentsExtensionCapability",
+    title: "Subagents Capability",
+    description: "Agent support for subagent extensions.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const RuleInstructionsKindSchema = Schema.Literals([
+    "agents-md",
+    "own-file",
+    "rules-dir",
+]).annotate({
+    identifier: "RuleInstructionsKind",
+    title: "Rule Instructions Kind",
+    description: "Operational instruction-file convention used by the agent.",
+    examples: ["agents-md", "own-file", "rules-dir"],
+});
+/** @experimental This API is unstable and may change without notice. */
+export const RuleInstructionsImportSyntaxSchema = Schema.Literals(["at-path"]).annotate({
+    identifier: "RuleInstructionsImportSyntax",
+    title: "Rule Instructions Import Syntax",
+    description: "Syntax an agent uses to import another instruction file.",
+    examples: ["at-path"],
+});
+const OptionalRuleDirectoryField = {
+    directory: Schema.optionalKey(Schema.NonEmptyString),
+};
+const AgentsMdRulesExtensionCapabilitySchema = Schema.Struct({
+    ...AvailableSpecTrackedNativeCapabilityFields,
+    ...OptionalRuleDirectoryField,
+    kind: Schema.Literal("agents-md"),
+    files: Schema.Tuple([Schema.Literal("AGENTS.md")]),
+    nestedDiscovery: Schema.Boolean,
+    importSyntax: Schema.NullOr(RuleInstructionsImportSyntaxSchema),
+});
+const OwnFileRulesExtensionCapabilitySchema = Schema.Struct({
+    ...AvailableSpecTrackedNativeCapabilityFields,
+    ...OptionalRuleDirectoryField,
+    kind: Schema.Literal("own-file"),
+    files: Schema.Tuple([Schema.NonEmptyString]),
+    nestedDiscovery: Schema.Boolean,
+    importSyntax: Schema.NullOr(RuleInstructionsImportSyntaxSchema),
+});
+const RulesDirRulesExtensionCapabilitySchema = Schema.Struct({
+    ...AvailableSpecTrackedNativeCapabilityFields,
+    kind: Schema.Literal("rules-dir"),
+    files: Schema.Array(Schema.NonEmptyString).pipe(Schema.check(Schema.isUnique())),
+    nestedDiscovery: Schema.Boolean,
+    importSyntax: Schema.NullOr(RuleInstructionsImportSyntaxSchema),
+    directory: Schema.NonEmptyString,
+});
+/** @experimental This API is unstable and may change without notice. */
+export const RulesExtensionCapabilitySchema = Schema.Struct({
+    native: Schema.Union([
+        AgentsMdRulesExtensionCapabilitySchema,
+        OwnFileRulesExtensionCapabilitySchema,
+        RulesDirRulesExtensionCapabilitySchema,
+        Schema.Struct(UnavailableNativeCapabilityFields),
+    ]),
+    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 ConfigFileFormatSchema = Schema.Literals([
+    "json",
+    "jsonc",
+    "toml",
+    "yaml",
+    "starlark",
+    "vscode-settings",
+]).annotate({
+    identifier: "ConfigFileFormat",
+    title: "Config File Format",
+    description: "Serialization format used by an agent's permission config file.",
+    examples: ["json", "toml", "yaml", "vscode-settings"],
+});
+/** @experimental This API is unstable and may change without notice. */
+export const McpServersKeySchema = Schema.Literals([
+    "mcpServers",
+    "servers",
+    "mcp",
+    "mcp_servers",
+    "context_servers",
+]).annotate({
+    identifier: "McpServersKey",
+    title: "MCP Servers Key",
+    description: "Top-level key containing MCP server entries in an agent config file.",
+    examples: ["mcpServers", "servers", "mcp"],
+});
+/** @experimental This API is unstable and may change without notice. */
+export const McpTargetAttributionSchema = Schema.Literals(["shared", "agent"]).annotate({
+    identifier: "McpTargetAttribution",
+    title: "MCP Target Attribution",
+    description: "Whether a config target identifies one agent or is a shared surface read by multiple agents.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const McpConfigTargetSchema = Schema.Struct({
+    scope: ScopeSchema,
+    path: Schema.NonEmptyString,
+    format: ConfigFileFormatSchema,
+    attribution: McpTargetAttributionSchema,
+}).annotate({
+    identifier: "McpConfigTarget",
+    title: "MCP Config Target",
+    description: "A config file target where MCP server entries can be written, with explicit presence attribution.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const McpTypeFieldValueMapSchema = Schema.Struct({
+    "streamable-http": Schema.NonEmptyString,
+    sse: Schema.optionalKey(Schema.NonEmptyString),
+}).annotate({
+    identifier: "McpTypeFieldValueMap",
+    title: "MCP Type Field Value Map",
+    description: "Agent discriminator values by upstream remote transport.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const McpTypeFieldRepresentationSchema = Schema.Struct({
+    name: Schema.NonEmptyString,
+    value: Schema.Union([Schema.NonEmptyString, McpTypeFieldValueMapSchema]),
+}).annotate({
+    identifier: "McpTypeFieldRepresentation",
+    title: "MCP Type Field Representation",
+    description: "One accepted per-entry transport discriminator representation.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const McpTypeFieldSchema = Schema.Struct({
+    required: Schema.NullOr(McpTypeFieldRepresentationSchema),
+    accepted: Schema.NonEmptyArray(Schema.NullOr(McpTypeFieldRepresentationSchema)),
+}).annotate({
+    identifier: "McpTypeField",
+    title: "MCP Type Field",
+    description: "The discriminator representation AXM writes and every representation the agent accepts.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const McpActivationFieldRepresentationSchema = Schema.Struct({
+    name: Schema.NonEmptyString,
+    enabled: Schema.Boolean,
+    disabled: Schema.Boolean,
+}).annotate({
+    identifier: "McpActivationFieldRepresentation",
+    title: "MCP Activation Field Representation",
+    description: "One accepted per-entry activation field and its boolean polarity.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const McpActivationFieldSchema = Schema.Struct({
+    required: Schema.NullOr(McpActivationFieldRepresentationSchema),
+    accepted: Schema.NonEmptyArray(Schema.NullOr(McpActivationFieldRepresentationSchema)),
+}).annotate({
+    identifier: "McpActivationField",
+    title: "MCP Activation Field",
+    description: "The activation representation AXM writes and every representation the agent accepts.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const McpStdioDialectSchema = Schema.Struct({
+    typeField: McpTypeFieldSchema,
+    command: Schema.Literals(["split", "array"]),
+    envKey: Schema.NullOr(Schema.NonEmptyString),
+}).annotate({
+    identifier: "McpStdioDialect",
+    title: "MCP Stdio Dialect",
+    description: "How an agent represents local stdio MCP server entries.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const McpUrlKeyMapSchema = Schema.Struct({
+    "streamable-http": Schema.NonEmptyString,
+    sse: Schema.optionalKey(Schema.NonEmptyString),
+}).annotate({
+    identifier: "McpUrlKeyMap",
+    title: "MCP URL Key Map",
+    description: "Agent URL field names by upstream remote transport.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const McpRemoteDialectSchema = Schema.Struct({
+    typeField: McpTypeFieldSchema,
+    urlKey: McpUrlKeyMapSchema,
+    headersKey: Schema.NullOr(Schema.NonEmptyString),
+    bearerTokenEnvKey: Schema.optionalKey(Schema.NullOr(Schema.NonEmptyString)),
+    envHeadersKey: Schema.optionalKey(Schema.NullOr(Schema.NonEmptyString)),
+}).annotate({
+    identifier: "McpRemoteDialect",
+    title: "MCP Remote Dialect",
+    description: "How an agent represents remote MCP server entries.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const McpConfigSchema = Schema.Struct({
+    serversKey: McpServersKeySchema,
+    activationField: McpActivationFieldSchema,
+    targets: Schema.Array(McpConfigTargetSchema),
+    stdio: Schema.NullOr(McpStdioDialectSchema),
+    remote: Schema.NullOr(McpRemoteDialectSchema),
+}).annotate({
+    identifier: "McpConfig",
+    title: "MCP Config",
+    description: "Prescriptive config writer metadata for an agent's MCP support.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const McpEnvExpansionSchema = Schema.Struct({
+    variables: Schema.Literals(["none", "braced"]),
+    defaults: Schema.Boolean,
+}).annotate({
+    identifier: "McpEnvExpansion",
+    title: "MCP Env Expansion",
+    description: "Whether an agent expands MCP config environment references.",
+});
+const McpUnavailableCapabilityStruct = Schema.Struct({
+    native: Schema.Struct(UnavailableNativeCapabilityFields),
+    axm: axmCapabilityStateSchema(Schema.Struct({ config: McpConfigSchema }), "McpAxmState"),
+});
+const McpNativeWithTransportsSchema = Schema.Struct({
+    ...AvailableSpecTrackedNativeCapabilityFields,
+    transports: NonEmptyMcpTransportsSchema,
+    mcpEnvExpansion: Schema.optionalKey(McpEnvExpansionSchema),
+});
+const McpAvailableCapabilityStruct = Schema.Struct({
+    native: McpNativeWithTransportsSchema,
+    axm: axmCapabilityStateSchema(Schema.Struct({ config: McpConfigSchema }), "McpAxmState"),
+});
+const McpExtensionCapabilityStruct = Schema.Union([
+    McpAvailableCapabilityStruct,
+    McpUnavailableCapabilityStruct,
+]);
+const McpExtensionCapabilitySchemaWithChecks = McpExtensionCapabilityStruct.pipe(Schema.check(Schema.makeFilter((capability) => {
+    const issues = [];
+    const activeSourcesIssue = requireSourcesForActiveAxmSupport(capability);
+    if (activeSourcesIssue !== undefined)
+        issues.push(activeSourcesIssue);
+    const writer = capability.axm.writer;
+    if (writer === null || !("transports" in capability.native))
+        return issues;
+    const config = writer.config;
+    if (capability.native.transports.includes("stdio") && config.stdio === null) {
+        issues.push({
+            path: ["axm", "writer", "config", "stdio"],
+            issue: "MCP stdio config is required when stdio transport is supported.",
+        });
+    }
+    if ((capability.native.transports.includes("http") ||
+        capability.native.transports.includes("sse")) &&
+        config.remote === null) {
+        issues.push({
+            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 = McpExtensionCapabilitySchemaWithChecks.annotate({
+    identifier: "McpExtensionCapability",
+    title: "MCP Capability",
+    description: "Agent support for MCP server extensions.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const PermissionMechanismSchema = Schema.Literals([
+    "config-file",
+    "cli-flag",
+    "ui-only",
+]).annotate({
+    identifier: "PermissionMechanism",
+    title: "Permission Mechanism",
+    description: "How an agent exposes permission configuration.",
+    examples: ["config-file", "cli-flag", "ui-only"],
+});
+const NonEmptyPermissionMechanismsSchema = Schema.NonEmptyArray(PermissionMechanismSchema).pipe(Schema.check(Schema.isUnique()));
+/** @experimental This API is unstable and may change without notice. */
+export const PermissionGrammarStyleSchema = Schema.Literals([
+    "tool-call",
+    "prefix",
+    "regex",
+    "glob",
+    "starlark-rule",
+]).annotate({
+    identifier: "PermissionGrammarStyle",
+    title: "Permission Grammar Style",
+    description: "Syntax shape used to express a permission rule.",
+    examples: ["tool-call", "prefix", "regex"],
+});
+/** @experimental This API is unstable and may change without notice. */
+export const ConfigFileLocationSchema = Schema.Struct({
+    scope: ScopeSchema,
+    path: Schema.NonEmptyString,
+    format: ConfigFileFormatSchema,
+    gitignored: Schema.Boolean,
+}).annotate({
+    identifier: "ConfigFileLocation",
+    title: "Config File Location",
+    description: "A configuration file where an agent's permission rules can live.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const CANONICAL_HOOK_EVENT_IDS = [
+    "session.start",
+    "prompt.submit",
+    "turn.end",
+    "tool.pre",
+    "tool.post",
+    "subagent.stop",
+    "compaction.pre",
+];
+/** @experimental This API is unstable and may change without notice. */
+export const CanonicalHookEventIdSchema = Schema.Literals(CANONICAL_HOOK_EVENT_IDS).annotate({
+    identifier: "CanonicalHookEventId",
+    title: "Canonical Hook Event ID",
+    description: "Vendor-neutral hook lifecycle event identifier.",
+    examples: ["tool.pre", "tool.post", "prompt.submit"],
+});
+/** @experimental This API is unstable and may change without notice. */
+export const HookEventTierSchema = Schema.Literals(["core", "extended"]).annotate({
+    identifier: "HookEventTier",
+    title: "Hook Event Tier",
+    description: "Whether a canonical hook event belongs to the stable core or extended tail.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const CanonicalHookEventSchema = Schema.Struct({
+    id: CanonicalHookEventIdSchema,
+    tier: HookEventTierSchema,
+}).annotate({
+    identifier: "CanonicalHookEvent",
+    title: "Canonical Hook Event",
+    description: "Registered AXM hook event concept.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const CANONICAL_HOOK_EVENTS = [
+    { id: "session.start", tier: "core" },
+    { id: "prompt.submit", tier: "core" },
+    { id: "turn.end", tier: "core" },
+    { id: "tool.pre", tier: "core" },
+    { id: "tool.post", tier: "core" },
+    { id: "subagent.stop", tier: "extended" },
+    { id: "compaction.pre", tier: "extended" },
+];
+/** @experimental This API is unstable and may change without notice. */
+export const CANONICAL_HOOK_TOOL_IDS = [
+    "file.read",
+    "file.write",
+    "file.edit",
+    "shell.exec",
+    "web.fetch",
+    "mcp.call",
+];
+/** @experimental This API is unstable and may change without notice. */
+export const CanonicalHookToolIdSchema = Schema.Literals(CANONICAL_HOOK_TOOL_IDS).annotate({
+    identifier: "CanonicalHookToolId",
+    title: "Canonical Hook Tool ID",
+    description: "Vendor-neutral tool identity used by portable hook matchers.",
+    examples: ["file.write", "file.edit", "shell.exec"],
+});
+/** @experimental This API is unstable and may change without notice. */
+export const HookToolMappingSchema = Schema.Struct({
+    nativeName: Schema.NonEmptyString,
+    canonical: CanonicalHookToolIdSchema,
+    ...VerifiedProvenanceFields,
+}).annotate({
+    identifier: "HookToolMapping",
+    title: "Hook Tool Mapping",
+    description: "Native tool name with its canonical AXM tool identity and provenance.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const HookMechanismFamilySchema = Schema.Literals(["command-stdin", "raw"]).annotate({
+    identifier: "HookMechanismFamily",
+    title: "Hook Mechanism Family",
+    description: "How a native hook system invokes a hook.",
+    examples: ["command-stdin", "raw"],
+});
+const NonEmptyHookMechanismFamiliesSchema = Schema.NonEmptyArray(HookMechanismFamilySchema).pipe(Schema.check(Schema.isUnique()));
+/** @experimental This API is unstable and may change without notice. */
+export const HookMatcherKindSchema = Schema.Literals([
+    "regex",
+    "literal-list",
+    "glob",
+    "tool-category",
+    "exact-substring",
+    "none-imperative",
+]).annotate({
+    identifier: "HookMatcherKind",
+    title: "Hook Matcher Kind",
+    description: "Native matcher syntax used to scope hook invocation.",
+    examples: ["regex", "glob", "none-imperative"],
+});
+/** @experimental This API is unstable and may change without notice. */
+export const HookMatcherSchema = Schema.Struct({
+    kind: HookMatcherKindSchema,
+    example: Schema.NullOr(Schema.NonEmptyString),
+    notes: Schema.NullOr(Schema.NonEmptyString),
+}).annotate({
+    identifier: "HookMatcher",
+    title: "Hook Matcher",
+    description: "Matcher model for a native hook event.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const HookBlockOutcomeSchema = Schema.Literals(["allow", "deny", "ask"]).annotate({
+    identifier: "HookBlockOutcome",
+    title: "Hook Block Outcome",
+    description: "Decision outcome available to blocking hook systems.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const HookModifyOperationSchema = Schema.Literals([
+    "modify-input",
+    "inject-context",
+    "modify-output",
+    "synthesize",
+    "redact",
+]).annotate({
+    identifier: "HookModifyOperation",
+    title: "Hook Modify Operation",
+    description: "Transform operation available to modifying hook systems.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const HookDecisionCapabilitySchema = Schema.Union([
+    Schema.Struct({ kind: Schema.Literal("observe") }),
+    Schema.Struct({
+        kind: Schema.Literal("block"),
+        outcomes: Schema.NonEmptyArray(HookBlockOutcomeSchema).pipe(Schema.check(Schema.isUnique())),
+    }),
+    Schema.Struct({
+        kind: Schema.Literal("modify"),
+        operations: Schema.NonEmptyArray(HookModifyOperationSchema).pipe(Schema.check(Schema.isUnique())),
+    }),
+]).annotate({
+    identifier: "HookDecisionCapability",
+    title: "Hook Decision Capability",
+    description: "Whether a hook event can observe, block, or modify lifecycle behavior.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const HookEventMappingSchema = Schema.Struct({
+    nativeName: Schema.NonEmptyString,
+    canonical: CanonicalHookEventIdSchema,
+    matcher: HookMatcherSchema,
+    decision: Schema.NonEmptyArray(HookDecisionCapabilitySchema),
+    ...VerifiedProvenanceFields,
+}).annotate({
+    identifier: "HookEventMapping",
+    title: "Hook Event Mapping",
+    description: "Native hook event name with its canonical AXM event pointer and provenance.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const HooksSerializerSchema = Schema.Literals(["command-stdin"]).annotate({
+    identifier: "HooksSerializer",
+    title: "Hooks Serializer",
+    description: "Native settings serializer AXM uses for managed hook declarations.",
+    examples: ["command-stdin"],
+});
+/** @experimental This API is unstable and may change without notice. */
+export const HookMatcherSerializationSchema = Schema.Literals([
+    "bare",
+    "slash-delimited",
+    "glob",
+]).annotate({
+    identifier: "HookMatcherSerialization",
+    title: "Hook Matcher Serialization",
+    description: "How AXM serializes manifest matcher strings into an agent-native hook group.",
+    examples: ["bare", "slash-delimited", "glob"],
+});
+/** @experimental This API is unstable and may change without notice. */
+export const HookTimeoutSerializationSchema = Schema.Literals(["seconds", "milliseconds"]).annotate({
+    identifier: "HookTimeoutSerialization",
+    title: "Hook Timeout Serialization",
+    description: "Unit AXM uses when serializing hook timeout fields into native settings.",
+    examples: ["seconds", "milliseconds"],
+});
+/** @experimental This API is unstable and may change without notice. */
+export const HookCommandNameSerializationSchema = Schema.Literals(["omit", "manifest"]).annotate({
+    identifier: "HookCommandNameSerialization",
+    title: "Hook Command Name Serialization",
+    description: "Whether native command hook entries need an explicit name field.",
+    examples: ["omit", "manifest"],
+});
+/** @experimental This API is unstable and may change without notice. */
+export const HooksWriterSchema = Schema.Struct({
+    serializer: HooksSerializerSchema,
+    configFiles: Schema.NonEmptyArray(ConfigFileLocationSchema),
+    settingsKey: Schema.NonEmptyString,
+    eventMap: Schema.Literal("native.events"),
+    matcherKind: HookMatcherKindSchema,
+    matcherSerialization: HookMatcherSerializationSchema,
+    timeoutSerialization: HookTimeoutSerializationSchema,
+    commandNameSerialization: HookCommandNameSerializationSchema,
+}).annotate({
+    identifier: "HooksWriter",
+    title: "Hooks Writer",
+    description: "Parameterized AXM hook writer metadata derived from native hook catalog data.",
+});
+const HooksAvailableNativeCapabilitySchema = Schema.Struct({
+    ...AvailableNativeCapabilityBaseFields,
+    mechanism: NonEmptyHookMechanismFamiliesSchema,
+    configFiles: Schema.Array(ConfigFileLocationSchema),
+    events: Schema.NonEmptyArray(HookEventMappingSchema),
+    tools: Schema.Array(HookToolMappingSchema),
+});
+const HooksUnmodeledNativeCapabilitySchema = Schema.Struct({
+    ...AvailableNativeCapabilityBaseFields,
+    modeling: Schema.Literal("native-unmodeled"),
+});
+const HooksExtensionCapabilityStruct = Schema.Struct({
+    native: Schema.Union([
+        HooksAvailableNativeCapabilitySchema,
+        HooksUnmodeledNativeCapabilitySchema,
+        Schema.Struct(UnavailableNativeCapabilityFields),
+    ]),
+    axm: axmCapabilityStateSchema(HooksWriterSchema, "HooksAxmState"),
+});
+/** @experimental This API is unstable and may change without notice. */
+export const HooksExtensionCapabilitySchema = HooksExtensionCapabilityStruct.pipe(Schema.check(Schema.makeFilter((capability) => {
+    const issues = [];
+    if (capability.axm.writer !== null && capability.native.sources.length === 0) {
+        issues.push({
+            path: ["native", "sources"],
+            issue: "Hook writer claims require at least one native source.",
+        });
+    }
+    if ("events" in capability.native) {
+        const nativeToolNames = new Set(capability.native.tools.map((tool) => tool.nativeName));
+        if (nativeToolNames.size !== capability.native.tools.length) {
+            issues.push({
+                path: ["native", "tools"],
+                issue: "Hook native tool mappings require unique nativeName values.",
+            });
+        }
+    }
+    return issues;
+}))).annotate({
+    identifier: "HooksExtensionCapability",
+    title: "Hooks Capability",
+    description: "Agent support for lifecycle hook extensions.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const PermissionGrammarSchema = Schema.Struct({
+    style: PermissionGrammarStyleSchema,
+    example: Schema.NonEmptyString,
+    notes: Schema.NullOr(Schema.NonEmptyString),
+}).annotate({
+    identifier: "PermissionGrammar",
+    title: "Permission Grammar",
+    description: "Rule syntax used by an agent's permission system.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const PermissionPrerequisiteSchema = Schema.Struct({
+    key: Schema.NonEmptyString,
+    value: Schema.NonEmptyString,
+    scope: ScopeSchema,
+    note: Schema.NullOr(Schema.NonEmptyString),
+}).annotate({
+    identifier: "PermissionPrerequisite",
+    title: "Permission Prerequisite",
+    description: "Mode or gate that must be set before allow rules take effect.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const PermissionCliFlagSchema = Schema.Struct({
+    flag: Schema.NonEmptyString,
+    note: Schema.NullOr(Schema.NonEmptyString),
+}).annotate({
+    identifier: "PermissionCliFlag",
+    title: "Permission CLI Flag",
+    description: "Invocation-time flag that adjusts approval or sandbox behavior.",
+});
+const PermissionGrantStruct = Schema.Struct({
+    target: Schema.NonEmptyString,
+    patch: Schema.NullOr(Schema.Unknown),
+    template: Schema.NullOr(Schema.NonEmptyString),
+});
+/** @experimental This API is unstable and may change without notice. */
+export const PermissionGrantSchema = PermissionGrantStruct.pipe(Schema.check(Schema.makeFilter((grant) => grant.patch === null && grant.template === null
+    ? "Permission grants require patch or template."
+    : undefined))).annotate({
+    identifier: "PermissionGrant",
+    title: "Permission Grant",
+    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.Struct({
+    native: Schema.Union([
+        Schema.Struct({
+            ...AvailableNativeCapabilityBaseFields,
+            mechanism: NonEmptyPermissionMechanismsSchema,
+            configFiles: Schema.Array(ConfigFileLocationSchema),
+            grammar: Schema.NullOr(PermissionGrammarSchema),
+            prerequisites: Schema.Array(PermissionPrerequisiteSchema),
+            cliFlags: Schema.Array(PermissionCliFlagSchema),
+        }),
+        Schema.Struct(UnavailableNativeCapabilityFields),
+    ]),
+    axm: axmCapabilityStateSchema(Schema.Struct({ grants: Schema.Record(Schema.String, PermissionGrantSchema) }), "PermissionsAxmState"),
+})
+    .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.",
+});
+const PerAgentCapabilitySchemaByType = {
+    skill: SkillsExtensionCapabilitySchema,
+    "mcp-server": McpExtensionCapabilitySchema,
+    subagent: SubagentsExtensionCapabilitySchema,
+    hook: HooksExtensionCapabilitySchema,
+};
+/** @experimental This API is unstable and may change without notice. */
+export const AgentCapabilitiesSchema = Schema.Struct(PerAgentCapabilitySchemaByType).annotate({
+    identifier: "AgentCapabilities",
+    title: "Agent Capabilities",
+    description: "Agent extension capabilities keyed by per-agent 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.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const CapabilityTargetingEntrySchema = Schema.Struct({
+    grades: Schema.Array(Schema.NonEmptyString).pipe(Schema.check(Schema.isUnique())),
+    nouns: Schema.Record(Schema.String, Schema.NonEmptyString),
+    affordances: Schema.Record(Schema.String, Schema.NonEmptyString),
+}).annotate({
+    identifier: "CapabilityTargetingEntry",
+    title: "Capability Targeting Entry",
+    description: "Additional portable grades, target-native nouns, and maintained affordance phrases for one capability.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const CapabilityTargetingSchema = Schema.Struct({
+    extends: Schema.NullOr(AgentIdFromYamlSchema),
+    capabilities: Schema.Record(Schema.String, CapabilityTargetingEntrySchema),
+}).annotate({
+    identifier: "CapabilityTargeting",
+    title: "Capability Targeting",
+    description: "Catalog inputs used by AXM's capability-targeted extension renderer and fallback graph.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const HostedInstallDeliverySchema = Schema.Literals(["upload", "directory"]).annotate({
+    identifier: "HostedInstallDelivery",
+    title: "Hosted Install Delivery",
+    description: "User-mediated delivery mechanism accepted by a hosted agent surface.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const HostedInstallArtifactSchema = Schema.Literals([
+    "directory",
+    "zip",
+    "skill-file-or-zip",
+]).annotate({
+    identifier: "HostedInstallArtifact",
+    title: "Hosted Install Artifact",
+    description: "Artifact shape a hosted agent accepts for manual extension delivery.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const HostedInstallTargetSchema = Schema.Struct({
+    kind: Schema.Literal("hosted"),
+    delivery: Schema.NonEmptyArray(HostedInstallDeliverySchema).pipe(Schema.check(Schema.isUnique())),
+    artifact: HostedInstallArtifactSchema,
+    instructions: Schema.NonEmptyString,
+    docs: UrlSchema,
+}).annotate({
+    identifier: "HostedInstallTarget",
+    title: "Hosted Install Target",
+    description: "Manual delivery instructions for a hosted agent after AXM packages and validates an extension.",
+});
+const AgentStruct = Schema.Struct({
+    id: AgentIdFromYamlSchema,
+    name: Schema.NonEmptyString,
+    vendor: Schema.NonEmptyString,
+    homepage: UrlSchema,
+    interfaces: Schema.NonEmptyArray(AgentInterfaceSchema).pipe(Schema.check(Schema.isUnique())),
+    family: Schema.NullOr(Schema.NonEmptyString),
+    rootDir: Schema.NullOr(Schema.NonEmptyString),
+    installTarget: Schema.optionalKey(HostedInstallTargetSchema),
+    lifecycle: AgentLifecycleSchema,
+    detection: DetectionSchema,
+    docs: Schema.Array(DocLinkSchema),
+    capabilities: AgentCapabilitiesSchema,
+    instructions: RulesExtensionCapabilitySchema,
+    permissions: PermissionsExtensionCapabilitySchema,
+    targeting: Schema.optionalKey(CapabilityTargetingSchema),
+});
+/** @experimental This API is unstable and may change without notice. */
+export const AgentSchema = AgentStruct.pipe(Schema.check(Schema.makeFilter((agent) => {
+    const issues = [];
+    if ("kind" in agent.instructions.native &&
+        agent.instructions.native.kind === "agents-md" &&
+        agent.instructions.native.files[0] !== "AGENTS.md") {
+        issues.push({
+            path: ["instructions", "native", "files"],
+            issue: 'instructions.kind "agents-md" requires AGENTS.md.',
+        });
+    }
+    const hostedOnly = agent.interfaces.every((interfaceKind) => interfaceKind === "chat" || interfaceKind === "hosted-agent");
+    const hasHostedInterface = agent.interfaces.some((interfaceKind) => interfaceKind === "chat" || interfaceKind === "hosted-agent");
+    const hasDetectionMarkers = agent.detection.project.markers.length > 0 || agent.detection.user.markers.length > 0;
+    if (hasHostedInterface && agent.installTarget === undefined) {
+        issues.push({
+            path: ["installTarget"],
+            issue: "Agents with a hosted interface require installTarget.",
+        });
+    }
+    if (hostedOnly && agent.rootDir !== null) {
+        issues.push({
+            path: ["rootDir"],
+            issue: "Hosted-only agents cannot declare rootDir.",
+        });
+    }
+    if (hostedOnly && hasDetectionMarkers) {
+        issues.push({
+            path: ["detection"],
+            issue: "Hosted-only agents cannot declare local detection markers.",
+        });
+    }
+    const capabilitySlots = [
+        ...Object.values(agent.capabilities),
+        agent.instructions,
+        agent.permissions,
+    ];
+    if (hostedOnly && capabilitySlots.some((capability) => capability.axm.writer !== null)) {
+        issues.push({
+            path: ["capabilities"],
+            issue: "Hosted-only agents cannot declare filesystem writers.",
+        });
+    }
+    if (hostedOnly &&
+        capabilitySlots.some((capability) => "directory" in capability.native ||
+            ("configFiles" in capability.native && capability.native.configFiles.length > 0))) {
+        issues.push({
+            path: ["capabilities"],
+            issue: "Hosted-only agents cannot declare local capability paths.",
+        });
+    }
+    if (!hasHostedInterface && agent.installTarget !== undefined) {
+        issues.push({
+            path: ["installTarget"],
+            issue: "Local-only agents cannot declare a hosted installTarget.",
+        });
+    }
+    return issues;
+}))).annotate({
+    identifier: "Agent",
+    title: "Agent",
+    description: "AI coding agent and its verified extension capability claims.",
+});
+//# sourceMappingURL=schema.js.map