jishushell 0.6.5 → 0.7.3

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

@@ -1,307 +0,0 @@
-/**
- * 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 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); 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>>;
-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): Promise<{
-    stdout: string;
-    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;
-/** @deprecated Use {@link getMaxAppMemoryMB} from config.ts for the live ceiling. */
-export declare const MAX_MEMORY_MB = 4096;
-/** @deprecated Use {@link getMaxAppMemoryMB} from config.ts for the live ceiling. */
-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 {
-    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 startAppJob 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(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.
-     */
-    export 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).
-     */
-    export 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.
-     */
-    export function waitForRunning(appId: 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 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.
-     */
-    export 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").
-     */
-    export 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).
-     */
-    export function execInApp(appId: string, taskName: string | undefined, command: string[], timeoutMs?: number): Promise<ExecResult>;
-    export function streamExecInApp(appId: 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 startInstance(nomadJobId: string): Promise<ServiceResult>;
-    export function stopInstance(nomadJobId: string, purge?: boolean): Promise<ServiceResult>;
-    export function restartInstance(nomadJobId: string): Promise<ServiceResult>;
-    export function getInstanceLogs(nomadJobId: string, lines?: number, logType?: string): Promise<string[]>;
-    export function execInInstance(nomadJobId: string, command: string[], timeoutMs?: number): 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 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 validateNomadPortHostNetworks: typeof UnifiedNomadJobs.validateNomadPortHostNetworks;
-export declare const buildNomadReservedPort: typeof UnifiedNomadJobs.buildNomadReservedPort;
-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;
-export declare const __aggregateHealthStatusForTests: typeof UnifiedNomadJobs.aggregateHealthStatus;