jishushell 0.6.5 → 0.6.18

package/dist/services/repair/runtime-repair.js

@@ -0,0 +1,307 @@
+import { getIntegration } from "../integrations/index.js";
+import { resolveIntegrationKindFromMetadata } from "../app-common/integration-refs.js";
+import { resolveNomadJobId } from "../runtime/job-id.js";
+import { dirname, join } from "path";
+import { accessSync, chmodSync, constants, existsSync, statSync } from "fs";
+import { APPS_DIR, JISHUSHELL_HOME } from "../../config.js";
+import { chownToServiceUser, getConfig, getInstance, getRuntimeEnvFiles, listInstances, parseEnvFile, resolveServiceUser, updateInstanceMeta, updateEnvFile, } from "../instances/manager.js";
+import { bootstrapInstanceProxy, ensureInstanceProxyToken, } from "../llm-proxy/instance-proxy.js";
+import { getDefaultLlmProvider } from "../llm-proxy/providers.js";
+export const LEGACY_JOB_SPEC_RESTART_REPAIR_ID = "legacy-prefixed-nomad-job-spec-v1";
+const ANYTHINGLLM_INSTANCE_ID = "anythingllm-container";
+const ANYTHINGLLM_KNOWLEDGE_CAPABILITY = "knowledge-anythingllm";
+const OPENCLAW_KNOWLEDGE_SLOT = "KNOWLEDGE_BASE_URL";
+function runtimeEnv(instanceId) {
+    const env = {};
+    for (const envFile of getRuntimeEnvFiles(instanceId)) {
+        Object.assign(env, parseEnvFile(envFile));
+    }
+    return env;
+}
+function configUsesProxy(config) {
+    if (!config)
+        return false;
+    if (config["x-jishushell"]?.proxy?.enabled)
+        return true;
+    const defaultModel = String(config.agents?.defaults?.model || "");
+    if (defaultModel.startsWith("jsproxy/") || defaultModel.startsWith("js-"))
+        return true;
+    const providers = config.models?.providers;
+    if (!providers || typeof providers !== "object")
+        return false;
+    return Object.values(providers).some((provider) => provider && typeof provider.baseUrl === "string" && provider.baseUrl.includes("/proxy"));
+}
+function legacyProviderKeys(env) {
+    return Object.keys(env)
+        .filter((key) => key.endsWith("_API_KEY") && key !== "JSPROXY_API_KEY")
+        .sort();
+}
+function providerEnvPath(instanceId) {
+    const envFile = getRuntimeEnvFiles(instanceId)[0];
+    return envFile ? join(dirname(envFile), "provider.env") : null;
+}
+function providerSecret(instanceId) {
+    const path = providerEnvPath(instanceId);
+    return path ? (parseEnvFile(path).UPSTREAM_API_KEY || "") : "";
+}
+function hasAnythingllmCredentials() {
+    return existsSync(join(JISHUSHELL_HOME, "provider-credentials", ANYTHINGLLM_INSTANCE_ID, "credentials.json"))
+        || existsSync(join(APPS_DIR, ANYTHINGLLM_INSTANCE_ID, "credentials.json"));
+}
+function maybeRepairOpenClawKnowledgeDefault(instanceId, instance, options, repaired, warnings) {
+    const connections = instance.connections && typeof instance.connections === "object" && !Array.isArray(instance.connections)
+        ? { ...instance.connections }
+        : {};
+    if (Object.prototype.hasOwnProperty.call(connections, OPENCLAW_KNOWLEDGE_SLOT))
+        return;
+    if (!hasAnythingllmCredentials())
+        return;
+    // Runtime repair boundary only: pre-Step-5 OpenClaw treated a missing
+    // KNOWLEDGE_BASE_URL binding as "use AnythingLLM if credentials.json exists".
+    // The runtime hook no longer guesses that. Repair can safely preserve the old
+    // behavior by writing the observed historical default into canonical
+    // `instance.connections`, without overwriting explicit user disconnect/binds.
+    const nextConnections = {
+        ...connections,
+        [OPENCLAW_KNOWLEDGE_SLOT]: {
+            kind: "single",
+            providerId: ANYTHINGLLM_INSTANCE_ID,
+            capability: ANYTHINGLLM_KNOWLEDGE_CAPABILITY,
+        },
+    };
+    if (options.dryRun) {
+        warnings.push("would materialize legacy OpenClaw AnythingLLM knowledge default into instance.connections");
+        return;
+    }
+    updateInstanceMeta(instanceId, { connections: nextConnections });
+    repaired.push("knowledge-default-connection");
+}
+function serviceUserAccessError(path) {
+    if (!existsSync(path))
+        return null;
+    const serviceUser = resolveServiceUser();
+    if (serviceUser) {
+        try {
+            const stat = statSync(path);
+            const mode = stat.mode & 0o777;
+            const ownedByServiceUser = stat.uid === serviceUser.uid && stat.gid === serviceUser.gid;
+            const readableByServiceUser = (stat.uid === serviceUser.uid && (mode & 0o400) !== 0) ||
+                (stat.gid === serviceUser.gid && (mode & 0o040) !== 0) ||
+                ((mode & 0o004) !== 0);
+            if (ownedByServiceUser && readableByServiceUser)
+                return null;
+            return `service user ${serviceUser.username} cannot safely read ${path} (uid=${stat.uid}, gid=${stat.gid}, mode=${mode.toString(8)})`;
+        }
+        catch (error) {
+            return error?.message ?? String(error);
+        }
+    }
+    try {
+        accessSync(path, constants.R_OK);
+        return null;
+    }
+    catch (error) {
+        return error?.message ?? String(error);
+    }
+}
+function repairReadableFile(path, repairId, label, options, repaired, warnings) {
+    if (!path)
+        return;
+    const before = serviceUserAccessError(path);
+    if (!before)
+        return;
+    if (options.dryRun) {
+        warnings.push(`would repair ${label} permissions: ${path}`);
+        return;
+    }
+    try {
+        chmodSync(path, 0o600);
+    }
+    catch {
+        // chown below may still recover root-owned files when repair runs with sudo.
+    }
+    chownToServiceUser(path);
+    const after = serviceUserAccessError(path);
+    if (after) {
+        warnings.push(`${label} is not readable after ownership repair: ${after}`);
+    }
+    else {
+        repaired.push(repairId);
+    }
+}
+function proxyUpstreamProviderId(instance, config) {
+    return String(config?.["x-jishushell"]?.proxy?.upstream?.providerId
+        ?? instance["x-jishushell"]?.proxy?.upstream?.providerId
+        ?? "").trim();
+}
+function integrationPrefix(integrationKind) {
+    try {
+        return getIntegration(integrationKind).nomadJobPrefix ?? "";
+    }
+    catch {
+        return "";
+    }
+}
+function appliedRuntimeRepairRestarts(meta) {
+    const extension = meta?.["x-jishushell"];
+    const current = extension?.runtimeRepairRestartsApplied;
+    if (current && typeof current === "object" && !Array.isArray(current))
+        return current;
+    // Repair boundary only: releases that mixed instance repair into system
+    // reconciliation persisted this old acknowledgement field. Read it once so
+    // already-applied repairs do not start warning again after upgrade.
+    const legacy = extension?.runtimeRestartAdvisoriesApplied;
+    return legacy && typeof legacy === "object" && !Array.isArray(legacy) ? legacy : {};
+}
+function isRuntimeRepairRestartApplied(meta, repairId) {
+    return Boolean(appliedRuntimeRepairRestarts(meta)[repairId]);
+}
+export function markRuntimeRepairRestartApplied(instanceId, repairId = LEGACY_JOB_SPEC_RESTART_REPAIR_ID) {
+    const meta = getInstance(instanceId);
+    if (!meta)
+        return;
+    const extension = meta["x-jishushell"] && typeof meta["x-jishushell"] === "object"
+        ? { ...meta["x-jishushell"] }
+        : {};
+    extension.runtimeRepairRestartsApplied = {
+        ...appliedRuntimeRepairRestarts(meta),
+        [repairId]: {
+            appliedAt: new Date().toISOString(),
+        },
+    };
+    updateInstanceMeta(instanceId, { "x-jishushell": extension });
+}
+export async function repairRuntimeInstance(instance, options = {}) {
+    const instanceId = String(instance.id || "");
+    const integrationKind = resolveIntegrationKindFromMetadata(instance) ?? "unknown";
+    const repaired = [];
+    const warnings = [];
+    try {
+        const envFiles = getRuntimeEnvFiles(instanceId);
+        if (integrationKind === "openclaw" || integrationKind === "hermes") {
+            for (const envFile of envFiles) {
+                repairReadableFile(envFile, "runtime-env-permissions", "runtime env file", options, repaired, warnings);
+            }
+            repairReadableFile(providerEnvPath(instanceId), "provider-secret-permissions", "provider.env", options, repaired, warnings);
+        }
+        const beforeEnv = runtimeEnv(instanceId);
+        const beforeToken = beforeEnv.JSPROXY_API_KEY || "";
+        const beforeConfig = getConfig(instanceId);
+        const beforeUsesProxy = configUsesProxy(beforeConfig);
+        if (integrationKind === "openclaw") {
+            maybeRepairOpenClawKnowledgeDefault(instanceId, instance, options, repaired, warnings);
+            if (!options.dryRun) {
+                await bootstrapInstanceProxy(instanceId, { allowLegacyConfigFallback: true });
+            }
+            else if (!beforeToken || !beforeUsesProxy) {
+                warnings.push("would bootstrap proxy token and jsproxy config");
+            }
+            const afterEnv = runtimeEnv(instanceId);
+            const afterConfig = getConfig(instanceId);
+            if (!beforeToken && afterEnv.JSPROXY_API_KEY)
+                repaired.push("proxy-token");
+            if (!beforeUsesProxy && configUsesProxy(afterConfig))
+                repaired.push("jsproxy-config");
+            if (afterEnv.JSPROXY_API_KEY) {
+                if (!options.dryRun) {
+                    const { writeInstanceVariables } = await import("../runtime/drivers/nomad.js");
+                    await writeInstanceVariables(instanceId);
+                    repaired.push("nomad-variables");
+                }
+                else {
+                    warnings.push("would write Nomad Variables for JSPROXY_API_KEY");
+                }
+            }
+            else {
+                warnings.push("JSPROXY_API_KEY is missing; no Nomad Variables were written");
+            }
+        }
+        else if (integrationKind === "hermes") {
+            if (!beforeToken) {
+                if (!options.dryRun) {
+                    ensureInstanceProxyToken(instanceId);
+                    repaired.push("proxy-token");
+                }
+                else {
+                    warnings.push("would generate proxy-token");
+                }
+            }
+            const beforeSecret = providerSecret(instanceId);
+            const upstreamProviderId = proxyUpstreamProviderId(instance, beforeConfig);
+            if (!beforeSecret && upstreamProviderId) {
+                const defaultProvider = getDefaultLlmProvider();
+                if (defaultProvider?.apiKey && defaultProvider.id === upstreamProviderId) {
+                    if (!options.dryRun) {
+                        const path = providerEnvPath(instanceId);
+                        if (path) {
+                            updateEnvFile(path, { UPSTREAM_API_KEY: defaultProvider.apiKey });
+                            repaired.push("provider-secret");
+                        }
+                        else {
+                            warnings.push("Hermes env file is missing; provider.env path cannot be resolved");
+                        }
+                    }
+                    else {
+                        warnings.push("would write Hermes provider.env UPSTREAM_API_KEY from the default provider");
+                    }
+                }
+                else {
+                    warnings.push(`Hermes provider.env is missing and cannot be auto-repaired for upstream provider '${upstreamProviderId}'`);
+                }
+            }
+        }
+        const env = runtimeEnv(instanceId);
+        const legacyKeys = legacyProviderKeys(env);
+        if (legacyKeys.length > 0) {
+            warnings.push(`note: legacy env key(s) kept for backward compatibility: ${legacyKeys.join(", ")}`);
+        }
+        const prefix = integrationPrefix(integrationKind);
+        const resolvedJobId = resolveNomadJobId(instanceId, prefix);
+        const hadPrefixedId = !!prefix && instanceId === resolvedJobId && instanceId.startsWith(prefix);
+        const restartRequired = (integrationKind === "openclaw" || integrationKind === "hermes")
+            && hadPrefixedId
+            && !isRuntimeRepairRestartApplied(instance, LEGACY_JOB_SPEC_RESTART_REPAIR_ID);
+        const status = restartRequired
+            ? "needs-restart"
+            : repaired.length > 0
+                ? "repaired"
+                : warnings.length > 0
+                    ? "manual"
+                    : "ok";
+        return {
+            instanceId,
+            integrationKind,
+            status,
+            repaired,
+            warnings,
+            restartRequired,
+            ...(restartRequired ? { reason: "Nomad job template path may have changed; restart the instance to resubmit the job" } : {}),
+        };
+    }
+    catch (error) {
+        return {
+            instanceId,
+            integrationKind,
+            status: "error",
+            repaired,
+            warnings,
+            restartRequired: false,
+            error: error?.message ?? String(error),
+        };
+    }
+}
+export async function repairRuntimeInstances(options = {}) {
+    const results = [];
+    for (const instance of listInstances()) {
+        const integrationKind = resolveIntegrationKindFromMetadata(instance);
+        if (integrationKind !== "openclaw" && integrationKind !== "hermes")
+            continue;
+        results.push(await repairRuntimeInstance(instance, options));
+    }
+    return {
+        ok: results.every((result) => result.status !== "error"),
+        dryRun: options.dryRun === true,
+        results,
+    };
+}
+//# sourceMappingURL=runtime-repair.js.map

