jishushell 0.4.10 → 0.4.24-beta.2

package/dist/services/update-manager.d.ts

@@ -0,0 +1,47 @@
+/**
+ * src/services/update-manager.ts
+ *
+ * Version checking and package upgrade — no console.log, returns data.
+ * Both the CLI and the HTTP API can safely call these functions.
+ */
+export interface UpdateInfo {
+    hasUpdate: boolean;
+    currentVersion: string;
+    latestVersion: string;
+}
+export type UpdateRuntimeState = "idle" | "running" | "restarting" | "completed" | "failed";
+export interface UpdateStatusSnapshot {
+    status: UpdateRuntimeState;
+    currentVersion: string;
+    installedVersion: string;
+    targetVersion?: string;
+    startedAt?: number;
+    updatedAt?: number;
+    message?: string;
+    error?: string;
+    inProgress: boolean;
+}
+export declare function compareVersions(a: string, b: string): number;
+export declare function isVersionAtLeast(version: string, expected: string): boolean;
+export declare function getInstalledGlobalVersion(): string;
+export declare function markUpdateRestarting(targetVersion: string, currentVersion: string, installedVersion: string): void;
+export declare function markUpdateFailed(error: string, currentVersion?: string): void;
+export declare function startBackgroundUpgrade(info: UpdateInfo): UpdateStatusSnapshot;
+export declare function getUpdateStatus(): UpdateStatusSnapshot;
+/**
+ * Check for a newer jishushell version on npm.
+ * Caches for 30 s; safe to call from both CLI and HTTP routes.
+ */
+export declare function checkUpdate(): Promise<UpdateInfo>;
+/**
+ * Run `npm install -g jishushell`.
+ * Throws on failure; returns trimmed npm stdout on success.
+ */
+export declare function upgradePackage(): Promise<{
+    output: string;
+}>;
+/**
+ * Spawn a detached `jishushell restart` after `delayMs` ms, then return.
+ * The spawned child outlives the current process (useful after upgrade).
+ */
+export declare function scheduleRestart(delayMs?: number): void;

package/dist/services/update-manager.js

