@syengup/friday-channel-next 0.1.25 → 0.1.27

package/src/http/handlers/health.ts

@@ -2,6 +2,7 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import { extractBearerToken } from "../middleware/auth.js";
 import { loadNodePairingModule } from "../../agent/node-pairing-bridge.js";
 import { createFridayNextLogger } from "../../logging.js";
+import { PLUGIN_VERSION } from "../../version.js";
 
 const REQUIRED_NODE_CAPS = ["location", "canvas"];
 const REQUIRED_NODE_COMMANDS = [
@@ -34,6 +35,7 @@ export interface HealthCheckResult {
   timestamp: number;
   deviceId: string;
   nodeDeviceId: string;
+  pluginVersion: string;
   nodePairing?: HealthComponentStatus;
   repairActions?: RepairAction[];
 }
@@ -64,6 +66,7 @@ export async function handleHealth(req: IncomingMessage, res: ServerResponse): P
     timestamp: Date.now(),
     deviceId,
     nodeDeviceId,
+    pluginVersion: PLUGIN_VERSION,
   };
 
   const log = createFridayNextLogger("health");

package/src/http/handlers/history-messages.test.ts

@@ -170,6 +170,39 @@ describe("handleHistoryMessages", () => {
     expect(body.messages[0].text).toBe("from app");
   });
 