package/dist/services/repair/runtime-repair.js.map

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

package/dist/services/runtime/driver-registry.d.ts

@@ -0,0 +1,21 @@
+import type { AppTask, AppTaskRuntime } from "../../types.js";
+import type { RuntimeSpec } from "./types.js";
+import type { TaskRuntimeContribution } from "./workload-types.js";
+export interface RuntimeDriverCompileContext {
+    instanceId: string;
+    extraEnv: Record<string, string>;
+    runtime?: RuntimeSpec;
+    contribution?: TaskRuntimeContribution;
+}
+export interface CompiledTaskFragment {
+    task: Record<string, unknown>;
+    reservedPorts: Array<Record<string, unknown>>;
+}
+export interface RuntimeDriver<TTask extends AppTask = AppTask> {
+    readonly kind: AppTaskRuntime;
+    compile(task: TTask, ctx: RuntimeDriverCompileContext): CompiledTaskFragment;
+}
+export declare function registerRuntimeDriver(driver: RuntimeDriver): void;
+export declare function hasRuntimeDriver(kind: AppTaskRuntime): boolean;
+export declare function getRuntimeDriver(kind: AppTaskRuntime): RuntimeDriver;
+export declare function __resetRuntimeDriversForTests(): void;

package/dist/services/runtime/driver-registry.js

