@senpi/runtime 1.0.95-dev.runtime-phase-2-api.20260507182734 → 1.1.0-dev.main.20260527104621

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

@@ -0,0 +1,65 @@
+export declare const SKILLS_MANAGER_STATE_FILE: string;
+/**
+ * Default skills-directory search path.
+ *
+ * Parses `SENPI_SKILLS_DIR` as a comma-separated list (consistent with
+ * `SENPI_ALLOWED_SKILLS`). A single value is also accepted — it just yields a
+ * one-element array. Empty / unset falls back to the canonical install path.
+ *
+ * Semantics when the array has more than one entry:
+ * - **Writes** (bootstrap, install) always target the **first** entry
+ *   (the *primary*).
+ * - **Reads** (SKILL.md version checks) try each entry in order,
+ *   first-found wins.
+ * - **Discovery** (`skills: []`) merges immediate subdirs across all
+ *   entries, dedup by name with first-found wins.
+ *
+ * For paths containing commas, use the JSON array form in `openclaw.json`
+ * (`"skillsDir": ["/path,with,commas", "/other"]`) — the env-var path is
+ * comma-delimited and offers no escaping.
+ */
+export declare const DEFAULT_SKILLS_DIRS: readonly string[];
+export declare const SKILLS_REPO_URL: string;
+/** Branch to clone and fetch raw files from. Override for dev/testing. */
+export declare const SKILLS_REPO_BRANCH: string;
+/** Raw content host for the skills repo (no trailing slash, no branch segment). */
+export declare const SKILLS_RAW_REPO_URL: string;
+/** Full base URL for fetching raw skill files: <raw-repo-url>/<branch>. */
+export declare const SKILLS_RAW_BASE_URL: string;
+/** Allowlist of skill names that may be installed from the remote skills repo. */
+export declare const ALLOWED_SKILLS: readonly string[];
+/**
+ * Character budget for skills-update notifications before the renderer
+ * starts shedding detail (descriptions first, then capping per-section
+ * lists). See `SkillsUpdateCoordinator.sendUpdateSummary` for the
+ * three-tier sizing logic.
+ *
+ * Default: **4000** — 96 chars under Telegram's hard 4096-char per-message
+ * limit, leaving headroom for the openclaw channel's markdown→HTML wrap
+ * tags so the converted HTML payload stays under the API ceiling.
+ *
+ * Override: `SENPI_TELEGRAM_NOTIFICATION_BUDGET_CHARS` env var. Useful
+ * if your downstream channel has a different limit (e.g. a custom
+ * non-Telegram transport that accepts longer messages, or a stricter
+ * gateway that needs more headroom). Values must be a positive integer;
+ * anything unparseable falls back to the default.
+ */
+export declare const TELEGRAM_NOTIFICATION_BUDGET_CHARS: number;
+/**
+ * Per-section cap (Updated: / Failed to update:) when even the compact
+ * notification render would exceed `TELEGRAM_NOTIFICATION_BUDGET_CHARS`.
+ * The renderer shows the first N skills of each section and appends a
+ * "… and M more <updated|failed> skills not shown" tail line.
+ *
+ * Default: **10** — chosen so a single-section overflow still produces
+ * a useful actionable list rather than collapsing to a one-line summary
+ * (per PR #78 review feedback).
+ *
+ * Override: `SENPI_NOTIFICATION_SKILL_LIST_TOP_N` env var. Set higher
+ * to surface more skills per overflow notification (at the cost of a
+ * lower hit-rate against the budget), or lower to bias toward shorter
+ * messages. Values must be a positive integer; anything unparseable
+ * falls back to the default.
+ */
+export declare const NOTIFICATION_SKILL_LIST_TOP_N: number;
+//# sourceMappingURL=constants.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/skills-manager/constants.ts"],"names":[],"mappings":"AAkBA,eAAO,MAAM,yBAAyB,QAC8B,CAAC;AAErE;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAO7C,CAAC;AAEL,eAAO,MAAM,eAAe,QACqD,CAAC;AAElF,0EAA0E;AAC1E,eAAO,MAAM,kBAAkB,QACY,CAAC;AAE5C,mFAAmF;AACnF,eAAO,MAAM,mBAAmB,QACoE,CAAC;AAErG,2EAA2E;AAC3E,eAAO,MAAM,mBAAmB,QAAiD,CAAC;AAElF,kFAAkF;AAClF,eAAO,MAAM,cAAc,EAAE,SAAS,MAAM,EAIxC,CAAC;AAEL;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,kCAAkC,QAG9C,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,6BAA6B,QAGzC,CAAC"}

