@kuznai/inception-engine 0.19.0 → 0.21.0

package/dist/{core → src/core}/adapters/frontmatter.js

@@ -26,10 +26,10 @@ export function splitFrontmatter(raw) {
 export function parseFrontmatterDocument(raw) {
     const { frontmatter, body } = splitFrontmatter(raw);
     if (!(frontmatter || raw.startsWith("---"))) {
-        return { attributes: {}, body };
+        return { attributes: {}, body, hasFrontmatter: false };
     }
     const attributes = YAML.parse(frontmatter);
-    return { attributes: (attributes || {}), body };
+    return { attributes: (attributes || {}), body, hasFrontmatter: true };
 }
 /**
  * Serializes an object to a YAML block.
@@ -42,9 +42,15 @@ export function serializeFrontmatter(data) {
  * Builds the full content of a frontmatter-bearing Markdown file.
  */
 export function buildFrontmatterDocument(frontmatter, body = "") {
+    return buildMarkdownDocument(frontmatter, body, { hasFrontmatter: true });
+}
+export function buildMarkdownDocument(frontmatter, body = "", options = {}) {
+    const cleanBody = body.trimStart();
+    if (Object.keys(frontmatter).length === 0 && !options.hasFrontmatter) {
+        return cleanBody;
+    }
     const serialized = serializeFrontmatter(frontmatter);
     // Ensure exactly one newline after the closing delimiter before the body
-    const cleanBody = body.trimStart();
     const separator = cleanBody ? "\n\n" : "\n";
     return `---\n${serialized}\n---\n${separator}${cleanBody}`;
 }
@@ -58,17 +64,28 @@ function createAtomicTempPath(targetPath) {
  * Returns `{ attributes: {}, body: "" }` if the file does not exist.
  */
 export async function readFrontmatterFile(filePath) {
+    const document = await readFrontmatterDocumentFile(filePath);
+    return { attributes: document.attributes, body: document.body };
+}
+export async function readFrontmatterDocumentFile(filePath) {
     let raw;
     try {
         raw = await readFile(filePath, "utf-8");
     }
     catch (err) {
         const code = err.code;
-        if (code === "ENOENT")
-            return { attributes: {}, body: "" };
+        if (code === "ENOENT") {
+            return {
+                exists: false,
+                hasFrontmatter: false,
+                attributes: {},
+                body: "",
+            };
+        }
         throw err;
     }
-    return parseFrontmatterDocument(raw);
+    const parsed = parseFrontmatterDocument(raw);
+    return { exists: true, ...parsed };
 }
 /**
  * Atomically writes a Markdown file with the given frontmatter and optional

package/dist/src/core/adapters/index.js

@@ -0,0 +1,25 @@
+import { compileAgentDefinitionActions, compileAgentDefinitionReverts, } from "./agent-definitions.js";
+import { compileMcpServerActions, compileMcpServerReverts } from "./mcp.js";
+import { compilePermissionsActions, compilePermissionsReverts, } from "./permissions.js";
+import { compileAgentRuleActions, compileAgentRuleReverts } from "./rules.js";
+export { compileAgentDefinitionReverts, compileAgentRuleReverts, compileMcpServerReverts, compilePermissionsReverts, };
+async function compileAll(entries, fn) {
+    const results = await Promise.all(entries.map(fn));
+    return {
+        actions: results.flatMap((r) => r.actions),
+        warnings: results.flatMap((r) => r.warnings),
+    };
+}
+export async function compileAdapterActions(mcpServers, agentRules, permissions, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo, agentDefinitions, workspace) {
+    const actions = [];
+    const warnings = [];
+    const [mcp, rules, perms, defs] = await Promise.all([
+        compileAll(mcpServers, (entry) => compileMcpServerActions(entry, detectedAgents, home, repo, workspace)),
+        compileAll(agentRules, (entry) => compileAgentRuleActions(entry, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo, workspace)),
+        compileAll(permissions, (entry) => compilePermissionsActions(entry, detectedAgents, home)),
+        compileAll(agentDefinitions ?? [], (entry) => compileAgentDefinitionActions(entry, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo, workspace)),
+    ]);
+    actions.push(...mcp.actions, ...rules.actions, ...perms.actions, ...defs.actions);
+    warnings.push(...mcp.warnings, ...rules.warnings, ...perms.warnings, ...defs.warnings);
+    return { actions, warnings };
+}

package/dist/{core → src/core}/adapters/mcp.js

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { AGENT_REGISTRY_BY_ID } from "../../config/agents.js";
+import { planCapabilityForDeploy, resolveCapabilitySurface, } from "../capabilities.js";
 import { getPlatformKey, resolvePlaceholders } from "../resolve.js";
 import { validateMcpServerConfigShape } from "../validation.js";
 /**
@@ -53,26 +53,26 @@ export function compileMcpServerActions(entry, detectedAgents, home, repo, works
     for (const agentId of entry.agents) {
         if (!detectedAgents.includes(agentId))
             continue;
-        const agent = AGENT_REGISTRY_BY_ID[agentId];
-        const support = agent?.mcpSupport;
-        if (!support || support.status === "unsupported") {
-            warnings.push({
-                kind: "confidence",
-                message: `mcpServers: agent "${agentId}" uses ${support?.schemaLabel ?? "an unsupported MCP schema"} and ${support?.status === "unsupported" ? support.reason : "does not expose a supported MCP adapter"} — skipping "${entry.name}"`,
-            });
+        const plan = planCapabilityForDeploy({
+            agentId,
+            capability: "mcpServers",
+            entryName: entry.name,
+            targetAgentIds: entry.agents,
+            scope: entry.scope,
+        });
+        if (plan.outcome === "warn") {
+            warnings.push(plan.warning);
             continue;
         }
-        if (support.status === "planned") {
-            warnings.push({
-                kind: "confidence",
-                message: `mcpServers: agent "${agentId}" MCP support is planned via ${support.plannedSurface} — skipping "${entry.name}" until that surface is implemented`,
-            });
+        if (plan.outcome === "native" || plan.outcome === "redundant")
+            continue;
+        const support = resolveCapabilitySurface(agentId, "mcpServers", entry.scope).support;
+        if (!support)
             continue;
-        }
         validateMcpServerConfigShape(entry.config, entry.name, agentId);
         const rawTarget = resolvePlaceholders(support.path[platform], entry.name, home, repo, workspace);
         const resolvedTarget = path.resolve(rawTarget);
-        const confidence = agent.provenance.mcpConfig ?? "provisional";
+        const confidence = plan.confidence ?? "provisional";
         const mcpPatchKey = support.mcpPatchKey ?? "mcpServers";
         actions.push(buildMcpDeployAction(entry, agentId, resolvedTarget, confidence, mcpPatchKey));
     }
@@ -84,11 +84,8 @@ export function compileMcpServerReverts(entry, agentFilter, home, repo, workspac
     for (const agentId of entry.agents) {
         if (agentFilter && !agentFilter.includes(agentId))
             continue;
-        const agent = AGENT_REGISTRY_BY_ID[agentId];
-        const support = agent?.mcpSupport;
-        if (!support ||
-            support.status === "unsupported" ||
-            support.status === "planned")
+        const support = resolveCapabilitySurface(agentId, "mcpServers", entry.scope).support;
+        if (!support)
             continue;
         const rawTarget = resolvePlaceholders(support.path[platform], entry.name, home, repo, workspace);
         const target = path.resolve(rawTarget);

package/dist/{core → src/core}/adapters/permissions.js

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { AGENT_REGISTRY_BY_ID } from "../../config/agents.js";
+import { planCapabilityForDeploy, resolveCapabilitySurface, } from "../capabilities.js";
 import { getPlatformKey, resolvePlaceholders } from "../resolve.js";
 import { validatePermissionsConfigShape } from "../validation.js";
 function isTomlTarget(targetPath) {
@@ -12,26 +12,25 @@ export function compilePermissionsActions(entry, detectedAgents, home) {
     for (const agentId of entry.agents) {
         if (!detectedAgents.includes(agentId))
             continue;
-        const agent = AGENT_REGISTRY_BY_ID[agentId];
-        const support = agent?.permissionsSupport;
-        if (!support || support.status === "unsupported") {
-            warnings.push({
-                kind: "confidence",
-                message: `permissions: agent "${agentId}" ${support?.status === "unsupported" ? support.reason : "does not expose a supported permissions adapter"} — skipping "${entry.name}"`,
-            });
+        const plan = planCapabilityForDeploy({
+            agentId,
+            capability: "permissions",
+            entryName: entry.name,
+            targetAgentIds: entry.agents,
+        });
+        if (plan.outcome === "warn") {
+            warnings.push(plan.warning);
             continue;
         }
-        if (support.status === "planned") {
-            warnings.push({
-                kind: "confidence",
-                message: `permissions: agent "${agentId}" permissions support is planned via ${support.plannedSurface} — skipping "${entry.name}" until that surface is implemented`,
-            });
+        if (plan.outcome === "native" || plan.outcome === "redundant")
+            continue;
+        const support = resolveCapabilitySurface(agentId, "permissions").support;
+        if (!support)
             continue;
-        }
         validatePermissionsConfigShape(entry.config, entry.name, agentId);
         const rawTarget = resolvePlaceholders(support.path[platform], entry.name, home);
         const resolvedTarget = path.resolve(rawTarget);
-        const confidence = agent.provenance.permissions ?? "provisional";
+        const confidence = plan.confidence ?? "provisional";
         if (isTomlTarget(resolvedTarget)) {
             actions.push({
                 kind: "toml-patch",
@@ -61,11 +60,8 @@ export function compilePermissionsReverts(entry, agentFilter, home) {
     for (const agentId of entry.agents) {
         if (agentFilter && !agentFilter.includes(agentId))
             continue;
-        const agent = AGENT_REGISTRY_BY_ID[agentId];
-        const support = agent?.permissionsSupport;
-        if (!support ||
-            support.status === "unsupported" ||
-            support.status === "planned")
+        const support = resolveCapabilitySurface(agentId, "permissions").support;
+        if (!support)
             continue;
         const rawTarget = resolvePlaceholders(support.path[platform], entry.name, home);
         const target = path.resolve(rawTarget);

package/dist/{core → src/core}/adapters/rules.js

@@ -1,44 +1,21 @@
 import path from "node:path";
-import { AGENT_REGISTRY_BY_ID } from "../../config/agents.js";
+import { planCapabilityForDeploy, resolveCapabilitySurface, } from "../capabilities.js";
 import { getPlatformKey, resolvePlaceholders } from "../resolve.js";
 import { validateAgentRuleMarkdownPath, validateInstructionFileRequirements, validateSourceFile, validateSourcePath, } from "../validation.js";
-function resolveRulesSupport(agentId, scope) {
-    const agent = AGENT_REGISTRY_BY_ID[agentId];
-    if (scope === "repo") {
-        return agent?.agentRulesRepoSupport ?? agent?.agentRulesSupport;
-    }
-    if (scope === "workspace") {
-        return (agent?.agentRulesWorkspaceSupport ??
-            agent?.agentRulesRepoSupport ??
-            agent?.agentRulesSupport);
-    }
-    return agent?.agentRulesSupport;
-}
 function resolveAgentTarget(agentId, entry, home, repo, platform, workspace, allTargetAgentIds) {
-    const support = resolveRulesSupport(agentId, entry.scope);
-    if (!support || support.status === "unsupported") {
-        return {
-            kind: "confidence",
-            message: `agentRules: agent "${agentId}" uses ${support?.schemaLabel ?? "an unsupported instruction schema"} (unsupported) and ${support?.status === "unsupported" ? support.reason : "does not expose a supported rules adapter"} — skipping "${entry.name}"`,
-        };
-    }
-    if (support.status === "planned") {
-        return {
-            kind: "confidence",
-            message: `agentRules: agent "${agentId}" rules support is planned via ${support.plannedSurface} — skipping "${entry.name}" until that surface is implemented`,
-        };
-    }
-    // shared-via: when requiresPrimary is set and the primary agent is absent
-    // from the target list, emit a guidance warning instead of deploying.
-    if (support.surfaceKind?.kind === "shared-via" &&
-        support.surfaceKind.requiresPrimary &&
-        allTargetAgentIds &&
-        !allTargetAgentIds.includes(support.surfaceKind.via)) {
-        return {
-            kind: "confidence",
-            message: `agentRules: agent "${agentId}" reads this surface via "${support.surfaceKind.via}" — add "${support.surfaceKind.via}" to the entry's agents list to deploy to this surface, or deploy via the "${support.surfaceKind.via}" agentRules target instead`,
-        };
-    }
+    const plan = planCapabilityForDeploy({
+        agentId,
+        capability: "agentRules",
+        entryName: entry.name,
+        targetAgentIds: allTargetAgentIds ?? [agentId],
+        scope: entry.scope,
+    });
+    if (plan.outcome === "warn")
+        return plan.warning;
+    if (plan.outcome === "native" || plan.outcome === "redundant")
+        return null;
+    const surface = resolveCapabilitySurface(agentId, "agentRules", entry.scope);
+    const support = surface.support;
     if (entry.scope === "repo" && !repo) {
         return {
             kind: "confidence",
@@ -51,11 +28,10 @@ function resolveAgentTarget(agentId, entry, home, repo, platform, workspace, all
             message: `agentRules: scope "workspace" requires a workspace or repository path but none was resolved — skipping "${entry.name}" for agent "${agentId}"`,
         };
     }
-    const agent = AGENT_REGISTRY_BY_ID[agentId];
     return {
         agentId,
-        confidence: agent?.provenance.agentRules ?? "provisional",
-        target: resolvePlaceholders(support.path[platform], entry.name, home, repo, workspace),
+        confidence: plan.confidence,
+        target: resolvePlaceholders(support?.path[platform] ?? [], entry.name, home, repo, workspace),
     };
 }
 export async function compileAgentRuleActions(entry, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo, workspace) {
@@ -69,6 +45,9 @@ export async function compileAgentRuleActions(entry, sourceDir, resolvedSourceDi
     }
     for (const agentId of targetAgents) {
         const result = resolveAgentTarget(agentId, entry, home, repo, platform, workspace, targetAgents);
+        if (result === null) {
+            continue;
+        }
         if ("kind" in result) {
             warnings.push(result);
         }
@@ -85,12 +64,10 @@ export async function compileAgentRuleActions(entry, sourceDir, resolvedSourceDi
     const seenTargetPaths = new Set();
     const dedupedTargets = [];
     for (const t of supportedTargets) {
-        const sup = resolveRulesSupport(t.agentId, entry.scope);
-        if (sup?.status === "supported" &&
-            sup.surfaceKind?.kind === "shared-via" &&
-            supportedTargets.some((o) => o.agentId ===
-                sup.surfaceKind.via &&
-                o.target === t.target)) {
+        const surface = resolveCapabilitySurface(t.agentId, "agentRules", entry.scope);
+        if (surface.surfaceKind === "shared-via" &&
+            surface.sharedVia &&
+            supportedTargets.some((o) => o.agentId === surface.sharedVia && o.target === t.target)) {
             // Primary agent is present and writes the same target — skip rider.
             continue;
         }
@@ -125,10 +102,9 @@ export function compileAgentRuleReverts(entry, agentFilter, home, repo, workspac
     for (const agentId of entry.agents) {
         if (agentFilter && !agentFilter.includes(agentId))
             continue;
-        const support = resolveRulesSupport(agentId, entry.scope);
-        if (!support ||
-            support.status === "unsupported" ||
-            support.status === "planned") {
+        const surface = resolveCapabilitySurface(agentId, "agentRules", entry.scope);
+        const support = surface.support;
+        if (surface.supportStatus !== "supported" || !support) {
             continue;
         }
         if (entry.scope === "repo" && !repo)

package/dist/src/core/capabilities.d.ts

@@ -0,0 +1,47 @@
+import type { AgentId, AgentSurfaceSupport, CapabilityKind, Confidence, PlanWarning, SupportedAgentSurface } from "../types.ts";
+type CapabilityScope = "global" | "repo" | "workspace";
+export interface ResolvedCapabilitySurface {
+    agentId: AgentId;
+    capability: CapabilityKind;
+    supportStatus: "supported" | "unsupported" | "planned";
+    support?: SupportedAgentSurface;
+    supportRecord?: AgentSurfaceSupport;
+    confidence?: Confidence;
+    schemaLabel: string;
+    surfaceKind: "agent-specific" | "native" | "shared-via";
+    sharedVia?: AgentId;
+    requiresPrimary: boolean;
+    canDeployDirectlyWhenPrimaryAbsent: boolean;
+    includeInInitByDefault: boolean;
+    reason?: string;
+    plannedSurface?: string;
+}
+export type DeployCapabilityPlan = {
+    outcome: "action";
+    confidence?: Confidence;
+    support?: SupportedAgentSurface;
+} | {
+    outcome: "redundant";
+    confidence?: Confidence;
+    support?: SupportedAgentSurface;
+    sharedVia: AgentId;
+} | {
+    outcome: "warn";
+    warning: PlanWarning;
+} | {
+    outcome: "native";
+};
+export declare function resolveCapabilitySurface(agentId: AgentId, capability: CapabilityKind, scope?: CapabilityScope): ResolvedCapabilitySurface;
+export declare function planCapabilityForDeploy(opts: {
+    agentId: AgentId;
+    capability: CapabilityKind;
+    entryName: string;
+    targetAgentIds: AgentId[];
+    scope?: CapabilityScope;
+}): DeployCapabilityPlan;
+export declare function shouldInitIncludeAgent(agentId: AgentId, capability: CapabilityKind, scope?: CapabilityScope): boolean;
+export declare function describeCapabilityConfidence(agentId: AgentId, capability: CapabilityKind, scope?: CapabilityScope): {
+    confidence?: Confidence;
+    message: string | null;
+};
+export {};

package/dist/src/core/capabilities.js

@@ -0,0 +1,280 @@
+import { AGENT_REGISTRY_BY_ID } from "../config/agents.js";
+function resolveAgentRulesSupport(agentId, scope) {
+    const agent = AGENT_REGISTRY_BY_ID[agentId];
+    if (scope === "repo") {
+        return agent?.agentRulesRepoSupport ?? agent?.agentRulesSupport;
+    }
+    if (scope === "workspace") {
+        return (agent?.agentRulesWorkspaceSupport ??
+            agent?.agentRulesRepoSupport ??
+            agent?.agentRulesSupport);
+    }
+    return agent?.agentRulesSupport;
+}
+function resolveMcpSupport(agentId, scope) {
+    const agent = AGENT_REGISTRY_BY_ID[agentId];
+    if (scope === "repo") {
+        return agent?.mcpRepoSupport ?? agent?.mcpSupport;
+    }
+    if (scope === "workspace") {
+        return (agent?.mcpWorkspaceSupport ?? agent?.mcpRepoSupport ?? agent?.mcpSupport);
+    }
+    return agent?.mcpSupport;
+}
+function resolveAgentDefinitionsSupport(agentId, scope) {
+    const agent = AGENT_REGISTRY_BY_ID[agentId];
+    if (scope === "repo") {
+        return agent?.agentDefinitionsRepoSupport ?? agent?.agentDefinitionsSupport;
+    }
+    if (scope === "workspace") {
+        return (agent?.agentDefinitionsWorkspaceSupport ??
+            agent?.agentDefinitionsRepoSupport ??
+            agent?.agentDefinitionsSupport);
+    }
+    return agent?.agentDefinitionsSupport;
+}
+function capabilityLabel(capability) {
+    switch (capability) {
+        case "skills":
+            return "skills";
+        case "mcpServers":
+            return "mcpServers";
+        case "agentRules":
+            return "agentRules";
+        case "permissions":
+            return "permissions";
+        case "agentDefinitions":
+            return "agentDefinitions";
+    }
+}
+function capabilitySurfaceLabel(capability) {
+    switch (capability) {
+        case "skills":
+            return "skill";
+        case "mcpServers":
+            return "MCP";
+        case "agentRules":
+            return "rules";
+        case "permissions":
+            return "permissions";
+        case "agentDefinitions":
+            return "agent-definitions";
+    }
+}
+function resolveSkillsCapability(agentId) {
+    const agent = AGENT_REGISTRY_BY_ID[agentId];
+    if (agent.skills) {
+        return {
+            agentId,
+            capability: "skills",
+            supportStatus: "supported",
+            confidence: agent.provenance.skills ?? "provisional",
+            schemaLabel: "dedicated skill directory",
+            surfaceKind: "agent-specific",
+            requiresPrimary: false,
+            canDeployDirectlyWhenPrimaryAbsent: true,
+            includeInInitByDefault: true,
+        };
+    }
+    const via = agent.skillsSurfaceKind?.via;
+    return {
+        agentId,
+        capability: "skills",
+        supportStatus: "supported",
+        confidence: agent.provenance.skills,
+        schemaLabel: "shared native skill directory",
+        surfaceKind: agent.skillsSurfaceKind?.kind === "shared-via" ? "shared-via" : "native",
+        sharedVia: via,
+        requiresPrimary: true,
+        canDeployDirectlyWhenPrimaryAbsent: false,
+        includeInInitByDefault: false,
+    };
+}
+function getSurfaceRecordAndConfidence(agentId, capability, scope) {
+    const agent = AGENT_REGISTRY_BY_ID[agentId];
+    if (capability === "mcpServers") {
+        return {
+            supportRecord: resolveMcpSupport(agentId, scope),
+            confidence: agent.provenance.mcpConfig,
+        };
+    }
+    if (capability === "agentRules") {
+        return {
+            supportRecord: resolveAgentRulesSupport(agentId, scope),
+            confidence: agent.provenance.agentRules,
+        };
+    }
+    if (capability === "permissions") {
+        return {
+            supportRecord: agent.permissionsSupport,
+            confidence: agent.provenance.permissions,
+        };
+    }
+    return {
+        supportRecord: resolveAgentDefinitionsSupport(agentId, scope),
+        confidence: agent.provenance.agentDefinitions,
+    };
+}
+function resolveUnsupportedSurface(agentId, capability, supportRecord, confidence) {
+    return {
+        agentId,
+        capability,
+        supportStatus: "unsupported",
+        supportRecord,
+        confidence,
+        schemaLabel: supportRecord?.schemaLabel ?? "an unsupported surface",
+        surfaceKind: "agent-specific",
+        requiresPrimary: false,
+        canDeployDirectlyWhenPrimaryAbsent: false,
+        includeInInitByDefault: false,
+        reason: supportRecord?.status === "unsupported"
+            ? supportRecord.reason
+            : undefined,
+    };
+}
+function resolvePlannedSurface(agentId, capability, supportRecord, confidence) {
+    return {
+        agentId,
+        capability,
+        supportStatus: "planned",
+        supportRecord,
+        confidence,
+        schemaLabel: supportRecord.schemaLabel,
+        surfaceKind: "agent-specific",
+        requiresPrimary: false,
+        canDeployDirectlyWhenPrimaryAbsent: false,
+        includeInInitByDefault: false,
+        reason: supportRecord.reason,
+        plannedSurface: supportRecord.plannedSurface,
+    };
+}
+function resolveSupportedSurface(agentId, capability, supportRecord, confidence) {
+    const surfaceKind = supportRecord.surfaceKind?.kind ?? "agent-specific";
+    const sharedVia = supportRecord.surfaceKind?.kind === "shared-via"
+        ? supportRecord.surfaceKind.via
+        : undefined;
+    const requiresPrimary = supportRecord.surfaceKind?.kind === "shared-via" &&
+        supportRecord.surfaceKind.requiresPrimary === true;
+    return {
+        agentId,
+        capability,
+        supportStatus: "supported",
+        support: supportRecord,
+        supportRecord,
+        confidence: confidence ?? "provisional",
+        schemaLabel: supportRecord.schemaLabel,
+        surfaceKind,
+        sharedVia,
+        requiresPrimary,
+        canDeployDirectlyWhenPrimaryAbsent: surfaceKind !== "shared-via" || !requiresPrimary,
+        includeInInitByDefault: surfaceKind === "agent-specific",
+    };
+}
+export function resolveCapabilitySurface(agentId, capability, scope = "global") {
+    if (capability === "skills")
+        return resolveSkillsCapability(agentId);
+    const { supportRecord, confidence } = getSurfaceRecordAndConfidence(agentId, capability, scope);
+    if (!supportRecord || supportRecord.status === "unsupported") {
+        return resolveUnsupportedSurface(agentId, capability, supportRecord, confidence);
+    }
+    if (supportRecord.status === "planned") {
+        return resolvePlannedSurface(agentId, capability, supportRecord, confidence);
+    }
+    return resolveSupportedSurface(agentId, capability, supportRecord, confidence);
+}
+function createSurfaceWarning(surface, entryName) {
+    const label = capabilityLabel(surface.capability);
+    if (surface.supportStatus === "unsupported") {
+        return {
+            kind: "confidence",
+            message: `${label}: agent "${surface.agentId}" uses ${surface.schemaLabel} (unsupported) and ${surface.reason ?? "does not expose a supported adapter"} — skipping "${entryName}"`,
+        };
+    }
+    if (surface.supportStatus === "planned") {
+        return {
+            kind: "confidence",
+            message: `${label}: agent "${surface.agentId}" ${capabilitySurfaceLabel(surface.capability)} support is planned via ${surface.plannedSurface} — skipping "${entryName}" until that surface is implemented`,
+        };
+    }
+    if (surface.surfaceKind === "shared-via" && surface.sharedVia) {
+        return {
+            kind: "confidence",
+            message: `${label}: agent "${surface.agentId}" reads this surface via "${surface.sharedVia}" — add "${surface.sharedVia}" to the entry's agents list to deploy to this surface, or deploy via the "${surface.sharedVia}" ${label} target instead`,
+        };
+    }
+    return {
+        kind: "confidence",
+        message: `${label}: agent "${surface.agentId}" does not expose a directly deployable surface — skipping "${entryName}"`,
+    };
+}
+export function planCapabilityForDeploy(opts) {
+    const surface = resolveCapabilitySurface(opts.agentId, opts.capability, opts.scope);
+    if (surface.supportStatus !== "supported") {
+        return {
+            outcome: "warn",
+            warning: createSurfaceWarning(surface, opts.entryName),
+        };
+    }
+    if (surface.surfaceKind === "native") {
+        return { outcome: "native" };
+    }
+    if (surface.surfaceKind === "shared-via" && surface.sharedVia) {
+        if (opts.targetAgentIds.includes(surface.sharedVia)) {
+            return {
+                outcome: "redundant",
+                confidence: surface.confidence,
+                support: surface.support,
+                sharedVia: surface.sharedVia,
+            };
+        }
+        if (!surface.canDeployDirectlyWhenPrimaryAbsent) {
+            return {
+                outcome: "warn",
+                warning: createSurfaceWarning(surface, opts.entryName),
+            };
+        }
+    }
+    return {
+        outcome: "action",
+        confidence: surface.confidence,
+        support: surface.support,
+    };
+}
+export function shouldInitIncludeAgent(agentId, capability, scope = "global") {
+    return resolveCapabilitySurface(agentId, capability, scope)
+        .includeInInitByDefault;
+}
+export function describeCapabilityConfidence(agentId, capability, scope = "global") {
+    const surface = resolveCapabilitySurface(agentId, capability, scope);
+    if (surface.supportStatus === "planned") {
+        return {
+            confidence: surface.confidence,
+            message: `Agent "${agentId}" ${capabilitySurfaceLabel(capability)} support remains planned via ${surface.plannedSurface}.`,
+        };
+    }
+    if (surface.supportStatus === "unsupported") {
+        return {
+            confidence: surface.confidence,
+            message: `Agent "${agentId}" ${capabilitySurfaceLabel(capability)} surface is unsupported: ${surface.reason ?? surface.schemaLabel}.`,
+        };
+    }
+    if (surface.surfaceKind === "shared-via" && surface.sharedVia) {
+        return {
+            confidence: surface.confidence,
+            message: `Agent "${agentId}" ${capabilitySurfaceLabel(capability)} surface is shared through "${surface.sharedVia}"${surface.requiresPrimary ? " and requires the primary target to deploy" : ""}.`,
+        };
+    }
+    if (surface.confidence === "implementation-only") {
+        return {
+            confidence: surface.confidence,
+            message: `Agent "${agentId}" ${capabilitySurfaceLabel(capability)} support is implementation-only: behavior is based on registry inspection and local validation, not published documentation.`,
+        };
+    }
+    if (surface.confidence === "provisional") {
+        return {
+            confidence: surface.confidence,
+            message: `Agent "${agentId}" ${capabilitySurfaceLabel(capability)} support is provisional: behavior has not been independently verified.`,
+        };
+    }
+    return { confidence: surface.confidence, message: null };
+}