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

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

@@ -1,20 +1,32 @@
 /**
  * Central lifecycle manager for Senpi skills auto-update.
  *
- * Mirrors AutoUpdateCoordinator from src/runtime/auto-update/coordinator.ts:
- * same runToken + stopped + running triple for thread-safety, same
- * self-managed setTimeout loop, same injectable-dependency pattern for
- * testability.
+ * Mirrors AutoUpdateCoordinator from src/runtime/auto-update/coordinator.ts
+ * for thread-safety (runToken + stopped + running triple) and uses the same
+ * injectable-dependency pattern for testability.
  *
- * On start(): bootstrap missing skills then schedule the first poll.
- * Each tick(): resolve skill names, check remote versions in parallel,
- * auto-apply patch/minor, notify on major (deduped), skip on none/unknown.
+ * Scheduling: this coordinator does not own a timer. Ticks fire from
+ * outside — currently from auto-update's `onTickComplete` hook in
+ * `src/index.ts`, which calls {@link SkillsUpdateCoordinator.runTickOnce}
+ * after every auto-update cycle. Skills-manager therefore inherits the
+ * `autoUpdate.pollIntervalMinutes` cadence and the same failure-backoff
+ * cadence.
+ *
+ * On start(): load persisted state, bootstrap any missing skills, mark
+ * health as healthy. The first tick fires on the next external invocation
+ * of `runTickOnce()`.
+ *
+ * Each tick: resolve skill names (configured list or discovery), check
+ * remote versions in parallel, auto-apply patch/minor, notify on major
+ * (deduped by version), skip on none/unknown.
  */
 import type { SkillsManagerSnapshot, SkillsUpdateCoordinatorOptions } from "./types.js";
