jishushell 0.4.17 → 0.4.24

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

@@ -1,16 +1,79 @@
 /**
- * Nomad-based service manager for OpenClaw instances.
- * Communicates with Nomad via its HTTP API.
+ * Nomad-based service manager — kind-agnostic scheduler layer.
+ *
+ * §32.2 / §32.8: this file contains ZERO knowledge of specific agent kinds.
+ * Runtime-specific task assembly (`buildNomadTask`), pre-start patches
+ * (`hooks.onBeforeStart`), and capability profiles live inside
+ * `src/services/runtime/adapters/<agentType>.ts`. Framework dispatch is:
+ *
+ *     const agentType = resolveAgentType(getInstance(id));
+ *     const adapter = getAdapter(agentType);
+ *     await adapter.hooks?.onBeforeStart?.({ instanceId });
+ *     const task = await adapter.buildNomadTask(instanceId);
  */
+import type { AppSpec, ExecResult, InstanceStatus, ServiceResult } from "../types.js";
 export declare const DOCKER_IMAGE_RE: RegExp;
+/**
+ * Linux username validation regex. Shared by adapter 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 adapter 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 setPanelPort(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>;
-export declare const VALID_USER_RE: RegExp;
+/**
+ * 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); adapters 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>>;
+/**
+ * startInstance 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" | "pre_start_hook" | "submit";
+/**
+ * §32.2 / §32.8: pure adapter dispatch. Framework owns five generic
+ * responsibilities delegated to `phase*` helpers above; every kind-
+ * specific concern lives in `adapter.hooks.onBeforeStart()`.
+ *
+ * Phase ordering:
+ *   running_check → home_conflict → pre_start_hook → port_alloc → submit
+ *
+ * `pre_start_hook` intentionally runs BEFORE `port_alloc` so deterministic
+ * errors (missing config, missing image, variables-write failure) surface
+ * ahead of port-reallocation noise. A port reallocation failure after a
+ * successful hook means the environment is genuinely contended; a hook
+ * failure after a reallocation would waste the allocation and bury the
+ * real cause under an incidental port change.
+ *
+ * Error returns carry a `phase` tag so callers and logs can distinguish
+ * *where* the failure happened. The shape stays backward-compatible: old
+ * callers that only read `ok`/`error` continue to work.
+ */
 export declare function startInstance(instanceId: string): Promise<Record<string, any>>;
 export declare function stopInstance(instanceId: string, purge?: boolean): Promise<Record<string, any>>;
 export declare function restartInstance(instanceId: string): Promise<Record<string, any>>;
@@ -20,3 +83,197 @@ export declare function exec(instanceId: string, command: string[], timeoutMs?:
     stderr: string;
     exitCode: number;
 }>;
