@agentxm/extension-model 0.36.0 → 0.37.3

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

@@ -39,7 +39,6 @@
  *
  * @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";
@@ -76,31 +75,62 @@ export const ConventionSchema = Schema.Literals(["universal", "vendor", "hosted"
     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"],
 });
+/** A declared reader path; physical resolution and ownership belong to the workspace. */
+const NativeReadLocationFields = {
+    scope: ScopeSchema,
+    root: Schema.Literals(["project", "home", "xdg-config"]),
+    path: Schema.NonEmptyString,
+    configRootRelativePath: Schema.optionalKey(Schema.NonEmptyString),
+    shape: Schema.Literals(["directory", "file"]),
+    role: Schema.Literals(["primary", "additional"]),
+    status: Schema.Literals(["canonical", "compat", "deprecated"]),
+    applicability: Schema.Union([
+        Schema.Struct({ kind: Schema.Literal("always") }),
+        Schema.Struct({ kind: Schema.Literal("conditional"), condition: Schema.NonEmptyString }),
+    ]),
+    provenance: Schema.Union([
+        Schema.Struct({ kind: Schema.Literal("capability-sources") }),
+        Schema.Struct({ kind: Schema.Literal("sources"), sources: Schema.NonEmptyArray(UrlSchema) }),
+    ]),
+};
+const nativeReadLocationCheck = Schema.makeFilter((location) => {
+    if (location.configRootRelativePath !== undefined &&
+        (location.scope !== "user" ||
+            /^(?:[\\/~]|[A-Za-z]:)/.test(location.configRootRelativePath) ||
+            location.configRootRelativePath.split(/[\\/]/).includes(".."))) {
+        return {
+            path: ["configRootRelativePath"],
+            issue: "Configuration-root overrides require a bounded relative path in user scope.",
+        };
+    }
+    if ((location.scope === "project") !== (location.root === "project")) {
+        return {
+            path: ["root"],
+            issue: "Project locations require the project root; user locations require home or xdg-config.",
+        };
+    }
+    if (/^(?:[\\/~]|[A-Za-z]:)/.test(location.path) ||
+        location.path.split(/[\\/]/).includes("..")) {
+        return {
+            path: ["path"],
+            issue: "Native locations must be relative to their declared root without parent traversal.",
+        };
+    }
+    return undefined;
+});
+export const NativeReadLocationSchema = Schema.Struct(NativeReadLocationFields)
+    .check(nativeReadLocationCheck)
+    .annotate({
+    identifier: "NativeReadLocation",
+    title: "Native Reader Location",
+    description: "A documented native reader path with explicit scope, root, shape, conditions, and evidence; it grants no writer ownership.",
+});
 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";
