@syengup/friday-channel-next 0.1.27 → 0.1.29

package/src/link-preview/ssrf-guard.test.ts

@@ -0,0 +1,234 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("node:dns/promises", () => ({
+  default: { lookup: vi.fn() },
+}));
+
+import dns from "node:dns/promises";
+import {
+  BlockedUrlError,
+  assertPublicHttpUrl,
+  assertResolvesPublic,
+  fetchPublicUrl,
+  isPrivateAddress,
+  parseHttpUrl,
+} from "./ssrf-guard.js";
+
+const lookupMock = vi.mocked(dns.lookup);
+
+function mockPublicDns(): void {
+  lookupMock.mockResolvedValue([{ address: "93.184.216.34", family: 4 }] as never);
+}
+
+beforeEach(() => {
+  lookupMock.mockReset();
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe("parseHttpUrl", () => {
+  it("accepts absolute http/https URLs", () => {
+    expect(parseHttpUrl("https://example.com/a?b=1")?.hostname).toBe("example.com");
+    expect(parseHttpUrl("  http://example.com  ")?.protocol).toBe("http:");
+  });
+
+  it("rejects non-http schemes and garbage", () => {
+    expect(parseHttpUrl("ftp://example.com/a")).toBeNull();
+    expect(parseHttpUrl("file:///etc/passwd")).toBeNull();
+    expect(parseHttpUrl("javascript:alert(1)")).toBeNull();
+    expect(parseHttpUrl("not a url")).toBeNull();
+    expect(parseHttpUrl("/relative/path")).toBeNull();
+  });
+});
+
+describe("assertPublicHttpUrl", () => {
+  it("rejects non-default ports", () => {
+    expect(() => assertPublicHttpUrl(new URL("http://example.com:8080/"))).toThrow(BlockedUrlError);
+    expect(() => assertPublicHttpUrl(new URL("https://example.com:8443/"))).toThrow(BlockedUrlError);
+  });
+
+  it("allows default and explicit 80/443 ports", () => {
+    expect(() => assertPublicHttpUrl(new URL("https://example.com/"))).not.toThrow();
+    expect(() => assertPublicHttpUrl(new URL("http://example.com:80/"))).not.toThrow();
+    expect(() => assertPublicHttpUrl(new URL("https://example.com:443/"))).not.toThrow();
+  });
+
+  it("rejects localhost and internal-suffix hostnames", () => {
+    expect(() => assertPublicHttpUrl(new URL("http://localhost/"))).toThrow(BlockedUrlError);
+    expect(() => assertPublicHttpUrl(new URL("http://gateway.local/"))).toThrow(BlockedUrlError);
+    expect(() => assertPublicHttpUrl(new URL("http://db.internal/"))).toThrow(BlockedUrlError);
+    expect(() => assertPublicHttpUrl(new URL("http://nas.home.arpa/"))).toThrow(BlockedUrlError);
+  });
+
+  it("rejects private IP literals including bracketed IPv6", () => {
+    expect(() => assertPublicHttpUrl(new URL("http://127.0.0.1/"))).toThrow(BlockedUrlError);
+    expect(() => assertPublicHttpUrl(new URL("http://10.0.0.5/"))).toThrow(BlockedUrlError);
+    expect(() => assertPublicHttpUrl(new URL("http://[::1]/"))).toThrow(BlockedUrlError);
+    expect(() => assertPublicHttpUrl(new URL("http://[fc00::1]/"))).toThrow(BlockedUrlError);
+  });
+
+  it("allows public IP literals", () => {
+    expect(() => assertPublicHttpUrl(new URL("http://93.184.216.34/"))).not.toThrow();
+  });
+});
+
+describe("isPrivateAddress", () => {
+  it("flags private/reserved IPv4 ranges", () => {
+    for (const ip of [
+      "0.0.0.0",
+      "10.1.2.3",
+      "100.64.0.1",
+      "100.127.255.255",
+      "127.0.0.1",
+      "169.254.1.1",
+      "172.16.0.1",
+      "172.31.255.255",
+      "192.0.0.1",
+      "192.168.1.1",
+      "224.0.0.1",
+      "255.255.255.255",
+    ]) {
+      expect(isPrivateAddress(ip), ip).toBe(true);
+    }
+  });
+
+  it("passes public IPv4", () => {
+    for (const ip of ["8.8.8.8", "93.184.216.34", "100.63.0.1", "100.128.0.1", "172.32.0.1", "198.20.0.1"]) {
+      expect(isPrivateAddress(ip), ip).toBe(false);
+    }
+  });
+
+  it("passes 198.18/15 (fake-IP DNS range used by clash/surge tun mode)", () => {
+    expect(isPrivateAddress("198.18.1.156")).toBe(false);
+    expect(isPrivateAddress("198.19.255.255")).toBe(false);
+  });
+
+  it("flags private/reserved IPv6 and mapped IPv4", () => {
+    for (const ip of ["::1", "::", "fc00::1", "fd12:3456::1", "fe80::1", "::ffff:10.0.0.1", "::ffff:127.0.0.1"]) {
+      expect(isPrivateAddress(ip), ip).toBe(true);
+    }
+  });
+
+  it("passes public IPv6 and mapped public IPv4", () => {
+    expect(isPrivateAddress("2606:2800:220:1:248:1893:25c8:1946")).toBe(false);
+    expect(isPrivateAddress("::ffff:93.184.216.34")).toBe(false);
+  });
+
+  it("treats non-IP strings as unsafe", () => {
+    expect(isPrivateAddress("not-an-ip")).toBe(true);
+  });
+});
+
+describe("assertResolvesPublic", () => {
+  it("passes when all resolved addresses are public", async () => {
+    lookupMock.mockResolvedValue([
+      { address: "93.184.216.34", family: 4 },
+      { address: "2606:2800:220:1:248:1893:25c8:1946", family: 6 },
+    ] as never);
+    await expect(assertResolvesPublic(new URL("https://example.com/"))).resolves.toBeUndefined();
+  });
+
+  it("throws BlockedUrlError when any resolved address is private", async () => {
+    lookupMock.mockResolvedValue([
+      { address: "93.184.216.34", family: 4 },
+      { address: "10.0.0.5", family: 4 },
+    ] as never);
+    await expect(assertResolvesPublic(new URL("https://rebind.example.com/"))).rejects.toThrow(BlockedUrlError);
+  });
+
+  it("validates IP-literal hosts without a DNS lookup", async () => {
+    await expect(assertResolvesPublic(new URL("http://127.0.0.1/"))).rejects.toThrow(BlockedUrlError);
+    await expect(assertResolvesPublic(new URL("http://93.184.216.34/"))).resolves.toBeUndefined();
+    expect(lookupMock).not.toHaveBeenCalled();
+  });
+
+  it("throws a plain error (not BlockedUrlError) on DNS failure", async () => {
+    lookupMock.mockRejectedValue(new Error("ENOTFOUND"));
+    const err = await assertResolvesPublic(new URL("https://nope.example.com/")).catch((e) => e);
+    expect(err).toBeInstanceOf(Error);
+    expect(err).not.toBeInstanceOf(BlockedUrlError);
+  });
+});
+
+describe("fetchPublicUrl", () => {
+  const opts = { maxBytes: 1024, timeoutMs: 5000 };
+
+  it("fetches a public URL and returns body + finalUrl", async () => {
+    mockPublicDns();
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => new Response("<html>hi</html>", { status: 200, headers: { "content-type": "text/html; charset=utf-8" } })),
+    );
+    const result = await fetchPublicUrl("https://example.com/page", opts);
+    expect(result?.finalUrl).toBe("https://example.com/page");
+    expect(result?.contentType).toContain("text/html");
+    expect(result?.body.toString()).toBe("<html>hi</html>");
+  });
+
+  it("follows redirects and re-validates each hop", async () => {
+    mockPublicDns();
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValueOnce(new Response(null, { status: 302, headers: { location: "https://other.example.com/final" } }))
+      .mockResolvedValueOnce(new Response("ok", { status: 200, headers: { "content-type": "text/html" } }));
+    vi.stubGlobal("fetch", fetchMock);
+    const result = await fetchPublicUrl("https://example.com/start", opts);
+    expect(result?.finalUrl).toBe("https://other.example.com/final");
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(lookupMock).toHaveBeenCalledTimes(2);
+  });
+
+  it("throws BlockedUrlError when a redirect targets a private address", async () => {
+    mockPublicDns();
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => new Response(null, { status: 302, headers: { location: "http://127.0.0.1/admin" } })),
+    );
+    await expect(fetchPublicUrl("https://example.com/start", opts)).rejects.toThrow(BlockedUrlError);
+  });
+
+  it("throws BlockedUrlError for a directly-blocked URL", async () => {
+    await expect(fetchPublicUrl("http://192.168.1.1/", opts)).rejects.toThrow(BlockedUrlError);
+  });
+
+  it("returns null when the body exceeds maxBytes (ignoring content-length)", async () => {
+    mockPublicDns();
+    const big = "x".repeat(2048);
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => new Response(big, { status: 200, headers: { "content-type": "text/html", "content-length": "10" } })),
+    );
+    expect(await fetchPublicUrl("https://example.com/big", opts)).toBeNull();
+  });
+
+  it("returns null when content-type does not match the required prefixes", async () => {
+    mockPublicDns();
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => new Response("{}", { status: 200, headers: { "content-type": "application/json" } })),
+    );
+    expect(
+      await fetchPublicUrl("https://example.com/api", { ...opts, requireContentTypePrefixes: ["text/html", "application/xhtml+xml"] }),
+    ).toBeNull();
+  });
+
+  it("returns null on non-2xx and on DNS failure", async () => {
+    mockPublicDns();
+    vi.stubGlobal("fetch", vi.fn(async () => new Response("nope", { status: 404 })));
+    expect(await fetchPublicUrl("https://example.com/missing", opts)).toBeNull();
+
+    lookupMock.mockRejectedValue(new Error("ENOTFOUND"));
+    expect(await fetchPublicUrl("https://nope.example.com/", opts)).toBeNull();
+  });
+
+  it("gives up after too many redirects", async () => {
+    mockPublicDns();
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => new Response(null, { status: 302, headers: { location: "https://example.com/loop" } })),
+    );
+    expect(await fetchPublicUrl("https://example.com/loop", opts)).toBeNull();
+  });
+});

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