+export declare const DEFAULT_PIDS_LIMIT = 512;
+export declare const DEFAULT_ARGS: string[];
+export declare const DEFAULT_USER: string;
+export declare const DEFAULT_CWD: string;
+export declare const DEFAULT_ENV: Record<string, string>;
+export declare const DEFAULT_RESOURCES: {
+    CPU: number;
+    MemoryMB: number;
+};
+export declare const MAX_CPU_MHZ = 4000;
+export declare const MAX_MEMORY_MB = 4096;
+export declare const MAX_MEMORY_MAX_MB = 4096;
+/**
+ * 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 {
+    const DOCKER_IMAGE_RE: RegExp;
+    const MAX_DOCKER_IMAGE_NAME_LEN = 256;
+    const VALID_LOG_TYPES: Set<string>;
+    const NOMAD_TEMPLATE_UNSAFE_RE: RegExp;
+    function isAppJob(id: string): boolean;
+    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.
+     */
+    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)
+     */
+    function parseMemoryMB(memory: string | number | undefined): number;
+    /**
+     * Check whether a binary process is already running on the host OS by
+     * matching its command path via pgrep -f.
+     *
+     * Used by startAppJob to skip Nomad submission when the binary is already
+     * running (e.g. started outside of Nomad or when raw_exec driver is unavailable).
+     */
+    function isBinaryRunning(command: string): Promise<boolean>;
+    /**
+     * 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.
+     */
+    function shouldAutoStart(appId: string): Promise<boolean>;
+    /**
+     * Get the aggregated status of an app job.
+     *
+     * @param appId       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.
+     */
+    function getAppStatus(appId: string, primaryTask?: string): Promise<AppJobStatus>;
+    /**
+     * Submit a Nomad job for an app.
+     *
+     * @param spec     Validated AppSpec.
+     * @param appId    Unique instance ID (job name suffix).
+     * @param extraEnv Env vars injected into every task (e.g. resolved capability addresses).
+     */
+    function startAppJob(spec: AppSpec, appId: 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.
+     */
+    function waitForRunning(appId: string, timeoutMs?: number, pollIntervalMs?: number): Promise<boolean>;
+    function checkDependencies(spec: AppSpec): Promise<{
+        ok: boolean;
+        errors: string[];
+    }>;
+    /**
+     * Stop (and optionally purge) a Nomad app job.
+     */
+    function stopAppJob(appId: string, purge?: boolean): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    /**
+     * Restart a running app job.
+     * Prefers native Nomad allocation restart to preserve alloc history.
+     * Falls back to stop + re-submit when no AppSpec is available for re-submit.
+     *
+     * @param appId       App instance ID.
+     * @param primaryTask Task name to restart. Defaults to the first task.
+     */
+    function restartAppJob(appId: string, primaryTask?: string): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    /**
+     * Fetch recent log lines for a task in an app job.
+     *
+     * @param appId    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").
+     */
+    function getAppLogs(appId: 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 appId     App instance ID.
+     * @param taskName  Task name from AppSpec.
+     * @param command   Command + args array.
+     * @param timeoutMs Execution timeout in ms (default 120 s).
+     */
+    function execInApp(appId: string, taskName: string | undefined, command: string[], timeoutMs?: number): Promise<ExecResult>;
+    function streamExecInApp(appId: string, taskName: string | undefined, command: string[], handlers?: ExecStreamHandlers, timeoutMs?: number): Promise<ExecResult>;
+    function listInstanceIds(): Promise<string[]>;
+    function readInstanceMeta(nomadJobId: string): Record<string, any> | null;
+    function resolveInstanceId(id?: string): Promise<string>;
+    function resolveInstanceForPairing(instanceId?: string): Promise<string>;
+    function ensureNomadToken(): void;
+    function getInstanceStatus(nomadJobId: string): Promise<InstanceStatus>;
+    function startInstance(nomadJobId: string): Promise<ServiceResult>;
+    function stopInstance(nomadJobId: string, purge?: boolean): Promise<ServiceResult>;
+    function restartInstance(nomadJobId: string): Promise<ServiceResult>;
+    function getInstanceLogs(nomadJobId: string, lines?: number, logType?: string): Promise<string[]>;
+    function execInInstance(nomadJobId: string, command: string[], timeoutMs?: number): Promise<ExecResult>;
+    function streamExecInInstance(nomadJobId: string, command: string[], handlers?: ExecStreamHandlers, timeoutMs?: number, taskName?: string): Promise<ExecResult>;
+}
+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 getAppStatus: typeof UnifiedNomadJobs.getAppStatus;
+export declare const startAppJob: typeof UnifiedNomadJobs.startAppJob;
+export declare const waitForRunning: typeof UnifiedNomadJobs.waitForRunning;
+export declare const checkDependencies: typeof UnifiedNomadJobs.checkDependencies;
+export declare const stopAppJob: typeof UnifiedNomadJobs.stopAppJob;
+export declare const restartAppJob: typeof UnifiedNomadJobs.restartAppJob;
+export declare const getAppLogs: typeof UnifiedNomadJobs.getAppLogs;
+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 startNomadJobInstance: typeof UnifiedNomadJobs.startInstance;
+export declare const stopNomadJobInstance: typeof UnifiedNomadJobs.stopInstance;
+export declare const restartNomadJobInstance: typeof UnifiedNomadJobs.restartInstance;
+export type AppJobStatus = UnifiedNomadJobs.AppJobStatus;