@syengup/friday-channel-next 0.1.26 → 0.1.28

package/dist/src/link-preview/preview-service.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Link-preview orchestration: fetch page → parse Open Graph → re-host the cover image through
+ * the gateway's stored files → cache.
+ *
+ * The cover image is downloaded server-side and served from /friday-next/files/ so the app only
+ * ever talks to the trusted gateway host (same rationale as `downloadRemoteMedia` for outbound
+ * media). Failures degrade to "no card" on the app side, so every error path returns a typed
+ * error instead of throwing.
+ */
+export interface LinkPreviewPayload {
+    url: string;
+    finalUrl: string;
+    siteName: string | null;
+    title: string;
+    description: string | null;
+    /** Gateway-relative cover URL ("/friday-next/files/{token}") or null. */
+    imageUrl: string | null;
+    /** Gateway-relative favicon URL ("/friday-next/files/{token}") or null. */
+    iconUrl: string | null;
+    fetchedAt: number;
+}
+export type LinkPreviewError = "invalid_url" | "blocked_url" | "fetch_failed" | "no_metadata";
+export type LinkPreviewResult = {
+    ok: true;
+    preview: LinkPreviewPayload;
+} | {
+    ok: false;
+    error: LinkPreviewError;
+};
+export declare function resetLinkPreviewCacheForTest(): void;
+export declare function getLinkPreview(rawUrl: string): Promise<LinkPreviewResult>;

package/dist/src/link-preview/preview-service.js