@@ -0,0 +1,305 @@
+/**
+ * src/services/update-manager.ts
+ *
+ * Version checking and package upgrade — no console.log, returns data.
+ * Both the CLI and the HTTP API can safely call these functions.
+ */
+import { execFileSync, spawn } from "child_process";
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import * as http from "http";
+import * as https from "https";
+import { getPanelConfig, JISHUSHELL_HOME } from "../config.js";
+import { checkAndReport, checkAndReportHeartbeat } from "./telemetry/index.js";
+const __filename = fileURLToPath(import.meta.url);
+// services/ is one level below root; cli.js lives at ../../cli.js from dist/services/
+const CLI_PATH = join(dirname(__filename), "../cli.js");
+const UPDATE_STATE_FILE = join(JISHUSHELL_HOME, "update-state.json");
+const UPDATE_RESTART_TIMEOUT_MS = 5 * 60_000;
+// ── Internal helpers ───────────────────────────────────────────────────────
+let _updateCache = null;
+const UPDATE_CACHE_TTL = 30_000;
+function getNpmBinPath() {
+    return join(dirname(process.execPath), "npm");
+}
+function getCurrentPackageVersion() {
+    try {
+        const pkgPath = join(dirname(fileURLToPath(import.meta.url)), "../../package.json");
+        return JSON.parse(readFileSync(pkgPath, "utf-8")).version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+function parseVersion(version) {
+    const [major = 0, minor = 0, patch = 0] = version
+        .replace(/^v/, "")
+        .split(".")
+        .map((part) => parseInt(part, 10) || 0);
+    return [major, minor, patch];
+}
+export function compareVersions(a, b) {
+    const [aMaj, aMin, aPat] = parseVersion(a);
+    const [bMaj, bMin, bPat] = parseVersion(b);
+    if (aMaj !== bMaj)
+        return aMaj - bMaj;
+    if (aMin !== bMin)
+        return aMin - bMin;
+    return aPat - bPat;
+}
+export function isVersionAtLeast(version, expected) {
+    return compareVersions(version, expected) >= 0;
+}
+function readPersistedUpdateState() {
+    if (!existsSync(UPDATE_STATE_FILE))
+        return null;
+    try {
+        return JSON.parse(readFileSync(UPDATE_STATE_FILE, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+function writePersistedUpdateState(state) {
+    writeFileSync(UPDATE_STATE_FILE, `${JSON.stringify(state, null, 2)}\n`, "utf-8");
+}
+export function getInstalledGlobalVersion() {
+    try {
+        const npmRoot = execFileSync(getNpmBinPath(), ["root", "-g"], {
+            encoding: "utf-8",
+            timeout: 5000,
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        if (!npmRoot)
+            return getCurrentPackageVersion();
+        const pkgPath = join(npmRoot, "jishushell", "package.json");
+        if (!existsSync(pkgPath))
+            return getCurrentPackageVersion();
+        return JSON.parse(readFileSync(pkgPath, "utf-8")).version ?? getCurrentPackageVersion();
+    }
+    catch {
+        return getCurrentPackageVersion();
+    }
+}
+export function markUpdateRestarting(targetVersion, currentVersion, installedVersion) {
+    const previous = readPersistedUpdateState();
+    writePersistedUpdateState({
+        status: "restarting",
+        currentVersion,
+        targetVersion,
+        installedVersion,
+        startedAt: previous?.startedAt ?? Date.now(),
+        updatedAt: Date.now(),
+        message: `Updated to ${installedVersion}; waiting for panel restart`,
+    });
+}
+export function markUpdateFailed(error, currentVersion = getCurrentPackageVersion()) {
+    const previous = readPersistedUpdateState();
+    writePersistedUpdateState({
+        status: "failed",
+        currentVersion,
+        targetVersion: previous?.targetVersion,
+        installedVersion: getInstalledGlobalVersion(),
+        startedAt: previous?.startedAt ?? Date.now(),
+        updatedAt: Date.now(),
+        message: "Update failed",
+        error,
+    });
+}
+export function startBackgroundUpgrade(info) {
+    const status = getUpdateStatus();
+    if (status.inProgress) {
+        throw new Error("Update already in progress");
+    }
+    writePersistedUpdateState({
+        status: "running",
+        currentVersion: info.currentVersion,
+        targetVersion: info.latestVersion,
+        installedVersion: getInstalledGlobalVersion(),
+        startedAt: Date.now(),
+        updatedAt: Date.now(),
+        message: `Updating JishuShell to ${info.latestVersion}`,
+    });
+    const nodeBinDir = dirname(process.execPath);
+    const childEnv = {
+        ...process.env,
+        PATH: `${nodeBinDir}${process.env.PATH ? `:${process.env.PATH}` : ""}`,
+        JISHUSHELL_WEB_UPDATE: "1",
+        JISHUSHELL_UPDATE_CURRENT_VERSION: info.currentVersion,
+        JISHUSHELL_UPDATE_TARGET_VERSION: info.latestVersion,
+    };
+    try {
+        const child = spawn(process.execPath, [CLI_PATH, "update"], {
+            detached: true,
+            stdio: "ignore",
+            env: childEnv,
+        });
+        child.unref();
+    }
+    catch (err) {
+        markUpdateFailed(err.message || "Failed to start update worker", info.currentVersion);
+        throw err;
+    }
+    return getUpdateStatus();
+}
+export function getUpdateStatus() {
+    const currentVersion = getCurrentPackageVersion();
+    const installedVersion = getInstalledGlobalVersion();
+    let state = readPersistedUpdateState();
+    if (state?.status === "running" && state.targetVersion && isVersionAtLeast(installedVersion, state.targetVersion)) {
+        state = {
+            ...state,
+            status: "restarting",
+            installedVersion,
+            updatedAt: Date.now(),
+            message: `Updated to ${installedVersion}; waiting for panel restart`,
+        };
+        writePersistedUpdateState(state);
+    }
+    if (state?.status === "restarting" && state.targetVersion) {
+        if (currentVersion === installedVersion && isVersionAtLeast(installedVersion, state.targetVersion)) {
+            state = {
+                ...state,
+                status: "completed",
+                currentVersion,
+                installedVersion,
+                updatedAt: Date.now(),
+                message: `Update applied: ${installedVersion}`,
+            };
+            writePersistedUpdateState(state);
+        }
+        else if (Date.now() - (state.updatedAt || state.startedAt) > UPDATE_RESTART_TIMEOUT_MS) {
+            state = {
+                ...state,
+                status: "failed",
+                currentVersion,
+                installedVersion,
+                updatedAt: Date.now(),
+                message: "Update failed",
+                error: `Panel did not restart into ${state.targetVersion}`,
+            };
+            writePersistedUpdateState(state);
+        }
+    }
+    if (!state) {
+        return {
+            status: "idle",
+            currentVersion,
+            installedVersion,
+            inProgress: false,
+        };
+    }
+    return {
+        status: state.status,
+        currentVersion,
+        installedVersion,
+        targetVersion: state.targetVersion,
+        startedAt: state.startedAt,
+        updatedAt: state.updatedAt,
+        message: state.message,
+        error: state.error,
+        inProgress: state.status === "running" || state.status === "restarting",
+    };
+}
+function getNpmRegistryUrl() {
+    const panelReg = getPanelConfig().npm_registry;
+    if (typeof panelReg === "string" && panelReg.trim())
+        return panelReg.trim().replace(/\/+$/, "");
+    try {
+        const reg = execFileSync(getNpmBinPath(), ["config", "get", "registry"], {
+            encoding: "utf-8", timeout: 5000,
+        }).trim();
+        if (reg && reg !== "undefined")
+            return reg.replace(/\/+$/, "");
+    }
+    catch { /* fall through */ }
+    return "https://registry.npmjs.org";
+}
+// ── Public API ─────────────────────────────────────────────────────────────
+/**
+ * Check for a newer jishushell version on npm.
+ * Caches for 30 s; safe to call from both CLI and HTTP routes.
+ */
+export async function checkUpdate() {
+    if (_updateCache && Date.now() - _updateCache.ts < UPDATE_CACHE_TTL) {
+        return _updateCache.info;
+    }
+    const currentVersion = getCurrentPackageVersion();
+    let latestVersion = currentVersion;
+    let hasUpdate = false;
+    try {
+        const registryUrl = getNpmRegistryUrl();
+        const metaUrl = new URL(`/jishushell/latest`, registryUrl);
+        const transport = metaUrl.protocol === "https:" ? https : http;
+        latestVersion = await new Promise((resolve, reject) => {
+            const req = transport.get(metaUrl, { headers: { accept: "application/json" }, timeout: 8000 }, (res) => {
+                let body = "";
+                res.on("data", (d) => (body += d));
+                res.on("end", () => {
+                    try {
+                        resolve(JSON.parse(body).version ?? currentVersion);
+                    }
+                    catch {
+                        reject(new Error("parse error"));
+                    }
+                });
+            });
+            req.on("error", reject);
+            req.on("timeout", () => { req.destroy(); reject(new Error("timeout")); });
+        });
+        hasUpdate = compareVersions(latestVersion, currentVersion) > 0;
+    }
+    catch { /* network unavailable — return no-update */ }
+    const info = { hasUpdate, currentVersion, latestVersion };
+    _updateCache = { ts: Date.now(), info };
+    // Piggyback telemetry on update checks (fire-and-forget)
+    checkAndReport();
+    checkAndReportHeartbeat();
+    return info;
+}
+/**
+ * Run `npm install -g jishushell`.
+ * Throws on failure; returns trimmed npm stdout on success.
+ */
+export async function upgradePackage() {
+    const nodeBinDir = dirname(process.execPath);
+    const npmBin = getNpmBinPath();
+    const childEnv = {
+        ...process.env,
+        PATH: `${nodeBinDir}${process.env.PATH ? `:${process.env.PATH}` : ""}`,
+    };
+    // JISHU_RUNNING_IN_INSTALLER=1 tells post-install.sh it is managed by a
+    // parent installer and should skip the interactive sudo / TTY checks,
+    // do only the minimal wrapper+service update, then exit 0.  This works
+    // with every published version of jishushell (the env-var guard predates
+    // the JISHUSHELL_WEB_UPDATE check added later).
+    const npmEnv = {
+        ...childEnv,
+        JISHU_RUNNING_IN_INSTALLER: "1",
+    };
+    try {
+        const out = execFileSync(npmBin, ["install", "-g", "jishushell", "--registry", getNpmRegistryUrl() + "/"], { encoding: "utf-8", timeout: 120_000, stdio: ["ignore", "pipe", "pipe"], env: npmEnv });
+        _updateCache = null; // invalidate
+        return { output: out?.trim() ?? "" };
+    }
+    catch (err) {
+        const detail = err.stderr ? err.stderr.trim() : err.message;
+        throw new Error(detail || err.message);
+    }
+}
+/**
+ * Spawn a detached `jishushell restart` after `delayMs` ms, then return.
+ * The spawned child outlives the current process (useful after upgrade).
+ */
+export function scheduleRestart(delayMs = 2000) {
+    const nodeBinDir = dirname(process.execPath);
+    const childEnv = {
+        ...process.env,
+        PATH: `${nodeBinDir}${process.env.PATH ? `:${process.env.PATH}` : ""}`,
+    };
+    const delaySecs = Math.max(1, Math.round(delayMs / 1000));
+    const child = spawn("sh", ["-c", `sleep ${delaySecs} && exec ${JSON.stringify(process.execPath)} ${JSON.stringify(CLI_PATH)} restart`], { detached: true, stdio: "ignore", env: childEnv });
+    child.unref();
+}
+//# sourceMappingURL=update-manager.js.map

package/dist/services/update-manager.js.map

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

package/dist/types.d.ts

@@ -10,6 +10,22 @@ export interface ServiceResult {
     error?: string;
     warning?: string;
     pid?: number;
+    /**
+     * startInstance-only: tag identifying which phase of the start pipeline
+     * produced the error. Present on every error result returned by
+     * nomad-manager.startInstance so callers (routes, tests, logs) can
+     * distinguish where the failure happened.
+     */
+    phase?: "running_check" | "home_conflict" | "port_alloc" | "pre_start_hook" | "submit";
+    /** Adapter signaled an async background build; poll taskId for progress. */
+    building?: boolean;
+    taskId?: string;
+    /** Nomad alloc ID returned by waitForRunning / restartInstance. */
+    alloc_id?: string;
+    /** Nomad eval ID returned by submitJob. */
+    eval_id?: string;
+    /** Port allocation metadata from adapters (process-manager / nomad-manager). */
+    port_allocation?: unknown;
 }
 export interface ExecResult {
     stdout: string;
@@ -25,12 +41,54 @@ export interface ServiceManager {
     /** Run a command inside the running instance (docker exec or direct exec). */
     exec(id: string, command: string[], timeoutMs?: number): Promise<ExecResult>;
 }
+/**
+ * Runtime catalog entry stored in panel.json.runtime_catalog.<agentType>.
+ * See docs/multi-agent-runtime-generalization-plan.md §32.1 (digest pin) and §32.3 (MVP shape).
+ * Fields are camelCase per §8 naming convention.
+ */
+export interface RuntimeCatalogEntry {
+    defaultImage: string;
+    defaultImageDigest?: string;
+    shimPath?: string;
+    configFormat: "json" | "yaml+env" | "custom";
+    homeDirName: string;
+    resources: {
+        CPU: number;
+        MemoryMB: number;
+        MemoryMaxMB?: number;
+    };
+    allowDockerSock?: boolean;
+}
+export interface RuntimeCatalog {
+    openclaw?: RuntimeCatalogEntry;
+    hermes?: RuntimeCatalogEntry;
+    [agentType: string]: RuntimeCatalogEntry | undefined;
+}
 export interface PanelConfig {
     service_manager?: "process" | "nomad";
     nomad_driver?: "docker";
+    /**
+     * Legacy openclaw image field. Still written by {@link setOpenclawDockerImage}
+     * for compatibility with older panel.json consumers; the authoritative value
+     * now lives in `runtime_catalog.openclaw.defaultImage`. Drop after one release
+     * cycle, together with the legacy read fallback in {@link getOpenclawDockerImage}.
+     */
     openclaw_image?: string;
     nomad_token?: string;
     allowed_origins?: string[];
+    /**
+     * Per-runtime catalog. Openclaw and Hermes both live here; `openclaw_image`
+     * is kept as a legacy mirror until the next major release.
+     */
+    runtime_catalog?: RuntimeCatalog;
+    /**
+     * Version of the `runtime_catalog` schema this panel.json was last written
+     * against. Panel code advertises the highest version it understands via
+     * `CURRENT_CATALOG_SCHEMA_VERSION`; a newer value here (written by a newer
+     * panel) triggers a startup warning and disables catalog mutations so a
+     * downgraded panel cannot silently corrupt structure it doesn't recognize.
+     */
+    runtime_catalog_schema_version?: number;
     default_provider?: {
         providerId?: string;
         baseUrl?: string;
@@ -49,3 +107,169 @@ export interface PanelConfig {
     activation_reported?: boolean;
     [key: string]: any;
 }
+export type AppTaskRuntime = "container" | "process" | "vm";
+export type AppTaskRole = "service" | "init" | "sidecar" | "cleanup";
+export type AppTaskPortVisibility = "external" | "internal" | "public";
+export interface AppTaskResources {
+    cpu?: string;
+    memory?: string;
+}
+export interface AppTaskPort {
+    name: string;
+    port: number;
+    host_port?: number;
+    container_port?: number;
+    visibility?: AppTaskPortVisibility;
+}
+export interface AppTaskHealth {
+    http?: {
+        path: string;
+        port: number;
+    };
+    interval?: string;
+    timeout?: string;
+    retries?: number;
+    /** Grace period after start during which probe failures don't count. */
+    start_period?: string;
+}
+export interface AppDependsOnEntry {
+    /** Readiness condition: "started" | "completed" | "healthy" */
+    condition: "started" | "completed" | "healthy";
+    /** When true (default), dependency failure blocks this app. */
+    required?: boolean;
+}
+export interface AppTaskVolume {
+    source: string;
+    target: string;
+    readonly?: boolean;
+}
+export interface AppTask {
+    name: string;
+    role?: AppTaskRole;
+    runtime: AppTaskRuntime;
+    image?: string;
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    resources?: AppTaskResources;
+    ports?: AppTaskPort[];
+    health?: AppTaskHealth;
+    after?: string[];
+    /** Volumes: string format "src:dest[:ro]" or object { source, target, readonly? } */
+    volumes?: Array<string | AppTaskVolume>;
+}
+export interface AppTerminalCommandPreset {
+    cmd: string;
+    label?: string;
+    description?: string;
+}
+export interface AppTerminalConfig {
+    /** Base argv prepended when the user enters only a sub-command. */
+    command: string[];
+    /** Optional task name for multi-task app specs; defaults to the first service task. */
+    task?: string;
+    prompt?: string;
+    welcome?: string;
+    timeout_ms?: number;
+    commands?: Record<string, Array<string | AppTerminalCommandPreset>>;
+}
+export interface AppProvide {
+    capability: string;
+    port?: number;
+    path?: string;
+    url?: string;
+    protocol?: "http" | "https" | "tcp" | "udp" | (string & {});
+    visibility?: string;
+    description?: string;
+    terminal?: AppTerminalConfig;
+}
+export interface AppRequire {
+    capability: string;
+    inject_as: string;
+    required?: boolean;
+}
+export type AppLifecycleStep = {
+    run: string;
+    timeout_ms?: number;
+    successIfCommandExists?: string;
+    sudo?: boolean;
+    ifFileExists?: string;
+} | {
+    downloadImage: string;
+    timeout_ms?: number;
+} | {
+    deleteImage: string;
+} | {
+    downloadBinary: {
+        url: string;
+        dest: string;
+        chmod?: string;
+    };
+} | {
+    deleteBinary: string;
+} | {
+    mkdir: string;
+} | {
+    deleteDir: string;
+} | {
+    checkNotCommand: string;
+    message?: string;
+};
+export interface AppLifecycle {
+    pre_install?: AppLifecycleStep[];
+    /** Steps run during `app install`, before the job is created. */
+    install?: AppLifecycleStep[];
+    /** Steps run during `app uninstall`, before files are removed. */
+    uninstall?: AppLifecycleStep[];
+    /** Steps run after the Nomad job transitions to `running`. */
+    post_start?: AppLifecycleStep[];
+}
+export interface AppSpec {
+    id: string;
+    app_id?: string;
+    name?: string;
+    version?: string;
+    description?: string;
+    /** Minimum JishuShell version required to install this app spec. */
+    jishushell?: {
+        min_version?: string;
+    };
+    /** When true (default), only one instance can be installed. When false, multiple instances get -1, -2 suffix. */
+    singleInstance?: boolean;
+    /** Custom prefix inserted before the numeric suffix for multi-instance naming. e.g. "inst" → ollama-inst1, ollama-inst2 */
+    instancePrefix?: string;
+    tasks: AppTask[];
+    depends_on?: Record<string, AppDependsOnEntry>;
+    provides?: AppProvide[];
+    requires?: AppRequire[];
+    /**
+     * Target runtime for instances created from this spec. Drives the
+     * `adapter.createInstance()` dispatch in `routes/apps.ts`. When omitted,
+     * the app install flow defaults to `"openclaw"` for backward
+     * compatibility with specs authored before the multi-runtime contract
+     * (§32.2).
+     */
+    agentType?: string;
+    /**
+     * Runtime-scoped overlays the adapter applies during `createInstance()`.
+     * Plan §17 shape: `{ agentType?, defaults?, capabilities?, ... }`.
+     * Adapters are free to read extra keys (e.g. OpenClaw reads `skills` here).
+     */
+    runtime?: Record<string, any>;
+    lifecycle?: AppLifecycle;
+    /** @deprecated use `runtime` — kept as a legacy alias for pre-§17 specs. */
+    openclaw?: Record<string, any>;
+    _engine?: Record<string, any>;
+}
+export interface AppManifestArtifact {
+    type: "image" | "binary" | "dir";
+    path: string;
+}
+export interface AppManifest {
+    id: string;
+    installed_at: string;
+    source?: string;
+    spec_hash?: string;
+    install_mode?: "app-dir" | "instance-dir";
+    artifacts?: AppManifestArtifact[];
+}

package/dist/utils/docker-host.d.ts

@@ -0,0 +1,15 @@
+type ExecFileSyncLike = (command: string, args?: readonly string[], options?: Record<string, any>) => string | Buffer;
+type ExistsSyncLike = (path: string) => boolean;
+export interface ResolveDockerHostOptions {
+    jishuHome: string;
+    colimaProfile?: string;
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform | string;
+    execFileSyncImpl?: ExecFileSyncLike;
+    existsSyncImpl?: ExistsSyncLike;
+}
+export declare function managedColimaSocketPath(jishuHome: string, colimaProfile?: string): string;
+export declare function managedColimaDockerHost(jishuHome: string, colimaProfile?: string): string;
+export declare function resolveDockerHost(options: ResolveDockerHostOptions): string | undefined;
+export declare function buildDockerClientEnv(options: ResolveDockerHostOptions): NodeJS.ProcessEnv;
+export {};