+  it("resolves user [media attached: file://] markers into downloadable /friday-next/files URLs", async () => {
+    // The server-local source the marker points at (only exists on the gateway host).
+    const srcDir = fs.mkdtempSync(path.join(os.tmpdir(), "friday-inbound-"));
+    const srcFile = path.join(srcDir, "ce1ff405-28ad-48b9-b4a7-4f2228d77649.jpg");
+    fs.writeFileSync(srcFile, Buffer.from([0xff, 0xd8, 0xff, 0xe0, 0x00, 0x10]));
+    const file = writeTranscript("media.jsonl", [
+      {
+        type: "message",
+        id: "u1",
+        message: {
+          role: "user",
+          content: `你见过这个可乐吗？\n\n[media attached: file://${srcFile}]`,
+        },
+      },
+    ]);
+    setForward({ "agent:main:main": { sessionId: "s", sessionFile: file } });
+
+    const res = new MockRes();
+    await handleHistoryMessages(
+      makeReq("/friday-next/history/messages?sessionKey=agent:main:main", AUTH),
+      res as any,
+    );
+    expect(res.statusCode).toBe(200);
+    const body = JSON.parse(res.body);
+    const userMsg = body.messages.find((m: any) => m.role === "user");
+    expect(userMsg.images?.length).toBe(1);
+    // The raw server-local file:// path must be resolved to a gateway-served URL the
+    // app can actually download — otherwise the attachment bubble is lost on history sync.
+    expect(userMsg.images[0].url.startsWith("file://")).toBe(false);
+    expect(userMsg.images[0].url.startsWith("/friday-next/files/")).toBe(true);
+    fs.rmSync(srcDir, { recursive: true, force: true });
+  });
+
   it("falls back to getSessionMessages when the transcript is not on disk", async () => {
     setForward({}); // no entry → disk read yields nothing
     setRuntime(async () => ({

package/src/http/handlers/history-messages.ts

@@ -11,6 +11,7 @@
  */
 
 import type { IncomingMessage, ServerResponse } from "node:http";
+import { fileURLToPath } from "node:url";
 import { getFridayNextRuntime } from "../../runtime.js";
 import { extractBearerToken } from "../middleware/auth.js";
 import { normalizeHistoryMessages } from "../../history/normalize-message.js";
@@ -28,6 +29,26 @@ type SubagentSessionApi = {
   }) => Promise<{ messages?: unknown[] }>;
 };
 
+/**
+ * For an `images[].url` produced from a `[media attached: …]` marker: returns the
+ * server-local filesystem path to resolve (`file://…` or a bare absolute path), or
+ * null to leave the image untouched. Already-served `/friday-next/files/…` URLs and
+ * remote `http(s)://` / `data:` URLs are NOT local paths — never feed them to
+ * `resolveMediaAttachment` (it would mis-treat them as paths and break valid URLs).
+ */
+function serverLocalPathForImageUrl(url: string): string | null {
+  if (url.startsWith("file://")) {
+    try {
+      return fileURLToPath(url);
+    } catch {
+      return url.slice("file://".length);
+    }
+  }
+  if (url.startsWith("/friday-next/files/")) return null;
+  if (url.startsWith("/")) return url;
+  return null;
+}
+
 function resolveSubagentApi(): SubagentSessionApi | undefined {
   try {
     const runtime = getFridayNextRuntime();
@@ -95,15 +116,32 @@ export async function handleHistoryMessages(
   // (copies the file into the plugin's attachments/ dir — the same mechanism the
   // live deliver path uses), then drop the raw paths from the wire.
   for (const message of messages) {
-    if (!message.mediaPaths?.length) continue;
-    const resolved = message.mediaPaths
-      .map((p) => resolveMediaAttachment(p))
-      .filter((r): r is NonNullable<typeof r> => Boolean(r))
-      .map((r) => ({ url: r.url, filename: r.fileName }));
-    if (resolved.length) {
-      message.images = [...(message.images ?? []), ...resolved];
+    if (message.mediaPaths?.length) {
+      const resolved = message.mediaPaths
+        .map((p) => resolveMediaAttachment(p))
+        .filter((r): r is NonNullable<typeof r> => Boolean(r))
+        .map((r) => ({ url: r.url, filename: r.fileName }));
+      if (resolved.length) {
+        message.images = [...(message.images ?? []), ...resolved];
+      }
+      delete message.mediaPaths;
+    }
+
+    // User attachments arrive as `[media attached: file://<server-path>]` markers,
+    // which normalize-message extracts into images[].url as a RAW server-local path.
+    // Unlike MEDIA: paths (resolved above), these were never copied into the file
+    // store, so the app would try to load a path that only exists on the gateway host
+    // and the attachment bubble is lost on history sync. Resolve them the same way.
+    if (message.images?.length) {
+      message.images = message.images.map((img) => {
+        if (!img.url || img.data) return img;
+        const local = serverLocalPathForImageUrl(img.url);
+        if (!local) return img;
+        const resolved = resolveMediaAttachment(local);
+        if (!resolved) return img;
+        return { ...img, url: resolved.url, filename: img.filename ?? resolved.fileName };
+      });
     }
-    delete message.mediaPaths;
   }
 
   const sessionId = resolveSessionId(sessionKey);

package/src/http/handlers/messages.test.ts

@@ -2,7 +2,7 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 import { EventEmitter } from "node:events";
 import { PassThrough } from "node:stream";
 import type { IncomingMessage, ServerResponse } from "node:http";
-import { handleMessages } from "./messages.js";
+import { handleMessages, composeBodyWithMediaRefs } from "./messages.js";
 import { clearFridayNextRuntime, setFridayNextRuntime } from "../../runtime.js";
 import {
   __resetMockFridayDispatchForTests,
@@ -23,6 +23,24 @@ class MockRes extends EventEmitter {
   }
 }
 
+describe("composeBodyWithMediaRefs", () => {
+  it("returns trimmed text alone when no media refs", () => {
+    expect(composeBodyWithMediaRefs("  hi  ", [])).toBe("hi");
+  });
+
+  it("joins text and media refs with a blank line", () => {
+    expect(composeBodyWithMediaRefs("hi", ["[media attached: file:///a]"])).toBe(
+      "hi\n\n[media attached: file:///a]",
+    );
+  });
+
+  it("omits the leading blank line when text is empty (attachment-only)", () => {
+    expect(composeBodyWithMediaRefs("", ["[media attached: file:///a]", "[media attached: file:///b]"])).toBe(
+      "[media attached: file:///a]\n[media attached: file:///b]",
+    );
+  });
+});
+
 describe("handleMessages dispatch context (owner fields)", () => {
   afterEach(() => {
     clearFridayNextRuntime();
@@ -70,6 +88,62 @@ describe("handleMessages dispatch context (owner fields)", () => {
     expect(capturedCtx!.From).toBe(want);
   });
 
+  it("accepts attachment-only messages (empty text + attachments) and dispatches", async () => {
+    setFridayNextRuntime({
+      config: { loadConfig: () => ({ gateway: { auth: { token: "tok" } }, channels: {} }) },
+    } as never);
+
+    let dispatched = false;
+    const dispatchCalled = new Promise<void>((resolve) => {
+      __setMockFridayDispatchForTests(() => {
+        dispatched = true;
+        resolve();
+        return Promise.resolve();
+      });
+    });
+
+    const req = new PassThrough() as unknown as IncomingMessage;
+    req.method = "POST";
+    req.headers = { authorization: "Bearer tok" };
+    const res = new MockRes() as unknown as ServerResponse;
+    const p = handleMessages(req, res);
+
+    req.end(
+      JSON.stringify({
+        deviceId: "AA11",
+        text: "",
+        attachments: ["att-1"],
+        sessionKey: "default",
+      }),
+    );
+
+    await p;
+    await dispatchCalled;
+
+    expect((res as unknown as MockRes).statusCode).toBe(202);
+    expect(dispatched).toBe(true);
+  });
+
+  it("rejects messages with neither text nor attachments", async () => {
+    setFridayNextRuntime({
+      config: { loadConfig: () => ({ gateway: { auth: { token: "tok" } }, channels: {} }) },
+    } as never);
+
+    const req = new PassThrough() as unknown as IncomingMessage;
+    req.method = "POST";
+    req.headers = { authorization: "Bearer tok" };
+    const res = new MockRes() as unknown as ServerResponse;
+    const p = handleMessages(req, res);
+
+    req.end(
+      JSON.stringify({ deviceId: "AA11", text: "   ", attachments: [], sessionKey: "default" }),
+    );
+
+    await p;
+
+    expect((res as unknown as MockRes).statusCode).toBe(400);
+  });
+
   it("adds fridayNext mediaKind metadata for audio deliver payload", async () => {
     setFridayNextRuntime({
       config: { loadConfig: () => ({ gateway: { auth: { token: "tok" } }, channels: {} }) },

package/src/http/handlers/messages.ts

@@ -362,6 +362,16 @@ export interface FridayMessagePayload {
   thinkingLevel?: string;
 }
 
+/**
+ * 把可选文本与媒体引用拼成给 agent 的最终 body。纯附件（文本为空）场景下
+ * 不能带前导空行，否则 agent 收到的是 `\n\n[media…]`——故拆成可测纯函数。
+ */
+export function composeBodyWithMediaRefs(text: string, mediaRefs: string[]): string {
+  const trimmed = text.trim();
+  if (mediaRefs.length === 0) return trimmed;
+  return trimmed ? `${trimmed}\n\n${mediaRefs.join("\n")}` : mediaRefs.join("\n");
+}
+
 async function buildBodyForAgentWithAttachments(text: string, attachmentIds: string[]): Promise<string> {
   if (attachmentIds.length === 0) return text.trim();
 
@@ -376,8 +386,7 @@ async function buildBodyForAgentWithAttachments(text: string, attachmentIds: str
     }
   }
 
-  if (mediaRefs.length === 0) return text.trim();
-  return `${text.trim()}\n\n${mediaRefs.join("\n")}`;
+  return composeBodyWithMediaRefs(text, mediaRefs);
 }
 
 export async function handleMessages(req: IncomingMessage, res: ServerResponse): Promise<boolean> {
@@ -428,15 +437,18 @@ export async function handleMessages(req: IncomingMessage, res: ServerResponse):
     return true;
   }
 
-  if (!text || !text.trim()) {
-    log("BAD_REQUEST", normalizedDeviceId, undefined, "missing text", "warn");
+  // 允许"只发附件、不发文本"：text 与 attachments 不能同时为空，但任一非空即放行。
+  const hasText = Boolean(text && text.trim());
+  const hasAttachments = Array.isArray(attachments) && attachments.length > 0;
+  if (!hasText && !hasAttachments) {
+    log("BAD_REQUEST", normalizedDeviceId, undefined, "missing text and attachments", "warn");
     res.statusCode = 400;
     res.setHeader("Content-Type", "application/json");
-    res.end(JSON.stringify({ error: "Missing required field: text" }));
+    res.end(JSON.stringify({ error: "Missing required field: text or attachments" }));
     return true;
   }
 
-  const trimmedText = text.trim();
+  const trimmedText = (text ?? "").trim();
   touchFridayInbound();
 
   const isSlashCommand = trimmedText.startsWith("/");
@@ -492,7 +504,7 @@ export async function handleMessages(req: IncomingMessage, res: ServerResponse):
   sseEmitter.trackDeviceForRun(normalizedDeviceId, runId);
   registerRunRoute({ runId, deviceId: normalizedDeviceId, sessionKey: baseSessionKey });
 
-  const bodyForAgent = await buildBodyForAgentWithAttachments(text, attachments);
+  const bodyForAgent = await buildBodyForAgentWithAttachments(trimmedText, attachments);
 
   const msgContext = {
     Body: trimmedText,

package/src/http/handlers/plugin-info.ts

@@ -0,0 +1,51 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { extractBearerToken } from "../middleware/auth.js";
+import { PLUGIN_VERSION } from "../../version.js";
+import {
+  fetchLatestVersion,
+  getInstallSource,
+  semverGreater,
+} from "../../plugin-install-info.js";
+
+export interface PluginInfoResult {
+  currentVersion: string;
+  latestVersion: string | null;
+  installSource: string;
+  /** True when the install is npm-managed (the only auto-upgradable source). */
+  canAutoUpgrade: boolean;
+  /** True when a newer version is published AND the install can be auto-upgraded. */
+  upgradable: boolean;
+}
+
+export async function handlePluginInfo(req: IncomingMessage, res: ServerResponse): Promise<boolean> {
+  if (req.method !== "GET") {
+    res.statusCode = 405;
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify({ error: "Method Not Allowed" }));
+    return true;
+  }
+  if (!extractBearerToken(req)) {
+    res.statusCode = 401;
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify({ error: "Unauthorized: bearer token mismatch" }));
+    return true;
+  }
+
+  const installSource = getInstallSource();
+  const canAutoUpgrade = installSource === "npm";
+  const latestVersion = await fetchLatestVersion(Date.now());
+  const upgradable = canAutoUpgrade && semverGreater(latestVersion, PLUGIN_VERSION);
+
+  const result: PluginInfoResult = {
+    currentVersion: PLUGIN_VERSION,
+    latestVersion,
+    installSource,
+    canAutoUpgrade,
+    upgradable,
+  };
+
+  res.statusCode = 200;
+  res.setHeader("Content-Type", "application/json");
+  res.end(JSON.stringify(result));
+  return true;
+}

package/src/http/handlers/plugin-upgrade.ts

@@ -0,0 +1,112 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { extractBearerToken } from "../middleware/auth.js";
+import { createFridayNextLogger } from "../../logging.js";
+import { PLUGIN_PACKAGE_NAME, PLUGIN_VERSION } from "../../version.js";
+import { getInstallSource } from "../../plugin-install-info.js";
+import { getUpgradeRuntime } from "../../upgrade-runtime.js";
+
+const UPGRADE_TIMEOUT_MS = 120_000;
+/** Give the 202 response time to flush before the restart kills the process. */
+const RESTART_DELAY_MS = 500;
+
+/**
+ * POST /friday-next/plugin/upgrade
+ *
+ * Runs `openclaw plugins install @syengup/friday-channel-next@latest --force`
+ * (registry-aware, updates the install record), responds 202, then triggers a
+ * safe gateway restart so the new version loads. Only npm-installed plugins are
+ * eligible — dev (load.paths / source==="path") installs return 409 to protect
+ * the dev environment from duplicate npm installs.
+ */
+export async function handlePluginUpgrade(req: IncomingMessage, res: ServerResponse): Promise<boolean> {
+  if (req.method !== "POST") {
+    res.statusCode = 405;
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify({ error: "Method Not Allowed" }));
+    return true;
+  }
+  if (!extractBearerToken(req)) {
+    res.statusCode = 401;
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify({ error: "Unauthorized: bearer token mismatch" }));
+    return true;
+  }
+
+  const log = createFridayNextLogger("upgrade");
+  const installSource = getInstallSource();
+  if (installSource !== "npm") {
+    res.statusCode = 409;
+    res.setHeader("Content-Type", "application/json");
+    res.end(
+      JSON.stringify({
+        error: "auto-upgrade not available",
+        detail: `install source is "${installSource}"; only npm installs can be auto-upgraded`,
+        installSource,
+      }),
+    );
+    return true;
+  }
+
+  const rt = getUpgradeRuntime();
+  if (!rt) {
+    res.statusCode = 500;
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify({ error: "upgrade runtime unavailable" }));
+    return true;
+  }
+
+  const spec = `${PLUGIN_PACKAGE_NAME}@latest`;
+  log.info(`Starting plugin upgrade: ${spec} (from ${PLUGIN_VERSION})`);
+
+  let result;
+  try {
+    result = await rt.runCommandWithTimeout(
+      ["openclaw", "plugins", "install", spec, "--force"],
+      UPGRADE_TIMEOUT_MS,
+    );
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    log.error(`plugin upgrade command failed to spawn: ${msg}`);
+    res.statusCode = 500;
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify({ error: "upgrade command failed", detail: msg }));
+    return true;
+  }
+
+  if (result.code !== 0) {
+    const stderrTail = (result.stderr ?? "").slice(-2000);
+    log.error(`plugin upgrade exited code=${result.code}: ${stderrTail}`);
+    res.statusCode = 500;
+    res.setHeader("Content-Type", "application/json");
+    res.end(
+      JSON.stringify({
+        error: "upgrade command exited non-zero",
+        code: result.code,
+        detail: stderrTail,
+      }),
+    );
+    return true;
+  }
+
+  log.info("Plugin upgrade install succeeded; scheduling gateway restart");
+
+  // Respond first so the app receives confirmation before the restart drops the
+  // connection, then trigger the safe restart after a short flush delay.
+  res.statusCode = 202;
+  res.setHeader("Content-Type", "application/json");
+  res.end(JSON.stringify({ status: "upgrading", from: PLUGIN_VERSION }));
+
+  setTimeout(() => {
+    void rt
+      .mutateConfigFile({
+        afterWrite: { mode: "restart", reason: "friday-next 插件自动升级后重启" },
+        mutate: () => {},
+      })
+      .catch((err: unknown) => {
+        const msg = err instanceof Error ? err.message : String(err);
+        log.error(`gateway restart trigger failed: ${msg}`);
+      });
+  }, RESTART_DELAY_MS).unref?.();
+
+  return true;
+}

package/src/http/handlers/sse.ts

@@ -4,6 +4,7 @@ import { getHostOpenClawConfigSnapshot } from "../../host-config.js";
 import { getFridayNextRuntime } from "../../runtime.js";
 import { sseEmitter } from "../../sse/emitter.js";
 import { extractBearerToken } from "../middleware/auth.js";
+import { PLUGIN_VERSION } from "../../version.js";
 
 function parseLastEventId(req: IncomingMessage, url: URL): number {
   const query = Number.parseInt(url.searchParams.get("lastEventId") ?? "", 10);
@@ -56,6 +57,7 @@ export async function handleSseStream(req: IncomingMessage, res: ServerResponse)
         deviceId: normalized,
         serverTime: Date.now(),
         lastSeq,
+        pluginVersion: PLUGIN_VERSION,
       },
     },
     deviceId,

package/src/http/handlers/status.ts

@@ -2,6 +2,7 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import { getActiveRunIds } from "../../agent/active-runs.js";
 import { sseEmitter } from "../../sse/emitter.js";
 import { extractBearerToken } from "../middleware/auth.js";
+import { PLUGIN_VERSION } from "../../version.js";
 
 export async function handleStatus(req: IncomingMessage, res: ServerResponse): Promise<boolean> {
   if (req.method !== "GET") {
@@ -24,6 +25,7 @@ export async function handleStatus(req: IncomingMessage, res: ServerResponse): P
       ok: true,
       channel: "friday-next",
       version: "v2",
+      pluginVersion: PLUGIN_VERSION,
       connections: sseEmitter.getConnectionCount(),
       activeRuns,
       activeRunCount: activeRuns.length,

package/src/http/server.ts

@@ -21,6 +21,8 @@ import { handleHistoryMessages } from "./handlers/history-messages.js";
 import { handleHistorySetTitle } from "./handlers/history-set-title.js";
 import { handleStatus } from "./handlers/status.js";
 import { handleHealth } from "./handlers/health.js";
+import { handlePluginInfo } from "./handlers/plugin-info.js";
+import { handlePluginUpgrade } from "./handlers/plugin-upgrade.js";
 import { applyCorsHeaders } from "./middleware/cors.js";
 import { resolveFridayNextConfig } from "../config.js";
 import { getHostOpenClawConfigSnapshot } from "../host-config.js";
@@ -109,6 +111,16 @@ async function handleFridayNextRoute(
     return await handleHealth(req, res);
   }
 
+  // Route: GET /friday-next/plugin/info (current/latest version + upgradability)
+  if (req.method === "GET" && pathname === "/friday-next/plugin/info") {
+    return await handlePluginInfo(req, res);
+  }
+
+  // Route: POST /friday-next/plugin/upgrade (npm install @latest + safe gateway restart)
+  if (req.method === "POST" && pathname === "/friday-next/plugin/upgrade") {
+    return await handlePluginUpgrade(req, res);
+  }
+
   // Not found
   return false;
 }

package/src/plugin-install-info.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import { semverGreater } from "./plugin-install-info.js";
+
+describe("semverGreater", () => {
+  it("returns true when a is a higher patch/minor/major", () => {
+    expect(semverGreater("0.1.27", "0.1.26")).toBe(true);
+    expect(semverGreater("0.2.0", "0.1.99")).toBe(true);
+    expect(semverGreater("1.0.0", "0.9.9")).toBe(true);
+  });
+
+  it("returns false when equal or lower", () => {
+    expect(semverGreater("0.1.27", "0.1.27")).toBe(false);
+    expect(semverGreater("0.1.26", "0.1.27")).toBe(false);
+    expect(semverGreater("0.1.0", "0.1.0")).toBe(false);
+  });
+
+  it("tolerates a leading v and pre-release/build suffixes", () => {
+    expect(semverGreater("v0.1.27", "0.1.26")).toBe(true);
+    expect(semverGreater("0.1.27-beta.1", "0.1.26")).toBe(true);
+    expect(semverGreater("0.1.27", "0.1.27-rc.1")).toBe(false);
+  });
+
+  it("returns false for null/undefined inputs", () => {
+    expect(semverGreater(null, "0.1.0")).toBe(false);
+    expect(semverGreater("0.1.0", null)).toBe(false);
+    expect(semverGreater(undefined, undefined)).toBe(false);
+  });
+});

package/src/plugin-install-info.ts

@@ -0,0 +1,95 @@
+/**
+ * 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";
+
+/** 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 function getInstallSource(): InstallSource {
+  const rt = getUpgradeRuntime();
+  if (!rt) return "unknown";
+  try {
+    const cfg = rt.currentConfig() as {
+      plugins?: { installs?: Record<string, { source?: string } | undefined> };
+    } | undefined;
+    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: string | null | undefined, b: string | null | undefined): boolean {
+  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: string): [number, number, number] {
+  // 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: { version: string | null; fetchedAt: number } | null = 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: number): Promise<string | null> {
+  if (cachedLatest && nowMs - cachedLatest.fetchedAt < LATEST_TTL_MS) {
+    return cachedLatest.version;
+  }
+  let version: string | null = 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()) as { version?: string };
+        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(): void {
+  cachedLatest = null;
+}