@@ -0,0 +1,216 @@
+/**
+ * Link-preview orchestration: fetch page → parse Open Graph → re-host the cover image through
+ * the gateway's stored files → cache.
+ *
+ * The cover image is downloaded server-side and served from /friday-next/files/ so the app only
+ * ever talks to the trusted gateway host (same rationale as `downloadRemoteMedia` for outbound
+ * media). Failures degrade to "no card" on the app side, so every error path returns a typed
+ * error instead of throwing.
+ */
+import { createFridayNextLogger } from "../logging.js";
+import { storeFile } from "../http/handlers/files.js";
+import { parseOpenGraph } from "./og-parse.js";
+import { BlockedUrlError, fetchPublicUrl, parseHttpUrl } from "./ssrf-guard.js";
+const HTML_MAX_BYTES = 2 * 1024 * 1024;
+const HTML_TIMEOUT_MS = 10_000;
+const IMAGE_MAX_BYTES = 8 * 1024 * 1024;
+const IMAGE_TIMEOUT_MS = 10_000;
+const SUCCESS_TTL_MS = 24 * 60 * 60 * 1000;
+const FAILURE_TTL_MS = 10 * 60 * 1000;
+const MAX_CACHE_ENTRIES = 1000;
+const logger = createFridayNextLogger("link-preview");
+const cache = new Map();
+const inFlight = new Map();
+export function resetLinkPreviewCacheForTest() {
+    cache.clear();
+    inFlight.clear();
+}
+export async function getLinkPreview(rawUrl) {
+    const parsed = parseHttpUrl(rawUrl);
+    if (!parsed)
+        return { ok: false, error: "invalid_url" };
+    const key = parsed.toString();
+    const cached = cache.get(key);
+    if (cached) {
+        const ttl = cached.result.ok ? SUCCESS_TTL_MS : FAILURE_TTL_MS;
+        if (Date.now() - cached.cachedAt < ttl)
+            return cached.result;
+        cache.delete(key);
+    }
+    const pending = inFlight.get(key);
+    if (pending)
+        return pending;
+    const task = buildPreview(key)
+        .then((result) => {
+        writeCache(key, result);
+        return result;
+    })
+        .finally(() => {
+        inFlight.delete(key);
+    });
+    inFlight.set(key, task);
+    return task;
+}
+function writeCache(key, result) {
+    if (cache.size >= MAX_CACHE_ENTRIES) {
+        let oldestKey = null;
+        let oldestAt = Infinity;
+        for (const [k, entry] of cache) {
+            if (entry.cachedAt < oldestAt) {
+                oldestAt = entry.cachedAt;
+                oldestKey = k;
+            }
+        }
+        if (oldestKey)
+            cache.delete(oldestKey);
+    }
+    cache.set(key, { result, cachedAt: Date.now() });
+}
+async function buildPreview(pageUrl) {
+    let page;
+    try {
+        page = await fetchPublicUrl(pageUrl, {
+            maxBytes: HTML_MAX_BYTES,
+            timeoutMs: HTML_TIMEOUT_MS,
+            accept: "text/html,application/xhtml+xml",
+            requireContentTypePrefixes: ["text/html", "application/xhtml+xml"],
+        });
+    }
+    catch (err) {
+        if (err instanceof BlockedUrlError) {
+            logger.warn(`link-preview blocked: ${pageUrl} (${err.reason})`);
+            return { ok: false, error: "blocked_url" };
+        }
+        page = null; // network/timeout — fall through to a favicon-only minimal card
+    }
+    const finalUrl = page?.finalUrl ?? pageUrl;
+    const og = page ? parseOpenGraph(page.body.toString("utf8"), finalUrl) : null;
+    const hostname = (() => {
+        try {
+            return new URL(finalUrl).hostname;
+        }
+        catch {
+            return null;
+        }
+    })();
+    // Favicon: parsed <link rel icon> first, then the conventional /favicon.ico (which is reachable
+    // even for pages that block bots, e.g. zhihu → redirects to its CDN icon).
+    const iconUrl = await resolveFavicon(og?.iconUrl ?? null, finalUrl);
+    // A failed page fetch only yields a (minimal) card when the favicon resolved — that proves the
+    // domain is real/reachable (e.g. bot-blocked zhihu). A dead domain (favicon also fails) collapses.
+    const reachable = page !== null || iconUrl !== null;
+    const title = og?.title ?? hostname;
+    if (!reachable || !title) {
+        return { ok: false, error: page ? "no_metadata" : "fetch_failed" };
+    }
+    const imageUrl = og?.imageUrl ? await rehostCoverImage(og.imageUrl) : null;
+    return {
+        ok: true,
+        preview: {
+            url: pageUrl,
+            finalUrl,
+            siteName: og?.siteName ?? hostname,
+            title: title ?? hostname ?? pageUrl,
+            description: og?.description ?? null,
+            imageUrl,
+            iconUrl,
+            fetchedAt: Date.now(),
+        },
+    };
+}
+/** Re-host a favicon: try the parsed `<link rel icon>`, then `<origin>/favicon.ico`. */
+async function resolveFavicon(parsedIconUrl, finalUrl) {
+    const candidates = [];
+    if (parsedIconUrl)
+        candidates.push(parsedIconUrl);
+    try {
+        candidates.push(new URL("/favicon.ico", finalUrl).toString());
+    }
+    catch {
+        // finalUrl unparseable — skip the conventional fallback
+    }
+    for (const candidate of candidates) {
+        const rehosted = await rehostIconImage(candidate);
+        if (rehosted)
+            return rehosted;
+    }
+    return null;
+}
+/** Download a favicon (full SSRF checks) and re-publish via stored files. Null on any failure. */
+async function rehostIconImage(iconUrl) {
+    let image;
+    try {
+        image = await fetchPublicUrl(iconUrl, {
+            maxBytes: 1024 * 1024,
+            timeoutMs: IMAGE_TIMEOUT_MS,
+            accept: "image/*",
+            requireContentTypePrefixes: ["image/"],
+        });
+    }
+    catch {
+        return null;
+    }
+    if (!image)
+        return null;
+    const sniffed = sniffImageType(image.body);
+    if (!sniffed)
+        return null;
+    try {
+        const stored = storeFile(image.body, `link-preview-icon.${sniffed.ext}`, sniffed.mime);
+        return `/friday-next/files/${encodeURIComponent(stored.urlToken)}`;
+    }
+    catch {
+        return null;
+    }
+}
+/** Download og:image (full SSRF checks) and re-publish via stored files. Null on any failure. */
+async function rehostCoverImage(imageUrl) {
+    let image;
+    try {
+        image = await fetchPublicUrl(imageUrl, {
+            maxBytes: IMAGE_MAX_BYTES,
+            timeoutMs: IMAGE_TIMEOUT_MS,
+            accept: "image/*",
+            requireContentTypePrefixes: ["image/"],
+        });
+    }
+    catch {
+        return null; // blocked og:image just means no cover
+    }
+    if (!image)
+        return null;
+    const sniffed = sniffImageType(image.body);
+    if (!sniffed)
+        return null;
+    try {
+        const stored = storeFile(image.body, `link-preview-cover.${sniffed.ext}`, sniffed.mime);
+        return `/friday-next/files/${encodeURIComponent(stored.urlToken)}`;
+    }
+    catch (err) {
+        logger.warn(`link-preview cover store failed for ${imageUrl}: ${String(err)}`);
+        return null;
+    }
+}
+/** Magic-byte sniff — second line of defense after the Content-Type check. */
+function sniffImageType(buffer) {
+    if (buffer.length < 12)
+        return null;
+    // ICO: 00 00 01 00 (favicons are commonly .ico; iOS ImageIO decodes them).
+    if (buffer[0] === 0x00 && buffer[1] === 0x00 && buffer[2] === 0x01 && buffer[3] === 0x00) {
+        return { ext: "ico", mime: "image/x-icon" };
+    }
+    if (buffer[0] === 0x89 && buffer[1] === 0x50 && buffer[2] === 0x4e && buffer[3] === 0x47) {
+        return { ext: "png", mime: "image/png" };
+    }
+    if (buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff) {
+        return { ext: "jpg", mime: "image/jpeg" };
+    }
+    if (buffer.subarray(0, 4).toString("latin1") === "GIF8") {
+        return { ext: "gif", mime: "image/gif" };
+    }
+    if (buffer.subarray(0, 4).toString("latin1") === "RIFF" &&
+        buffer.subarray(8, 12).toString("latin1") === "WEBP") {
+        return { ext: "webp", mime: "image/webp" };
+    }
+    return null;
+}

