@senpi/runtime 1.1.0-dev.runtime-phase-2.20260513122539 → 1.1.0-dev.runtime-phase-2.20260514134437

package/dist/skills-manager/state-store.d.ts

@@ -9,10 +9,23 @@ import type { LoggerLike, SkillsManagerState } from "./types.js";
  */
 export declare class SkillsManagerStateStore {
     private readonly stateDir;
+    /**
+     * Skills directory search path. Single-string form is accepted for
+     * backward compat with legacy callers; arrays follow the standard
+     * "primary first, mirrors after" convention.
+     */
     private readonly skillsDir;
     private readonly logger?;
     private readonly filePath;
-    constructor(stateDir: string, skillsDir: string, logger?: LoggerLike | undefined);
+    constructor(stateDir: string, 
+    /**
+     * Skills directory search path. Single-string form is accepted for
+     * backward compat with legacy callers; arrays follow the standard
+     * "primary first, mirrors after" convention.
+     */
+    skillsDir: string | readonly string[], logger?: LoggerLike | undefined);
+    /** All configured dirs as an array, regardless of how the constructor was called. */
+    private get skillsDirs();
     /**
      * Load persisted state, falling back to defaults when the file is absent
      * (first run) or unreadable / corrupt.
@@ -25,9 +38,19 @@ export declare class SkillsManagerStateStore {
     /** Atomically write state; creates the directory if it does not exist. */
     save(state: SkillsManagerState): Promise<void>;
     /**
-     * Called on first run (no state file yet). Reads `skillsDir` and creates
-     * a default {@link SkillState} entry for every installed skill so the first
-     * poll tick starts with a populated state rather than an empty map.
+     * Called on first run (no state file yet). Walks every dir in the
+     * `skillsDir` search path and creates a default {@link SkillState} entry
+     * for each installed skill so the first poll tick starts with a populated
+     * state rather than an empty map.
+     *
+     * Multi-dir semantics: dirs are scanned in order; the first dir containing
+     * a given skill name wins. This matches the read priority used elsewhere
+     * (`readLocalVersion`, bootstrap pre-check) — the primary dir's view of a
+     * skill is canonical, secondary mirrors are fallbacks only.
+     *
+     * Per-dir ENOENT is silent (dir does not exist yet); any other I/O error
+     * is logged as a warning and the scan continues into the next dir, so one
+     * misconfigured mirror cannot wipe the whole initial state.
      */
     private buildInitialState;
 }

