@gajae-code/coding-agent 0.16.3 → 0.16.6

package/src/extensibility/runtime-skill-discovery.ts

@@ -1,16 +1,31 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import { getPluginsDir, getTrustedHomeDir } from "@gajae-code/utils";
-import { findRepoRoot, invalidate as invalidateFsCache } from "../capability/fs";
+import {
+	getAgentDir,
+	getAgentProfileAuthority,
+	getTrustedHomeDir,
+	normalizePathForComparison,
+} from "@gajae-code/utils";
+import { findRepoRoot } from "../capability/fs";
 import type { Skill as CapabilitySkill } from "../capability/skill";
 import type { SkillsSettings } from "../config/settings-schema";
 import { resolveSkillScopeTrust } from "../config/skill-settings-defaults";
 import { scanClaudeProjectSkills, scanClaudeUserSkills } from "../discovery/claude";
+import { loadMarketplaceSkills } from "../discovery/claude-plugins";
 import { scanCodexProjectSkills, scanCodexUserSkills } from "../discovery/codex";
-import { compareSkillOrder, listClaudePluginRoots, SOURCE_PATHS, scanSkillsFromDir } from "../discovery/helpers";
-import { CANONICAL_GJC_WORKFLOW_SKILLS } from "../skill-state/canonical-skills";
+import {
+	compareSkillOrder,
+	getAncestorDirs,
+	getUserSkillScanDirs,
+	SOURCE_PATHS,
+	scanSkillsFromDir,
+} from "../discovery/helpers";
+import {
+	getSkillFilesystemIdentity,
+	isCanonicalGjcWorkflowSkillFilesystemAlias,
+} from "../skill-state/canonical-skills";
 import { expandTilde } from "../tools/path-utils";
-import type { Skill } from "./skills";
+import { loadSkills, type Skill } from "./skills";
 
 export type RuntimeSkillDiscoverySource = "project" | "user";
 