package/dist/src/link-preview/ssrf-guard.d.ts

@@ -0,0 +1,43 @@
+/**
+ * SSRF guard + restricted fetch for the link-preview endpoint.
+ *
+ * Unlike `downloadRemoteMedia` (agent-supplied URLs for outbound media), link-preview fetches
+ * URLs that originate from arbitrary message text, so every hop must be validated: protocol,
+ * port, hostname literals, and the full set of DNS-resolved addresses. Redirects are followed
+ * manually so each target is re-checked before the next request.
+ *
+ * Known residual risk: DNS rebinding TOCTOU — we validate resolved addresses, then `fetch`
+ * resolves again. Closing that gap requires dialing by IP with SNI/Host rewriting, which is
+ * disproportionate for preview metadata; accepted at this threat level.
+ */
+export declare class BlockedUrlError extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+/** Parse an absolute http/https URL. Returns null for anything else (caller maps to invalid_url). */
+export declare function parseHttpUrl(raw: string): URL | null;
+/** Synchronous literal checks: port, hostname blocklist, IP-literal hosts. Throws BlockedUrlError. */
+export declare function assertPublicHttpUrl(url: URL): void;
+/** True when the IP (v4 or v6, including ::ffff: mapped v4) is private, loopback, or reserved. */
+export declare function isPrivateAddress(ip: string): boolean;
+/** Resolve the hostname and require every returned address to be public. Throws BlockedUrlError. */
+export declare function assertResolvesPublic(url: URL): Promise<void>;
+export interface FetchPublicUrlOptions {
+    maxBytes: number;
+    timeoutMs: number;
+    /** Sent as the Accept header. */
+    accept?: string;
+    /** When set, the response Content-Type must start with one of these prefixes. */
+    requireContentTypePrefixes?: string[];
+}
+export interface FetchPublicUrlResult {
+    finalUrl: string;
+    contentType: string;
+    body: Buffer;
+}
+/**
+ * Fetch a public http/https URL with manual redirects (≤5 hops, each hop re-validated) and a
+ * streamed size cap (Content-Length is not trusted). Returns null on ordinary failures (non-2xx,
+ * oversize, timeout, bad content type, DNS error); throws BlockedUrlError on SSRF rejection.
+ */
+export declare function fetchPublicUrl(rawUrl: string, opts: FetchPublicUrlOptions): Promise<FetchPublicUrlResult | null>;