package/dist/skills-manager/state-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state-store.d.ts","sourceRoot":"","sources":["../../src/skills-manager/state-store.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAIjE;;;GAGG;AACH,qBAAa,uBAAuB;IAIhC,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IAL1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;gBAGf,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,UAAU,YAAA;IAKtC;;;;;;;OAOG;IACG,IAAI,IAAI,OAAO,CAAC,kBAAkB,CAAC;IAkDzC,0EAA0E;IACpE,IAAI,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAKpD;;;;OAIG;YACW,iBAAiB;CAoBhC"}
+{"version":3,"file":"state-store.d.ts","sourceRoot":"","sources":["../../src/skills-manager/state-store.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAIjE;;;GAGG;AACH,qBAAa,uBAAuB;IAIhC,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IAV1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;gBAGf,QAAQ,EAAE,MAAM;IACjC;;;;OAIG;IACc,SAAS,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,EACrC,MAAM,CAAC,EAAE,UAAU,YAAA;IAKtC,qFAAqF;IACrF,OAAO,KAAK,UAAU,GAErB;IAED;;;;;;;OAOG;IACG,IAAI,IAAI,OAAO,CAAC,kBAAkB,CAAC;IAkDzC,0EAA0E;IACpE,IAAI,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAKpD;;;;;;;;;;;;;;OAcG;YACW,iBAAiB;CAwBhC"}

package/dist/skills-manager/state-store.js

@@ -16,12 +16,22 @@ export class SkillsManagerStateStore {
     skillsDir;
     logger;
     filePath;
-    constructor(stateDir, skillsDir, logger) {
+    constructor(stateDir, 
+    /**
+     * Skills directory search path. Single-string form is accepted for
+     * backward compat with legacy callers; arrays follow the standard
+     * "primary first, mirrors after" convention.
+     */
+    skillsDir, logger) {
         this.stateDir = stateDir;
         this.skillsDir = skillsDir;
         this.logger = logger;
         this.filePath = join(stateDir, SKILLS_MANAGER_STATE_FILE);
     }
+    /** All configured dirs as an array, regardless of how the constructor was called. */
+    get skillsDirs() {
+        return typeof this.skillsDir === "string" ? [this.skillsDir] : this.skillsDir;
+    }
     /**
      * Load persisted state, falling back to defaults when the file is absent
      * (first run) or unreadable / corrupt.
@@ -76,28 +86,44 @@ export class SkillsManagerStateStore {
         await writeFile(this.filePath, JSON.stringify(state, null, 2), "utf8");
     }
     /**
-     * Called on first run (no state file yet). Reads `skillsDir` and creates
-     * a default {@link SkillState} entry for every installed skill so the first
-     * poll tick starts with a populated state rather than an empty map.
+     * Called on first run (no state file yet). Walks every dir in the
+     * `skillsDir` search path and creates a default {@link SkillState} entry
+     * for each installed skill so the first poll tick starts with a populated
+     * state rather than an empty map.
+     *
+     * Multi-dir semantics: dirs are scanned in order; the first dir containing
+     * a given skill name wins. This matches the read priority used elsewhere
+     * (`readLocalVersion`, bootstrap pre-check) — the primary dir's view of a
+     * skill is canonical, secondary mirrors are fallbacks only.
+     *
+     * Per-dir ENOENT is silent (dir does not exist yet); any other I/O error
+     * is logged as a warning and the scan continues into the next dir, so one
+     * misconfigured mirror cannot wipe the whole initial state.
      */
     async buildInitialState() {
-        try {
-            const entries = await readdir(this.skillsDir, { withFileTypes: true });
-            const skills = {};
-            for (const entry of entries) {
-                if (entry.isDirectory() && !entry.name.startsWith(".")) {
-                    const installedVersion = await readLocalVersion(this.skillsDir, entry.name, this.logger);
+        const skills = {};
+        for (const dir of this.skillsDirs) {
+            try {
+                const entries = await readdir(dir, { withFileTypes: true });
+                for (const entry of entries) {
+                    if (!entry.isDirectory() || entry.name.startsWith("."))
+                        continue;
+                    // First-found wins — secondary dirs cannot override the primary's
+                    // entry once it's been written into the map.
+                    if (skills[entry.name])
+                        continue;
+                    const installedVersion = await readLocalVersion(dir, entry.name, this.logger);
                     skills[entry.name] = { ...createDefaultSkillState(entry.name), installedVersion };
                 }
             }
-            return { skills };
-        }
-        catch (err) {
-            if (err.code !== "ENOENT") {
-                this.logger?.warn(`[senpi-skills-manager] failed to read skills directory, starting with empty skill state | path=${this.skillsDir} err=${formatErr(err)}`);
+            catch (err) {
+                if (err.code !== "ENOENT") {
+                    this.logger?.warn(`[senpi-skills-manager] failed to read skills directory, continuing with remaining dirs | path=${dir} err=${formatErr(err)}`);
+                }
+                // Continue scanning the remaining dirs even on error — don't bail.
             }
-            return createDefaultSkillsManagerState();
         }
+        return Object.keys(skills).length > 0 ? { skills } : createDefaultSkillsManagerState();
     }
 }
 //# sourceMappingURL=state-store.js.map

package/dist/skills-manager/state-store.js.map

@@ -1 +1 @@
-{"version":3,"file":"state-store.js","sourceRoot":"","sources":["../../src/skills-manager/state-store.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AAE3D,OAAO,EAAE,+BAA+B,EAAE,uBAAuB,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACjG,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAExD;;;GAGG;AACH,MAAM,OAAO,uBAAuB;IAIf;IACA;IACA;IALF,QAAQ,CAAS;IAElC,YACmB,QAAgB,EAChB,SAAiB,EACjB,MAAmB;QAFnB,aAAQ,GAAR,QAAQ,CAAQ;QAChB,cAAS,GAAT,SAAS,CAAQ;QACjB,WAAM,GAAN,MAAM,CAAa;QAEpC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,EAAE,yBAAyB,CAAC,CAAC;IAC5D,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,IAAI;QACR,2EAA2E;QAC3E,IAAI,GAAW,CAAC;QAChB,IAAI,CAAC;YACH,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAC9C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACrD,IAAI,CAAC,MAAM,EAAE,IAAI,CACf,qEAAqE,IAAI,CAAC,QAAQ,QAAQ,SAAS,CAAC,GAAG,CAAC,EAAE,CAC3G,CAAC;gBACF,OAAO,IAAI,CAAC,iBAAiB,EAAE,CAAC;YAClC,CAAC;YACD,IAAI,CAAC,MAAM,EAAE,IAAI,CACf,2EAA2E,IAAI,CAAC,QAAQ,QAAQ,SAAS,CAAC,GAAG,CAAC,EAAE,CACjH,CAAC;YACF,OAAO,+BAA+B,EAAE,CAAC;QAC3C,CAAC;QAED,2EAA2E;QAC3E,IAAI,MAAmC,CAAC;QACxC,IAAI,CAAC;YACH,MAAM,KAAK,GAAY,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YACvC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;gBACxE,IAAI,CAAC,MAAM,EAAE,IAAI,CACf,qFAAqF,IAAI,CAAC,QAAQ,EAAE,CACrG,CAAC;gBACF,OAAO,+BAA+B,EAAE,CAAC;YAC3C,CAAC;YACD,MAAM,GAAG,KAAoC,CAAC;QAChD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,MAAM,EAAE,IAAI,CACf,kFAAkF,IAAI,CAAC,QAAQ,QAAQ,SAAS,CAAC,GAAG,CAAC,EAAE,CACxH,CAAC;YACF,OAAO,+BAA+B,EAAE,CAAC;QAC3C,CAAC;QAED,OAAO;YACL,GAAG,+BAA+B,EAAE;YACpC,GAAG,MAAM;YACT,6CAA6C;YAC7C,MAAM,EACJ,MAAM,CAAC,MAAM,KAAK,IAAI;gBACtB,MAAM,CAAC,MAAM,KAAK,SAAS;gBAC3B,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ;gBACjC,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC;gBAC3B,CAAC,CAAC,MAAM,CAAC,MAAM;gBACf,CAAC,CAAC,EAAE;SACT,CAAC;IACJ,CAAC;IAED,0EAA0E;IAC1E,KAAK,CAAC,IAAI,CAAC,KAAyB;QAClC,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACzD,MAAM,SAAS,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IACzE,CAAC;IAED;;;;OAIG;IACK,KAAK,CAAC,iBAAiB;QAC7B,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;YACvE,MAAM,MAAM,GAAiC,EAAE,CAAC;YAChD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;gBAC5B,IAAI,KAAK,CAAC,WAAW,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;oBACvD,MAAM,gBAAgB,GAAG,MAAM,gBAAgB,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;oBACzF,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,uBAAuB,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,gBAAgB,EAAE,CAAC;gBACpF,CAAC;YACH,CAAC;YACD,OAAO,EAAE,MAAM,EAAE,CAAC;QACpB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACrD,IAAI,CAAC,MAAM,EAAE,IAAI,CACf,kGAAkG,IAAI,CAAC,SAAS,QAAQ,SAAS,CAAC,GAAG,CAAC,EAAE,CACzI,CAAC;YACJ,CAAC;YACD,OAAO,+BAA+B,EAAE,CAAC;QAC3C,CAAC;IACH,CAAC;CACF"}
+{"version":3,"file":"state-store.js","sourceRoot":"","sources":["../../src/skills-manager/state-store.ts"],"names":[],"mappings":"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"}

package/dist/skills-manager/types.d.ts

@@ -12,15 +12,29 @@ export type SkillsManagerHealth = "healthy" | "degraded" | "unhealthy" | "disabl
  */
 export interface RawSkillsManagerConfig {
     enabled?: boolean;
-    skillsDir?: string;
-    pollIntervalMinutes?: number;
+    /**
+     * Skills install/search directory.
+     *
+     * Accepts either a single string (legacy form) or an array of strings
+     * (search path, first is the primary write target). `resolveSkillsManagerConfig`
+     * normalises both shapes to a non-empty `string[]` and falls back to
+     * `DEFAULT_SKILLS_DIRS` when omitted, null, an empty array, or wrong-typed.
+     */
+    skillsDir?: string | string[];
     skills?: string[];
 }
 /** Resolved config — all fields have safe defaults filled in. */
 export interface SkillsManagerConfig {
     enabled: boolean;
-    skillsDir: string;
-    pollIntervalMinutes: number;
+    /**
+     * Skills directory search path. Always a non-empty array after
+     * resolution; `[0]` is the **primary** (writes go here), the rest are
+     * read-only mirrors scanned during version checks and discovery.
+     *
+     * For backward compat with code that wants a single string (logs, snapshot
+     * fields, single-dir helpers), use `skillsDir[0]`.
+     */
+    skillsDir: string[];
     /**
      * Skill names this coordinator manages.
      *
@@ -52,12 +66,16 @@ export interface SkillsManagerState {
 /** Read-only snapshot for gateway RPCs and health views. */
 export interface SkillsManagerSnapshot {
     enabled: boolean;
-    skillsDir: string;
+    /**
+     * Skills directory search path. Mirrors `SkillsManagerConfig.skillsDir` — a
+     * non-empty array where `[0]` is the primary write target. Callers
+     * rendering this for humans should join with commas (e.g. `dirs.join(", ")`).
+     */
+    skillsDir: string[];
     health: SkillsManagerHealth;
     lastAction: string;
     lastError: string | null;
     skills: SkillSnapshot[];
-    nextCheckAt: string | null;
 }
 /** Per-skill entry in a snapshot. */
 export interface SkillSnapshot {
@@ -73,14 +91,34 @@ export interface SkillVersionInfo {
     localVersion: string | null;
     remoteVersion: string | null;
     updateKind: SkillUpdateKind;
+    /**
+     * Short description parsed from the **remote** SKILL.md frontmatter (the
+     * version the user is being notified about), surfaced back to the
+     * coordinator so notification text can include an "About:" line that
+     * reflects the upcoming version rather than the potentially-stale local
+     * copy.
+     *
+     * Null when:
+     * - The remote fetch returned 404 (skill not in the remote repo).
+     * - The remote SKILL.md is present but its frontmatter has no
+     *   `description` field.
+     *
+     * Optional in the interface for backward compatibility with injected
+     * test deps that only return version data; the real `checkSkillVersion`
+     * always populates it (possibly null) on every return path.
+     */
+    remoteDescription?: string | null;
 }
 /** Injectable overrides used in unit tests to avoid network and git calls. */
 export interface SkillsUpdateCoordinatorDeps {
     /**
-     * Override version check — called as (skillsDir, skillName, rawBaseUrl, logger).
+     * Override version check — called as (skillsDirs, skillName, rawBaseUrl, logger).
      * Defaults to the real checkSkillVersion with fetchImpl omitted (uses global fetch).
+     *
+     * `skillsDirs` is the search-path array from the resolved config; the real
+     * `checkSkillVersion` tries each in order when reading SKILL.md.
      */
-    checkSkillVersion?: (skillsDir: string, skillName: string, rawBaseUrl: string, logger?: LoggerLike) => Promise<SkillVersionInfo>;
+    checkSkillVersion?: (skillsDirs: readonly string[], skillName: string, rawBaseUrl: string, logger?: LoggerLike) => Promise<SkillVersionInfo>;
     /**
      * Override clone + install — receives the list of skill names that need
      * updating and the config. Defaults to real cloneSkillsRepo + installSkill.

package/dist/skills-manager/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/skills-manager/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/skills-manager/types.ts"],"names":[],"mappings":"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"}

package/dist/skills-manager/utils.d.ts

@@ -43,4 +43,21 @@ export declare function createDefaultSkillsManagerState(): SkillsManagerState;
 export declare function createDefaultSkillState(name: string): SkillState;
 /** Formats an unknown thrown value as a short string for log messages. */
 export declare function formatErr(e: unknown): string;
+/**
+ * Normalise the raw `skillsDir` value into a non-empty `string[]` (the
+ * "search path" form used internally).
+ *
+ * Resolution rules:
+ * - Single string → wrap as `[value]` (legacy single-dir form)
+ * - Array → filter out non-strings and empty/whitespace entries; if anything
+ *   survives, use the filtered array
+ * - Anything else (undefined, null, empty array post-filter, wrong type) →
+ *   fall back to `DEFAULT_SKILLS_DIRS` (which itself reads `SENPI_SKILLS_DIR`
+ *   as a comma-separated list, or the canonical install path as the final
+ *   fallback)
+ *
+ * Always returns a non-empty array — callers can rely on `[0]` existing as
+ * the *primary* (writes go here; reads scan in order).
+ */
+export declare function normalizeSkillsDir(value: unknown): string[];
 //# sourceMappingURL=utils.d.ts.map

package/dist/skills-manager/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/skills-manager/utils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,sBAAsB,EACtB,mBAAmB,EACnB,kBAAkB,EAClB,UAAU,EACX,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,MAAM,EAA8B,CAAC;AAEnF;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,CAAC,EAAE,sBAAsB,GAAG,IAAI,GACpC,mBAAmB,CAiBrB;AAED;;;;;;GAMG;AACH,wBAAgB,+BAA+B,IAAI,kBAAkB,CAEpE;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAWhE;AAED,0EAA0E;AAC1E,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,CAE5C"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/skills-manager/utils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,sBAAsB,EACtB,mBAAmB,EACnB,kBAAkB,EAClB,UAAU,EACX,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,MAAM,EAA8B,CAAC;AAEnF;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,CAAC,EAAE,sBAAsB,GAAG,IAAI,GACpC,mBAAmB,CAcrB;AAED;;;;;;GAMG;AACH,wBAAgB,+BAA+B,IAAI,kBAAkB,CAEpE;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAWhE;AAED,0EAA0E;AAC1E,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,CAE5C;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAc3D"}

package/dist/skills-manager/utils.js

@@ -1,4 +1,4 @@
-import { DEFAULT_SKILLS_DIR } from "./constants.js";
+import { DEFAULT_SKILLS_DIRS } from "./constants.js";
 /**
  * Canonical default list of managed skill names when the user omits the
  * `skills` field. Kept in sync with the JSON Schema default in
@@ -28,10 +28,7 @@ export function resolveSkillsManagerConfig(value) {
     const raw = value ?? {};
     return {
         enabled: toBool(raw.enabled, true),
-        skillsDir: typeof raw.skillsDir === "string" && raw.skillsDir.length > 0
-            ? raw.skillsDir
-            : DEFAULT_SKILLS_DIR,
-        pollIntervalMinutes: clamp(toFinite(raw.pollIntervalMinutes, 60), 1, 24 * 60),
+        skillsDir: normalizeSkillsDir(raw.skillsDir),
         // Field-omitted vs explicit-empty distinction matters here:
         // - undefined / null / non-array → use canonical default (matches the
         //   JSON Schema default in openclaw.plugin.json — keeps wizard-written
@@ -75,13 +72,48 @@ export function createDefaultSkillState(name) {
 export function formatErr(e) {
     return e instanceof Error ? e.message : String(e);
 }
+/**
+ * Normalise the raw `skillsDir` value into a non-empty `string[]` (the
+ * "search path" form used internally).
+ *
+ * Resolution rules:
+ * - Single string → wrap as `[value]` (legacy single-dir form)
+ * - Array → filter out non-strings and empty/whitespace entries; if anything
+ *   survives, use the filtered array
+ * - Anything else (undefined, null, empty array post-filter, wrong type) →
+ *   fall back to `DEFAULT_SKILLS_DIRS` (which itself reads `SENPI_SKILLS_DIR`
+ *   as a comma-separated list, or the canonical install path as the final
+ *   fallback)
+ *
+ * Always returns a non-empty array — callers can rely on `[0]` existing as
+ * the *primary* (writes go here; reads scan in order).
+ */
+export function normalizeSkillsDir(value) {
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        if (trimmed.length > 0)
+            return [trimmed];
+    }
+    else if (Array.isArray(value)) {
+        const filtered = value
+            .filter((v) => typeof v === "string")
+            .map((s) => s.trim())
+            .filter((s) => s.length > 0);
+        if (filtered.length > 0)
+            return filtered;
+    }
+    // DEFAULT_SKILLS_DIRS is a readonly tuple at module level — return a fresh
+    // mutable copy so callers that mutate (e.g. tests) don't poison the global.
+    return [...DEFAULT_SKILLS_DIRS];
+}
+// ─── Local config-coercion helpers ──────────────────────────────────────────
+// `toBool` is intentionally duplicated from `src/runtime/auto-update/types.ts`
+// to keep `src/skills-manager/` free of any compile- or runtime-time
+// dependency on the auto-update package. An earlier attempt to consolidate
+// this style of helper across the two modules (commit 48592db, "consolidate
+// formatErr into policy.ts") was reverted in 5a94af8 with the explicit rule
+// "do not touch auto-update module" — same rationale applies here.
 function toBool(value, fallback) {
     return typeof value === "boolean" ? value : fallback;
 }
-function toFinite(value, fallback) {
-    return typeof value === "number" && Number.isFinite(value) ? value : fallback;
-}
-function clamp(v, min, max) {
-    return Math.min(max, Math.max(min, v));
-}
 //# sourceMappingURL=utils.js.map

package/dist/skills-manager/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/skills-manager/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAQpD;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAsB,CAAC,uBAAuB,CAAC,CAAC;AAEnF;;;;;;;;;GASG;AACH,MAAM,UAAU,0BAA0B,CACxC,KAAqC;IAErC,MAAM,GAAG,GAAG,KAAK,IAAI,EAAE,CAAC;IACxB,OAAO;QACL,OAAO,EAAE,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC;QAClC,SAAS,EAAE,OAAO,GAAG,CAAC,SAAS,KAAK,QAAQ,IAAI,GAAG,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC;YACtE,CAAC,CAAC,GAAG,CAAC,SAAS;YACf,CAAC,CAAC,kBAAkB;QACtB,mBAAmB,EAAE,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,mBAAmB,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC;QAC7E,4DAA4D;QAC5D,sEAAsE;QACtE,uEAAuE;QACvE,6BAA6B;QAC7B,oEAAoE;QACpE,MAAM,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC;YAC/B,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;YACjE,CAAC,CAAC,CAAC,GAAG,sBAAsB,CAAC;KAChC,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,+BAA+B;IAC7C,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;AACxB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAAY;IAClD,OAAO;QACL,IAAI;QACJ,gBAAgB,EAAE,IAAI;QACtB,aAAa,EAAE,IAAI;QACnB,kBAAkB,EAAE,IAAI;QACxB,wBAAwB,EAAE,IAAI;QAC9B,mBAAmB,EAAE,CAAC;QACtB,aAAa,EAAE,IAAI;QACnB,iBAAiB,EAAE,IAAI;KACxB,CAAC;AACJ,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,SAAS,CAAC,CAAU;IAClC,OAAO,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;AACpD,CAAC;AAED,SAAS,MAAM,CAAC,KAAc,EAAE,QAAiB;IAC/C,OAAO,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC;AACvD,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc,EAAE,QAAgB;IAChD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC;AAChF,CAAC;AAED,SAAS,KAAK,CAAC,CAAS,EAAE,GAAW,EAAE,GAAW;IAChD,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;AACzC,CAAC"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/skills-manager/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAQrD;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAsB,CAAC,uBAAuB,CAAC,CAAC;AAEnF;;;;;;;;;GASG;AACH,MAAM,UAAU,0BAA0B,CACxC,KAAqC;IAErC,MAAM,GAAG,GAAG,KAAK,IAAI,EAAE,CAAC;IACxB,OAAO;QACL,OAAO,EAAE,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC;QAClC,SAAS,EAAE,kBAAkB,CAAC,GAAG,CAAC,SAAS,CAAC;QAC5C,4DAA4D;QAC5D,sEAAsE;QACtE,uEAAuE;QACvE,6BAA6B;QAC7B,oEAAoE;QACpE,MAAM,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC;YAC/B,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;YACjE,CAAC,CAAC,CAAC,GAAG,sBAAsB,CAAC;KAChC,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,+BAA+B;IAC7C,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;AACxB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAAY;IAClD,OAAO;QACL,IAAI;QACJ,gBAAgB,EAAE,IAAI;QACtB,aAAa,EAAE,IAAI;QACnB,kBAAkB,EAAE,IAAI;QACxB,wBAAwB,EAAE,IAAI;QAC9B,mBAAmB,EAAE,CAAC;QACtB,aAAa,EAAE,IAAI;QACnB,iBAAiB,EAAE,IAAI;KACxB,CAAC;AACJ,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,SAAS,CAAC,CAAU;IAClC,OAAO,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;AACpD,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAc;IAC/C,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;QAC7B,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3C,CAAC;SAAM,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAChC,MAAM,QAAQ,GAAG,KAAK;aACnB,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC;aACjD,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;aACpB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QAC/B,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,QAAQ,CAAC;IAC3C,CAAC;IACD,2EAA2E;IAC3E,4EAA4E;IAC5E,OAAO,CAAC,GAAG,mBAAmB,CAAC,CAAC;AAClC,CAAC;AAED,+EAA+E;AAC/E,+EAA+E;AAC/E,qEAAqE;AACrE,2EAA2E;AAC3E,4EAA4E;AAC5E,4EAA4E;AAC5E,mEAAmE;AACnE,SAAS,MAAM,CAAC,KAAc,EAAE,QAAiB;IAC/C,OAAO,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC;AACvD,CAAC"}

package/dist/skills-manager/version-manager.d.ts

@@ -26,18 +26,91 @@ export declare function normalizeVersion(v: string): string;
  * Returns null when the frontmatter block is absent or the field is missing.
  */
 export declare function parseSkillMdVersion(content: string): string | null;
+/**
+ * Extract the `description` value from a SKILL.md YAML frontmatter block.
+ *
+ * Skill descriptions can be authored a few different ways. This helper
+ * handles the real-world shapes that appear in the senpi-skills repo today:
+ *
+ *   1. Single-line, double-quoted:
+ *        description: "Configure, deploy, ..."
+ *   2. Single-line, single-quoted or unquoted:
+ *        description: Manage runtimes ...
+ *   3. YAML block scalar (folded or literal, optional chomping indicator):
+ *        description: >
+ *          A short summary
+ *          continues on this line.
+ *        description: >-       # strip trailing newlines (this PR's senpi-skills repo)
+ *          A short summary
+ *        description: |        # literal — preserves newlines (collapsed to spaces here)
+ *          A short summary
+ *        description: |+       # keep trailing newlines (same handling)
+ *
+ *      The block scalar header is `[>|][-+]?` per the YAML 1.2 spec:
+ *      `>` = folded, `|` = literal; `-` strips trailing newlines,
+ *      `+` keeps them, no indicator clips. For notification rendering we
+ *      always collapse to a single line joined by spaces, so the chomping
+ *      indicator only affects whether we match the block-scalar branch.
+ *
+ * Returns null when the field is absent or the frontmatter block is missing.
+ *
+ * Note: kept as a regex extractor rather than introducing a full YAML
+ * parse here — `parseSkillMdVersion` uses the same approach, and skill
+ * frontmatters are constrained enough that the regex covers the shapes we
+ * actually encounter. If we ever adopt a full YAML parser for this file,
+ * both helpers should switch together.
+ */
+export declare function parseSkillMdDescription(content: string): string | null;
+/**
+ * Read both the installed version and description for a skill from its local
+ * SKILL.md. Shared core for `readLocalVersion` and `readLocalDescription` so a
+ * tick that needs both pays a single file read per dir rather than two.
+ *
+ * Multi-dir search path: tries each entry in order and returns the first
+ * readable SKILL.md's parsed fields. Either field may be null if absent in
+ * the frontmatter — that's distinct from "no SKILL.md found at all" (which
+ * returns nulls only after every dir has been tried).
+ */
+export declare function readLocalSkillMetadata(skillsDir: string | readonly string[], skillName: string, logger?: LoggerLike): Promise<{
+    version: string | null;
+    description: string | null;
+}>;
 /**
  * Read the installed version for a skill from its local SKILL.md.
- * Returns null when the file is absent or the version field is missing.
- * Logs a warning for unexpected errors (anything other than ENOENT).
+ *
+ * Accepts either a single dir (legacy callers) or an array of dirs (new
+ * multi-dir search path). When given an array, tries each entry in order and
+ * returns the first non-null match — this mirrors the documented behaviour
+ * that `skillsDir[0]` is the *primary* (writes go here) and the remaining
+ * entries are read-only fallbacks scanned during version checks.
+ *
+ * Returns null when no readable SKILL.md is found across any of the
+ * candidate dirs, or when the version field is absent. Logs a warning per
+ * dir for unexpected errors (anything other than ENOENT).
  */
-export declare function readLocalVersion(skillsDir: string, skillName: string, logger?: LoggerLike): Promise<string | null>;
+export declare function readLocalVersion(skillsDir: string | readonly string[], skillName: string, logger?: LoggerLike): Promise<string | null>;
 /**
- * Fetch the remote SKILL.md for a skill and return its version.
+ * Read the installed description for a skill from its local SKILL.md.
+ * Multi-dir search path semantics identical to `readLocalVersion`.
+ *
+ * Returns null when no readable SKILL.md is found across any of the
+ * candidate dirs, or when the description field is absent.
+ */
+export declare function readLocalDescription(skillsDir: string | readonly string[], skillName: string, logger?: LoggerLike): Promise<string | null>;
+/**
+ * Fetch the remote SKILL.md for a skill and return both the version and the
+ * description in one network round-trip.
  *
- * Returns null when the skill does not exist in the remote repo (HTTP 404) —
- * that's a legitimate state ("skill removed or not yet published"), not an
- * error, so it should not pollute failure counters.
+ * Notification text uses the description from the **remote** SKILL.md (not
+ * the local one) so the "About:" line reflects the version the user is being
+ * asked about — a description on disk for v1.x may be stale relative to the
+ * v2.0.0 the major-update notification is announcing.
+ *
+ * Returns null fields when the skill does not exist in the remote repo
+ * (HTTP 404) — that's a legitimate state ("skill removed or not yet
+ * published"), not an error, so it should not pollute failure counters.
+ * Both fields may also be null when the remote SKILL.md is present but
+ * its frontmatter omits the corresponding field.
  *
  * Throws on transient/operational failures (network errors, timeouts, 5xx
  * responses, body-parse failures) so the caller's failure-recording path can
@@ -45,6 +118,18 @@ export declare function readLocalVersion(skillsDir: string, skillName: string, l
  *
  * @param fetchImpl Injectable for unit testing — defaults to global `fetch`.
  */
+export declare function fetchRemoteSkillMetadata(skillName: string, rawBaseUrl?: string, fetchImpl?: typeof fetch): Promise<{
+    version: string | null;
+    description: string | null;
+}>;
+/**
+ * Fetch the remote SKILL.md for a skill and return its version.
+ *
+ * Thin wrapper over {@link fetchRemoteSkillMetadata} kept for backward
+ * compatibility with callers (and tests) that only need the version field.
+ * New code that wants both version + description in a single round-trip
+ * should call `fetchRemoteSkillMetadata` directly.
+ */
 export declare function fetchRemoteVersion(skillName: string, rawBaseUrl?: string, fetchImpl?: typeof fetch): Promise<string | null>;
 /**
  * Compare the local and remote versions for a skill and return a classified diff.
@@ -57,5 +142,5 @@ export declare function fetchRemoteVersion(skillName: string, rawBaseUrl?: strin
  * - Remote version is absent or unparseable → "unknown", caller should log and
  *   skip.
  */
-export declare function checkSkillVersion(skillsDir: string, skillName: string, rawBaseUrl?: string, fetchImpl?: typeof fetch, logger?: LoggerLike): Promise<SkillVersionInfo>;
+export declare function checkSkillVersion(skillsDir: string | readonly string[], skillName: string, rawBaseUrl?: string, fetchImpl?: typeof fetch, logger?: LoggerLike): Promise<SkillVersionInfo>;
 //# sourceMappingURL=version-manager.d.ts.map

package/dist/skills-manager/version-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"version-manager.d.ts","sourceRoot":"","sources":["../../src/skills-manager/version-manager.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,KAAK,EAAE,UAAU,EAAmB,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAGhF;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMlE;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,UAAU,GAClB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAaxB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,MAAM,EACjB,UAAU,GAAE,MAA4B,EACxC,SAAS,GAAE,OAAO,KAAa,GAC9B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA+BxB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,UAAU,GAAE,MAA4B,EACxC,SAAS,GAAE,OAAO,KAAa,EAC/B,MAAM,CAAC,EAAE,UAAU,GAClB,OAAO,CAAC,gBAAgB,CAAC,CAyC3B"}
+{"version":3,"file":"version-manager.d.ts","sourceRoot":"","sources":["../../src/skills-manager/version-manager.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,KAAK,EAAE,UAAU,EAAmB,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAGhF;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMlE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA6CtE;AASD;;;;;;;;;GASG;AACH,wBAAsB,sBAAsB,CAC1C,SAAS,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,EACrC,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,UAAU,GAClB,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,CA2BjE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,EACrC,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,UAAU,GAClB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAExB;AAED;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,SAAS,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,EACrC,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,UAAU,GAClB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAExB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,wBAAwB,CAC5C,SAAS,EAAE,MAAM,EACjB,UAAU,GAAE,MAA4B,EACxC,SAAS,GAAE,OAAO,KAAa,GAC9B,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,CAkCjE;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,MAAM,EACjB,UAAU,GAAE,MAA4B,EACxC,SAAS,GAAE,OAAO,KAAa,GAC9B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAExB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,EACrC,SAAS,EAAE,MAAM,EACjB,UAAU,GAAE,MAA4B,EACxC,SAAS,GAAE,OAAO,KAAa,EAC/B,MAAM,CAAC,EAAE,UAAU,GAClB,OAAO,CAAC,gBAAgB,CAAC,CAgD3B"}