@senpi/runtime 1.0.95-dev.runtime-phase-2.20260508073606 → 1.1.0-dev.main.20260527104621

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

@@ -0,0 +1,346 @@
+/**
+ * Central lifecycle manager for Senpi skills auto-update.
+ *
+ * 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.
+ *
+ * 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 operationChain;
+    private stopped;
+    private runToken;
+    private state;
+    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 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>;
+    /**
+     * 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;
+    /**
+     * Force an immediate version check and apply for one named skill.
+     *
+     * Skips installation when the update kind is `"none"` (already current) or
+     * `"unknown"` (remote version could not be classified — e.g. the fetch
+     * failed or the remote `version` field is missing). Falling through on
+     * `"unknown"` would write `installedVersion: null` and lose tracking, so we
+     * treat it the same as `"none"` and return `updated: false`.
+     *
+     * @throws On network or install error so the gateway RPC can return ok=false.
+     */
+    updateSkill(skillName: string): Promise<{
+        updated: boolean;
+        version: string | null;
+    }>;
+    /**
+     * Force an immediate version check and apply for all discovered/configured skills.
+     * Individual failures do not abort the remaining skills.
+     *
+     * All skills share a single `git clone` — the repo is cloned once, every
+     * skill that needs an update is installed from that same checkout, then the
+     * checkout is cleaned up. A previous version called `updateSkill` in a loop,
+     * which caused one full clone per skill (N redundant clones for N skills);
+     * this mirrors the tick path's batching instead.
+     */
+    updateAll(): Promise<Array<{
+        name: string;
+        updated: boolean;
+        version: string | null;
+        error?: string;
+    }>>;
+    /**
+     * 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.
+     */
+    private runTick;
+    /**
+     * Clone the repo once and install every skill in `skillNames`.
+     * Per-skill errors are recorded in state without aborting the others.
+     * The update summary notification distinguishes successful installs from
+     * failures so the user can see exactly which skills need attention.
+     *
+     * If the clone itself fails we log and return without touching state or
+     * sending a summary — a full-clone failure is almost always a transient
+     * network/git issue that affects every skill equally, so attributing it
+     * per-skill would be misleading. The next tick retries.
+     */
+    private applyUpdates;
+    /**
+     * Clone the remote skills repo exactly once and install every skill in
+     * `skillNames` from that single checkout. Returns a per-skill outcome map:
+     * `{ version }` on success or `{ version: null, error }` on install failure.
+     *
+     * Throws only when the clone itself fails — per-skill install failures are
+     * captured in the map so callers can continue processing the rest.
+     *
+     * When `deps.cloneAndInstall` is supplied (unit tests), that injector is
+     * called in place of the real clone+install loop; any names missing from
+     * its returned map are treated as install failures.
+     */
+    private cloneAndInstallMany;
+    /**
+     * Record a successful install on in-memory skill state.
+     *
+     * Resets failure tracking — a successful end-to-end install is the only
+     * signal we treat as "operationally healthy." A successful version check
+     * alone is NOT sufficient (and intentionally does not call this), because:
+     *
+     * - The version check only proves the raw SKILL.md is reachable. It does
+     *   not exercise the clone/copy/swap pipeline that actually keeps the skill
+     *   working.
+     * - Clearing failure state on every check-success would wipe install-failure
+     *   history mid-tick: a skill failing to install on every tick would still
+     *   report `consecutiveFailures: 1` (instead of N) because each tick's
+     *   check-success reset would precede the install-failure increment.
+     *
+     * Consequence: a skill that's perpetually up-to-date but had a one-off
+     * failure in the past will retain a non-zero `consecutiveFailures` until
+     * the next install. We accept that trade-off — surfacing a stale failure
+     * counter is preferable to silently wiping real install-failure history.
+     */
+    private recordSuccess;
+    /**
+     * Record a version-check failure on in-memory skill state.
+     *
+     * Shared by `runTick` and `updateAll` — both need to bump
+     * `consecutiveFailures` and capture the reason when `Promise.allSettled`
+     * surfaces a rejected check. `lastCheckedAt` is updated too so the snapshot
+     * doesn't look like the skill was never polled (it was — the poll failed).
+     */
+    private recordCheckFailure;
+    /**
+     * Apply one install outcome to in-memory skill state and return a compact
+     * success/failure result for the caller's bookkeeping.
+     */
+    private processInstallOutcome;
+    /**
+     * Apply a single skill update (used by the manual `updateSkill` RPC path).
+     * Returns the installed version.
+     *
+     * Delegates to {@link cloneAndInstallMany} so the single-skill and batch
+     * paths share one implementation of clone+install. The per-skill install
+     * error is re-thrown here so `updateSkill` can surface it to the RPC
+     * 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.
+     *
+     * The dedup key (`lastNotifiedMajorVersion`) is only set after the notify
+     * call resolves successfully. If the notification fails (Telegram API down,
+     * transient network error, etc.) the key is left unchanged so the next tick
+     * retries delivery instead of silently suppressing it forever.
+     */
+    private handleMajorAvailable;
+    /**
+     * Send an aggregated notification summarising the outcome of this tick's
+     * updates. Successful installs and failures are shown in separate sections
+     * 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;
+    /**
+     * Return the version-check function for this coordinator: either the
+     * injected `deps.checkSkillVersion` (unit tests) or the real
+     * `checkSkillVersion` with the default `fetchImpl`.
+     *
+     * Extracted so the three call sites (`updateSkill`, `updateAll`, `runTick`)
+     * don't repeat the same resolve-and-wrap lambda — a change to the real
+     * `checkSkillVersion` signature now only has to land here.
+     */
+    private resolveCheckFn;
+    /**
+     * Resolve the list of skill names to check this tick.
+     * Uses `config.skills` when non-empty; otherwise discovers all immediate
+     * 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;
+    /**
+     * Build the point-in-time snapshot returned by {@link getSnapshot}.
+     *
+     * The snapshot is the single serialisable view of the coordinator's state
+     * consumed by gateway RPCs (`senpi.skills.status`) and any health UI. It
+     * fuses three data sources:
+     *   1. Per-skill persisted state (`this.state.skills`) — installed version,
+     *      last check time, consecutive failures, last failure reason.
+     *   2. In-memory `this.latestVersions` map — the most recent remote version
+     *      observed during a version check (may not yet be installed).
+     *   3. Caller-supplied lifecycle metadata — `health`, `lastAction`,
+     *      `lastError` describing the most recent tick / manual RPC outcome.
+     *
+     * 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
+     * state rather than stale pre-action data.
+     */
+    private buildSnapshot;
+    private persistState;
+}
+//# sourceMappingURL=coordinator.d.ts.map

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

@@ -0,0 +1 @@
+{"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;AASpB,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;IAmGxD;;;;;;;;;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;IA2ID;;;OAGG;YACW,aAAa;IAwB3B;;;;;OAKG;IACH,OAAO,CAAC,4BAA4B;IAqBpC;;;OAGG;YACW,OAAO;IAuFrB;;;;;;;;;;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;IAgCxB;;;;;;;;OAQG;YACW,oBAAoB;IAuClC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;YACW,iBAAiB;IA8F/B;;;;;;;;OAQG;IACH,OAAO,CAAC,cAAc;IAYtB;;;;;;;;;OASG;YACW,iBAAiB;IAqC/B;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,aAAa;YA+BP,YAAY;CAS3B"}