package/dist/src/link-preview/ssrf-guard.js

@@ -0,0 +1,223 @@
+/**
+ * SSRF guard + restricted fetch for the link-preview endpoint.
+ *
+ * Unlike `downloadRemoteMedia` (agent-supplied URLs for outbound media), link-preview fetches
+ * URLs that originate from arbitrary message text, so every hop must be validated: protocol,
+ * port, hostname literals, and the full set of DNS-resolved addresses. Redirects are followed
+ * manually so each target is re-checked before the next request.
+ *
+ * Known residual risk: DNS rebinding TOCTOU — we validate resolved addresses, then `fetch`
+ * resolves again. Closing that gap requires dialing by IP with SNI/Host rewriting, which is
+ * disproportionate for preview metadata; accepted at this threat level.
+ */
+import dns from "node:dns/promises";
+import net from "node:net";
+const MAX_REDIRECTS = 5;
+export class BlockedUrlError extends Error {
+    reason;
+    constructor(reason) {
+        super(`Blocked URL: ${reason}`);
+        this.name = "BlockedUrlError";
+        this.reason = reason;
+    }
+}
+/** Parse an absolute http/https URL. Returns null for anything else (caller maps to invalid_url). */
+export function parseHttpUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw.trim());
+    }
+    catch {
+        return null;
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:")
+        return null;
+    return url;
+}
+const BLOCKED_HOST_SUFFIXES = [".local", ".internal", ".home.arpa", ".localhost"];
+/** Synchronous literal checks: port, hostname blocklist, IP-literal hosts. Throws BlockedUrlError. */
+export function assertPublicHttpUrl(url) {
+    if (url.port && url.port !== "80" && url.port !== "443") {
+        throw new BlockedUrlError(`port ${url.port} not allowed`);
+    }
+    const host = url.hostname.toLowerCase().replace(/\.$/, "");
+    if (!host)
+        throw new BlockedUrlError("empty host");
+    if (host === "localhost" || BLOCKED_HOST_SUFFIXES.some((s) => host.endsWith(s))) {
+        throw new BlockedUrlError(`host "${host}" is not public`);
+    }
+    // IPv6 literal in a URL comes bracketed: strip for net.isIP.
+    const bareHost = host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
+    if (net.isIP(bareHost) && isPrivateAddress(bareHost)) {
+        throw new BlockedUrlError(`address ${bareHost} is private/reserved`);
+    }
+}
+/** True when the IP (v4 or v6, including ::ffff: mapped v4) is private, loopback, or reserved. */
+export function isPrivateAddress(ip) {
+    const version = net.isIP(ip);
+    if (version === 4)
+        return isPrivateIPv4(ip);
+    if (version === 6)
+        return isPrivateIPv6(ip);
+    return true; // not an IP at all — treat as unsafe
+}
+function isPrivateIPv4(ip) {
+    const parts = ip.split(".").map(Number);
+    if (parts.length !== 4 || parts.some((n) => !Number.isInteger(n) || n < 0 || n > 255))
+        return true;
+    const [a, b] = parts;
+    if (a === 0)
+        return true; // 0.0.0.0/8
+    if (a === 10)
+        return true; // 10/8
+    if (a === 100 && b >= 64 && b <= 127)
+        return true; // 100.64/10 CGNAT
+    if (a === 127)
+        return true; // loopback
+    if (a === 169 && b === 254)
+        return true; // link-local
+    if (a === 172 && b >= 16 && b <= 31)
+        return true; // 172.16/12
+    if (a === 192 && b === 0 && parts[2] === 0)
+        return true; // 192.0.0/24
+    if (a === 192 && b === 168)
+        return true; // 192.168/16
+    // 198.18/15 (benchmarking) intentionally NOT blocked: fake-IP DNS setups (clash/surge tun
+    // mode, common on gateway hosts) resolve EVERY domain into this range, so blocking it kills
+    // all lookups. The range is not used for real LAN services, so the SSRF exposure is nil.
+    if (a >= 224)
+        return true; // multicast 224/4 + reserved 240/4 + broadcast
+    return false;
+}
+function isPrivateIPv6(ip) {
+    const lower = ip.toLowerCase();
+    // ::ffff:a.b.c.d mapped IPv4 → validate the embedded v4.
+    const mapped = lower.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+    if (mapped)
+        return isPrivateIPv4(mapped[1]);
+    if (lower === "::" || lower === "::1")
+        return true; // unspecified / loopback
+    const head = lower.split(":")[0];
+    if (head.startsWith("fc") || head.startsWith("fd"))
+        return true; // fc00::/7 ULA
+    if (/^fe[89ab]/.test(head))
+        return true; // fe80::/10 link-local
+    return false;
+}
+/** Resolve the hostname and require every returned address to be public. Throws BlockedUrlError. */
+export async function assertResolvesPublic(url) {
+    const host = url.hostname.replace(/^\[|\]$/g, "");
+    if (net.isIP(host)) {
+        if (isPrivateAddress(host))
+            throw new BlockedUrlError(`address ${host} is private/reserved`);
+        return;
+    }
+    let addresses;
+    try {
+        addresses = await dns.lookup(host, { all: true, verbatim: true });
+    }
+    catch {
+        throw new Error(`DNS lookup failed for ${host}`);
+    }
+    if (!addresses.length)
+        throw new Error(`DNS lookup returned no addresses for ${host}`);
+    for (const { address } of addresses) {
+        if (isPrivateAddress(address)) {
+            throw new BlockedUrlError(`${host} resolves to private/reserved address ${address}`);
+        }
+    }
+}
+const PREVIEW_USER_AGENT = "Mozilla/5.0 (compatible; OpenClawLinkPreview/1.0)";
+/**
+ * Fetch a public http/https URL with manual redirects (≤5 hops, each hop re-validated) and a
+ * streamed size cap (Content-Length is not trusted). Returns null on ordinary failures (non-2xx,
+ * oversize, timeout, bad content type, DNS error); throws BlockedUrlError on SSRF rejection.
+ */
+export async function fetchPublicUrl(rawUrl, opts) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), opts.timeoutMs);
+    try {
+        let current = rawUrl;
+        for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+            const url = parseHttpUrl(current);
+            if (!url)
+                return null;
+            assertPublicHttpUrl(url);
+            await assertResolvesPublic(url);
+            const res = await fetch(url, {
+                redirect: "manual",
+                signal: controller.signal,
+                headers: {
+                    "User-Agent": PREVIEW_USER_AGENT,
+                    ...(opts.accept ? { Accept: opts.accept } : {}),
+                },
+            });
+            if (res.status >= 300 && res.status < 400) {
+                const location = res.headers.get("location");
+                await res.body?.cancel().catch(() => { });
+                if (!location)
+                    return null;
+                try {
+                    current = new URL(location, url).toString();
+                }
+                catch {
+                    return null;
+                }
+                continue;
+            }
+            if (!res.ok) {
+                await res.body?.cancel().catch(() => { });
+                return null;
+            }
+            const contentType = res.headers.get("content-type")?.trim().toLowerCase() ?? "";
+            if (opts.requireContentTypePrefixes &&
+                !opts.requireContentTypePrefixes.some((p) => contentType.startsWith(p))) {
+                await res.body?.cancel().catch(() => { });
+                return null;
+            }
+            const body = await readBodyCapped(res, opts.maxBytes);
+            if (body === null)
+                return null;
+            return { finalUrl: url.toString(), contentType, body };
+        }
+        return null; // too many redirects
+    }
+    catch (err) {
+        if (err instanceof BlockedUrlError)
+            throw err;
+        return null; // timeout / network / DNS failure
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Stream the response body, aborting once it exceeds maxBytes. */
+async function readBodyCapped(res, maxBytes) {
+    if (!res.body) {
+        const buffer = Buffer.from(await res.arrayBuffer());
+        return buffer.length <= maxBytes ? buffer : null;
+    }
+    const reader = res.body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (value) {
+                total += value.byteLength;
+                if (total > maxBytes) {
+                    await reader.cancel().catch(() => { });
+                    return null;
+                }
+                chunks.push(Buffer.from(value));
+            }
+        }
+    }
+    catch {
+        return null;
+    }
+    const buffer = Buffer.concat(chunks);
+    return buffer.length ? buffer : null;
+}