@@ -0,0 +1,22 @@
+const registry = new Map();
+export function registerRuntimeDriver(driver) {
+    if (registry.has(driver.kind)) {
+        throw new Error(`Runtime driver for kind "${driver.kind}" already registered`);
+    }
+    registry.set(driver.kind, driver);
+}
+export function hasRuntimeDriver(kind) {
+    return registry.has(kind);
+}
+export function getRuntimeDriver(kind) {
+    const driver = registry.get(kind);
+    if (!driver) {
+        throw new Error(`No runtime driver registered for kind="${kind}". ` +
+            `Registered kinds: [${[...registry.keys()].join(", ") || "none"}]`);
+    }
+    return driver;
+}
+export function __resetRuntimeDriversForTests() {
+    registry.clear();
+}
+//# sourceMappingURL=driver-registry.js.map

package/dist/services/runtime/driver-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver-registry.js","sourceRoot":"","sources":["../../../src/services/runtime/driver-registry.ts"],"names":[],"mappings":"AAqBA,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAiC,CAAC;AAE1D,MAAM,UAAU,qBAAqB,CAAC,MAAqB;IACzD,IAAI,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,4BAA4B,MAAM,CAAC,IAAI,sBAAsB,CAAC,CAAC;IACjF,CAAC;IACD,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AACpC,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,IAAoB;IACnD,OAAO,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAC5B,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,IAAoB;IACnD,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAClC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,0CAA0C,IAAI,KAAK;YACjD,sBAAsB,CAAC,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,MAAM,GAAG,CACrE,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,6BAA6B;IAC3C,QAAQ,CAAC,KAAK,EAAE,CAAC;AACnB,CAAC"}