@@ -402,8 +432,7 @@ export const SkillsExtensionCapabilitySchema = Schema.Struct({
         Schema.Struct({
             ...AvailableSpecTrackedNativeCapabilityFields,
             convention: Schema.Literals(["universal", "vendor"]),
-            directory: Schema.NonEmptyString,
-            additionalReadPaths: Schema.Array(SkillReadPathSchema).pipe(Schema.withDecodingDefaultKey(Effect.succeed([])), Schema.optionalKey),
+            locations: Schema.Array(NativeReadLocationSchema),
         }),
         Schema.Struct({
             ...AvailableSpecTrackedNativeCapabilityFields,
@@ -419,14 +448,6 @@ export const SkillsExtensionCapabilitySchema = Schema.Struct({
     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,
@@ -437,8 +458,7 @@ export const SubagentsExtensionCapabilitySchema = Schema.Struct({
         Schema.Struct({
             ...AvailableNativeCapabilityBaseFields,
             availability: NativeAvailabilitySchema,
-            directory: Schema.NonEmptyString,
-            layout: SubagentsLayoutSchema,
+            locations: Schema.Array(NativeReadLocationSchema),
         }),
         PluginSubagentsNativeCapabilitySchema,
         Schema.Struct(UnavailableNativeCapabilityFields),
@@ -469,39 +489,22 @@ export const RuleInstructionsImportSyntaxSchema = Schema.Literals(["at-path"]).a
     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({
+const AvailableRulesExtensionCapabilitySchema = Schema.Struct({
     ...AvailableSpecTrackedNativeCapabilityFields,
-    ...OptionalRuleDirectoryField,
-    kind: Schema.Literal("own-file"),
-    files: Schema.Tuple([Schema.NonEmptyString]),
+    kind: RuleInstructionsKindSchema,
+    locations: Schema.Array(NativeReadLocationSchema),
     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,
-});
+}).check(Schema.makeFilter((capability) => {
+    const shape = capability.kind === "rules-dir" ? "directory" : "file";
+    return capability.locations.some((location) => location.role === "primary" && location.shape !== shape)
+        ? { path: ["locations"], issue: `Primary instruction locations must have ${shape} shape` }
+        : undefined;
+}));
 /** @experimental This API is unstable and may change without notice. */
 export const RulesExtensionCapabilitySchema = Schema.Struct({
     native: Schema.Union([
-        AgentsMdRulesExtensionCapabilitySchema,
-        OwnFileRulesExtensionCapabilitySchema,
-        RulesDirRulesExtensionCapabilitySchema,
+        AvailableRulesExtensionCapabilitySchema,
         Schema.Struct(UnavailableNativeCapabilityFields),
     ]),
     axm: NoWriterAxmCapabilityStateSchema,
@@ -526,18 +529,43 @@ export const ConfigFileFormatSchema = Schema.Literals([
     description: "Serialization format used by an agent's permission config file.",
     examples: ["json", "toml", "yaml", "vscode-settings"],
 });
+/** One declared native configuration reader, independently of any AXM writer. */
+export const NativeConfigReadLocationSchema = Schema.Struct({
+    ...NativeReadLocationFields,
+    shape: Schema.Literal("file"),
+    id: Schema.NonEmptyString,
+    format: ConfigFileFormatSchema,
+    keyPath: Schema.optionalKey(Schema.NonEmptyArray(Schema.NonEmptyString)),
+    attribution: Schema.optionalKey(Schema.Literals(["shared", "agent"])),
+    gitignored: Schema.optionalKey(Schema.Boolean),
+})
+    .check(nativeReadLocationCheck)
+    .annotate({
+    identifier: "NativeConfigReadLocation",
+    title: "Native Configuration Reader Location",
+    description: "A scoped native file with its syntax, static container path, and source evidence. Writers refer to its id; no writer support or ownership is implied.",
+});
+const nativeConfigReferenceIssues = (locations, references, writerPath) => {
+    const issues = [];
+    const ids = new Set(locations.map((location) => location.id));
+    if (ids.size !== locations.length)
+        issues.push({
+            path: ["native", "locations"],
+            issue: "Native config location ids must be unique within a capability.",
+        });
+    if (references.some((id) => !ids.has(id)))
+        issues.push({
+            path: [...writerPath],
+            issue: "AXM writers must reference declared native config location ids.",
+        });
+    return issues;
+};
 /** @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"],
+export const McpServersPathSchema = Schema.NonEmptyArray(Schema.NonEmptyString).annotate({
+    identifier: "McpServersPath",
+    title: "MCP Servers Path",
+    description: "Object key path containing MCP server entries in a native config file.",
+    examples: [["mcpServers"], ["mcp", "servers"]],
 });
 /** @experimental This API is unstable and may change without notice. */
 export const McpTargetAttributionSchema = Schema.Literals(["shared", "agent"]).annotate({
@@ -547,6 +575,8 @@ export const McpTargetAttributionSchema = Schema.Literals(["shared", "agent"]).a
 });
 /** @experimental This API is unstable and may change without notice. */
 export const McpConfigTargetSchema = Schema.Struct({
+    /** Explicit captured native root for a resolved runtime destination. */
+    nativeRoot: Schema.optionalKey(Schema.NonEmptyString),
     scope: ScopeSchema,
     path: Schema.NonEmptyString,
     format: ConfigFileFormatSchema,
@@ -625,6 +655,9 @@ export const McpUrlKeyMapSchema = Schema.Struct({
 });
 /** @experimental This API is unstable and may change without notice. */
 export const McpRemoteDialectSchema = Schema.Struct({
+    implicitTransport: Schema.optionalKey(Schema.Literal("http-or-sse")).annotate({
+        description: "A documented URL-only remote entry selects HTTP or SSE through the endpoint, without an explicit transport discriminator.",
+    }),
     typeField: McpTypeFieldSchema,
     urlKey: McpUrlKeyMapSchema,
     headersKey: Schema.NullOr(Schema.NonEmptyString),
@@ -636,20 +669,26 @@ export const McpRemoteDialectSchema = Schema.Struct({
     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,
+export const McpEntryDialectSchema = Schema.Struct({
     activationField: McpActivationFieldSchema,
-    targets: Schema.Array(McpConfigTargetSchema),
     stdio: Schema.NullOr(McpStdioDialectSchema),
     remote: Schema.NullOr(McpRemoteDialectSchema),
+}).annotate({
+    identifier: "McpEntryDialect",
+    title: "Native MCP Entry Dialect",
+    description: "Verified native entry grammar, independent of AXM writer support.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const McpConfigSchema = Schema.Struct({
+    locationIds: Schema.NonEmptyArray(Schema.NonEmptyString).check(Schema.isUnique()),
 }).annotate({
     identifier: "McpConfig",
-    title: "MCP Config",
-    description: "Prescriptive config writer metadata for an agent's MCP support.",
+    title: "MCP Writer Locations",
+    description: "Native configuration locations selected by the AXM writer.",
 });
 /** @experimental This API is unstable and may change without notice. */
 export const McpEnvExpansionSchema = Schema.Struct({
-    variables: Schema.Literals(["none", "braced"]),
+    variables: Schema.Literals(["none", "braced", "env-tag"]),
     defaults: Schema.Boolean,
 }).annotate({
     identifier: "McpEnvExpansion",
@@ -663,6 +702,8 @@ const McpUnavailableCapabilityStruct = Schema.Struct({
 const McpNativeWithTransportsSchema = Schema.Struct({
     ...AvailableSpecTrackedNativeCapabilityFields,
     transports: NonEmptyMcpTransportsSchema,
+    entryDialect: Schema.NullOr(McpEntryDialectSchema),
+    locations: Schema.Array(NativeConfigReadLocationSchema),
     mcpEnvExpansion: Schema.optionalKey(McpEnvExpansionSchema),
 });
 const McpAvailableCapabilityStruct = Schema.Struct({
@@ -679,12 +720,39 @@ const McpExtensionCapabilitySchemaWithChecks = McpExtensionCapabilityStruct.pipe
     if (activeSourcesIssue !== undefined)
         issues.push(activeSourcesIssue);
     const writer = capability.axm.writer;
+    if ("locations" in capability.native) {
+        issues.push(...nativeConfigReferenceIssues(capability.native.locations, writer?.config.locationIds ?? [], ["axm", "writer", "config", "locationIds"]));
+        if (capability.native.locations.some((location) => location.keyPath === undefined))
+            issues.push({
+                path: ["native", "locations"],
+                issue: "MCP reader locations require an explicit servers-container keyPath.",
+            });
+        if (capability.native.locations.some((location) => location.attribution === undefined))
+            issues.push({
+                path: ["native", "locations"],
+                issue: "MCP reader locations require explicit attribution.",
+            });
+        const selected = new Set(writer?.config.locationIds ?? []);
+        if (capability.native.locations.some((location) => selected.has(location.id) && !Schema.is(McpServersPathSchema)(location.keyPath))) {
+            issues.push({
+                path: ["native", "locations"],
+                issue: "Writable MCP locations require a nonempty servers-container key path.",
+            });
+        }
+    }
     if (writer === null || !("transports" in capability.native))
         return issues;
-    const config = writer.config;
+    const config = capability.native.entryDialect;
+    if (config === null) {
+        issues.push({
+            path: ["native", "entryDialect"],
+            issue: "An MCP writer requires a verified native entry dialect.",
+        });
+        return issues;
+    }
     if (capability.native.transports.includes("stdio") && config.stdio === null) {
         issues.push({
-            path: ["axm", "writer", "config", "stdio"],
+            path: ["native", "entryDialect", "stdio"],
             issue: "MCP stdio config is required when stdio transport is supported.",
         });
     }
@@ -692,7 +760,7 @@ const McpExtensionCapabilitySchemaWithChecks = McpExtensionCapabilityStruct.pipe
         capability.native.transports.includes("sse")) &&
         config.remote === null) {
         issues.push({
-            path: ["axm", "writer", "config", "remote"],
+            path: ["native", "entryDialect", "remote"],
             issue: "MCP remote config is required when http or sse transport is supported.",
         });
     }
@@ -730,17 +798,6 @@ export const PermissionGrammarStyleSchema = Schema.Literals([
     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",
@@ -919,30 +976,39 @@ export const HookCommandNameSerializationSchema = Schema.Literals(["omit", "mani
     examples: ["omit", "manifest"],
 });
 /** @experimental This API is unstable and may change without notice. */
-export const HooksWriterSchema = Schema.Struct({
+export const HookEntryDialectSchema = 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: "HookEntryDialect",
+    title: "Native Hook Entry Dialect",
+    description: "Verified native Hook entry grammar, independent of AXM writer support.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const HooksWriterSchema = Schema.Struct({
+    locationIds: Schema.NonEmptyArray(Schema.NonEmptyString).check(Schema.isUnique()),
+    eventMap: Schema.Literal("native.events"),
 }).annotate({
     identifier: "HooksWriter",
     title: "Hooks Writer",
-    description: "Parameterized AXM hook writer metadata derived from native hook catalog data.",
+    description: "Native Hook locations and event mappings selected by the AXM writer.",
 });
 const HooksAvailableNativeCapabilitySchema = Schema.Struct({
     ...AvailableNativeCapabilityBaseFields,
     mechanism: NonEmptyHookMechanismFamiliesSchema,
-    configFiles: Schema.Array(ConfigFileLocationSchema),
+    entryDialect: Schema.NullOr(HookEntryDialectSchema),
+    locations: Schema.Array(NativeConfigReadLocationSchema),
     events: Schema.NonEmptyArray(HookEventMappingSchema),
     tools: Schema.Array(HookToolMappingSchema),
 });
 const HooksUnmodeledNativeCapabilitySchema = Schema.Struct({
     ...AvailableNativeCapabilityBaseFields,
     modeling: Schema.Literal("native-unmodeled"),
+    entryDialect: Schema.NullOr(HookEntryDialectSchema),
+    locations: Schema.Array(NativeConfigReadLocationSchema),
 });
 const HooksExtensionCapabilityStruct = Schema.Struct({
     native: Schema.Union([
@@ -955,6 +1021,22 @@ const HooksExtensionCapabilityStruct = Schema.Struct({
 /** @experimental This API is unstable and may change without notice. */
 export const HooksExtensionCapabilitySchema = HooksExtensionCapabilityStruct.pipe(Schema.check(Schema.makeFilter((capability) => {
     const issues = [];
+    if ("locations" in capability.native) {
+        issues.push(...nativeConfigReferenceIssues(capability.native.locations, capability.axm.writer?.locationIds ?? [], ["axm", "writer", "locationIds"]));
+        const selected = new Set(capability.axm.writer?.locationIds ?? []);
+        if (capability.native.locations.some((location) => selected.has(location.id) && location.keyPath === undefined))
+            issues.push({
+                path: ["native", "locations"],
+                issue: "Writable Hook reader locations require a static keyPath.",
+            });
+    }
+    if (capability.axm.writer !== null &&
+        (!("entryDialect" in capability.native) || capability.native.entryDialect === null)) {
+        issues.push({
+            path: ["native", "entryDialect"],
+            issue: "A Hook writer requires a verified native entry dialect.",
+        });
+    }
     if (capability.axm.writer !== null && capability.native.sources.length === 0) {
         issues.push({
             path: ["native", "sources"],
@@ -1007,7 +1089,11 @@ export const PermissionCliFlagSchema = Schema.Struct({
     description: "Invocation-time flag that adjusts approval or sandbox behavior.",
 });
 const PermissionGrantStruct = Schema.Struct({
-    target: Schema.NonEmptyString,
+    destination: Schema.Union([
+        Schema.Struct({ kind: Schema.Literal("location"), locationId: Schema.NonEmptyString }),
+        Schema.Struct({ kind: Schema.Literal("invocation") }),
+        Schema.Struct({ kind: Schema.Literal("settings-ui") }),
+    ]),
     patch: Schema.NullOr(Schema.Unknown),
     template: Schema.NullOr(Schema.NonEmptyString),
 });
@@ -1025,7 +1111,7 @@ export const PermissionsExtensionCapabilitySchema = Schema.Struct({
         Schema.Struct({
             ...AvailableNativeCapabilityBaseFields,
             mechanism: NonEmptyPermissionMechanismsSchema,
-            configFiles: Schema.Array(ConfigFileLocationSchema),
+            locations: Schema.Array(NativeConfigReadLocationSchema),
             grammar: Schema.NullOr(PermissionGrammarSchema),
             prerequisites: Schema.Array(PermissionPrerequisiteSchema),
             cliFlags: Schema.Array(PermissionCliFlagSchema),
@@ -1034,7 +1120,9 @@ export const PermissionsExtensionCapabilitySchema = Schema.Struct({
     ]),
     axm: axmCapabilityStateSchema(Schema.Struct({ grants: Schema.Record(Schema.String, PermissionGrantSchema) }), "PermissionsAxmState"),
 })
-    .pipe(Schema.check(Schema.makeFilter(requireSourcesForActiveAxmSupport)))
+    .pipe(Schema.check(Schema.makeFilter(requireSourcesForActiveAxmSupport)), Schema.check(Schema.makeFilter((capability) => "locations" in capability.native
+    ? nativeConfigReferenceIssues(capability.native.locations, Object.values(capability.axm.writer?.grants ?? {}).flatMap((grant) => grant.destination.kind === "location" ? [grant.destination.locationId] : []), ["axm", "writer", "grants"])
+    : undefined)))
     .annotate({
     identifier: "PermissionsExtensionCapability",
     title: "Permissions Capability",
@@ -1159,9 +1247,11 @@ export const AgentSchema = AgentStruct.pipe(Schema.check(Schema.makeFilter((agen
     const issues = [];
     if ("kind" in agent.instructions.native &&
         agent.instructions.native.kind === "agents-md" &&
-        agent.instructions.native.files[0] !== "AGENTS.md") {
+        agent.instructions.native.locations.some((location) => location.scope === "project" &&
+            location.role === "primary" &&
+            (location.shape !== "file" || location.path !== "AGENTS.md"))) {
         issues.push({
-            path: ["instructions", "native", "files"],
+            path: ["instructions", "native", "locations"],
             issue: 'instructions.kind "agents-md" requires AGENTS.md.',
         });
     }
@@ -1198,8 +1288,7 @@ export const AgentSchema = AgentStruct.pipe(Schema.check(Schema.makeFilter((agen
         });
     }
     if (hostedOnly &&
-        capabilitySlots.some((capability) => "directory" in capability.native ||
-            ("configFiles" in capability.native && capability.native.configFiles.length > 0))) {
+        capabilitySlots.some((capability) => "locations" in capability.native && capability.native.locations.length > 0)) {
         issues.push({
             path: ["capabilities"],
             issue: "Hosted-only agents cannot declare local capability paths.",

package/dist/src/unstable/agents/registry.d.ts

@@ -8,7 +8,7 @@
  */
 import type { AgentRegistry } from "./types.js";
 /**
- * Derived descriptors for all known AI coding agents, including the synthetic universal target.
+ * Derived descriptors for all known configurable coding agents.
  *
  * Keys are agent IDs, values are full descriptor objects.
  * Paths are pre-expanded at module initialization.

package/dist/src/unstable/agents/registry.js

@@ -9,19 +9,8 @@
 import * as Record from "effect/Record";
 import { CONFIGURABLE_AGENTS_BY_ID } from "../agent-capabilities/catalog.js";
 import { deriveAgentDescriptor } from "../agent-capabilities/derive.js";
-import { UNIVERSAL_SKILLS_DIR } from "../extensions/universal-skills-dir.js";
-const UNIVERSAL_AGENT_DESCRIPTOR = {
-    id: "universal",
-    name: "Universal",
-    rootDir: undefined,
-    skills: {
-        dir: UNIVERSAL_SKILLS_DIR,
-        additionalReadPaths: [],
-    },
-    detection: { project: { markers: [] }, user: { markers: [] } },
-};
 /**
- * Derived descriptors for all known AI coding agents, including the synthetic universal target.
+ * Derived descriptors for all known configurable coding agents.
  *
  * Keys are agent IDs, values are full descriptor objects.
  * Paths are pre-expanded at module initialization.
@@ -30,6 +19,5 @@ const UNIVERSAL_AGENT_DESCRIPTOR = {
  */
 export const AGENT_DESCRIPTORS = {
     ...Record.map(CONFIGURABLE_AGENTS_BY_ID, deriveAgentDescriptor),
-    universal: UNIVERSAL_AGENT_DESCRIPTOR,
 };
 //# sourceMappingURL=registry.js.map

package/dist/src/unstable/agents/types.d.ts

@@ -6,17 +6,16 @@
  */
 import type { Record } from "effect";
 import { CONFIGURABLE_AGENT_IDS, type ConfigurableAgentId } from "../agent-capabilities/identity.js";
-import type { DetectionMarker, Scope, ScopeDetection, SkillReadPath } from "../agent-capabilities/schema.js";
+import type { DetectionMarker, Scope, ScopeDetection, NativeReadLocation } from "../agent-capabilities/schema.js";
 /**
  * Skills-specific configuration for an agent.
  *
  * @experimental This API is unstable and may change without notice.
  */
 export interface AgentSkillsDescriptor {
-    /** Skills directory, relative to cwd (e.g., ".claude/skills") */
-    readonly dir: string;
-    /** Additional native directories read for discovery. AXM never writes to these paths. */
-    readonly additionalReadPaths: ReadonlyArray<SkillReadPath>;
+    readonly locations: ReadonlyArray<NativeReadLocation>;
+    readonly scopes: ReadonlyArray<Scope>;
+    readonly writerSupported: boolean;
 }
 /**
  * Subagents-specific configuration for an agent.
@@ -24,18 +23,9 @@ export interface AgentSkillsDescriptor {
  * @experimental This API is unstable and may change without notice.
  */
 export interface AgentSubagentsDescriptor {
-    /** Subagents directory, relative to cwd (e.g., ".claude/agents") */
-    readonly dir: string;
-    /**
-     * Scopes the agent itself supports for subagents. See
-     * The scopes the agent itself supports for subagents.
-     */
+    readonly locations: ReadonlyArray<NativeReadLocation>;
     readonly scopes: ReadonlyArray<Scope>;
-    /**
-     * When true, the path is a single file (e.g., ".roomodes") rather than a
-     * directory containing subagent files.
-     */
-    readonly isFile?: boolean;
+    readonly writerSupported: boolean;
 }
 /**
  * Workspace instruction-file convention for one coding agent.
@@ -48,19 +38,13 @@ export interface AgentSubagentsDescriptor {
  *
  * @experimental
  */
-export type AgentInstructionsDescriptor = {
-    readonly kind: "agents-md";
-    readonly rulesDir?: string;
-} | {
-    readonly kind: "own-file";
-    readonly file: string;
+export interface AgentInstructionsDescriptor {
+    readonly kind: "agents-md" | "own-file" | "rules-dir";
+    readonly locations: ReadonlyArray<NativeReadLocation>;
+    readonly scopes: ReadonlyArray<Scope>;
+    readonly writerSupported: boolean;
     readonly importSyntax?: "at-path";
-    readonly rulesDir?: string;
-} | {
-    readonly kind: "rules-dir";
-    readonly dir: string;
-    readonly format: "frontmatter";
-};
+}
 /** @experimental This API is unstable and may change without notice. */
 export type AgentDetectionMarker = DetectionMarker;
 /** @experimental This API is unstable and may change without notice. */
@@ -74,8 +58,8 @@ export interface AgentDetectionDescriptor {
 }
 /** @experimental This API is unstable and may change without notice. */
 export { CONFIGURABLE_AGENT_IDS, type ConfigurableAgentId };
-/** Configurable agents plus the synthetic universal materialization target. @experimental */
-export declare const MATERIALIZATION_TARGET_IDS: readonly ["adal", "aider-desk", "amp", "antigravity", "antigravity-cli", "augment", "claude-code", "cline", "codearts-agent", "codebuddy", "codemaker", "codestudio", "codex", "command-code", "continue", "cortex", "crush", "cursor", "deepagents", "devin", "dexto", "droid", "firebender", "forgecode", "gemini-cli", "github-copilot-cli", "goose", "grok-cli", "hermes", "ibm-bob", "iflow-cli", "junie", "lingma", "kilo", "kimi-cli", "kiro-cli", "kode", "mcpjam", "minimax-code", "mistral-vibe", "mux", "neovate", "openclaw", "opencode", "openhands", "ona", "pi", "pochi", "qoder", "qoder-cn", "qwen-code", "replit", "roo", "rovodev", "tabnine-cli", "trae-cn", "trae", "warp", "windsurf", "zencoder", "zed", "zenflow", "universal"];
+/** Real agents that can participate in native materialization. @experimental */
+export declare const MATERIALIZATION_TARGET_IDS: readonly ["adal", "aider-desk", "amp", "antigravity", "antigravity-cli", "augment", "claude-code", "cline", "codearts-agent", "codebuddy", "codemaker", "codestudio", "codex", "command-code", "continue", "cortex", "crush", "cursor", "deepagents", "devin", "dexto", "droid", "firebender", "forgecode", "gemini-cli", "github-copilot-cli", "goose", "grok-cli", "hermes", "ibm-bob", "iflow-cli", "junie", "lingma", "kilo", "kimi-cli", "kiro-cli", "kode", "mcpjam", "minimax-code", "mistral-vibe", "mux", "neovate", "openclaw", "opencode", "openhands", "ona", "pi", "pochi", "qoder", "qoder-cn", "qwen-code", "replit", "roo", "rovodev", "tabnine-cli", "trae-cn", "trae", "warp", "windsurf", "zencoder", "zed", "zenflow"];
 /** @experimental This API is unstable and may change without notice. */
 export type MaterializationTargetId = (typeof MATERIALIZATION_TARGET_IDS)[number];
 /**
@@ -88,25 +72,9 @@ export interface AgentDescriptor {
     readonly id: MaterializationTargetId;
     /** Human-readable display name (e.g., "Claude Code") */
     readonly name: string;
-    /**
-     * Per-agent native configuration root, relative to the workspace root
-     * (e.g., `.claude` for Claude Code, `.cursor` for Cursor). The
-     * workspace read-model scanners look for this agent's `settings.json`,
-     * `mcp.json`, and other native config files inside this directory.
-     *
-     * Three states (with `exactOptionalPropertyTypes: true`):
-     *
-     * - `string` — use this directory as the explicit native config root.
-     * - omitted (key not present) — fall back to the first segment of
-     *   `skills.dir` when a verified Skill surface exists, otherwise `.<id>`.
-     * - `undefined` — explicit opt-out. Scanners SHALL NOT attempt to
-     *   discover native config for this agent. Use this when an agent's
-     *   first `skills.dir` segment collides with another agent's (e.g.,
-     *   several agents share a parent like `.agents`) and there is no
-     *   authoritative answer about the real native config root.
-     */
+    /** Explicit project native configuration root. Undefined suppresses root discovery. */
     readonly rootDir?: string | undefined;
-    /** Skills installation configuration, omitted when AXM has no verified writable surface. */
+    /** Native Skill reader declarations, independent of AXM writer support. */
     readonly skills?: AgentSkillsDescriptor;
     /** Subagents installation configuration (optional — not all agents support subagents) */
     readonly subagents?: AgentSubagentsDescriptor;

package/dist/src/unstable/agents/types.js

@@ -10,6 +10,6 @@ import { CONFIGURABLE_AGENT_IDS, } from "../agent-capabilities/identity.js";
 // -----------------------------------------------------------------------------
 /** @experimental This API is unstable and may change without notice. */
 export { CONFIGURABLE_AGENT_IDS };
-/** Configurable agents plus the synthetic universal materialization target. @experimental */
-export const MATERIALIZATION_TARGET_IDS = [...CONFIGURABLE_AGENT_IDS, "universal"];
+/** Real agents that can participate in native materialization. @experimental */
+export const MATERIALIZATION_TARGET_IDS = [...CONFIGURABLE_AGENT_IDS];
 //# sourceMappingURL=types.js.map

package/dist/src/unstable/extensions/common.d.ts

@@ -677,8 +677,7 @@ export { AgentIdSchema };
 /**
  * Agent identifiers users may persist in `axm.json`.
  *
- * Synthetic materialization targets such as `universal` are known agents, but
- * they are injected by repository code rather than configured by users.
+ * Shared native locations are policy, not additional agent identities.
  *
  * @experimental This API is unstable and may change without notice.
  */