@clawling/clawchat-plugin-openclaw 2026.6.24-1 → 2026.6.30-2

package/src/skill-update.ts

@@ -0,0 +1,752 @@
+import crypto from "node:crypto";
+import { existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Conversational, adapter-driven skill hot-update for the OpenClaw ClawChat
+ * plugin.
+ *
+ * member-backend fires a content-free `notify.signal` with
+ * `payload.type === "clawchat.skill.update.check"` at this agent. On receipt the
+ * adapter (not the LLM) checks the official skill source for a newer version of
+ * each bundled skill; if one exists it asks the owner in their direct chat for
+ * consent, and on an affirmative owner reply it ATOMICALLY writes the new
+ * `SKILL.md` into the OpenClaw-managed skills dir (`<stateDir>/skills/<id>/`).
+ * The host chokidar-watches that dir (`src/skills/runtime/refresh.ts:107`) and
+ * loads managed skills at HIGHER precedence than plugin-bundled ones
+ * (managed=3 > bundled=2, `src/skills/loading/workspace.ts:1220-1239`), so the
+ * write both overrides the bundled copy of the same id AND bumps the skills
+ * snapshot to rebuild the system prompt next turn — no restart, no
+ * `config reload`. See {@link resolveManagedSkillsDir} for why this dir (not
+ * the bundled `./skills`, which lives in node_modules → may be read-only and is
+ * clobbered on `openclaw plugins update`).
+ *
+ * Design notes:
+ * - The version-check helpers (`parseSkillsManifest` / `checkSkillUpdate` /
+ *   `fetchSkillMarkdown`) are a self-contained port of the reference
+ *   implementation in `@clawling/clawchat-plugin-install-cli`
+ *   (`packages/core/src/skills/check-update.ts`). That package is
+ *   workspace-private, so the logic is duplicated here rather than imported.
+ * - Strict semver compare mirrors the reference `parseComparableVersion`
+ *   (`X.Y[.Z[.W]][-buildnum]`).
+ * - All network IO goes through an injected `FetchLike`; tests never touch the
+ *   real network.
+ *
+ * Cross-language contract / spec: see
+ * `ops/agent-plugin/skill-dynamic-update-plan.md` (§2, §3 phase 4,
+ * §4 #5, §6.4, §6.7, §7.2).
+ */
+
+// ---------------------------------------------------------------------------
+// Constants — fixed contract (must match the install-cli `config.ts`).
+// ---------------------------------------------------------------------------
+
+/**
+ * Canonical, official source for ClawChat agent skill markdown. Hard-coded on
+ * purpose: a skill-update trigger signal NEVER carries a URL or ref, only a
+ * version that maps to a git ref. `clawling` is a public org so raw fetches are
+ * unauthenticated.
+ */
+export const OFFICIAL_SKILLS_BASE =
+  "https://raw.githubusercontent.com/clawling/clawchat-plugin-install-cli";
+
+/**
+ * Default git ref for the skills tree. Production callers SHOULD pin an
+ * immutable `skills-vX.Y.Z` tag instead of tracking the moving `main`.
+ */
+export const DEFAULT_SKILLS_REF = "main";
+
+/** Refuse to treat an absurdly large response as a skill file (defence in depth). */
+export const MAX_SKILL_BYTES = 256 * 1024;
+
+/** This adapter's host target inside `skills/manifest.json`. */
+export const SKILL_TARGET = "openclaw";
+
+/** Skill ids this OpenClaw plugin bundles and can hot-update. */
+export const OPENCLAW_SKILL_IDS = ["clawchat", "liveware-app"] as const;
+export type OpenclawSkillId = (typeof OPENCLAW_SKILL_IDS)[number];
+
+// ---------------------------------------------------------------------------
+// Minimal fetch abstraction (compatible with the global `fetch`).
+// ---------------------------------------------------------------------------
+
+export interface FetchResponseLike {
+  ok: boolean;
+  status: number;
+  text(): Promise<string>;
+}
+export type FetchLike = (
+  url: string,
+  init?: { method?: string },
+) => Promise<FetchResponseLike>;
+
+// ---------------------------------------------------------------------------
+// Strict semver compare (ported from install-cli `metadata.ts`).
+// ---------------------------------------------------------------------------
+
+function parseComparableVersion(version: string): { parts: number[]; build: number } {
+  const match = version.match(/^(\d+(?:\.\d+){1,3})(?:-(\d+))?$/);
+  if (!match) {
+    throw new Error(`unsupported version: ${version}`);
+  }
+  return {
+    parts: (match[1] ?? "").split(".").map(Number),
+    build: match[2] ? Number(match[2]) : 0,
+  };
+}
+
+function compareVersions(a: string, b: string): number {
+  const left = parseComparableVersion(a);
+  const right = parseComparableVersion(b);
+  const width = Math.max(left.parts.length, right.parts.length);
+  for (let i = 0; i < width; i += 1) {
+    const diff = (left.parts[i] ?? 0) - (right.parts[i] ?? 0);
+    if (diff !== 0) {
+      return diff > 0 ? 1 : -1;
+    }
+  }
+  const buildDiff = left.build - right.build;
+  if (buildDiff !== 0) {
+    return buildDiff > 0 ? 1 : -1;
+  }
+  return 0;
+}
+
+/** True when `candidate` is strictly newer than `current`. */
+export function isVersionOlder(current: string, candidate: string): boolean {
+  return compareVersions(current, candidate) < 0;
+}
+
+// ---------------------------------------------------------------------------
+// Manifest parsing + validation (ported from install-cli `check-update.ts`).
+// ---------------------------------------------------------------------------
+
+export interface SkillManifestEntry {
+  /** Skill version (matches the SKILL.md frontmatter `version`). */
+  version: string;
+  /** Repo-relative path under `skills/`, e.g. `openclaw/clawchat/SKILL.md`. */
+  path: string;
+  /** Lowercase hex sha256 of the raw `SKILL.md` bytes. */
+  sha256: string;
+  /** Byte length of the raw `SKILL.md`. */
+  bytes: number;
+}
+
+export interface SkillsManifest {
+  schema: number;
+  skills: Record<string, Record<string, SkillManifestEntry>>;
+}
+
+export interface SkillUpdate {
+  skillId: string;
+  /** Locally installed version, or `null` when the skill is not installed. */
+  current: string | null;
+  /** Version offered by the official source. */
+  latest: string;
+  hasUpdate: boolean;
+  path: string;
+  sha256: string;
+  bytes: number;
+}
+
+export interface CheckSkillUpdateOutcome {
+  ref: string;
+  results: SkillUpdate[];
+  hasUpdate: boolean;
+}
+
+function skillsBase(base: string | undefined, ref: string): string {
+  return `${(base ?? OFFICIAL_SKILLS_BASE).replace(/\/+$/, "")}/${ref}/skills`;
+}
+
+export function manifestUrl(ref: string = DEFAULT_SKILLS_REF, base?: string): string {
+  return `${skillsBase(base, ref)}/manifest.json`;
+}
+
+export function skillContentUrl(
+  entryPath: string,
+  ref: string = DEFAULT_SKILLS_REF,
+  base?: string,
+): string {
+  return `${skillsBase(base, ref)}/${entryPath.replace(/^\/+/, "")}`;
+}
+
+function asEntry(value: unknown, where: string): SkillManifestEntry {
+  if (!value || typeof value !== "object") {
+    throw new Error(`skills manifest entry ${where} is not an object`);
+  }
+  const v = value as Record<string, unknown>;
+  const version = typeof v.version === "string" ? v.version.trim() : "";
+  const entryPath = typeof v.path === "string" ? v.path.trim() : "";
+  const sha256 = typeof v.sha256 === "string" ? v.sha256.trim().toLowerCase() : "";
+  const bytes = typeof v.bytes === "number" ? v.bytes : NaN;
+  if (!version) throw new Error(`skills manifest entry ${where} missing version`);
+  if (!entryPath) throw new Error(`skills manifest entry ${where} missing path`);
+  if (!/^[0-9a-f]{64}$/.test(sha256)) {
+    throw new Error(`skills manifest entry ${where} has invalid sha256`);
+  }
+  if (!Number.isInteger(bytes) || bytes < 0) {
+    throw new Error(`skills manifest entry ${where} has invalid bytes`);
+  }
+  return { version, path: entryPath, sha256, bytes };
+}
+
+/** Parse and validate raw manifest text. */
+export function parseSkillsManifest(text: string): SkillsManifest {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (err) {
+    throw new Error(`failed to parse skills manifest: ${(err as Error).message}`);
+  }
+  if (!parsed || typeof parsed !== "object") {
+    throw new Error("skills manifest must be a JSON object");
+  }
+  const data = parsed as Record<string, unknown>;
+  if (data.schema !== 1) {
+    throw new Error(`unsupported skills manifest schema: ${JSON.stringify(data.schema)}`);
+  }
+  if (!data.skills || typeof data.skills !== "object") {
+    throw new Error("skills manifest missing `skills`");
+  }
+  const skills: SkillsManifest["skills"] = {};
+  for (const [target, entries] of Object.entries(data.skills as Record<string, unknown>)) {
+    if (!entries || typeof entries !== "object") {
+      throw new Error(`skills manifest target ${target} is not an object`);
+    }
+    skills[target] = {};
+    for (const [skillId, entry] of Object.entries(entries as Record<string, unknown>)) {
+      skills[target][skillId] = asEntry(entry, `${target}.${skillId}`);
+    }
+  }
+  return { schema: 1, skills };
+}
+
+async function fetchText(url: string, fetchFn: FetchLike): Promise<string> {
+  let response: FetchResponseLike;
+  try {
+    response = await fetchFn(url, { method: "GET" });
+  } catch (err) {
+    throw new Error(`fetch ${url} failed: ${(err as Error).message}`);
+  }
+  if (!response.ok) {
+    throw new Error(`fetch ${url} returned status ${response.status}`);
+  }
+  return response.text();
+}
+
+export interface CheckSkillUpdateOptions {
+  /** Locally installed versions: `{ "<skillId>": "<version>" }`. */
+  current: Record<string, string>;
+  ref?: string;
+  base?: string;
+  fetchFn: FetchLike;
+}
+
+/**
+ * Read the official manifest for the `openclaw` target and compare each skill's
+ * offered version against the locally installed `current` map. A skill missing
+ * from `current` is reported as `hasUpdate: true`.
+ */
+export async function checkSkillUpdate(
+  options: CheckSkillUpdateOptions,
+): Promise<CheckSkillUpdateOutcome> {
+  const ref = options.ref ?? DEFAULT_SKILLS_REF;
+  const text = await fetchText(manifestUrl(ref, options.base), options.fetchFn);
+  const manifest = parseSkillsManifest(text);
+  const targetSkills = manifest.skills[SKILL_TARGET];
+  if (!targetSkills) {
+    throw new Error(`skills manifest has no entry for target ${SKILL_TARGET}`);
+  }
+
+  const results: SkillUpdate[] = [];
+  for (const [skillId, entry] of Object.entries(targetSkills)) {
+    const current = options.current[skillId] ?? null;
+    const hasUpdate = current === null ? true : isVersionOlder(current, entry.version);
+    results.push({
+      skillId,
+      current,
+      latest: entry.version,
+      hasUpdate,
+      path: entry.path,
+      sha256: entry.sha256,
+      bytes: entry.bytes,
+    });
+  }
+  return { ref, results, hasUpdate: results.some((r) => r.hasUpdate) };
+}
+
+/**
+ * Download one skill markdown file and integrity-check it against the manifest
+ * entry (size cap + exact sha256). Returns the raw markdown text on success.
+ */
+export async function fetchSkillMarkdown(
+  entry: Pick<SkillManifestEntry, "path" | "sha256" | "bytes">,
+  options: { ref?: string; base?: string; fetchFn: FetchLike },
+): Promise<string> {
+  const ref = options.ref ?? DEFAULT_SKILLS_REF;
+  const text = await fetchText(skillContentUrl(entry.path, ref, options.base), options.fetchFn);
+  const buf = Buffer.from(text, "utf8");
+  if (buf.length > MAX_SKILL_BYTES) {
+    throw new Error(`skill ${entry.path} is ${buf.length} bytes, over the ${MAX_SKILL_BYTES} cap`);
+  }
+  const sha256 = crypto.createHash("sha256").update(buf).digest("hex");
+  if (sha256 !== entry.sha256.toLowerCase()) {
+    throw new Error(`skill ${entry.path} sha256 mismatch: got ${sha256}, expected ${entry.sha256}`);
+  }
+  return text;
+}
+
+// ---------------------------------------------------------------------------
+// Local skill version resolution (frontmatter `version:`).
+// ---------------------------------------------------------------------------
+
+/** Extract the `version` field from a SKILL.md YAML frontmatter block. */
+export function parseSkillFrontmatterVersion(markdown: string): string | null {
+  const match = markdown.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return null;
+  const frontmatter = match[1] ?? "";
+  const versionLine = frontmatter
+    .split(/\r?\n/)
+    .map((line) => line.match(/^version:\s*(.+?)\s*$/))
+    .find((m): m is RegExpMatchArray => m !== null);
+  if (!versionLine) return null;
+  const raw = (versionLine[1] ?? "").trim().replace(/^["']|["']$/g, "");
+  return raw || null;
+}
+
+/** Read one skill's frontmatter `version` from `<dir>/<skillId>/SKILL.md`. */
+async function readSingleSkillVersion(dir: string, skillId: string): Promise<string | null> {
+  try {
+    const md = await fs.readFile(path.join(dir, skillId, "SKILL.md"), "utf8");
+    return parseSkillFrontmatterVersion(md);
+  } catch {
+    return null; // missing / unreadable
+  }
+}
+
+/**
+ * Read the installed version of each requested skill from a SINGLE directory
+ * (`<skillsDir>/<skillId>/SKILL.md`). Missing files / missing frontmatter
+ * version are simply omitted (treated as "not installed" → update available).
+ */
+export async function readLocalSkillVersions(
+  skillsDir: string,
+  skillIds: readonly string[] = OPENCLAW_SKILL_IDS,
+): Promise<Record<string, string>> {
+  const versions: Record<string, string> = {};
+  for (const skillId of skillIds) {
+    const version = await readSingleSkillVersion(skillsDir, skillId);
+    if (version) versions[skillId] = version;
+  }
+  return versions;
+}
+
+/**
+ * Read the EFFECTIVE installed version of each skill, mirroring the host's
+ * managed-over-bundled precedence (`src/skills/loading/workspace.ts:1220-1239`,
+ * managed=3 > bundled=2): use the managed copy's frontmatter `version` when
+ * `<managedDir>/<id>/SKILL.md` exists, otherwise fall back to the bundled
+ * copy's. A skill present in neither is omitted (→ update available).
+ */
+export async function readEffectiveSkillVersions(
+  managedDir: string,
+  bundledDir: string | null,
+  skillIds: readonly string[] = OPENCLAW_SKILL_IDS,
+): Promise<Record<string, string>> {
+  const versions: Record<string, string> = {};
+  for (const skillId of skillIds) {
+    const managed = await readSingleSkillVersion(managedDir, skillId);
+    if (managed) {
+      versions[skillId] = managed;
+      continue;
+    }
+    if (bundledDir) {
+      const bundled = await readSingleSkillVersion(bundledDir, skillId);
+      if (bundled) versions[skillId] = bundled;
+    }
+  }
+  return versions;
+}
+
+/**
+ * Resolve OpenClaw's state directory, mirroring the host `src/utils.ts:132-154`:
+ * `OPENCLAW_STATE_DIR` if set; else the dirname of `OPENCLAW_CONFIG_PATH` if
+ * set; else `~/.openclaw`.
+ */
+export function resolveStateDir(env: NodeJS.ProcessEnv = process.env): string {
+  const stateDir = env.OPENCLAW_STATE_DIR?.trim();
+  if (stateDir) return stateDir;
+  const configPath = env.OPENCLAW_CONFIG_PATH?.trim();
+  if (configPath) return path.dirname(configPath);
+  return path.join(os.homedir(), ".openclaw");
+}
+
+/**
+ * Resolve the OpenClaw-managed skills directory — THE write target for an
+ * applied skill update: `<stateDir>/skills`.
+ *
+ * WHY THIS DIR (and NOT the plugin's bundled `./skills`):
+ * - It is chokidar-watched by the host (`src/skills/runtime/refresh.ts:107`),
+ *   so an atomic write triggers the snapshot rebuild on the next turn — the
+ *   same activation proven in plan §7.2, without a restart or `config reload`.
+ * - Managed skills load at HIGHER precedence than plugin-bundled ones
+ *   (managed=3 > bundled=2, `src/skills/loading/workspace.ts:1220-1239`), so a
+ *   managed `SKILL.md` OVERRIDES the bundled copy of the same skill id.
+ * - It is writable and persistent across npm installs, whereas the bundled
+ *   `./skills` lives under `node_modules` → can be read-only and is clobbered
+ *   on `openclaw plugins update`. This mirrors the Hermes adapter's
+ *   `$HERMES_HOME/clawchat-skills` design.
+ */
+export function resolveManagedSkillsDir(env: NodeJS.ProcessEnv = process.env): string {
+  return path.join(resolveStateDir(env), "skills");
+}
+
+/**
+ * Resolve the plugin's bundled skills directory.
+ *
+ * READ-SOURCE ONLY: this dir (the plugin's own `./skills`, declared
+ * `"skills": ["./skills"]` in `openclaw.plugin.json`) is used solely to read
+ * the first-boot / fallback "current installed version" when no managed copy
+ * exists yet. It is NEVER a write target — applied updates go to the
+ * OpenClaw-managed dir ({@link resolveManagedSkillsDir}).
+ *
+ * Resolution walks up from this module's location looking for a directory that
+ * contains both `openclaw.plugin.json` and a `skills/` subdir — this works for
+ * both the built layout (`dist/src/skill-update.js`) and the source layout
+ * (`src/skill-update.ts`).
+ */
+export function resolveBundledSkillsDir(fromUrl: string = import.meta.url): string {
+  let dir = path.dirname(fileURLToPath(fromUrl));
+  for (let i = 0; i < 8; i += 1) {
+    if (existsSync(path.join(dir, "openclaw.plugin.json")) && existsSync(path.join(dir, "skills"))) {
+      return path.join(dir, "skills");
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  throw new Error("could not resolve bundled skills dir (no openclaw.plugin.json + skills/ ancestor)");
+}
+
+/**
+ * Atomically write `<skillsDir>/<skillId>/SKILL.md` with `content`. `mkdir -p`
+ * the `<skillsDir>/<skillId>/` dir first (the managed dir may not exist yet).
+ *
+ * HARD INVARIANT (plan §4 #5): write to a temp file in the SAME directory then
+ * `rename` into place. NEVER delete-then-write — a transient "file missing"
+ * window would make OpenClaw drop the skill registration and demand a reload.
+ */
+export async function atomicWriteSkill(
+  skillsDir: string,
+  skillId: string,
+  content: string,
+): Promise<void> {
+  const dir = path.join(skillsDir, skillId);
+  await fs.mkdir(dir, { recursive: true });
+  const target = path.join(dir, "SKILL.md");
+  const tmp = path.join(dir, `.SKILL.md.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`);
+  await fs.writeFile(tmp, content, "utf8");
+  try {
+    await fs.rename(tmp, target);
+  } catch (err) {
+    await fs.rm(tmp, { force: true }).catch(() => {});
+    throw err;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Conservative consent parsing.
+// ---------------------------------------------------------------------------
+
+export type ConsentVerdict = "affirm" | "deny" | "ambiguous";
+
+const AFFIRM_TOKENS = new Set([
+  "更新",
+  "更新吧",
+  "确认",
+  "确认更新",
+  "同意",
+  "同意更新",
+  "好",
+  "好的",
+  "好啊",
+  "可以",
+  "行",
+  "yes",
+  "y",
+  "ok",
+  "okay",
+  "update",
+]);
+
+const DENY_TOKENS = new Set([
+  "取消",
+  "取消更新",
+  "不更新",
+  "不",
+  "不要",
+  "不用",
+  "否",
+  "拒绝",
+  "算了",
+  "no",
+  "n",
+  "cancel",
+]);
+
+/**
+ * CONSERVATIVE consent parse: only a message that, once stripped of whitespace
+ * and common punctuation, equals a single standalone consent token counts as
+ * affirm/deny. Anything else (a sentence that merely contains "更新", an
+ * unrelated reply, an empty string) is `ambiguous` and must NOT be consumed —
+ * it flows on to the normal LLM pipeline while the pending record survives
+ * until its timeout. This keeps "soft consent" from misfiring on ordinary chat.
+ */
+export function parseConsent(text: string): ConsentVerdict {
+  const norm = (text ?? "")
+    .trim()
+    .replace(/[\s。.!?！？,，、…~～·"'「」『』（）()【】\[\]]/g, "")
+    .toLowerCase();
+  if (!norm) return "ambiguous";
+  if (AFFIRM_TOKENS.has(norm)) return "affirm";
+  if (DENY_TOKENS.has(norm)) return "deny";
+  return "ambiguous";
+}
+
+// ---------------------------------------------------------------------------
+// Pending-consent store (in-memory, single pending record per runtime).
+// ---------------------------------------------------------------------------
+
+export interface PendingSkillTarget {
+  skillId: string;
+  current: string | null;
+  target: string;
+  path: string;
+  sha256: string;
+  bytes: number;
+}
+
+export interface PendingSkillUpdate {
+  ownerUserId: string;
+  ref: string;
+  base?: string;
+  updates: PendingSkillTarget[];
+  createdAt: number;
+  expiresAt: number;
+}
+
+/** Default consent window: a pending ask expires after 30 minutes. */
+export const DEFAULT_CONSENT_TIMEOUT_MS = 30 * 60 * 1000;
+
+export class PendingConsentStore {
+  private pending: PendingSkillUpdate | null = null;
+  constructor(private readonly now: () => number = Date.now) {}
+
+  set(record: PendingSkillUpdate): void {
+    this.pending = record;
+  }
+
+  /** Returns the live pending record, clearing + returning null if expired. */
+  get(): PendingSkillUpdate | null {
+    if (!this.pending) return null;
+    if (this.now() >= this.pending.expiresAt) {
+      this.pending = null;
+      return null;
+    }
+    return this.pending;
+  }
+
+  clear(): void {
+    this.pending = null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Orchestration: notify.signal check → ask owner; owner reply → apply.
+// ---------------------------------------------------------------------------
+
+export interface SkillUpdateLog {
+  info?: (m: string) => void;
+  error?: (m: string) => void;
+}
+
+export interface RunSkillUpdateCheckOptions {
+  ownerUserId: string;
+  /** Locally installed versions, `{ "<skillId>": "<version>" }`. */
+  localVersions: Record<string, string>;
+  fetchFn: FetchLike;
+  ref?: string;
+  base?: string;
+  store: PendingConsentStore;
+  sendOwnerMessage: (text: string) => Promise<void>;
+  now?: () => number;
+  timeoutMs?: number;
+  log?: SkillUpdateLog;
+}
+
+function describeUpdate(u: PendingSkillTarget): string {
+  return `「${u.skillId}」v${u.current ?? "无"} → v${u.target}`;
+}
+
+/**
+ * Step ③–⑤ (plan §2): on `clawchat.skill.update.check`, check the official
+ * source; if any skill has a newer version, message the owner asking for
+ * consent and record a pending consent entry. No-update → silent. Returns the
+ * recorded pending entry, or `null` when there was nothing to ask.
+ */
+export async function runSkillUpdateCheck(
+  options: RunSkillUpdateCheckOptions,
+): Promise<PendingSkillUpdate | null> {
+  const ownerUserId = options.ownerUserId.trim();
+  if (!ownerUserId) {
+    options.log?.error?.("clawchat skill-update check: no owner user id; cannot ask for consent");
+    return null;
+  }
+
+  const outcome = await checkSkillUpdate({
+    current: options.localVersions,
+    ...(options.ref ? { ref: options.ref } : {}),
+    ...(options.base ? { base: options.base } : {}),
+    fetchFn: options.fetchFn,
+  });
+
+  const updates: PendingSkillTarget[] = outcome.results
+    .filter((r) => r.hasUpdate)
+    .map((r) => ({
+      skillId: r.skillId,
+      current: r.current,
+      target: r.latest,
+      path: r.path,
+      sha256: r.sha256,
+      bytes: r.bytes,
+    }));
+
+  if (updates.length === 0) {
+    options.log?.info?.("clawchat skill-update check: no updates available");
+    return null;
+  }
+
+  const now = (options.now ?? Date.now)();
+  const record: PendingSkillUpdate = {
+    ownerUserId,
+    ref: outcome.ref,
+    ...(options.base ? { base: options.base } : {}),
+    updates,
+    createdAt: now,
+    expiresAt: now + (options.timeoutMs ?? DEFAULT_CONSENT_TIMEOUT_MS),
+  };
+  options.store.set(record);
+
+  const text = `我的技能有更新:${updates.map(describeUpdate).join(";")}。回复「更新」确认,「取消」忽略。`;
+  await options.sendOwnerMessage(text);
+  options.log?.info?.(
+    `clawchat skill-update check: asked owner for consent on ${updates.map((u) => u.skillId).join(",")}`,
+  );
+  return record;
+}
+
+export interface HandleOwnerConsentReplyOptions {
+  ownerUserId: string;
+  senderId: string;
+  text: string;
+  store: PendingConsentStore;
+  fetchFn: FetchLike;
+  ref?: string;
+  base?: string;
+  /**
+   * The OpenClaw-managed skills dir to write into — the chokidar-watched,
+   * higher-precedence target (see {@link resolveManagedSkillsDir}). NOT the
+   * bundled `./skills` dir.
+   */
+  skillsDir: string;
+  sendOwnerMessage: (text: string) => Promise<void>;
+  /** Re-read the on-disk version of a skill for idempotency checks. */
+  readLocalVersion?: (skillId: string) => Promise<string | null>;
+  log?: SkillUpdateLog;
+}
+
+/**
+ * Step ⑦–⑨ (plan §2): the owner-reply pending-consent gate.
+ *
+ * Returns `true` when the reply was CONSUMED (affirm → applied + acked, or
+ * deny → cleared + acked) and must NOT be forwarded to the LLM. Returns `false`
+ * when the reply must flow on to normal handling: no pending record, not from
+ * the owner, or an ambiguous reply (pending is kept until timeout).
+ */
+export async function handleOwnerConsentReply(
+  options: HandleOwnerConsentReplyOptions,
+): Promise<boolean> {
+  const pending = options.store.get();
+  if (!pending) return false;
+
+  const ownerUserId = options.ownerUserId.trim();
+  // Only the owner can consent, and only to their own pending ask.
+  if (!ownerUserId || options.senderId !== ownerUserId || pending.ownerUserId !== ownerUserId) {
+    return false;
+  }
+
+  const verdict = parseConsent(options.text);
+  if (verdict === "ambiguous") {
+    // Do NOT consume — let the message reach the LLM, keep pending until timeout.
+    return false;
+  }
+
+  if (verdict === "deny") {
+    options.store.clear();
+    await options.sendOwnerMessage("已取消");
+    options.log?.info?.("clawchat skill-update: owner declined; pending cleared");
+    return true;
+  }
+
+  // verdict === "affirm"
+  const readLocalVersion =
+    options.readLocalVersion ??
+    (async (skillId: string) => {
+      try {
+        const md = await fs.readFile(path.join(options.skillsDir, skillId, "SKILL.md"), "utf8");
+        return parseSkillFrontmatterVersion(md);
+      } catch {
+        return null;
+      }
+    });
+
+  const applied: PendingSkillTarget[] = [];
+  try {
+    for (const update of pending.updates) {
+      // Idempotency: skip a skill already at the target version on disk.
+      const onDisk = await readLocalVersion(update.skillId);
+      if (onDisk === update.target) {
+        applied.push(update);
+        continue;
+      }
+      const content = await fetchSkillMarkdown(
+        { path: update.path, sha256: update.sha256, bytes: update.bytes },
+        {
+          ref: pending.ref,
+          ...(pending.base ? { base: pending.base } : options.base ? { base: options.base } : {}),
+          fetchFn: options.fetchFn,
+        },
+      );
+      await atomicWriteSkill(options.skillsDir, update.skillId, content);
+      applied.push(update);
+      options.log?.info?.(
+        `clawchat skill-update: applied ${update.skillId} -> v${update.target} (atomic overwrite)`,
+      );
+    }
+  } catch (err) {
+    // Keep the pending record so the owner can retry with another "更新"; report
+    // the failure rather than silently dropping it.
+    options.log?.error?.(`clawchat skill-update: apply failed: ${(err as Error).message}`);
+    await options.sendOwnerMessage("技能更新失败,请稍后再回复「更新」重试。");
+    return true;
+  }
+
+  options.store.clear();
+  const summary = applied.map((u) => `「${u.skillId}」v${u.target}`).join("、");
+  await options.sendOwnerMessage(`✅ 已更新到 ${summary}`);
+  return true;
+}