jishushell 0.4.10 → 0.4.24-beta.2

package/dist/services/agent-apps/installers/adapter-probes.js

@@ -0,0 +1,223 @@
+/**
+ * Probe functions used by `buildCardView` to populate an adapter-backed
+ * `AgentAppCardView` — install status, disk size, and update availability.
+ *
+ * The update probe is the expensive one (needs to reach the upstream
+ * registry) so it runs behind a stale-while-revalidate cache: callers see
+ * whatever is cached immediately, and a background refresh kicks off when
+ * the cache is stale. `forceRefreshAllAdapterUpdates` is the explicit
+ * "check updates now" path used by the UI button; it awaits in-flight
+ * refreshes instead of skipping them so the button's result reflects the
+ * newest state, not the value that was cached at click time.
+ */
+import { execFile } from "child_process";
+import { promisify } from "util";
+import { HERMES_DEFAULT_IMAGE, getOpenclawDockerImage, getRuntimeCatalogEntry, } from "../../../config.js";
+import { getAdapter, hasAdapter } from "../../runtime/index.js";
+import { fetchRemoteDigest, parseImageRef } from "./registry-probe.js";
+const execFileAsync = promisify(execFile);
+// ── Image resolution ────────────────────────────────────────────────────
+/**
+ * Resolve the docker image an adapter's instances currently run on. Prefers
+ * the installed record in panel.json.runtime_catalog; falls back to the
+ * adapter's declared default so update checks still work even when the app
+ * has been uninstalled (or was never installed through the new flow).
+ */
+export function resolveAdapterImage(agentType) {
+    if (agentType === "openclaw")
+        return getOpenclawDockerImage();
+    const entry = getRuntimeCatalogEntry(agentType);
+    const fromCatalog = entry?.defaultImage;
+    if (typeof fromCatalog === "string" && fromCatalog.trim())
+        return fromCatalog;
+    // Fallback: hardcoded defaults per adapter. Adapters that want to
+    // participate in update checks without a runtime_catalog entry (yet)
+    // advertise their default here.
+    if (agentType === "hermes")
+        return HERMES_DEFAULT_IMAGE;
+    return null;
+}
+// ── Status probe ────────────────────────────────────────────────────────
+export async function probeAdapterStatus(agentType) {
+    if (!hasAdapter(agentType))
+        return null;
+    const adapter = getAdapter(agentType);
+    if (!adapter.getInstallStatus)
+        return null;
+    try {
+        return (await Promise.race([
+            Promise.resolve(adapter.getInstallStatus()),
+            new Promise((_, reject) => setTimeout(() => reject(new Error("install-status probe timed out")), 2500)),
+        ]));
+    }
+    catch {
+        return null;
+    }
+}
+// ── Image size probe ────────────────────────────────────────────────────
+/**
+ * Read the disk size (MB, decimal) of the adapter's current docker image.
+ * Uses `docker image ls --format {{.Size}}` (same cumulative-layer total
+ * admins see in `docker images`) instead of `docker image inspect .Size`
+ * which reports dedup'd unique bytes and doesn't match operator
+ * expectation.
+ */
+export async function probeAdapterImageSizeMB(agentType) {
+    const image = resolveAdapterImage(agentType);
+    if (!image)
+        return null;
+    try {
+        const { stdout } = await execFileAsync("docker", ["image", "ls", "--format", "{{.Size}}", image], { timeout: 2500, encoding: "utf-8" });
+        const firstLine = stdout.split("\n")[0]?.trim();
+        if (!firstLine)
+            return null;
+        return parseDockerSizeToMB(firstLine);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Parse docker's human-readable size strings ("2.26GB", "593MB", "12.5kB")
+ * into megabytes. Docker uses decimal (SI) units for these displays.
+ */
+function parseDockerSizeToMB(raw) {
+    const m = raw.trim().match(/^(\d+(?:\.\d+)?)\s*(B|kB|MB|GB|TB)$/i);
+    if (!m)
+        return null;
+    const value = parseFloat(m[1]);
+    if (!Number.isFinite(value))
+        return null;
+    const unit = m[2].toLowerCase();
+    const mb = unit === "b" ? value / 1_000_000 :
+        unit === "kb" ? value / 1_000 :
+            unit === "mb" ? value :
+                unit === "gb" ? value * 1_000 :
+                    unit === "tb" ? value * 1_000_000 : NaN;
+    return Number.isFinite(mb) ? Math.round(mb) : null;
+}
+const updateCache = new Map();
+const UPDATE_CACHE_TTL_OK_MS = 10 * 60 * 1000;
+const UPDATE_CACHE_TTL_NULL_MS = 60 * 1000;
+/**
+ * Read the local RepoDigest sha for the given image — this is what docker
+ * recorded when it pulled the tag (the manifest-list's digest for
+ * multi-arch images), so it lines up with what the registry HEAD returns.
+ */
+async function readLocalDigest(image) {
+    try {
+        const { stdout } = await execFileAsync("docker", ["image", "inspect", "--format", "{{range .RepoDigests}}{{.}}{{println}}{{end}}", image], { timeout: 5_000, encoding: "utf-8" });
+        const line = stdout.split("\n").find((l) => l.includes("@sha256:"));
+        const m = line?.match(/@sha256:([a-f0-9]{64})/);
+        return m ? m[1] : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function readRemoteDigest(image) {
+    const ref = parseImageRef(image);
+    if (!ref)
+        return null;
+    return fetchRemoteDigest(ref);
+}
+/**
+ * Refresh the update-cache entry for one agentType. Safe to call while a
+ * refresh is already in flight — the second caller awaits the same
+ * promise instead of starting a duplicate probe.
+ */
+function refreshUpdateCache(agentType, image) {
+    const cached = updateCache.get(agentType);
+    if (cached?.inflight)
+        return cached.inflight;
+    const t0 = Date.now();
+    console.log(`[agent-apps] ${agentType}: probing digest for ${image}`);
+    const inflight = (async () => {
+        try {
+            const [local, remote] = await Promise.all([
+                readLocalDigest(image),
+                readRemoteDigest(image),
+            ]);
+            const value = !local || !remote ? null : local !== remote;
+            console.log(`[agent-apps] ${agentType}: local=${local?.slice(0, 12) ?? "null"} ` +
+                `remote=${remote?.slice(0, 12) ?? "null"} result=${value} (+${Date.now() - t0}ms)`);
+            updateCache.set(agentType, { value, at: Date.now() });
+        }
+        catch (e) {
+            console.log(`[agent-apps] ${agentType}: probe error ${e?.message || e} (+${Date.now() - t0}ms)`);
+            updateCache.set(agentType, { value: null, at: Date.now() });
+        }
+    })();
+    updateCache.set(agentType, {
+        value: cached?.value ?? null,
+        at: cached?.at ?? 0,
+        inflight,
+    });
+    // When the async IIFE above writes the final value, the new entry will
+    // not carry `inflight`, so subsequent calls will see the fresh state.
+    inflight.finally(() => {
+        const final = updateCache.get(agentType);
+        if (final?.inflight === inflight) {
+            updateCache.set(agentType, { value: final.value, at: final.at });
+        }
+    });
+    return inflight;
+}
+/**
+ * Lazy background probe: returns whatever is currently cached, and kicks
+ * off a refresh in the background if the cache is stale. First cold call
+ * returns `null`; the next catalog poll after the refresh lands will flip
+ * to the real value.
+ */
+export async function probeAdapterUpdateAvailable(agentType) {
+    const image = resolveAdapterImage(agentType);
+    if (!image)
+        return null;
+    const cached = updateCache.get(agentType);
+    const now = Date.now();
+    const ttl = cached?.value == null ? UPDATE_CACHE_TTL_NULL_MS : UPDATE_CACHE_TTL_OK_MS;
+    const stale = !cached || now - cached.at > ttl;
+    if (stale && !cached?.inflight) {
+        refreshUpdateCache(agentType, image).catch(() => {
+            // swallowed — refreshUpdateCache writes a null entry on its own
+        });
+    }
+    return cached?.value ?? null;
+}
+/** Timestamp (ms since epoch) when the freshest cached probe completed. */
+export function getUpdateCacheLastCheckedAt() {
+    let latest = 0;
+    for (const entry of updateCache.values()) {
+        if (entry.at > latest)
+            latest = entry.at;
+    }
+    return latest > 0 ? latest : null;
+}
+/**
+ * Explicit "check updates now" path — backs `POST /api/agent-apps/check-
+ * updates`. Bypasses the TTL entirely: if a refresh is already running it
+ * awaits it instead of skipping (so the response carries the newest value,
+ * not a stale cached null). Runs all targets in parallel.
+ */
+export async function forceRefreshAllAdapterUpdates(agentTypes) {
+    const targets = [];
+    for (const agentType of agentTypes) {
+        const image = resolveAdapterImage(agentType);
+        if (image)
+            targets.push({ agentType, image });
+    }
+    await Promise.all(targets.map(({ agentType, image }) => {
+        const cached = updateCache.get(agentType);
+        // Already refreshing → wait for it. Otherwise start a fresh probe
+        // even if the TTL hasn't expired (user explicitly asked for a check).
+        if (cached?.inflight)
+            return cached.inflight;
+        return refreshUpdateCache(agentType, image);
+    }));
+    const out = {};
+    for (const { agentType } of targets) {
+        out[agentType] = updateCache.get(agentType)?.value ?? null;
+    }
+    return out;
+}
+//# sourceMappingURL=adapter-probes.js.map

package/dist/services/agent-apps/installers/adapter-probes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-probes.js","sourceRoot":"","sources":["../../../../src/services/agent-apps/installers/adapter-probes.ts"],"names":[],"mappings":"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"}

package/dist/services/agent-apps/installers/adapter.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Installer strategy for adapter-backed agent apps (hermes, openclaw).
+ *
+ * Delegates install to `adapter.startBuildRuntimeImage` (preferred when
+ * present — openclaw builds its image locally) or
+ * `adapter.startInstallRuntime` (hermes pulls from GHCR). Uninstall runs
+ * locally here (docker image rm + clear runtime_catalog + drop shim).
+ *
+ * Probe + cache logic lives in `adapter-probes.ts`; this file re-exports
+ * the probes so callers import one entry point.
+ */
+import type { InstallStartResult } from "../types.js";
+export { forceRefreshAllAdapterUpdates, getUpdateCacheLastCheckedAt, probeAdapterImageSizeMB, probeAdapterStatus, probeAdapterUpdateAvailable, resolveAdapterImage, } from "./adapter-probes.js";
+export declare function startAdapterInstall(agentType: string, options?: Record<string, any>): Promise<InstallStartResult>;
+export declare function startAdapterUninstall(agentType: string): InstallStartResult;
+/**
+ * Current running task for this agentType. Returns both the id and the
+ * kind so the UI can render "安装中" vs "卸载中" from one field instead
+ * of having to guess from task name shape.
+ *
+ * Install tasks match by prefix (`openclaw`, `openclaw-docker-pull`,
+ * `hermes`). Uninstall tasks use the disjoint `uninstall-${agentType}`
+ * name so no prefix collision is possible.
+ */
+export declare function findRunningAdapterTask(agentType: string): {
+    id: string;
+    kind: "install" | "uninstall";
+} | undefined;
+/** Count live instances bound to this agentType — used to block uninstall. */
+export declare function countInstancesUsingAgentType(agentType: string): number;

package/dist/services/agent-apps/installers/adapter.js

@@ -0,0 +1,171 @@
+/**
+ * Installer strategy for adapter-backed agent apps (hermes, openclaw).
+ *
+ * Delegates install to `adapter.startBuildRuntimeImage` (preferred when
+ * present — openclaw builds its image locally) or
+ * `adapter.startInstallRuntime` (hermes pulls from GHCR). Uninstall runs
+ * locally here (docker image rm + clear runtime_catalog + drop shim).
+ *
+ * Probe + cache logic lives in `adapter-probes.ts`; this file re-exports
+ * the probes so callers import one entry point.
+ */
+import { execFile } from "child_process";
+import { existsSync, rmSync } from "fs";
+import { promisify } from "util";
+import { HERMES_RUNTIME_DIR, getPanelConfig, savePanelConfig, } from "../../../config.js";
+import { listInstances } from "../../app/app-manager.js";
+import { getAdapter, hasAdapter, resolveAgentType } from "../../runtime/index.js";
+import { createTask, emitTask, getRunningTasks, } from "../../task-registry.js";
+import { resolveAdapterImage } from "./adapter-probes.js";
+const execFileAsync = promisify(execFile);
+export { forceRefreshAllAdapterUpdates, getUpdateCacheLastCheckedAt, probeAdapterImageSizeMB, probeAdapterStatus, probeAdapterUpdateAvailable, resolveAdapterImage, } from "./adapter-probes.js";
+// ── Dispatch: install ───────────────────────────────────────────────────
+export async function startAdapterInstall(agentType, options = {}) {
+    if (!hasAdapter(agentType)) {
+        return { ok: false, error: `Unknown agentType "${agentType}"` };
+    }
+    // Reject install while uninstall is running — they are destructive of
+    // each other. Names are disjoint (`uninstall-${agentType}` vs
+    // `${agentType}` / `${agentType}-*`), so this check can't match an
+    // install task.
+    if (getRunningTasks(`uninstall-${agentType}`).length > 0) {
+        return {
+            ok: false,
+            error: `${agentType} 正在卸载，请等待卸载完成后再安装`,
+        };
+    }
+    // Dedup: if a task for this agent is already running (Setup wizard, or
+    // the user clicked install twice), join it instead of starting a second.
+    // Adapters use prefix-based names (`openclaw`, `openclaw-docker-pull`,
+    // `hermes`), so a prefix match matches install variants but — by design
+    // — cannot match `uninstall-${agentType}`.
+    const existing = getRunningTasks(agentType);
+    if (existing.length > 0) {
+        return {
+            ok: true,
+            taskId: existing[0].id,
+            reused: true,
+            message: `${agentType} install already in progress`,
+        };
+    }
+    const adapter = getAdapter(agentType);
+    let result;
+    if (typeof adapter.startBuildRuntimeImage === "function") {
+        result = await adapter.startBuildRuntimeImage(options);
+    }
+    else if (typeof adapter.startInstallRuntime === "function") {
+        result = adapter.startInstallRuntime(options);
+    }
+    else {
+        return { ok: false, error: `Runtime "${agentType}" does not implement install` };
+    }
+    if (result && typeof result === "object") {
+        return {
+            ok: result.ok !== false,
+            taskId: result.taskId,
+            message: result.message,
+            error: result.ok === false ? (result.error || result.message) : undefined,
+        };
+    }
+    return { ok: false, error: "Adapter returned an unexpected install result" };
+}
+// ── Dispatch: uninstall ─────────────────────────────────────────────────
+export function startAdapterUninstall(agentType) {
+    if (!hasAdapter(agentType)) {
+        return { ok: false, error: `Unknown agentType "${agentType}"` };
+    }
+    // Reject uninstall while install/update is in flight — we don't want to
+    // yank the docker image out from under a running docker pull.
+    if (getRunningTasks(agentType).length > 0) {
+        return {
+            ok: false,
+            error: `${agentType} 正在安装/更新，请等待完成后再卸载`,
+        };
+    }
+    // Uninstall dedup: second uninstall clicks within the window join nothing
+    // — we just tell the user it's already running.
+    if (getRunningTasks(`uninstall-${agentType}`).length > 0) {
+        return {
+            ok: false,
+            error: `${agentType} 卸载已在进行中`,
+        };
+    }
+    const image = resolveAdapterImage(agentType);
+    const task = createTask(`uninstall-${agentType}`);
+    (async () => {
+        try {
+            emitTask(task, { type: "progress", message: `准备卸载 ${agentType}...`, progress: 0 });
+            if (image) {
+                emitTask(task, { type: "progress", message: `删除 docker 镜像: ${image}`, progress: 30 });
+                try {
+                    await execFileAsync("docker", ["image", "rm", "-f", image], {
+                        timeout: 30_000, encoding: "utf-8",
+                    });
+                    emitTask(task, { type: "log", message: "docker image rm 成功" });
+                }
+                catch (e) {
+                    emitTask(task, {
+                        type: "log",
+                        message: `docker image rm 失败（可能镜像不存在）: ${e.message || e}`,
+                    });
+                }
+            }
+            else {
+                emitTask(task, { type: "log", message: "未找到镜像引用，跳过 docker image rm" });
+            }
+            emitTask(task, { type: "progress", message: "清理 runtime_catalog...", progress: 70 });
+            const config = getPanelConfig();
+            if (config.runtime_catalog && typeof config.runtime_catalog === "object") {
+                delete config.runtime_catalog[agentType];
+                savePanelConfig(config);
+            }
+            if (agentType === "hermes") {
+                emitTask(task, { type: "progress", message: "清理 Hermes shim 目录...", progress: 85 });
+                try {
+                    if (existsSync(HERMES_RUNTIME_DIR)) {
+                        rmSync(HERMES_RUNTIME_DIR, { recursive: true, force: true });
+                    }
+                }
+                catch (e) {
+                    emitTask(task, { type: "log", message: `shim 目录清理失败: ${e.message || e}` });
+                }
+            }
+            emitTask(task, { type: "done", message: `${agentType} 卸载完成`, progress: 100 });
+            task.status = "done";
+        }
+        catch (e) {
+            emitTask(task, { type: "error", message: `卸载失败: ${e?.message || e}` });
+            task.status = "error";
+        }
+    })();
+    return { ok: true, taskId: task.id };
+}
+// ── Helpers consumed by routes/index layer ──────────────────────────────
+/**
+ * Current running task for this agentType. Returns both the id and the
+ * kind so the UI can render "安装中" vs "卸载中" from one field instead
+ * of having to guess from task name shape.
+ *
+ * Install tasks match by prefix (`openclaw`, `openclaw-docker-pull`,
+ * `hermes`). Uninstall tasks use the disjoint `uninstall-${agentType}`
+ * name so no prefix collision is possible.
+ */
+export function findRunningAdapterTask(agentType) {
+    const install = getRunningTasks(agentType)[0];
+    if (install)
+        return { id: install.id, kind: "install" };
+    const uninstall = getRunningTasks(`uninstall-${agentType}`)[0];
+    if (uninstall)
+        return { id: uninstall.id, kind: "uninstall" };
+    return undefined;
+}
+/** Count live instances bound to this agentType — used to block uninstall. */
+export function countInstancesUsingAgentType(agentType) {
+    let count = 0;
+    for (const meta of listInstances()) {
+        if (resolveAgentType(meta) === agentType)
+            count += 1;
+    }
+    return count;
+}
+//# sourceMappingURL=adapter.js.map

package/dist/services/agent-apps/installers/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../../../src/services/agent-apps/installers/adapter.ts"],"names":[],"mappings":"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"}

package/dist/services/agent-apps/installers/registry-probe.d.ts

@@ -0,0 +1,38 @@
+/**
+ * OCI / Docker Registry v2 digest lookups via curl.
+ *
+ * We shell out to curl instead of using Node's built-in `fetch` because:
+ *   - Node's fetch (undici) ships a 10 s TCP connect timeout that isn't
+ *     configurable without pulling undici in as a direct dep, and the TLS
+ *     handshake to ghcr.io from edge devices on slow international links
+ *     routinely exceeds that (9–15 s measured from a Pi in mainland China).
+ *   - curl's `--max-time` is wall-clock and reliable.
+ *   - curl is already present on every target platform.
+ *
+ * The call chain implements the standard OCI distribution bearer-token flow:
+ *   1. GET  <realm>?service=...&scope=...            → bearer token
+ *   2. HEAD /v2/<repository>/manifests/<reference>   → docker-content-digest
+ *
+ * Well-known public registries (GHCR, Docker Hub, Quay) always require a
+ * token, so we skip the throwaway unauthenticated probe for them — that
+ * alone saves ~10 s per image on slow WAN links.
+ */
+export interface ImageRef {
+    registry: string;
+    repository: string;
+    reference: string;
+}
+/**
+ * Parse a docker image reference into `{ registry, repository, reference }`.
+ * Handles: "ghcr.io/owner/name:tag", "owner/name:tag" (defaults to Docker
+ * Hub), "name" (defaults to "library/<name>:latest"). Returns null for
+ * digest-pinned refs (no lookup is needed) or malformed strings.
+ */
+export declare function parseImageRef(image: string): ImageRef | null;
+/**
+ * Fetch the current remote digest (sha256 hex, without the "sha256:" prefix)
+ * for a fully-resolved image reference. Returns null when the registry is
+ * unreachable, the image is private without an auth token we can obtain, or
+ * any other probe failure.
+ */
+export declare function fetchRemoteDigest(ref: ImageRef): Promise<string | null>;