@opengsd/gsd-pi 1.0.2-dev.867e002 → 1.0.2-dev.cce3612

package/dist/resources/extensions/gsd/skill-discovery.js

@@ -2,26 +2,23 @@
  * GSD Skill Discovery
  *
  * Detects skills installed during auto-mode by comparing the current
- * skills directory against a snapshot taken at auto-mode start.
+ * installed catalog and skill directories against a snapshot taken at auto-mode start.
  *
- * New skills are injected into the system prompt via before_agent_start,
- * making them visible to all subsequent units without requiring a reload.
+ * New skills are surfaced via resource reload when possible, with a fallback
+ * prompt block when reload fails before the next agent turn.
  */
 import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { join } from "node:path";
 import { homedir } from "node:os";
+import { join } from "node:path";
 import { gsdHome } from "./gsd-home.js";
-/** Skills directories — GSD bundled, skills.sh ecosystem, and Claude Code official */
-const GSD_SKILLS_DIR = join(gsdHome(), "agent", "skills");
-const SKILLS_DIR = join(homedir(), ".agents", "skills");
-const CLAUDE_SKILLS_DIR = join(homedir(), ".claude", "skills");
-/** Snapshot of skill names at auto-mode start */
+import { getInstalledSkills, normalizeSkillName } from "./skills.js";
+/** Snapshot of normalized skill names at auto-mode start */
 let baselineSkills = null;
 /**
- * Snapshot the current skills directory. Call at auto-mode start.
+ * Snapshot the current installed skill catalog. Call at auto-mode start.
  */
 export function snapshotSkills() {
-    baselineSkills = new Set(listSkillDirs());
+    baselineSkills = snapshotCurrentSkillNames();
 }
 /**
  * Clear the snapshot. Call when auto-mode stops.
@@ -37,80 +34,140 @@ export function hasSkillSnapshot() {
 }
 /**
  * Detect skills installed since the snapshot was taken.
- * Returns skill metadata for any new skills found.
+ * Returns skill metadata for any new skills found in the loader catalog or on disk.
  */
 export function detectNewSkills() {
     if (!baselineSkills)
         return [];
-    const current = listSkillDirs();
     const newSkills = [];
-    for (const dir of current) {
-        if (baselineSkills.has(dir))
-            continue;
-        // Check both skill directories for the SKILL.md file
-        const skillMdPath = resolveSkillMdPath(dir);
-        if (!skillMdPath)
+    for (const skill of getCurrentSkillsForDiscovery()) {
+        const normalized = normalizeSkillName(skill.name);
+        if (baselineSkills.has(normalized))
             continue;
-        const meta = parseSkillFrontmatter(skillMdPath);
-        if (meta) {
-            newSkills.push({
-                name: meta.name || dir,
-                description: meta.description || `Skill: ${dir}`,
-                location: skillMdPath,
-            });
-        }
+        newSkills.push(skill);
     }
     return newSkills;
 }
 /**
- * Format discovered skills as an XML block matching pi's <available_skills> format.
- * This can be appended to the system prompt so the LLM sees them naturally.
+ * Reload the skill catalog when auto-mode detects newly installed skills.
+ * Returns discovered skills even if reload fails so callers can surface them
+ * in the prompt. Updates the snapshot baseline only after a successful reload
+ * so detection is retried after failures.
  */
-export function formatSkillsXml(skills) {
-    if (skills.length === 0)
-        return "";
-    const entries = skills.map(s => `  <skill>
-    <name>${escapeXml(s.name)}</name>
-    <description>${escapeXml(s.description)}</description>
-    <location>${escapeXml(s.location)}</location>
-  </skill>`).join("\n");
-    return `\n<newly_discovered_skills>
-The following skills were installed during this auto-mode session.
-Use the read tool to load a skill's file when the task matches its description.
-
-${entries}
-</newly_discovered_skills>`;
+export async function refreshCatalogForNewSkills(options) {
+    const newSkills = detectNewSkills();
+    if (newSkills.length === 0)
+        return [];
+    if (options?.reload) {
+        try {
+            await options.reload();
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            options.notify?.(`GSD: failed to reload skill catalog: ${message}`, "warning");
+            return newSkills;
+        }
+    }
+    snapshotSkills();
+    const names = newSkills.map((skill) => skill.name).join(", ");
+    options?.notify?.(`GSD: loaded new skills: ${names}`, "info");
+    return newSkills;
+}
+export function appendDiscoveredSkillsFallback(systemPrompt, skills) {
+    const missingSkills = skills.filter(skill => !systemPrompt.includes(skill.location));
+    if (missingSkills.length === 0)
+        return systemPrompt;
+    return `${systemPrompt}\n\n${formatDiscoveredSkillsXml(missingSkills)}`;
 }
 // ─── Internals ────────────────────────────────────────────────────────────────
-function listSkillDirsFrom(dir) {
-    if (!existsSync(dir))
-        return [];
-    try {
-        return readdirSync(dir, { withFileTypes: true })
-            .filter(d => d.isDirectory())
-            .map(d => d.name);
+function formatDiscoveredSkillsXml(skills) {
+    const lines = [
+        "<newly_discovered_skills>",
+        "  <note>These skills were detected after this session started and may be absent from &lt;available_skills&gt;. If relevant, read the skill file at its location before using it.</note>",
+    ];
+    for (const skill of skills) {
+        lines.push("  <skill>", `    <name>${escapeXml(skill.name)}</name>`, `    <description>${escapeXml(skill.description)}</description>`, `    <location>${escapeXml(skill.location)}</location>`, "  </skill>");
     }
-    catch {
-        return [];
+    lines.push("</newly_discovered_skills>");
+    return lines.join("\n");
+}
+function escapeXml(value) {
+    return value.replace(/[<>&'"]/g, (char) => {
+        switch (char) {
+            case "<": return "&lt;";
+            case ">": return "&gt;";
+            case "&": return "&amp;";
+            case "'": return "&apos;";
+            case "\"": return "&quot;";
+            default: return char;
+        }
+    });
+}
+function skillSearchDirs() {
+    return [
+        join(gsdHome(), "agent", "skills"),
+        join(homedir(), ".agents", "skills"),
+        join(homedir(), ".claude", "skills"),
+    ];
+}
+function snapshotCurrentSkillNames() {
+    return new Set(getCurrentSkillsForDiscovery().map(skill => normalizeSkillName(skill.name)));
+}
+function getCurrentSkillsForDiscovery() {
+    const skills = new Map();
+    for (const skill of getInstalledSkills()) {
+        const normalized = normalizeSkillName(skill.name);
+        skills.set(normalized, {
+            name: skill.name,
+            description: skill.description || `Skill: ${skill.name}`,
+            location: skill.filePath,
+        });
     }
+    for (const skill of getDiskSkills()) {
+        const normalized = normalizeSkillName(skill.name);
+        if (!skills.has(normalized))
+            skills.set(normalized, skill);
+    }
+    return [...skills.values()];
 }
-function listSkillDirs() {
-    const names = new Set();
-    for (const name of listSkillDirsFrom(GSD_SKILLS_DIR))
-        names.add(name);
-    for (const name of listSkillDirsFrom(SKILLS_DIR))
-        names.add(name);
-    for (const name of listSkillDirsFrom(CLAUDE_SKILLS_DIR))
-        names.add(name);
-    return [...names];
+function getDiskSkills() {
+    const skills = new Map();
+    for (const dir of skillSearchDirs()) {
+        if (!existsSync(dir))
+            continue;
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory() && !entry.isSymbolicLink())
+                continue;
+            const skillMdPath = join(dir, entry.name, "SKILL.md");
+            if (!existsSync(skillMdPath))
+                continue;
+            const meta = parseSkillFrontmatter(skillMdPath);
+            const name = meta?.name || entry.name;
+            const normalized = normalizeSkillName(name);
+            if (skills.has(normalized))
+                continue;
+            skills.set(normalized, {
+                name,
+                description: meta?.description || `Skill: ${name}`,
+                location: skillMdPath,
+            });
+        }
+    }
+    return [...skills.values()];
 }
 function parseSkillFrontmatter(path) {
     try {
         const content = readFileSync(path, "utf-8");
-        // Use indexOf instead of [\s\S]*? regex to avoid backtracking (#468)
-        if (!content.startsWith('---\n'))
+        if (!content.startsWith("---\n"))
             return null;
-        const endIdx = content.indexOf('\n---', 4);
+        const endIdx = content.indexOf("\n---", 4);
         if (endIdx === -1)
             return null;
         const fm = content.slice(4, endIdx);
@@ -127,18 +184,3 @@ function parseSkillFrontmatter(path) {
         return null;
     }
 }
-function resolveSkillMdPath(skillName) {
-    for (const dir of [GSD_SKILLS_DIR, SKILLS_DIR, CLAUDE_SKILLS_DIR]) {
-        const candidate = join(dir, skillName, "SKILL.md");
-        if (existsSync(candidate))
-            return candidate;
-    }
-    return null;
-}
-function escapeXml(text) {
-    return text
-        .replace(/&/g, "&amp;")
-        .replace(/</g, "&lt;")
-        .replace(/>/g, "&gt;")
-        .replace(/"/g, "&quot;");
-}

package/dist/resources/extensions/gsd/skill-scope.js

@@ -0,0 +1,52 @@
+/**
+ * Per-unit skill catalog scoping for GSD auto and workflow dispatch.
+ */
+import { resolveSkillManifest } from "./skill-manifest.js";
+import { normalizeSkillName } from "./skills.js";
+import { resolveManifest } from "./unit-context-manifest.js";
+/**
+ * Resolve which skill names should appear in `<available_skills>` for a unit.
+ * Returns `undefined` for full catalog, `[]` for suppressed catalog, or a
+ * name list for allowlist mode.
+ */
+export function resolveVisibleSkillNames(unitType) {
+    if (!unitType)
+        return undefined;
+    const unitManifest = resolveManifest(unitType);
+    if (unitManifest) {
+        switch (unitManifest.skills.mode) {
+            case "none":
+                return [];
+            case "all":
+                return undefined;
+            case "allowlist":
+                return [...unitManifest.skills.skills];
+        }
+    }
+    const legacyAllowlist = resolveSkillManifest(unitType);
+    return legacyAllowlist ?? undefined;
+}
+/** Whether this unit narrows or suppresses the skill catalog (not mode "all"). */
+export function unitHasSkillManifest(unitType) {
+    if (!unitType)
+        return false;
+    const unitManifest = resolveManifest(unitType);
+    if (unitManifest) {
+        return unitManifest.skills.mode !== "all";
+    }
+    return resolveSkillManifest(unitType) !== null;
+}
+/** Apply unit manifest skill policy via setVisibleSkills. */
+export function applyUnitSkillVisibility(pi, unitType) {
+    pi.setVisibleSkills(resolveVisibleSkillNames(unitType));
+}
+/** Installed skill names visible for a unit per manifest policy. */
+export function effectiveSkillNamesForUnit(unitType, installed) {
+    const visible = resolveVisibleSkillNames(unitType);
+    if (visible === undefined)
+        return installed;
+    if (visible.length === 0)
+        return [];
+    const allowed = new Set(visible.map(normalizeSkillName));
+    return installed.filter((name) => allowed.has(normalizeSkillName(name)));
+}

package/dist/resources/extensions/gsd/skill-telemetry.js

@@ -6,14 +6,11 @@
  * "actively loaded" skills (read via tool calls during execution).
  *
  * Data flow:
- *   1. At dispatch, captureAvailableSkills() records skills from the system prompt
+ *   1. At dispatch, captureAvailableSkills(names) records catalog skill names
  *   2. During execution, recordSkillRead() tracks explicit SKILL.md reads
  *   3. At unit completion, getAndClearSkills() returns the loaded list for metrics
  */
-import { existsSync, readdirSync } from "node:fs";
-import { join } from "node:path";
-import { gsdHome } from "./gsd-home.js";
-import { homedir } from "node:os";
+import { getInstalledSkillNames } from "./skills.js";
 // ─── In-memory state ──────────────────────────────────────────────────────────
 /** Skills available in the system prompt for the current unit */
 let availableSkills = [];
@@ -22,17 +19,10 @@ const activelyLoadedSkills = new Set();
 // ─── Public API ───────────────────────────────────────────────────────────────
 /**
  * Capture the list of available skill names at dispatch time.
- * Called before each unit starts.
+ * Callers should pass names from resourceLoader / {@link getInstalledSkillNames}.
  */
-export function captureAvailableSkills() {
-    const gsdSkillsDir = join(gsdHome(), "agent", "skills");
-    const skillsDir = join(homedir(), ".agents", "skills");
-    const claudeSkillsDir = join(homedir(), ".claude", "skills");
-    const gsdNames = listSkillNames(gsdSkillsDir);
-    const names = listSkillNames(skillsDir);
-    const claudeNames = listSkillNames(claudeSkillsDir);
-    const all = new Set([...gsdNames, ...names, ...claudeNames]);
-    availableSkills = [...all];
+export function captureAvailableSkills(skillNames) {
+    availableSkills = [...skillNames];
     activelyLoadedSkills.clear();
 }
 /**
@@ -91,16 +81,7 @@ export function detectStaleSkills(units, thresholdDays) {
     const lastUsed = getSkillLastUsed(units);
     const cutoff = Date.now() - (thresholdDays * 24 * 60 * 60 * 1000);
     const stale = [];
-    // Check all installed skills, not just those with usage data
-    const gsdSkillsDir = join(gsdHome(), "agent", "skills");
-    const skillsDir = join(homedir(), ".agents", "skills");
-    const claudeSkillsDir = join(homedir(), ".claude", "skills");
-    const installedSet = new Set([
-        ...listSkillNames(gsdSkillsDir),
-        ...listSkillNames(skillsDir),
-        ...listSkillNames(claudeSkillsDir),
-    ]);
-    const installed = [...installedSet];
+    const installed = getInstalledSkillNames();
     for (const skill of installed) {
         const lastTs = lastUsed.get(skill);
         if (lastTs === undefined || lastTs < cutoff) {
@@ -109,17 +90,3 @@ export function detectStaleSkills(units, thresholdDays) {
     }
     return stale;
 }
-// ─── Internals ────────────────────────────────────────────────────────────────
-function listSkillNames(skillsDir) {
-    if (!existsSync(skillsDir))
-        return [];
-    try {
-        return readdirSync(skillsDir, { withFileTypes: true })
-            .filter(d => d.isDirectory() && !d.name.startsWith("."))
-            .filter(d => existsSync(join(skillsDir, d.name, "SKILL.md")))
-            .map(d => d.name);
-    }
-    catch {
-        return [];
-    }
-}

package/dist/resources/extensions/gsd/skills.js

@@ -0,0 +1,60 @@
+/**
+ * Canonical skill access for GSD extension code.
+ *
+ * Prefer {@link getInstalledSkills} (ResourceLoader / getLoadedSkills cache)
+ * over ad-hoc directory scans.
+ */
+import { getLoadedSkills } from "@gsd/pi-coding-agent";
+import { resolveSkillReference } from "./preferences-skills.js";
+/** Normalize a skill reference the same way preference matching does. */
+export function normalizeSkillName(ref) {
+    return ref.trim().toLowerCase();
+}
+/** Installed skills from the pi loader cache, or an explicit override (tests). */
+export function getInstalledSkills(override) {
+    if (override)
+        return override;
+    return typeof getLoadedSkills === "function" ? getLoadedSkills() : [];
+}
+/** Skill names from the installed catalog. */
+export function getInstalledSkillNames(skills) {
+    return getInstalledSkills(skills).map((skill) => skill.name);
+}
+/** Snapshot normalized skill names for auto-mode diffing. */
+export function snapshotInstalledSkillNames(skills) {
+    return new Set(getInstalledSkillNames(skills).map(normalizeSkillName));
+}
+/** Names present now but absent from `baseline`. */
+export function detectNewlyInstalledSkills(baseline, skills) {
+    const current = snapshotInstalledSkillNames(skills);
+    return [...current].filter((name) => !baseline.has(name));
+}
+/**
+ * Resolve a preference skill reference to a path, validating against the
+ * installed catalog when loader data is available.
+ */
+export function resolveInstalledSkill(ref, cwd, skills) {
+    const resolution = resolveSkillReference(ref, cwd);
+    const installed = getInstalledSkills(skills);
+    if (installed.length === 0) {
+        return resolution;
+    }
+    const byName = new Map(installed.map((skill) => [normalizeSkillName(skill.name), skill]));
+    const normalizedRef = normalizeSkillName(ref);
+    const byRef = byName.get(normalizedRef);
+    if (byRef) {
+        return {
+            ...resolution,
+            resolvedPath: byRef.filePath,
+            method: resolution.method === "unresolved" ? "user-skill" : resolution.method,
+            skill: byRef,
+        };
+    }
+    if (resolution.resolvedPath) {
+        const match = installed.find((skill) => skill.filePath === resolution.resolvedPath);
+        if (match) {
+            return { ...resolution, skill: match };
+        }
+    }
+    return resolution;
+}