@hivemagnus/magnus-agent 1.1.2 → 1.1.3

package/dist/upgrade/self-upgrade.d.ts

@@ -1,6 +1,23 @@
-import { type AgentSelfUpgradeStatus, type AgentUpgradeRequest } from '@hivemagnus/magnus-contracts';
+import { type AgentSelfUpgradeStatus, type AgentUpgradeReport, type AgentUpgradeRequest } from '@hivemagnus/magnus-contracts';
 export declare const STATE_FILE = "upgrade-state.json";
+export declare const LOCK_FILE = "upgrade-state.lock";
+/** Written while on trial when heartbeats cannot reach the control API; the launcher then extends the trial. */
+export declare const ALIVE_FILE = "trial-alive.json";
 export declare const AGENT_PACKAGE = "@hivemagnus/magnus-agent";
+/** The launcher protocol this agent needs. Kept equal to `magnusAgent.minLauncher` in package.json. */
+export declare const MIN_LAUNCHER_PROTOCOL = 1;
+/** Oldest npm the upgrade steps are tested with (overrides, `audit signatures`). */
+export declare const MIN_NPM_VERSION = "10.0.0";
+/** Per-step limits and the total budget; the server waits 15 minutes for an upgrade. */
+export declare const STEP_TIMEOUT_MS: {
+    readonly pack: number;
+    readonly install: number;
+    readonly audit: number;
+    readonly smoke: 60000;
+};
+export declare const STAGE_BUDGET_MS: number;
+/** After staging, the agent exits even if a graceful shutdown hangs. */
+export declare const EXIT_BACKSTOP_MS = 60000;
 export interface UpgradeState {
     state: 'idle' | 'staged' | 'trial' | 'confirmed' | 'reverted' | 'failed';
     from: string | null;
@@ -9,6 +26,7 @@ export interface UpgradeState {
     attempt?: number;
     maxAttempts?: number;
     trialDeadline?: string;
+    extended?: number;
     reason?: string | null;
     updatedAt?: string;
 }
@@ -20,51 +38,108 @@ export declare function readUpgradeState(dir: string): UpgradeState | null;
  * the owner can still replace or remove it. Otherwise this does nothing.
  */
 export declare function adoptInstallOwner(dir: string, path: string, uid?: number | undefined): void;
+/** Temp file, fsync, rename, fsync the directory: a crash leaves the old or the new content, never a torn file. */
+export declare function writeDurable(dir: string, name: string, text: string, mode?: number): void;
 export declare function writeUpgradeState(dir: string, state: UpgradeState): void;
+/** Atomically point `<dir>/<name>` (current, last-good) at versions/<version>. */
+export declare function pointLink(dir: string, name: string, version: string): void;
 export declare function pointCurrentAt(dir: string, version: string): void;
+/** The X of a `<name> -> versions/X` link, or null. */
+export declare function linkVersion(dir: string, name: string): string | null;
+/** versions/<version> holds a runnable agent. */
+export declare function versionComplete(dir: string, version: string | null | undefined): boolean;
+/** ./current resolves to versions/<version>. */
+export declare function runsVersion(dir: string, version: string): boolean;
+/** O_EXCL lock shared with the launcher around a read-modify-write of the state file. Synchronous; waits up to timeoutMs. */
+export declare function withStateLock<T>(dir: string, fn: () => T, { timeoutMs, staleMs }?: {
+    timeoutMs?: number | undefined;
+    staleMs?: number | undefined;
+}): T;
 export type Layout = AgentSelfUpgradeStatus['layout'];
 export declare function detectLayout(dir: string, env?: NodeJS.ProcessEnv): Layout;
+export interface NpmCommand {
+    command: string;
+    args: string[];
+    /** Prepended to PATH so npm and lifecycle scripts run the agent's own Node.js. */
+    pathPrefix: string;
+    version: string | null;
+    problem: string | null;
+}
+/**
+ * The npm that belongs to the running Node.js (npm-cli.js beside it, run with
+ * process.execPath), then MAGNUS_AGENT_NPM, then npm on PATH. A systemd PATH
+ * often lacks the directory of a version-managed Node.js.
+ */
+export declare function resolveNpm(env?: NodeJS.ProcessEnv, execPath?: string): NpmCommand;
 /** Whether this agent can upgrade itself, and why not. Reported with every heartbeat. */
 export declare function selfUpgradeStatus(version: string, env?: NodeJS.ProcessEnv): AgentSelfUpgradeStatus;
+/** The upgrade state when `version` is the one on trial. */
+export declare function trialOf(version: string, env?: NodeJS.ProcessEnv): UpgradeState | null;
+/** Tell the launcher this version runs but cannot reach the control API, so it extends the trial instead of reverting. */
+export declare function recordTrialAlive(version: string, error: string, env?: NodeJS.ProcessEnv, now?: number): boolean;
+/** A failed heartbeat POST that says nothing about this version: no answer, or a gateway with no upstream. */
+export declare function controlApiUnreachable(error: unknown): boolean;
+/** `export const LAUNCHER_PROTOCOL = N` in a launcher file, without running it. */
+export declare function declaredLauncherProtocol(path: string): number | null;
 /**
- * Called after every accepted heartbeat: the first one from a version on trial
- * confirms it, and versions other than the previous and the current one are pruned.
+ * Replace launcher/launcher.mjs with the confirmed version's copy when that
+ * declares a higher protocol and passes a self-check (`--protocol`). The
+ * running launcher keeps its loaded code; the new one is used from the next
+ * service start. The previous file is kept as launcher.mjs.previous.
+ */
+export declare function upgradeLauncher(dir: string, version: string, execPath?: string): string | null;
+/**
+ * Called after every accepted heartbeat: the first one from a version on
+ * trial confirms it (unless the trial window has closed or ./current no
+ * longer runs it), records it as last-good, and prunes other versions.
  */
 export declare function confirmTrial(version: string, env?: NodeJS.ProcessEnv, now?: Date): boolean;
 export declare function pruneVersions(dir: string, keep: ReadonlyArray<string | null>): void;
 export declare class SelfUpgradeError extends Error {
     readonly code: string;
-    readonly status: 400 | 409 | 422 | 500;
-    constructor(code: string, message: string, status?: 400 | 409 | 422 | 500);
+    readonly status: 400 | 409 | 422 | 500 | 504;
+    constructor(code: string, message: string, status?: 400 | 409 | 422 | 500 | 504);
+}
+export interface RunResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+    timedOut?: boolean;
 }
 export interface Runner {
     (command: string, args: readonly string[], options: {
         cwd: string;
         env: NodeJS.ProcessEnv;
-    }): Promise<{
-        code: number;
-        stdout: string;
-        stderr: string;
-    }>;
+        timeoutMs?: number;
+    }): Promise<RunResult>;
 }