+export declare class SkillsCoordinatorUnavailableError extends Error {
+    constructor(message: string);
+}
 export declare class SkillsUpdateCoordinator {
     private readonly options;
     private readonly store;
-    private timer;
     private operationChain;
     private stopped;
     private runToken;
@@ -22,17 +34,81 @@ export declare class SkillsUpdateCoordinator {
     private snapshot;
     /** Latest remote version per skill name — populated during ticks. */
     private latestVersions;
+    /**
+     * Local (pre-install) version per skill name — populated during ticks
+     * and manual RPC paths from `SkillVersionInfo.localVersion`. Used by the
+     * update-summary and major-available notifications to render the
+     * `prev → new` transition. Captured *before* the install runs so the
+     * value still reflects the on-disk version at the time the user chose to
+     * update; reading `state.skills[name].installedVersion` instead would
+     * surface the *post-install* version (recorded by `recordSuccess`) and
+     * collapse the transition to `vX -> vX`.
+     */
+    private previousVersions;
+    /**
+     * Cached short descriptions parsed from each skill's **remote** SKILL.md
+     * frontmatter — i.e. the description for the upcoming/current remote
+     * version, not whatever's installed locally. Used to enrich
+     * update-summary and major-available notifications with a one-line
+     * "About:" so the user gets context for the version the message is
+     * actually announcing.
+     *
+     * Populated during tick / updateSkill / updateAll alongside
+     * `latestVersions`; absent / null entries simply omit the line from the
+     * notification.
+     *
+     * Using the remote description (rather than the local one) keeps the
+     * notification description in sync with the version number it sits next
+     * to — e.g. when notifying about a major bump v1 → v2, the "About:" line
+     * reflects the v2 description, even if the v1 local copy on disk is
+     * stale or worded differently.
+     */
+    private skillDescriptions;
     constructor(options: SkillsUpdateCoordinatorOptions);
-    /** Load persisted state, bootstrap missing skills, and schedule the first poll. */
+    /**
+     * Load persisted state and bootstrap missing skills. Does **not** schedule
+     * a poll loop — skills-manager runs off the auto-update coordinator's
+     * `onTickComplete` hook (see `src/index.ts`), which invokes
+     * {@link runTickOnce} on whatever cadence auto-update is configured with.
+     *
+     * Calling `start()` is still required even in the externally-scheduled
+     * mode so bootstrap, state load, and the "ready" snapshot all happen
+     * before the first external tick fires.
+     */
     start(): Promise<void>;
     /**
-     * Cancel the next scheduled poll, prevent in-flight ticks from rescheduling,
-     * and wait for any currently-executing tick or manual RPC to finish so the
-     * caller can rely on no async work still touching state after `stop()`
-     * resolves. Without this drain, a caller `await coordinator.stop()` could
-     * proceed to e.g. delete the state dir while a tick mid-write fires.
+     * Stop the coordinator: prevent any new ticks from being processed, and
+     * wait for any in-flight tick or manual RPC to finish so the caller can
+     * rely on no async work still touching state after `stop()` resolves.
+     *
+     * Since scheduling is now external (auto-update's `onTickComplete` hook),
+     * there's no internal timer to cancel — `stop()` just flips the `stopped`
+     * flag (which `runTickOnce` checks) and drains the serialised operation
+     * queue. The auto-update hook itself becomes a no-op for stopped
+     * coordinators since `runTickOnce` returns early.
      */
     stop(): Promise<void>;
+    /**
+     * Public one-shot tick entry point. Called externally on whatever cadence
+     * the host wires up — currently from the auto-update coordinator's
+     * `onTickComplete` hook in `src/index.ts`, which fires after each
+     * auto-update version check completes (success or failure).
+     *
+     * Replaces the previous internal `tick()` + `scheduleNext()` pair: the
+     * coordinator no longer owns a timer of its own. Manual RPCs
+     * (`senpi.skills.update`, `senpi.skills.updateAll`) remain independent of
+     * this path.
+     *
+     * Returns early as a no-op when:
+     * - The coordinator has been stopped (e.g. plugin teardown).
+     * - The runToken has rolled (e.g. a stop/start cycle invalidated this call).
+     * - The coordinator was disabled at start time (config.enabled === false).
+     *
+     * Tick errors are logged + recorded on the snapshot but never thrown —
+     * the caller (auto-update) must not have its own scheduling disturbed by
+     * a transient skills-manager failure.
+     */
+    runTickOnce(): Promise<void>;
     /** Return the latest point-in-time snapshot for gateway RPCs. */
     getSnapshot(): SkillsManagerSnapshot;
     /**
@@ -66,13 +142,18 @@ export declare class SkillsUpdateCoordinator {
         version: string | null;
         error?: string;
     }>>;
-    private scheduleNext;
-    private tick;
     /**
      * Run coordinator work in a global critical section so periodic ticks and
      * manual RPC updates never interleave at await points.
      */
     private runSerialized;
+    /**
+     * Manual gateway RPCs (`updateSkill`, `updateAll`) are only valid while the
+     * coordinator is actively running and enabled. This prevents pre-start calls
+     * (e.g. when SENPI_RUNTIME_API_DISABLED=true skipped start()) from persisting
+     * the constructor-default empty state over a valid on-disk state file.
+     */
+    private assertManualOperationAllowed;
     /**
      * Core tick logic: resolve skill names, check versions in parallel, apply
      * policy per skill, then run a single clone for all skills needing update.
@@ -148,6 +229,39 @@ export declare class SkillsUpdateCoordinator {
      * caller via a rejected promise (batch path captures it instead).
      */
     private applyUpdate;
+    /**
+     * Format the per-skill nested-bullet block used in both notification
+     * shapes. Renders the structure suggested in PR #78 review feedback:
+     *
+     *   **skill-name**
+     *      • v1.0.0 → v2.0.0       (or "v1.0.0 (install failed)" when failed)
+     *      • description: …         (omitted when no remote description)
+     *      • error: …               (only on failure, replaces the description)
+     *
+     * **Why markdown, not HTML?**
+     * Openclaw's Telegram channel (`src/telegram/send.ts:sendMessageTelegram`)
+     * pipes outbound text through `renderTelegramHtmlText`, which defaults
+     * `textMode` to `"markdown"` — i.e. it expects the source to be markdown
+     * and runs `markdownToTelegramHtml` over it before handing the converted
+     * HTML to the Bot API with `parse_mode: "HTML"`. The `message` tool
+     * (which is what this coordinator's `notify` callback ultimately hits via
+     * `/tools/invoke`) does not expose `textMode`, so HTML written by us is
+     * treated as literal characters by the markdown step and rendered as
+     * visible `<b>` text in the chat (the actual production bug this docstring
+     * fixes — confirmed against a live notification screenshot).
+     *
+     * Using markdown source (`**bold**`, backticks) instead means the channel's
+     * markdown→HTML converter produces the correct `<b>` / `<code>` HTML
+     * payload and Telegram renders the formatting properly.
+     *
+     * @param skillName Skill identifier (rendered bold via `**name**`).
+     * @param toVersion Resolved upgraded-to version. `null` for failure rows
+     *                  where no install completed; renders as
+     *                  "vPREV (install failed)".
+     * @param errorReason Optional failure reason. When provided, replaces
+     *                    the description line with `error: …`.
+     */
+    private formatSkillBlock;
     /**
      * Send a one-way Telegram notification for a pending major update, deduped
      * by version.
@@ -164,6 +278,27 @@ export declare class SkillsUpdateCoordinator {
      * so the user can tell which skills still need attention. Sections with no
      * entries are omitted. If neither section has entries, no notification is
      * sent.
+     *
+     * Format (markdown source — see `formatSkillBlock` for why markdown
+     * rather than HTML):
+     *
+     *   Senpi skills update:
+     *
+     *   Updated:
+     *
+     *   **skill-a**
+     *      • v1.0.0 → v1.0.1
+     *      • description: …
+     *
+     *   **skill-b**
+     *      • v2.0.0 → v2.0.1
+     *      • description: …
+     *
+     *   Failed to update:
+     *
+     *   **skill-c**
+     *      • v1.0.0 (install failed)
+     *      • error: clone failed: …
      */
     private sendUpdateSummary;
     /**
@@ -179,7 +314,12 @@ export declare class SkillsUpdateCoordinator {
     /**
      * Resolve the list of skill names to check this tick.
      * Uses `config.skills` when non-empty; otherwise discovers all immediate
-     * subdirectories of `skillsDir`.
+     * subdirectories across every dir in the `skillsDir` search path,
+     * deduped by name and sorted.
+     *
+     * Per-dir read errors (other than ENOENT) are logged but do not abort the
+     * scan — a misconfigured secondary dir cannot mask skills present in the
+     * primary.
      */
     private resolveSkillNames;
     /**
@@ -195,9 +335,6 @@ export declare class SkillsUpdateCoordinator {
      *   3. Caller-supplied lifecycle metadata — `health`, `lastAction`,
      *      `lastError` describing the most recent tick / manual RPC outcome.
      *
-     * `nextCheckAt` is preserved from the previous snapshot so callers always
-     * see a valid ETA even on transient rebuilds (e.g. mid-tick error paths).
-     *
      * This is called at every state-mutating boundary (start, tick complete,
      * tick error, manual update complete, manual update skipped, manual update
      * clone failed, stop/disable) so the next RPC response reflects the latest

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

@@ -1 +1 @@
-{"version":3,"file":"coordinator.d.ts","sourceRoot":"","sources":["../../src/skills-manager/coordinator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAQH,OAAO,KAAK,EAMV,qBAAqB,EAGrB,8BAA8B,EAC/B,MAAM,YAAY,CAAC;AAIpB,qBAAa,uBAAuB;IAWtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAVpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA0B;IAChD,OAAO,CAAC,KAAK,CAA+B;IAC5C,OAAO,CAAC,cAAc,CAAoC;IAC1D,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,KAAK,CAAyD;IACtE,OAAO,CAAC,QAAQ,CAAwB;IACxC,qEAAqE;IACrE,OAAO,CAAC,cAAc,CAAoC;gBAE7B,OAAO,EAAE,8BAA8B;IAKpE,mFAAmF;IAC7E,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA8B5B;;;;;;OAMG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAe3B,iEAAiE;IACjE,WAAW,IAAI,qBAAqB;IAMpC;;;;;;;;;;OAUG;IACG,WAAW,CACf,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAwFxD;;;;;;;;;OASG;IACG,SAAS,IAAI,OAAO,CACxB,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAClF;IAuID,OAAO,CAAC,YAAY;YAWN,IAAI;IAoBlB;;;OAGG;YACW,aAAa;IAwB3B;;;OAGG;YACW,OAAO;IAoFrB;;;;;;;;;;OAUG;YACW,YAAY;IAsC1B;;;;;;;;;;;OAWG;YACW,mBAAmB;IAyDjC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,aAAa;IAQrB;;;;;;;OAOG;IACH,OAAO,CAAC,kBAAkB;IAU1B;;;OAGG;IACH,OAAO,CAAC,qBAAqB;IAmB7B;;;;;;;;OAQG;YACW,WAAW;IAmDzB;;;;;;;;OAQG;YACW,oBAAoB;IA6BlC;;;;;;OAMG;YACW,iBAAiB;IA+B/B;;;;;;;;OAQG;IACH,OAAO,CAAC,cAAc;IAQtB;;;;OAIG;YACW,iBAAiB;IAqB/B;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,aAAa;YAyBP,YAAY;CAS3B"}
+{"version":3,"file":"coordinator.d.ts","sourceRoot":"","sources":["../../src/skills-manager/coordinator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAQH,OAAO,KAAK,EAMV,qBAAqB,EAGrB,8BAA8B,EAC/B,MAAM,YAAY,CAAC;AAIpB,qBAAa,iCAAkC,SAAQ,KAAK;gBAC9C,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,uBAAuB;IAwCtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAvCpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA0B;IAChD,OAAO,CAAC,cAAc,CAAoC;IAC1D,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,KAAK,CAAyD;IACtE,OAAO,CAAC,QAAQ,CAAwB;IACxC,qEAAqE;IACrE,OAAO,CAAC,cAAc,CAAoC;IAC1D;;;;;;;;;OASG;IACH,OAAO,CAAC,gBAAgB,CAAoC;IAC5D;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,iBAAiB,CAAoC;gBAEhC,OAAO,EAAE,8BAA8B;IAKpE;;;;;;;;;OASG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA4B5B;;;;;;;;;;OAUG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAW3B;;;;;;;;;;;;;;;;;;;OAmBG;IACG,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAmBlC,iEAAiE;IACjE,WAAW,IAAI,qBAAqB;IAMpC;;;;;;;;;;OAUG;IACG,WAAW,CACf,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IA8FxD;;;;;;;;;OASG;IACG,SAAS,IAAI,OAAO,CACxB,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAClF;IA0ID;;;OAGG;YACW,aAAa;IAwB3B;;;;;OAKG;IACH,OAAO,CAAC,4BAA4B;IAqBpC;;;OAGG;YACW,OAAO;IAsFrB;;;;;;;;;;OAUG;YACW,YAAY;IAsC1B;;;;;;;;;;;OAWG;YACW,mBAAmB;IA4DjC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,aAAa;IAQrB;;;;;;;OAOG;IACH,OAAO,CAAC,kBAAkB;IAU1B;;;OAGG;IACH,OAAO,CAAC,qBAAqB;IAmB7B;;;;;;;;OAQG;YACW,WAAW;IAmDzB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,OAAO,CAAC,gBAAgB;IAwBxB;;;;;;;;OAQG;YACW,oBAAoB;IAuClC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;YACW,iBAAiB;IAgC/B;;;;;;;;OAQG;IACH,OAAO,CAAC,cAAc;IAYtB;;;;;;;;;OASG;YACW,iBAAiB;IAqC/B;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,aAAa;YA2BP,YAAY;CAS3B"}