@@ -40,6 +55,9 @@ export interface RuntimeSkillDiscoveryResult {
 export interface DiscoverRuntimeSkillsOptions {
 	cwd: string;
 	home?: string;
+	agentDir?: string;
+	/** Resolver-owned profile classification; unlike path comparison, this survives HOME refreshes. */
+	profileAuthority?: "default" | "custom";
 	query?: string;
 	limit?: number;
 	source?: RuntimeSkillDiscoverySource | "all";
@@ -53,8 +71,6 @@ function getRuntimeHome(): string {
 const DEFAULT_LIMIT = 20;
 const MAX_LIMIT = 50;
 const MAX_DIAGNOSTICS = 10;
-const BUILT_IN_SKILL_NAMES = new Set<string>(CANONICAL_GJC_WORKFLOW_SKILLS);
-
 function normalizeLimit(limit: number | undefined): number {
 	if (limit === undefined || !Number.isFinite(limit)) return DEFAULT_LIMIT;
 	return Math.max(1, Math.min(MAX_LIMIT, Math.trunc(limit)));
@@ -81,41 +97,19 @@ async function getProjectSkillDirs(
 ): Promise<{ scans: ProjectScanDir[]; repoRoot: string | null }> {
 	const scans: ProjectScanDir[] = [];
 	const repoRoot = await findRepoRoot(cwd);
-	const walkDirs = ancestorDirs(cwd, path.resolve(repoRoot ?? cwd), home);
-	for (const dir of walkDirs) {
+	const walkDirs = getAncestorDirs(cwd, path.resolve(repoRoot ?? cwd), home);
+	for (const { dir } of walkDirs) {
 		scans.push({ dir: path.join(dir, ".gjc", "skills"), label: "project .gjc/skills" });
 	}
 	return { scans, repoRoot };
 }
 
-/** Ancestor directories from `cwd` (inclusive) up to `stop` (inclusive), excluding `home`. */
-function ancestorDirs(cwd: string, stop: string, home: string): string[] {
-	const dirs: string[] = [];
-	let current = path.resolve(cwd);
-	const resolvedStop = path.resolve(stop);
-	const resolvedHome = path.resolve(home);
-	while (true) {
-		if (current !== resolvedHome) {
-			dirs.push(current);
-		}
-		if (current === resolvedStop) break;
-		const parent = path.dirname(current);
-		if (parent === current) break;
-		current = parent;
-	}
-	return dirs;
+function getUserSkillDirs(home: string, agentDir = getAgentDir(), profileAuthority?: "default" | "custom"): string[] {
+	return getUserSkillScanDirs(home, agentDir, profileAuthority);
 }
 
-function getUserSkillDirs(home: string): string[] {
-	const canonicalUserDir = SOURCE_PATHS.native.userAgent;
-	const configuredLegacyDir = SOURCE_PATHS.native.userBase;
-	return [
-		...new Set([
-			path.join(home, canonicalUserDir, "skills"),
-			path.join(home, configuredLegacyDir, "skills"),
-			path.join(home, ".gjc", "skills"),
-		]),
-	];
+function resolveRuntimeAgentDir(home: string, agentDir: string | undefined, homeWasInjected: boolean): string {
+	return agentDir ?? (homeWasInjected ? path.join(home, SOURCE_PATHS.native.userAgent) : getAgentDir());
 }
 
 /**
@@ -152,18 +146,6 @@ function getUseWhen(skill: CapabilitySkill): string[] | undefined {
 	return values.length > 0 ? values : undefined;
 }
 
-function toRuntimeSkill(skill: CapabilitySkill, source: RuntimeSkillDiscoverySource): Skill {
-	return {
-		name: skill.name,
-		description: typeof skill.frontmatter?.description === "string" ? skill.frontmatter.description : "",
-		filePath: skill.path,
-		baseDir: skill.path.replace(/[\\/]SKILL\.md$/, ""),
-		source: `runtime:${source}`,
-		hide: skill.frontmatter?.hide === true,
-		_source: { ...skill._source, providerName: "Runtime skill discovery" },
-	};
-}
-
 function sourceEnabled(source: RuntimeSkillDiscoverySource, policy: SkillsSettings | undefined): boolean {
 	if (policy?.enabled !== true) return false;
 	return resolveSkillScopeTrust(policy, source);
@@ -202,13 +184,13 @@ async function realPathOrSelf(filePath: string): Promise<string> {
 }
 
 interface ScanJobResult {
-	items: Array<{ skill: CapabilitySkill; source: RuntimeSkillDiscoverySource }>;
+	items: Array<{ skill: CapabilitySkill; source: RuntimeSkillDiscoverySource; providerPriority: number }>;
 	warnings: string[];
 	label: string;
 }
 
 function isAllowedByPolicy(skill: CapabilitySkill, policy: SkillsSettings | undefined, diagnostics: string[]): boolean {
-	if (BUILT_IN_SKILL_NAMES.has(skill.name)) {
+	if (isCanonicalGjcWorkflowSkillFilesystemAlias(skill.name)) {
 		pushDiagnostic(
 			diagnostics,
 			`skill "${skill.name}" is a bundled GJC workflow skill and always resolves to the bundled definition; the filesystem copy at ${skill.path} is shadowed`,
@@ -234,23 +216,16 @@ function pushDiagnostic(diagnostics: string[], message: string): void {
 	if (diagnostics.length < MAX_DIAGNOSTICS) diagnostics.push(message);
 }
 
-async function collectPluginSkillDirs(
+async function collectPluginSkills(
 	home: string,
 	cwd: string,
-): Promise<Array<{ dir: string; pluginName: string; level: "user" | "project" }>> {
-	// Ensure the underlying installed_plugins.json fs cache is current — install/upgrade
-	// writers already invalidate via clearPluginRootsAndCaches; this is a defensive
-	// fallback so a stale in-memory cache cannot mask a disabled/removed plugin.
-	invalidateFsCache(`${getPluginsDir(home)}/installed_plugins.json`);
+	allowedLevels: ReadonlySet<"user" | "project">,
+): Promise<{ items: CapabilitySkill[]; warnings: string[] }> {
 	try {
-		const { roots } = await listClaudePluginRoots(home, cwd);
-		return roots.map(root => ({
-			dir: `${root.path}/skills`,
-			pluginName: root.plugin,
-			level: root.scope,
-		}));
-	} catch {
-		return [];
+		const result = await loadMarketplaceSkills({ cwd, home, repoRoot: await findRepoRoot(cwd) }, allowedLevels);
+		return { items: result.items, warnings: result.warnings ?? [] };
+	} catch (error) {
+		return { items: [], warnings: [`marketplace skill scan failed: ${String(error)}`] };
 	}
 }
 
@@ -287,15 +262,18 @@ async function scanProjectOrUserDir(
 	level: "project" | "user",
 	label: string,
 	source: RuntimeSkillDiscoverySource,
+	providerPriority: number,
+	authorityRoot?: string,
 ): Promise<ScanJobResult> {
 	const result = await scanSkillsFromDir(ctx, {
 		dir,
+		authorityRoot,
 		providerId: "runtime",
 		level,
 		requireDescription: true,
 	});
 	return {
-		items: result.items.map(skill => ({ skill, source })),
+		items: result.items.map(skill => ({ skill, source, providerPriority })),
 		warnings: result.warnings ?? [],
 		label,
 	};
@@ -304,6 +282,7 @@ async function scanProjectOrUserDir(
 interface ConventionImportScan {
 	host: "Claude Code" | "Codex";
 	dir: string;
+	scope: RuntimeSkillDiscoverySource;
 	skills: CapabilitySkill[];
 }
 
@@ -326,20 +305,20 @@ async function collectConventionImportCandidates(
 	if ((source === "all" || source === "project") && sourceEnabled("project", policy)) {
 		jobs.push(
 			scanClaudeProjectSkills(ctx).then(result => {
-				scans.push({ host: "Claude Code", dir: ".claude/skills", skills: result.items });
+				scans.push({ host: "Claude Code", dir: ".claude/skills", scope: "project", skills: result.items });
 			}),
 			scanCodexProjectSkills(ctx).then(result => {
-				scans.push({ host: "Codex", dir: ".codex/skills", skills: result.items });
+				scans.push({ host: "Codex", dir: ".codex/skills", scope: "project", skills: result.items });
 			}),
 		);
 	}
 	if ((source === "all" || source === "user") && sourceEnabled("user", policy)) {
 		jobs.push(
 			scanClaudeUserSkills(ctx).then(result => {
-				scans.push({ host: "Claude Code", dir: "~/.claude/skills", skills: result.items });
+				scans.push({ host: "Claude Code", dir: "~/.claude/skills", scope: "user", skills: result.items });
 			}),
 			scanCodexUserSkills(ctx).then(result => {
-				scans.push({ host: "Codex", dir: "~/.codex/skills", skills: result.items });
+				scans.push({ host: "Codex", dir: "~/.codex/skills", scope: "user", skills: result.items });
 			}),
 		);
 	}
@@ -353,10 +332,17 @@ function reportConventionImportCandidates(
 	seenNames: Set<string>,
 	diagnostics: string[],
 ): void {
-	for (const scan of scans.sort((a, b) => a.host.localeCompare(b.host) || a.dir.localeCompare(b.dir))) {
+	// Project scope is reported first: the bounded diagnostic budget must not be
+	// spent on a populated user-home convention directory (hundreds of skills is
+	// ordinary) before a project convention skill is ever named.
+	const scopeRank = (scan: ConventionImportScan) => (scan.scope === "project" ? 0 : 1);
+	for (const scan of scans.sort(
+		(a, b) => scopeRank(a) - scopeRank(b) || a.host.localeCompare(b.host) || a.dir.localeCompare(b.dir),
+	)) {
 		for (const skill of scan.skills) {
-			if (seenNames.has(skill.name)) continue;
-			seenNames.add(skill.name);
+			const normalizedName = getSkillFilesystemIdentity(skill.name);
+			if (seenNames.has(normalizedName)) continue;
+			seenNames.add(normalizedName);
 			pushDiagnostic(
 				diagnostics,
 				`skill "${skill.name}" found at ${skill.path} (${scan.host} convention): import sources are not loaded directly; copy it into a trusted .gjc/skills directory to enable it, e.g. mkdir -p .gjc/skills/${skill.name} && cp ${skill.path} .gjc/skills/${skill.name}/SKILL.md`,
@@ -396,64 +382,73 @@ export function describeDisabledSkillScopes(
 export async function discoverRuntimeSkills(
 	options: DiscoverRuntimeSkillsOptions,
 ): Promise<RuntimeSkillDiscoveryResult> {
+	const hasExplicitHome = options.home !== undefined;
 	const home = options.home ?? getRuntimeHome();
 	const source = options.source ?? "all";
 	const policy = options.policy;
 	const diagnostics: string[] = [];
+	const agentDir = resolveRuntimeAgentDir(home, options.agentDir, hasExplicitHome);
+	const profileAuthority =
+		options.profileAuthority ??
+		(!hasExplicitHome
+			? options.agentDir !== undefined &&
+				normalizePathForComparison(options.agentDir) !== normalizePathForComparison(getAgentDir())
+				? "custom"
+				: getAgentProfileAuthority()
+			: undefined);
 	const scanJobs: Array<Promise<ScanJobResult>> = [];
 	const projectDirs = await getProjectSkillDirs(options.cwd, home);
 	const projectContext = { cwd: options.cwd, home, repoRoot: projectDirs.repoRoot };
 	if ((source === "all" || source === "project") && sourceEnabled("project", policy)) {
 		for (const { dir, label } of projectDirs.scans) {
-			scanJobs.push(scanProjectOrUserDir(projectContext, dir, "project", label, "project"));
+			scanJobs.push(scanProjectOrUserDir(projectContext, dir, "project", label, "project", 100));
 		}
 	}
 	if ((source === "all" || source === "user") && sourceEnabled("user", policy)) {
-		for (const dir of getUserSkillDirs(home)) {
+		for (const dir of getUserSkillDirs(home, agentDir, profileAuthority)) {
 			scanJobs.push(
-				scanProjectOrUserDir({ cwd: options.cwd, home, repoRoot: home }, dir, "user", `user ${dir}`, "user"),
+				scanProjectOrUserDir(
+					{ cwd: options.cwd, home, repoRoot: home },
+					dir,
+					"user",
+					`user ${dir}`,
+					"user",
+					100,
+					path.resolve(dir) === path.resolve(agentDir, "skills") ? agentDir : undefined,
+				),
 			);
 		}
 	}
 	if ((source === "all" || source === "user") && policy?.enabled === true) {
 		for (const dir of getCustomSkillDirs(policy, home)) {
 			scanJobs.push(
-				scanProjectOrUserDir({ cwd: options.cwd, home, repoRoot: home }, dir, "user", `custom ${dir}`, "user"),
+				scanProjectOrUserDir({ cwd: options.cwd, home, repoRoot: home }, dir, "user", `custom ${dir}`, "user", 0),
 			);
 		}
 	}
 
-	// Marketplace plugin skills: version-stable, enabled-only.
-	// Uses the same trust gate as native user/project scopes and the same
-	// discovery root (<installPath>/skills) the capability provider uses,
-	// namespaced as `plugin:skillName`.
+	// Marketplace plugin skills come from the same provider used to populate
+	// session.skills, so discovery, slash commands, SDK state, and exact-name
+	// invocation cannot drift on manifest paths, namespacing, or enabled roots.
 	if (policy?.enabled === true) {
-		const pluginDirs = await collectPluginSkillDirs(home, options.cwd);
-		for (const entry of pluginDirs) {
-			if (entry.level === "project" && !(source === "all" || source === "project")) continue;
-			if (entry.level === "user" && !(source === "all" || source === "user")) continue;
-			if (!sourceEnabled(entry.level, policy)) continue;
-			const label = `plugin ${entry.pluginName} skills`;
-			scanJobs.push(
-				(async () => {
-					const pluginCtx = { cwd: options.cwd, home, repoRoot: home };
-					const result = await scanSkillsFromDir(pluginCtx, {
-						dir: entry.dir,
-						providerId: "plugin",
-						level: entry.level,
-						requireDescription: true,
-					});
-					for (const skill of result.items) {
-						skill.name = `${entry.pluginName}:${skill.name}`;
-					}
-					return {
-						items: result.items.map(skill => ({ skill, source: entry.level as RuntimeSkillDiscoverySource })),
-						warnings: result.warnings ?? [],
-						label,
-					};
-				})(),
-			);
+		const allowedLevels = new Set<"user" | "project">();
+		if ((source === "all" || source === "project") && sourceEnabled("project", policy)) {
+			allowedLevels.add("project");
+		}
+		if ((source === "all" || source === "user") && sourceEnabled("user", policy)) {
+			allowedLevels.add("user");
 		}
+		scanJobs.push(
+			collectPluginSkills(home, options.cwd, allowedLevels).then(result => ({
+				items: result.items.map(skill => ({
+					skill,
+					source: skill.level as RuntimeSkillDiscoverySource,
+					providerPriority: 70,
+				})),
+				warnings: result.warnings,
+				label: "marketplace plugin skills",
+			})),
+		);
 	}
 	if (policy?.enabled === true && policy.customDirectories && policy.customDirectories.length > 0) {
 		for (const dir of getCustomSkillDirs(policy, home)) {
@@ -466,6 +461,7 @@ export async function discoverRuntimeSkills(
 	const seenNames = new Set<string>();
 	const seenPaths = new Set<string>();
 	const candidates: RuntimeSkillDiscoveryCandidate[] = [];
+	const orderedItems: ScanJobResult["items"] = [];
 	for (const entry of settled) {
 		if ("error" in entry) {
 			pushDiagnostic(diagnostics, `skill scan failed: ${entry.error}`);
@@ -476,29 +472,34 @@ export async function discoverRuntimeSkills(
 				pushDiagnostic(diagnostics, `${entry.label}: ${warning}`);
 			}
 		}
-		for (const item of entry.items) {
-			if (!isAllowedByPolicy(item.skill, policy, diagnostics)) continue;
-			const realPath = await realPathOrSelf(item.skill.path);
-			if (seenPaths.has(realPath) || seenNames.has(item.skill.name)) {
-				pushDiagnostic(
-					diagnostics,
-					`skill "${item.skill.name}" already resolved from a higher-precedence location; ignoring ${item.skill.path}`,
-				);
-				continue;
-			}
-			seenPaths.add(realPath);
-			seenNames.add(item.skill.name);
-
-			const candidate: RuntimeSkillDiscoveryCandidate = {
-				name: item.skill.name,
-				description:
-					typeof item.skill.frontmatter?.description === "string" ? item.skill.frontmatter.description : "",
-				source: item.source,
-				path: item.skill.path,
-				useWhen: getUseWhen(item.skill),
-			};
-			if (matchesQuery(candidate, options.query ?? "")) candidates.push(candidate);
+		orderedItems.push(...entry.items);
+	}
+	orderedItems.sort((a, b) => {
+		const levelOrder = { project: 0, user: 1 } as const;
+		return levelOrder[a.source] - levelOrder[b.source] || b.providerPriority - a.providerPriority;
+	});
+	for (const item of orderedItems) {
+		if (!isAllowedByPolicy(item.skill, policy, diagnostics)) continue;
+		const realPath = await realPathOrSelf(item.skill.path);
+		const normalizedName = getSkillFilesystemIdentity(item.skill.name);
+		if (seenPaths.has(realPath) || seenNames.has(normalizedName)) {
+			pushDiagnostic(
+				diagnostics,
+				`skill "${item.skill.name}" already resolved from a higher-precedence location; ignoring ${item.skill.path}`,
+			);
+			continue;
 		}
+		seenPaths.add(realPath);
+		seenNames.add(normalizedName);
+
+		const candidate: RuntimeSkillDiscoveryCandidate = {
+			name: item.skill.name,
+			description: typeof item.skill.frontmatter?.description === "string" ? item.skill.frontmatter.description : "",
+			source: item.source,
+			path: item.skill.path,
+			useWhen: getUseWhen(item.skill),
+		};
+		if (matchesQuery(candidate, options.query ?? "")) candidates.push(candidate);
 	}
 	candidates.sort((a, b) => compareSkillOrder(a.name, a.path, b.name, b.path));
 	reportConventionImportCandidates(
@@ -516,71 +517,29 @@ export async function findRuntimeSkillByName(
 	cwd: string,
 	name: string,
 	policy?: SkillsSettings,
-	home = getRuntimeHome(),
+	home?: string,
+	agentDir?: string,
+	profileAuthority?: "default" | "custom",
 ): Promise<Skill | undefined> {
 	const normalized = name.trim();
 	if (!normalized) return undefined;
-	const scanJobs: Array<Promise<{ skill: CapabilitySkill; source: RuntimeSkillDiscoverySource }[]>> = [];
-	const projectDirs = await getProjectSkillDirs(cwd, home);
-	const projectContext = { cwd, home, repoRoot: projectDirs.repoRoot };
-	if (sourceEnabled("project", policy)) {
-		scanJobs.push(
-			...projectDirs.scans.map(scan =>
-				scanSkillsFromDir(projectContext, {
-					dir: scan.dir,
-					providerId: "runtime",
-					level: "project",
-					requireDescription: true,
-				}).then(result => result.items.map(skill => ({ skill, source: "project" as const }))),
-			),
-		);
-	}
-	if (sourceEnabled("user", policy)) {
-		for (const dir of getUserSkillDirs(home)) {
-			scanJobs.push(
-				scanSkillsFromDir(
-					{ cwd, home, repoRoot: home },
-					{ dir, providerId: "runtime", level: "user", requireDescription: true },
-				).then(result => result.items.map(skill => ({ skill, source: "user" as const }))),
-			);
-		}
-	}
-	if (policy?.enabled === true) {
-		for (const dir of getCustomSkillDirs(policy, home)) {
-			scanJobs.push(
-				scanSkillsFromDir(
-					{ cwd, home, repoRoot: home },
-					{ dir, providerId: "runtime", level: "user", requireDescription: true },
-				).then(result => result.items.map(skill => ({ skill, source: "user" as const }))),
-			);
-		}
-	}
-	if (policy?.enabled === true) {
-		try {
-			const pluginDirs = await collectPluginSkillDirs(home, cwd);
-			for (const entry of pluginDirs) {
-				if (!sourceEnabled(entry.level, policy)) continue;
-				scanJobs.push(
-					scanSkillsFromDir(
-						{ cwd, home, repoRoot: home },
-						{
-							dir: entry.dir,
-							providerId: "plugin",
-							level: entry.level,
-							requireDescription: true,
-						},
-					).then(result => {
-						for (const skill of result.items) skill.name = `${entry.pluginName}:${skill.name}`;
-						return result.items.map(skill => ({ skill, source: entry.level as RuntimeSkillDiscoverySource }));
-					}),
-				);
-			}
-		} catch {}
-	}
-	for (const entry of (await Promise.all(scanJobs)).flat()) {
-		if (entry.skill.name === normalized && isAllowedByPolicy(entry.skill, policy, [])) {
-			return toRuntimeSkill(entry.skill, entry.source);
-		}
-	}
-	return undefined;
+	if (isCanonicalGjcWorkflowSkillFilesystemAlias(normalized)) return undefined;
+	const hasExplicitHome = home !== undefined;
+	const resolvedHome = home ?? getRuntimeHome();
+	const resolvedAgentDir = resolveRuntimeAgentDir(resolvedHome, agentDir, hasExplicitHome);
+	const resolvedProfileAuthority =
+		profileAuthority ??
+		(!hasExplicitHome
+			? agentDir !== undefined && normalizePathForComparison(agentDir) !== normalizePathForComparison(getAgentDir())
+				? "custom"
+				: getAgentProfileAuthority()
+			: undefined);
+	const loaded = await loadSkills({
+		...policy,
+		cwd,
+		home: resolvedHome,
+		agentDir: resolvedAgentDir,
+		profileAuthority: resolvedProfileAuthority,
+	});
+	return loaded.skills.find(skill => skill.name === normalized);
 }

package/src/extensibility/shared-events.ts

@@ -188,7 +188,7 @@ export interface AgentEndEvent {
 	sdkRunToken?: string;
 	/** Indicates whether the loop ended normally, suspended, cancelled, or entered maintenance. */
 	stopReason?: "completed" | "paused" | "cancelled" | "maintenance";
-	/** Present for maintenance checkpoints; non-aborted checkpoints are not terminal. */
+	/** Present for maintenance checkpoints; only committed maintenance outcomes are non-terminal. */
 	maintenanceOutcome?: MidRunMaintenanceOutcome;
 }