package/dist/services/runtime/drivers/nomad.d.ts

@@ -0,0 +1,260 @@
+/**
+ * Nomad runtime driver — kind-agnostic scheduler layer.
+ *
+ * This file contains no direct knowledge of specific agent kinds. The runtime
+ * dispatch surface is now reduced to two compile-path primitives:
+ *
+ *     const kind = resolvePrimaryIntegrationKind(getInstance(id));
+ *     const integration = getIntegration(kind);
+ *     const persistedRuntime = await integration.getPersistedRuntimeSpec(id);
+ *     const contribution = await integration.buildRuntimeContribution?.(id);
+ *
+ * The persisted runtime spec + contribution are then handed to
+ * WorkloadCompiler, which is the single canonical task builder. The app
+ * lifecycle pipeline owns integration pre-start materialization before calling
+ * the prepared submit path; the legacy direct start wrapper still preserves the
+ * older runtime-local hook path until remaining callers are migrated.
+ */
+import type { AppSpec, ExecOptions, ExecResult, InstanceStatus, ServiceResult } from "../../../types.js";
+export declare const DOCKER_IMAGE_RE: RegExp;
+/**
+ * Linux username validation regex. Shared by integration Nomad task builders
+ * (OpenClaw / Hermes) and re-exported here as a neutral framework constant
+ * so security-regression tests can assert on it without depending on a
+ * specific integration file.
+ *
+ * Strict form: lowercase letters/digits/dot/dash/underscore only, 1..32 chars.
+ * Rejects uppercase, shell metacharacters, paths, and empty strings.
+ */
+export declare const VALID_USER_RE: RegExp;
+export declare const MAX_DOCKER_IMAGE_NAME_LEN = 256;
+export declare function setCorePort(port: number): void;
+export declare const VALID_LOG_TYPES: Set<string>;
+export interface ExecStreamHandlers {
+    onStdout?: (text: string) => void;
+    onStderr?: (text: string) => void;
+}
+declare function jobId(instanceId: string): string;
+/** Exported only for unit tests — not part of the public API. */
+export declare function __jobIdForTests(instanceId: string): string;
+export declare const NOMAD_TEMPLATE_UNSAFE_RE: RegExp;
+declare function assertSafeTemplateId(id: string): void;
+declare function nomadGet(path: string): Promise<any>;
+declare function nomadPut(path: string, body: any): Promise<Response>;
+export declare function writeInstanceVariables(instanceId: string): Promise<void>;
+export declare function purgeInstanceVariables(instanceId: string): Promise<void>;
+/**
+ * Resolve the numeric uid:gid for a given username by reading /etc/passwd.
+ * Falls back to process.getuid!():process.getgid!() when the lookup fails.
+ * Still used here by the kind-agnostic `exec()` helper below (for docker
+ * exec user resolution); integrations carry their own copies for task build.
+ */
+declare function resolveUidGid(username: string): string;
+export declare function shouldAutoStart(instanceId: string): Promise<boolean>;
+export declare function getStatus(instanceId: string): Promise<Record<string, any>>;
+/**
+ * runtime submit phase tags. Returned on every error result so callers and
+ * tests can distinguish *where* the failure happened without parsing the
+ * message string. Backward-compatible: legacy callers that only read
+ * `result.ok` / `result.error` continue to work unchanged.
+ */
+export type StartPhase = "running_check" | "home_conflict" | "port_alloc" | "submit";
+export declare function getLogs(instanceId: string, lines?: number, logType?: string): Promise<string[]>;
+/** Field separator for the batched `docker stats --format` line. Exported so
+ *  tests can construct mock output without hardcoding the literal. */
+export declare const DOCKER_STATS_FIELD_SEP = "__JS__";
+/** Test-only: reset the shared docker-stats snapshot so each test starts from
+ *  a cold cache (the 30s TTL + single-flight would otherwise leak one test's
+ *  mocked snapshot into the next). Not used by production code paths. */
+export declare function __resetDockerStatsCacheForTests(): void;
+export declare function exec(instanceId: string, command: string[], timeoutMs?: number, options?: ExecOptions): Promise<{
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}>;
+/**
+ * Clamp container memory reservation/limit to the framework ceilings and
+ * ensure `MemoryMaxMB >= MemoryMB`. Shared by every container-runtime app
+ * manager (openclaw / custom / ollama / hermes) so they apply the same
+ * guard-rails before handing a task spec to Nomad.
+ */
+export declare function normalizeDockerResources(instanceId: string, runtime: Record<string, any>): Record<string, any>;
+export { jobId, resolveUidGid, nomadGet, nomadPut, assertSafeTemplateId, };
+declare namespace UnifiedNomadJobs {
+    export const DOCKER_IMAGE_RE: RegExp;
+    export const MAX_DOCKER_IMAGE_NAME_LEN = 256;
+    export const VALID_LOG_TYPES: Set<string>;
+    export const NOMAD_TEMPLATE_UNSAFE_RE: RegExp;
+    export function isAppJob(id: string): boolean;
+    export interface AppJobStatus {
+        status: string;
+        alloc_id?: string;
+        /** Per-task status map; key is task name. */
+        tasks: Record<string, {
+            state: string;
+            restarts: number;
+            started_at?: string;
+            health_status?: string;
+            health_checks?: Array<{
+                name: string;
+                status: string;
+                service?: string;
+                output?: string;
+            }>;
+        }>;
+        pid: null;
+        uptime: number | null;
+        memory_mb: number | null;
+        cpu_percent: number | null;
+        restarts: number;
+        error?: string;
+    }
+    /**
+     * Parse a CPU resource string to Nomad MHz integer.
+     *  "500m"  → 500  (millicores treated as MHz for simplicity)
+     *  "1"     → 1000 (1 core → 1000 MHz)
+     *  "1000"  → 1000 (bare integer treated as MHz already)
+     *
+     * Nomad doesn't have a concept of "cores"; it schedules by MHz.
+     * We treat 1 core = 1000 MHz as a reasonable proxy for a Pi-class host.
+     */
+    export function parseCpuMHz(cpu: string | number | undefined): number;
+    /**
+     * Parse a memory resource string to Nomad MB integer.
+     *  "512Mi" or "512MiB" → 512 MB
+     *  "1Gi"   or "1GiB"   → 1024 MB
+     *  "512M"  or "512MB"  → 512 MB
+     *  "1G"    or "1GB"    → 1024 MB
+     *  "1024"              → 1024 MB (bare integer = MB)
+     */
+    export function parseMemoryMB(memory: string | number | undefined): number;
+    type PortNetworkDeclaration = {
+        visibility?: string;
+        host_network?: string;
+    };
+    export function validateNomadPortHostNetworks(ports: PortNetworkDeclaration[]): Promise<string | null>;
+    export function buildNomadReservedPort(input: {
+        label: string;
+        value: number;
+        to?: number;
+        visibility?: string;
+        host_network?: string;
+    }): Record<string, any>;
+    /**
+     * Check whether a binary process is already running on the host OS by
+     * matching its command path via pgrep -f.
+     *
+     * Used by submitGenericAppSpecJob to skip Nomad submission when the binary is already
+     * running (e.g. started outside of Nomad or when raw_exec driver is unavailable).
+     */
+    export function isBinaryRunning(command: string): Promise<boolean>;
+    export function aggregateHealthStatus(checks: Array<{
+        status: string;
+    }>): string;
+    /**
+     * Returns true if this app job exists in Nomad and was NOT explicitly stopped.
+     * Used at JishuShell startup to auto-restart apps that were running before reboot.
+     */
+    export function shouldAutoStart(instanceId: string): Promise<boolean>;
+    /**
+     * Get the aggregated status of an app job.
+     *
+     * @param instanceId       App instance ID.
+     * @param primaryTask Task name to use for uptime/restarts summary.
+     *                    Defaults to the first service task in the spec.
+     *                    If omitted, the first task state found is used.
+     */
+    export function getInstanceInstallRecordStatus(instanceId: string, primaryTask?: string): Promise<AppJobStatus>;
+    /**
+     * Submit a Nomad job for an app.
+     *
+     * @param spec     Validated AppSpec.
+     * @param instanceId    Unique instance ID (job name suffix).
+     * @param extraEnv Env vars injected into every task (e.g. resolved capability addresses).
+     */
+    export function submitGenericAppSpecJob(spec: AppSpec, instanceId: string, extraEnv?: Record<string, string>): Promise<{
+        ok: boolean;
+        error?: string;
+        eval_id?: string;
+    }>;
+    /**
+     * Poll until the app job reaches "running" status or times out.
+     * Returns true if the job is running, false if timed out.
+     */
+    export function waitForRunning(instanceId: string, timeoutMs?: number, pollIntervalMs?: number): Promise<boolean>;
+    export function checkDependencies(spec: AppSpec): Promise<{
+        ok: boolean;
+        errors: string[];
+    }>;
+    /**
+     * Stop (and optionally purge) a Nomad app job.
+     */
+    export function stopGenericAppSpecJob(instanceId: string, purge?: boolean): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    /**
+     * Fetch recent log lines for a task in an app job.
+     *
+     * @param instanceId    App instance ID.
+     * @param taskName Nomad task name (task.name from AppSpec).
+     * @param lines    Number of lines to return (default 200).
+     * @param logType  "stdout" | "stderr" (default "stderr").
+     */
+    export function getInstanceInstallRecordLogs(instanceId: string, taskName?: string, lines?: number, logType?: string): Promise<string[]>;
+    /**
+     * Execute a command inside a running app task.
+     *
+     * Strategy:
+     *   1. Try `docker exec` (fast path for docker-driver tasks, no Nomad dependency).
+     *   2. If the container is not found, fall back to the Nomad WebSocket exec API
+     *      which works for both `docker` and `raw_exec` tasks.
+     *
+     * @param instanceId     App instance ID.
+     * @param taskName  Task name from AppSpec.
+     * @param command   Command + args array.
+     * @param timeoutMs Execution timeout in ms (default 120 s).
+     */
+    export function execInApp(instanceId: string, taskName: string | undefined, command: string[], timeoutMs?: number, options?: ExecOptions): Promise<ExecResult>;
+    export function streamExecInApp(instanceId: string, taskName: string | undefined, command: string[], handlers?: ExecStreamHandlers, timeoutMs?: number): Promise<ExecResult>;
+    export function listInstanceIds(): Promise<string[]>;
+    export function readInstanceMeta(nomadJobId: string): Record<string, any> | null;
+    export function resolveInstanceId(id?: string): Promise<string>;
+    export function resolveInstanceForPairing(instanceId?: string): Promise<string>;
+    export function ensureNomadToken(): void;
+    export function getInstanceStatus(nomadJobId: string): Promise<InstanceStatus>;
+    export function submitIntegrationRuntimeJob(nomadJobId: string): Promise<ServiceResult>;
+    export function stopIntegrationRuntimeJob(nomadJobId: string, purge?: boolean): Promise<ServiceResult>;
+    export function getInstanceLogs(nomadJobId: string, lines?: number, logType?: string): Promise<string[]>;
+    export function execInInstance(nomadJobId: string, command: string[], timeoutMs?: number, options?: ExecOptions): Promise<ExecResult>;
+    export function streamExecInInstance(nomadJobId: string, command: string[], handlers?: ExecStreamHandlers, timeoutMs?: number, taskName?: string): Promise<ExecResult>;
+    export {};
+}
+export declare const isAppJob: typeof UnifiedNomadJobs.isAppJob;
+export declare const parseCpuMHz: typeof UnifiedNomadJobs.parseCpuMHz;
+export declare const parseMemoryMB: typeof UnifiedNomadJobs.parseMemoryMB;
+export declare const isBinaryRunning: typeof UnifiedNomadJobs.isBinaryRunning;
+export declare const getInstanceInstallRecordStatus: typeof UnifiedNomadJobs.getInstanceInstallRecordStatus;
+export declare const submitGenericAppSpecJob: typeof UnifiedNomadJobs.submitGenericAppSpecJob;
+export declare const waitForRunning: typeof UnifiedNomadJobs.waitForRunning;
+export declare const checkDependencies: typeof UnifiedNomadJobs.checkDependencies;
+export declare const validateNomadPortHostNetworks: typeof UnifiedNomadJobs.validateNomadPortHostNetworks;
+export declare const buildNomadReservedPort: typeof UnifiedNomadJobs.buildNomadReservedPort;
+export declare const stopGenericAppSpecJob: typeof UnifiedNomadJobs.stopGenericAppSpecJob;
+export declare const getInstanceInstallRecordLogs: typeof UnifiedNomadJobs.getInstanceInstallRecordLogs;
+export declare const execInApp: typeof UnifiedNomadJobs.execInApp;
+export declare const streamExecInApp: typeof UnifiedNomadJobs.streamExecInApp;
+export declare const listInstanceIds: typeof UnifiedNomadJobs.listInstanceIds;
+export declare const readInstanceMeta: typeof UnifiedNomadJobs.readInstanceMeta;
+export declare const resolveInstanceId: typeof UnifiedNomadJobs.resolveInstanceId;
+export declare const resolveInstanceForPairing: typeof UnifiedNomadJobs.resolveInstanceForPairing;
+export declare const ensureNomadToken: typeof UnifiedNomadJobs.ensureNomadToken;
+export declare const getInstanceStatus: typeof UnifiedNomadJobs.getInstanceStatus;
+export declare const getInstanceLogs: typeof UnifiedNomadJobs.getInstanceLogs;
+export declare const execInInstance: typeof UnifiedNomadJobs.execInInstance;
+export declare const streamExecInInstance: typeof UnifiedNomadJobs.streamExecInInstance;
+export declare const shouldAutoStartNomadJob: typeof UnifiedNomadJobs.shouldAutoStart;
+export declare const submitIntegrationRuntimeJob: typeof UnifiedNomadJobs.submitIntegrationRuntimeJob;
+export declare const stopIntegrationRuntimeJob: typeof UnifiedNomadJobs.stopIntegrationRuntimeJob;
+export type AppJobStatus = UnifiedNomadJobs.AppJobStatus;
+export declare const __aggregateHealthStatusForTests: typeof UnifiedNomadJobs.aggregateHealthStatus;