package/dist/src/plugin-install-info.d.ts

@@ -0,0 +1,15 @@
+/** Install source from the OpenClaw config `plugins.installs[<id>].source`. */
+export type InstallSource = "npm" | "path" | "archive" | "clawhub" | "git" | "marketplace" | "unknown";
+/**
+ * Read the install source for this plugin from the live config snapshot.
+ * Returns "unknown" when the record can't be resolved (e.g. runtime not captured).
+ * Only "npm" is auto-upgradable; "path" means a dev (load.paths) install which must
+ * never be npm-upgraded (would duplicate-install and break agent media sends).
+ */
+export declare function getInstallSource(): InstallSource;
+/** Compare dotted numeric versions. Returns true if `a` is strictly greater than `b`. */
+export declare function semverGreater(a: string | null | undefined, b: string | null | undefined): boolean;
+/** Fetch the latest published version from the npm registry (cached ~10min). Null on failure. */
+export declare function fetchLatestVersion(nowMs: number): Promise<string | null>;
+/** Vitest-only */
+export declare function resetLatestVersionCacheForTest(): void;

package/dist/src/plugin-install-info.js

@@ -0,0 +1,87 @@
+/**
+ * Helpers for the plugin upgrade feature: read this plugin's install record
+ * (source: "npm" vs "path"/dev), compare semver, and look up the latest version
+ * published to the npm registry (cached).
+ */
+import { getUpgradeRuntime } from "./upgrade-runtime.js";
+import { PLUGIN_ID, PLUGIN_PACKAGE_NAME } from "./version.js";
+/**
+ * Read the install source for this plugin from the live config snapshot.
+ * Returns "unknown" when the record can't be resolved (e.g. runtime not captured).
+ * Only "npm" is auto-upgradable; "path" means a dev (load.paths) install which must
+ * never be npm-upgraded (would duplicate-install and break agent media sends).
+ */
+export function getInstallSource() {
+    const rt = getUpgradeRuntime();
+    if (!rt)
+        return "unknown";
+    try {
+        const cfg = rt.currentConfig();
+        const source = cfg?.plugins?.installs?.[PLUGIN_ID]?.source;
+        if (source === "npm" ||
+            source === "path" ||
+            source === "archive" ||
+            source === "clawhub" ||
+            source === "git" ||
+            source === "marketplace") {
+            return source;
+        }
+        return "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+/** Compare dotted numeric versions. Returns true if `a` is strictly greater than `b`. */
+export function semverGreater(a, b) {
+    if (!a || !b)
+        return false;
+    const pa = parseSemver(a);
+    const pb = parseSemver(b);
+    for (let i = 0; i < 3; i++) {
+        if (pa[i] > pb[i])
+            return true;
+        if (pa[i] < pb[i])
+            return false;
+    }
+    return false;
+}
+function parseSemver(v) {
+    // Strip a leading "v" and any pre-release/build suffix, keep major.minor.patch.
+    const core = v.trim().replace(/^v/i, "").split(/[-+]/)[0];
+    const parts = core.split(".").map((p) => Number.parseInt(p, 10));
+    return [parts[0] || 0, parts[1] || 0, parts[2] || 0];
+}
+let cachedLatest = null;
+const LATEST_TTL_MS = 10 * 60 * 1000;
+/** Fetch the latest published version from the npm registry (cached ~10min). Null on failure. */
+export async function fetchLatestVersion(nowMs) {
+    if (cachedLatest && nowMs - cachedLatest.fetchedAt < LATEST_TTL_MS) {
+        return cachedLatest.version;
+    }
+    let version = null;
+    try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 5000);
+        try {
+            const res = await fetch(`https://registry.npmjs.org/${PLUGIN_PACKAGE_NAME}/latest`, { signal: controller.signal, headers: { Accept: "application/json" } });
+            if (res.ok) {
+                const body = (await res.json());
+                if (typeof body.version === "string" && body.version)
+                    version = body.version;
+            }
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    catch {
+        version = null;
+    }
+    cachedLatest = { version, fetchedAt: nowMs };
+    return version;
+}
+/** Vitest-only */
+export function resetLatestVersionCacheForTest() {
+    cachedLatest = null;
+}

package/dist/src/upgrade-runtime.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Captures the full plugin runtime (`api.runtime`) at `registerFull` time so the
+ * plugin-info / plugin-upgrade HTTP handlers can reach `system.runCommandWithTimeout`
+ * and `config.mutateConfigFile` — capabilities the narrow `getFridayNextRuntime()`
+ * store does NOT expose (it only carries `config`/`logger`).
+ *
+ * Mirrors the `setFridayAgentForwardRuntime` capture pattern in agent-forward-runtime.ts.
+ */
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
+export type SpawnResultLike = {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+    [key: string]: unknown;
+};
+export type ConfigAfterWrite = {
+    mode: "auto";
+} | {
+    mode: "restart";
+    reason: string;
+} | {
+    mode: "none";
+    reason: string;
+};
+export type UpgradeRuntime = {
+    /** Run a command (argv) with a timeout in ms; resolves with stdout/stderr/code. */
+    runCommandWithTimeout: (argv: string[], timeoutMs: number) => Promise<SpawnResultLike>;
+    /** Read the current (deep-readonly) OpenClaw config snapshot. */
+    currentConfig: () => unknown;
+    /** Mutate the config file; `afterWrite: { mode: "restart" }` triggers a safe gateway restart. */
+    mutateConfigFile: (params: {
+        afterWrite: ConfigAfterWrite;
+        mutate: (draft: unknown) => unknown | void;
+    }) => Promise<unknown>;
+};
+export declare function setUpgradeRuntime(api: OpenClawPluginApi): void;
+export declare function getUpgradeRuntime(): UpgradeRuntime | null;
+/** Vitest-only */
+export declare function resetUpgradeRuntimeForTest(): void;

package/dist/src/upgrade-runtime.js

@@ -0,0 +1,27 @@
+let upgradeRuntime = null;
+export function setUpgradeRuntime(api) {
+    const runtime = api.runtime;
+    upgradeRuntime = {
+        runCommandWithTimeout: async (argv, timeoutMs) => {
+            const run = runtime.system?.runCommandWithTimeout;
+            if (!run)
+                throw new Error("runtime.system.runCommandWithTimeout unavailable");
+            // `runCommandWithTimeout(argv, number | CommandOptions)` — pass the bare ms.
+            return run(argv, timeoutMs);
+        },
+        currentConfig: () => runtime.config.current(),
+        mutateConfigFile: async (params) => {
+            const mutate = runtime.config.mutateConfigFile;
+            if (!mutate)
+                throw new Error("runtime.config.mutateConfigFile unavailable");
+            return mutate(params);
+        },
+    };
+}
+export function getUpgradeRuntime() {
+    return upgradeRuntime;
+}
+/** Vitest-only */
+export function resetUpgradeRuntimeForTest() {
+    upgradeRuntime = null;
+}