@syengup/friday-channel-next 0.1.26 → 0.1.27

package/dist/index.js

@@ -8,6 +8,7 @@ import { getFridayNextRuntime } from "./src/runtime.js";
 import { sseEmitter } from "./src/sse/emitter.js";
 import { forwardAgentEventRaw, getLastRegisteredFridayDeviceId, resolveFridayDeviceIdForSessionKey, } from "./src/friday-session.js";
 import { setFridayAgentForwardRuntime } from "./src/agent-forward-runtime.js";
+import { setUpgradeRuntime } from "./src/upgrade-runtime.js";
 import { getOpenClawAgentRunContext } from "./src/agent-run-context-bridge.js";
 import { accumulateRunUsage } from "./src/agent/run-usage-accumulator.js";
 import { createFridayNextLogger } from "./src/logging.js";
@@ -78,6 +79,7 @@ export default defineChannelPluginEntry({
     setRuntime: setFridayNextRuntime,
     registerFull: (api) => {
         setFridayAgentForwardRuntime(api);
+        setUpgradeRuntime(api);
         const sameApi = lastApiRoutesRegistered?.deref() === api;
         if (!sameApi) {
             lastApiRoutesRegistered = new WeakRef(api);

package/dist/src/http/handlers/health.d.ts

@@ -15,6 +15,7 @@ export interface HealthCheckResult {
     timestamp: number;
     deviceId: string;
     nodeDeviceId: string;
+    pluginVersion: string;
     nodePairing?: HealthComponentStatus;
     repairActions?: RepairAction[];
 }

package/dist/src/http/handlers/health.js

@@ -1,6 +1,7 @@
 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 = [
     "location.get",
@@ -36,6 +37,7 @@ export async function handleHealth(req, res) {
         timestamp: Date.now(),
         deviceId,
         nodeDeviceId,
+        pluginVersion: PLUGIN_VERSION,
     };
     const log = createFridayNextLogger("health");
     if (nodeDeviceId) {

package/dist/src/http/handlers/messages.d.ts

@@ -47,4 +47,9 @@ export interface FridayMessagePayload {
     reasoningLevel?: string;
     thinkingLevel?: string;
 }
+/**
+ * 把可选文本与媒体引用拼成给 agent 的最终 body。纯附件（文本为空）场景下
+ * 不能带前导空行，否则 agent 收到的是 `\n\n[media…]`——故拆成可测纯函数。
+ */
+export declare function composeBodyWithMediaRefs(text: string, mediaRefs: string[]): string;
 export declare function handleMessages(req: IncomingMessage, res: ServerResponse): Promise<boolean>;

package/dist/src/http/handlers/messages.js

@@ -262,6 +262,16 @@ async function resolveRunMetadataFromRuntimeSession(runtime, sessionKey) {
     }
     return null;
 }
+/**
+ * 把可选文本与媒体引用拼成给 agent 的最终 body。纯附件（文本为空）场景下
+ * 不能带前导空行，否则 agent 收到的是 `\n\n[media…]`——故拆成可测纯函数。
+ */
+export function composeBodyWithMediaRefs(text, mediaRefs) {
+    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, attachmentIds) {
     if (attachmentIds.length === 0)
         return text.trim();
@@ -275,9 +285,7 @@ async function buildBodyForAgentWithAttachments(text, attachmentIds) {
             mediaRefs.push(`[media attached: file://${saved.path}]`);
         }
     }
-    if (mediaRefs.length === 0)
-        return text.trim();
-    return `${text.trim()}\n\n${mediaRefs.join("\n")}`;
+    return composeBodyWithMediaRefs(text, mediaRefs);
 }
 export async function handleMessages(req, res) {
     if (req.method !== "POST") {
@@ -320,14 +328,17 @@ export async function handleMessages(req, res) {
         res.end(JSON.stringify({ error: "Missing required field: deviceId" }));
         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("/");
     const runId = crypto.randomUUID();
@@ -363,7 +374,7 @@ export async function handleMessages(req, res) {
     registerFridaySessionDeviceMapping(appSessionKey, normalizedDeviceId);
     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,
         BodyForAgent: bodyForAgent,

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

@@ -0,0 +1,11 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+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 declare function handlePluginInfo(req: IncomingMessage, res: ServerResponse): Promise<boolean>;

package/dist/src/http/handlers/plugin-info.js

@@ -0,0 +1,32 @@
+import { extractBearerToken } from "../middleware/auth.js";
+import { PLUGIN_VERSION } from "../../version.js";
+import { fetchLatestVersion, getInstallSource, semverGreater, } from "../../plugin-install-info.js";
+export async function handlePluginInfo(req, res) {
+    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 = {
+        currentVersion: PLUGIN_VERSION,
+        latestVersion,
+        installSource,
+        canAutoUpgrade,
+        upgradable,
+    };
+    res.statusCode = 200;
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify(result));
+    return true;
+}

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

@@ -0,0 +1,11 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+/**
+ * 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 declare function handlePluginUpgrade(req: IncomingMessage, res: ServerResponse): Promise<boolean>;

package/dist/src/http/handlers/plugin-upgrade.js

@@ -0,0 +1,94 @@
+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, res) {
+    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) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            log.error(`gateway restart trigger failed: ${msg}`);
+        });
+    }, RESTART_DELAY_MS).unref?.();
+    return true;
+}

package/dist/src/http/handlers/sse.js

@@ -3,6 +3,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, url) {
     const query = Number.parseInt(url.searchParams.get("lastEventId") ?? "", 10);
     if (Number.isFinite(query))
@@ -48,6 +49,7 @@ export async function handleSseStream(req, res) {
             deviceId: normalized,
             serverTime: Date.now(),
             lastSeq,
+            pluginVersion: PLUGIN_VERSION,
         },
     }, deviceId, true);
     const lastEventId = parseLastEventId(req, url);

package/dist/src/http/handlers/status.js

@@ -1,6 +1,7 @@
 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, res) {
     if (req.method !== "GET") {
         res.statusCode = 405;
@@ -21,6 +22,7 @@ export async function handleStatus(req, res) {
         ok: true,
         channel: "friday-next",
         version: "v2",
+        pluginVersion: PLUGIN_VERSION,
         connections: sseEmitter.getConnectionCount(),
         activeRuns,
         activeRunCount: activeRuns.length,

package/dist/src/http/server.js

@@ -19,6 +19,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";
@@ -87,6 +89,14 @@ async function handleFridayNextRoute(req, res) {
     if (req.method === "GET" && pathname === "/friday-next/health") {
         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/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;
+}

package/dist/src/version.d.ts

@@ -0,0 +1,5 @@
+export declare const PLUGIN_VERSION: string;
+/** npm package name, used for the upgrade spec and registry lookup. */
+export declare const PLUGIN_PACKAGE_NAME = "@syengup/friday-channel-next";
+/** Plugin id as registered with OpenClaw (used to read the install record). */
+export declare const PLUGIN_ID = "friday-next";

package/dist/src/version.js

@@ -0,0 +1,37 @@
+/**
+ * Plugin self-version.
+ *
+ * Resolved at module load by reading this package's own package.json relative to
+ * the compiled module URL. `tsc` does NOT copy package.json into `dist/`, and a
+ * JSON `import` would rewrite to a non-existent `dist/package.json`, so we read
+ * the real file from disk and walk a couple of candidate paths. Falls back to a
+ * hardcoded constant if the file can't be located (keep in sync with package.json).
+ */
+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";
+function resolvePluginVersion() {
+    // dist layout: <root>/dist/src/version.js → ../../package.json = <root>/package.json
+    // source layout (vitest/jiti): <root>/src/version.ts → ../package.json = <root>/package.json
+    const candidates = ["../../package.json", "../package.json"];
+    for (const rel of candidates) {
+        try {
+            const path = fileURLToPath(new URL(rel, import.meta.url));
+            const raw = readFileSync(path, "utf8");
+            const pkg = JSON.parse(raw);
+            if (pkg.name === "@syengup/friday-channel-next" && typeof pkg.version === "string" && pkg.version) {
+                return pkg.version;
+            }
+        }
+        catch {
+            // try next candidate
+        }
+    }
+    return FALLBACK_VERSION;
+}
+export const PLUGIN_VERSION = resolvePluginVersion();
+/** npm package name, used for the upgrade spec and registry lookup. */
+export const PLUGIN_PACKAGE_NAME = "@syengup/friday-channel-next";
+/** Plugin id as registered with OpenClaw (used to read the install record). */
+export const PLUGIN_ID = "friday-next";

package/index.ts

@@ -15,6 +15,7 @@ import {
   resolveFridayDeviceIdForSessionKey,
 } from "./src/friday-session.js";
 import { setFridayAgentForwardRuntime } from "./src/agent-forward-runtime.js";
+import { setUpgradeRuntime } from "./src/upgrade-runtime.js";
 import { getOpenClawAgentRunContext } from "./src/agent-run-context-bridge.js";
 import { accumulateRunUsage } from "./src/agent/run-usage-accumulator.js";
 import { createFridayNextLogger } from "./src/logging.js";
@@ -86,6 +87,7 @@ export default defineChannelPluginEntry({
   setRuntime: setFridayNextRuntime,
   registerFull: (api: OpenClawPluginApi) => {
     setFridayAgentForwardRuntime(api);
+    setUpgradeRuntime(api);
     const sameApi = lastApiRoutesRegistered?.deref() === api;
     if (!sameApi) {
       lastApiRoutesRegistered = new WeakRef(api);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syengup/friday-channel-next",
-  "version": "0.1.26",
+  "version": "0.1.27",
   "description": "OpenClaw Friday Next Apple channel plugin",
   "license": "MIT",
   "type": "module",

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/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;
+}

package/src/upgrade-runtime.ts

@@ -0,0 +1,69 @@
+/**
+ * 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>;
+};
+
+let upgradeRuntime: UpgradeRuntime | null = null;
+
+export function setUpgradeRuntime(api: OpenClawPluginApi): void {
+  const runtime = api.runtime as unknown as {
+    system?: { runCommandWithTimeout?: (argv: string[], opts: unknown) => Promise<SpawnResultLike> };
+    config: {
+      current: () => unknown;
+      mutateConfigFile?: (params: unknown) => Promise<unknown>;
+    };
+  };
+
+  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(): UpgradeRuntime | null {
+  return upgradeRuntime;
+}
+
+/** Vitest-only */
+export function resetUpgradeRuntimeForTest(): void {
+  upgradeRuntime = null;
+}

package/src/version.ts

@@ -0,0 +1,41 @@
+/**
+ * Plugin self-version.
+ *
+ * Resolved at module load by reading this package's own package.json relative to
+ * the compiled module URL. `tsc` does NOT copy package.json into `dist/`, and a
+ * JSON `import` would rewrite to a non-existent `dist/package.json`, so we read
+ * the real file from disk and walk a couple of candidate paths. Falls back to a
+ * hardcoded constant if the file can't be located (keep in sync with package.json).
+ */
+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";
+
+function resolvePluginVersion(): string {
+  // dist layout: <root>/dist/src/version.js → ../../package.json = <root>/package.json
+  // source layout (vitest/jiti): <root>/src/version.ts → ../package.json = <root>/package.json
+  const candidates = ["../../package.json", "../package.json"];
+  for (const rel of candidates) {
+    try {
+      const path = fileURLToPath(new URL(rel, import.meta.url));
+      const raw = readFileSync(path, "utf8");
+      const pkg = JSON.parse(raw) as { name?: string; version?: string };
+      if (pkg.name === "@syengup/friday-channel-next" && typeof pkg.version === "string" && pkg.version) {
+        return pkg.version;
+      }
+    } catch {
+      // try next candidate
+    }
+  }
+  return FALLBACK_VERSION;
+}
+
+export const PLUGIN_VERSION: string = resolvePluginVersion();
+
+/** npm package name, used for the upgrade spec and registry lookup. */
+export const PLUGIN_PACKAGE_NAME = "@syengup/friday-channel-next";
+
+/** Plugin id as registered with OpenClaw (used to read the install record). */
+export const PLUGIN_ID = "friday-next";