@@ -0,0 +1,229 @@
+/**
+ * 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 {
+  readonly reason: string;
+  constructor(reason: string) {
+    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: string): URL | null {
+  let url: 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: URL): void {
+  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: string): boolean {
+  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: string): boolean {
+  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: string): boolean {
+  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: URL): Promise<void> {
+  const host = url.hostname.replace(/^\[|\]$/g, "");
+  if (net.isIP(host)) {
+    if (isPrivateAddress(host)) throw new BlockedUrlError(`address ${host} is private/reserved`);
+    return;
+  }
+  let addresses: { address: string }[];
+  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}`);
+    }
+  }
+}
+
+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;
+}
+
+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: string,
+  opts: FetchPublicUrlOptions,
+): Promise<FetchPublicUrlResult | null> {
+  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: Response, maxBytes: number): Promise<Buffer | null> {
+  if (!res.body) {
+    const buffer = Buffer.from(await res.arrayBuffer());
+    return buffer.length <= maxBytes ? buffer : null;
+  }
+  const reader = res.body.getReader();
+  const chunks: Buffer[] = [];
+  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/src/plugin-install-info.test.ts

@@ -1,5 +1,35 @@
 import { describe, expect, it } from "vitest";
-import { semverGreater } from "./plugin-install-info.js";
+import { classifyInstallSourceFromLoadedPath, semverGreater } from "./plugin-install-info.js";
+
+describe("classifyInstallSourceFromLoadedPath", () => {
+  it("treats paths under the managed npm projects dir as npm", () => {
+    expect(
+      classifyInstallSourceFromLoadedPath(
+        "/Users/me/.openclaw/npm/projects/syengup-friday-channel-next-ef89e139a1/node_modules/@syengup/friday-channel-next/dist/index.js",
+      ),
+    ).toBe("npm");
+    // install-path form (no /dist/index.js suffix) also resolves to npm
+    expect(
+      classifyInstallSourceFromLoadedPath(
+        "/Users/me/.openclaw/npm/projects/syengup-friday-channel-next-ef89e139a1/node_modules/@syengup/friday-channel-next",
+      ),
+    ).toBe("npm");
+  });
+
+  it("treats a dev/link checkout path as path", () => {
+    expect(
+      classifyInstallSourceFromLoadedPath(
+        "/Users/me/Documents/Project/Friday-Next/openclaw-fridaynext-channel/dist/index.js",
+      ),
+    ).toBe("path");
+  });
+
+  it("returns unknown for missing/empty input", () => {
+    expect(classifyInstallSourceFromLoadedPath(null)).toBe("unknown");
+    expect(classifyInstallSourceFromLoadedPath(undefined)).toBe("unknown");
+    expect(classifyInstallSourceFromLoadedPath("")).toBe("unknown");
+  });
+});
 
 describe("semverGreater", () => {
   it("returns true when a is a higher patch/minor/major", () => {

package/src/plugin-install-info.ts

@@ -10,10 +10,33 @@ import { PLUGIN_ID, PLUGIN_PACKAGE_NAME } from "./version.js";
 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).
+ * Infer the install source from the loaded plugin's filesystem path (`api.source`).
+ *
+ * OpenClaw copies non-dev installs (npm/archive/clawhub/git) into
+ * `~/.openclaw/npm/projects/<hash>/node_modules/...`, whereas a dev install
+ * (`load.paths` / `plugins install --link`) is loaded directly from the source
+ * checkout. For this plugin's purposes the only distinction that matters is
+ * npm-managed (auto-upgradable) vs dev (must never npm-upgrade — see
+ * dev-no-duplicate-plugin-install), so anything under the managed projects dir
+ * is treated as "npm".
+ */
+export function classifyInstallSourceFromLoadedPath(loadedPath: string | null | undefined): InstallSource {
+  if (!loadedPath) return "unknown";
+  return loadedPath.includes("/.openclaw/npm/projects/") ? "npm" : "path";
+}
+
+/**
+ * Resolve the install source for this plugin (npm vs dev path).
+ * Returns "unknown" when it can't be resolved (e.g. runtime not captured).
+ * Only "npm" is auto-upgradable; "path" means a dev (load.paths / --link) install
+ * which must never be npm-upgraded (would duplicate-install and break agent media sends).
+ *
+ * Resolution order:
+ *  1. The explicit `plugins.installs[<id>].source` config record — present on older
+ *     OpenClaw builds that surface install records in the runtime config snapshot.
+ *  2. Fallback: OpenClaw 2026.6.x moved install records out of the config snapshot
+ *     into a separate registry (~/.openclaw/state.db), leaving `plugins.installs`
+ *     unset — so infer from the loaded plugin path (`api.source`) instead.
  */
 export function getInstallSource(): InstallSource {
   const rt = getUpgradeRuntime();
@@ -33,10 +56,10 @@ export function getInstallSource(): InstallSource {
     ) {
       return source;
     }
-    return "unknown";
   } catch {
-    return "unknown";
+    // fall through to the path-based heuristic
   }