package/dist/skills-manager/constants.js

@@ -0,0 +1,91 @@
+// Env-overridable constants for the skills-manager module.
+//
+// All declarations follow the same pattern: read `process.env.<NAME>` at
+// module load time and fall back to a hardcoded default on missing /
+// unparseable input. Numeric constants delegate parsing to
+// `parseEnvPositiveInt` in `./utils.js` so this file stays purely a list
+// of "what env var maps to what default" — no logic, just declarations.
+//
+// On the constants ↔ utils import edge: `utils.ts` imports
+// `DEFAULT_SKILLS_DIRS` from this file for `normalizeSkillsDir`'s
+// fallback, and this file imports `parseEnvPositiveInt` from utils. The
+// resulting ESM cycle is benign because both reads are deferred — `utils.ts`
+// only touches `DEFAULT_SKILLS_DIRS` inside the function body of
+// `normalizeSkillsDir` (called at runtime, after both modules have
+// finished evaluating), and this file only calls `parseEnvPositiveInt`
+// after Node has hoisted utils's function declarations into scope.
+import { parseEnvPositiveInt } from "./utils.js";
+export const SKILLS_MANAGER_STATE_FILE = process.env.SENPI_SKILLS_STATE_FILE ?? "skills-manager-state.json";
+/**
+ * Default skills-directory search path.
+ *
+ * Parses `SENPI_SKILLS_DIR` as a comma-separated list (consistent with
+ * `SENPI_ALLOWED_SKILLS`). A single value is also accepted — it just yields a
+ * one-element array. Empty / unset falls back to the canonical install path.
+ *
+ * Semantics when the array has more than one entry:
+ * - **Writes** (bootstrap, install) always target the **first** entry
+ *   (the *primary*).
+ * - **Reads** (SKILL.md version checks) try each entry in order,
+ *   first-found wins.
+ * - **Discovery** (`skills: []`) merges immediate subdirs across all
+ *   entries, dedup by name with first-found wins.
+ *
+ * For paths containing commas, use the JSON array form in `openclaw.json`
+ * (`"skillsDir": ["/path,with,commas", "/other"]`) — the env-var path is
+ * comma-delimited and offers no escaping.
+ */
+export const DEFAULT_SKILLS_DIRS = (() => {
+    const parsed = process.env.SENPI_SKILLS_DIR
+        ?.split(",")
+        .map((s) => s.trim())
+        .filter(Boolean) ?? [];
+    return parsed.length > 0 ? parsed : ["/data/.openclaw/skills"];
+})();
+export const SKILLS_REPO_URL = process.env.SENPI_SKILLS_REPO_URL ?? "https://github.com/Senpi-ai/senpi-skills";
+/** Branch to clone and fetch raw files from. Override for dev/testing. */
+export const SKILLS_REPO_BRANCH = process.env.SENPI_SKILLS_BRANCH ?? "main";
+/** Raw content host for the skills repo (no trailing slash, no branch segment). */
+export const SKILLS_RAW_REPO_URL = process.env.SENPI_SKILLS_RAW_REPO_URL ?? "https://raw.githubusercontent.com/Senpi-ai/senpi-skills";
+/** Full base URL for fetching raw skill files: <raw-repo-url>/<branch>. */
+export const SKILLS_RAW_BASE_URL = `${SKILLS_RAW_REPO_URL}/${SKILLS_REPO_BRANCH}`;
+/** Allowlist of skill names that may be installed from the remote skills repo. */
+export const ALLOWED_SKILLS = (() => {
+    const parsed = process.env.SENPI_ALLOWED_SKILLS?.split(",").map((s) => s.trim()).filter(Boolean) ?? [];
+    return parsed.length > 0 ? parsed : ["senpi-trading-runtime"];
+})();
+/**
+ * Character budget for skills-update notifications before the renderer
+ * starts shedding detail (descriptions first, then capping per-section
+ * lists). See `SkillsUpdateCoordinator.sendUpdateSummary` for the
+ * three-tier sizing logic.
+ *
+ * Default: **4000** — 96 chars under Telegram's hard 4096-char per-message
+ * limit, leaving headroom for the openclaw channel's markdown→HTML wrap
+ * tags so the converted HTML payload stays under the API ceiling.
+ *
+ * Override: `SENPI_TELEGRAM_NOTIFICATION_BUDGET_CHARS` env var. Useful
+ * if your downstream channel has a different limit (e.g. a custom
+ * non-Telegram transport that accepts longer messages, or a stricter
+ * gateway that needs more headroom). Values must be a positive integer;
+ * anything unparseable falls back to the default.
+ */
+export const TELEGRAM_NOTIFICATION_BUDGET_CHARS = parseEnvPositiveInt(process.env.SENPI_TELEGRAM_NOTIFICATION_BUDGET_CHARS, 4000);
+/**
+ * Per-section cap (Updated: / Failed to update:) when even the compact
+ * notification render would exceed `TELEGRAM_NOTIFICATION_BUDGET_CHARS`.
+ * The renderer shows the first N skills of each section and appends a
+ * "… and M more <updated|failed> skills not shown" tail line.
+ *
+ * Default: **10** — chosen so a single-section overflow still produces
+ * a useful actionable list rather than collapsing to a one-line summary
+ * (per PR #78 review feedback).
+ *
+ * Override: `SENPI_NOTIFICATION_SKILL_LIST_TOP_N` env var. Set higher
+ * to surface more skills per overflow notification (at the cost of a
+ * lower hit-rate against the budget), or lower to bias toward shorter
+ * messages. Values must be a positive integer; anything unparseable
+ * falls back to the default.
+ */
+export const NOTIFICATION_SKILL_LIST_TOP_N = parseEnvPositiveInt(process.env.SENPI_NOTIFICATION_SKILL_LIST_TOP_N, 10);
+//# sourceMappingURL=constants.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/skills-manager/constants.ts"],"names":[],"mappings":"AAAA,2DAA2D;AAC3D,EAAE;AACF,yEAAyE;AACzE,qEAAqE;AACrE,2DAA2D;AAC3D,yEAAyE;AACzE,wEAAwE;AACxE,EAAE;AACF,2DAA2D;AAC3D,kEAAkE;AAClE,wEAAwE;AACxE,6EAA6E;AAC7E,iEAAiE;AACjE,mEAAmE;AACnE,uEAAuE;AACvE,mEAAmE;AACnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEjD,MAAM,CAAC,MAAM,yBAAyB,GACpC,OAAO,CAAC,GAAG,CAAC,uBAAuB,IAAI,2BAA2B,CAAC;AAErE;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAsB,CAAC,GAAG,EAAE;IAC1D,MAAM,MAAM,GACV,OAAO,CAAC,GAAG,CAAC,gBAAgB;QAC1B,EAAE,KAAK,CAAC,GAAG,CAAC;SACX,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;IAC3B,OAAO,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,wBAAwB,CAAC,CAAC;AACjE,CAAC,CAAC,EAAE,CAAC;AAEL,MAAM,CAAC,MAAM,eAAe,GAC1B,OAAO,CAAC,GAAG,CAAC,qBAAqB,IAAI,0CAA0C,CAAC;AAElF,0EAA0E;AAC1E,MAAM,CAAC,MAAM,kBAAkB,GAC7B,OAAO,CAAC,GAAG,CAAC,mBAAmB,IAAI,MAAM,CAAC;AAE5C,mFAAmF;AACnF,MAAM,CAAC,MAAM,mBAAmB,GAC9B,OAAO,CAAC,GAAG,CAAC,yBAAyB,IAAI,yDAAyD,CAAC;AAErG,2EAA2E;AAC3E,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAG,mBAAmB,IAAI,kBAAkB,EAAE,CAAC;AAElF,kFAAkF;AAClF,MAAM,CAAC,MAAM,cAAc,GAAsB,CAAC,GAAG,EAAE;IACrD,MAAM,MAAM,GACV,OAAO,CAAC,GAAG,CAAC,oBAAoB,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;IAC1F,OAAO,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,uBAAuB,CAAC,CAAC;AAChE,CAAC,CAAC,EAAE,CAAC;AAEL;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,kCAAkC,GAAG,mBAAmB,CACnE,OAAO,CAAC,GAAG,CAAC,wCAAwC,EACpD,IAAI,CACL,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,mBAAmB,CAC9D,OAAO,CAAC,GAAG,CAAC,mCAAmC,EAC/C,EAAE,CACH,CAAC"}

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"}