+/** Runs a command in its own process group; at timeoutMs the whole group gets SIGTERM, then SIGKILL. */
 export declare const runProcess: Runner;
 /** npm pack names files `<scope>-<name>-<version>.tgz`. */
 export declare function tarballName(version: string): string;
 export declare function sha512Integrity(file: string): string;
 /** Other @hivemagnus tarballs in the source directory, used instead of the registry (offline nodes). */
 export declare function sourceOverrides(sourceDir: string, agentTarball: string): Record<string, string>;
+/** Why `engines.node` rules out `nodeVersion`, or null. Range forms satisfiesRange cannot judge are not refused. */
+export declare function engineProblem(range: string | undefined, nodeVersion: string): string | null;
 export interface StageOptions {
     request: AgentUpgradeRequest;
     version: string;
     env?: NodeJS.ProcessEnv;
     run?: Runner;
     now?: Date;
+    /** Monotonic-enough milliseconds for the step budget (tests). */
+    clock?: () => number;
+    nodeVersion?: string;
 }
 export interface StageResult {
     from: string;
     to: string;
     integrity: string;
     requestId: string;
+    /** The same request was already handled: nothing was changed, `upgrade` is the current state. */
+    repeated?: boolean;
+    upgrade?: AgentUpgradeReport;
 }
 /** Download, verify, install and switch. The caller exits afterwards so the launcher starts the new version. */
 export declare function stageUpgrade(options: StageOptions): Promise<StageResult>;