+  return classifyInstallSourceFromLoadedPath(rt.pluginSource);
 }
 
 /** Compare dotted numeric versions. Returns true if `a` is strictly greater than `b`. */

package/src/upgrade-runtime.ts

@@ -30,6 +30,12 @@ export type UpgradeRuntime = {
     afterWrite: ConfigAfterWrite;
     mutate: (draft: unknown) => unknown | void;
   }) => Promise<unknown>;
+  /**
+   * Filesystem path of THIS loaded plugin (`api.source`). Used to infer the install
+   * source (npm vs dev) on OpenClaw builds (2026.6.x+) that no longer surface
+   * `plugins.installs` in the config snapshot. See `getInstallSource`.
+   */
+  pluginSource: string | undefined;
 };
 
 let upgradeRuntime: UpgradeRuntime | null = null;
@@ -56,6 +62,7 @@ export function setUpgradeRuntime(api: OpenClawPluginApi): void {
       if (!mutate) throw new Error("runtime.config.mutateConfigFile unavailable");
       return mutate(params);
     },
+    pluginSource: typeof api.source === "string" ? api.source : undefined,
   };
 }
 

package/src/version.ts

@@ -11,7 +11,7 @@ import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 
 /** Keep in sync with package.json "version" as a last-resort fallback. */
-const FALLBACK_VERSION = "0.1.27";
+const FALLBACK_VERSION = "0.1.29";
 
 function resolvePluginVersion(): string {
   // dist layout: <root>/dist/src/version.js → ../../package.json = <root>/package.json