@kici-dev/orchestrator 0.18.0 → 0.20.0

package/dist/agent/registry.d.ts

@@ -70,8 +70,16 @@ export interface AgentEntry {
      * In memory rather than DB-backed, unlike reboot-pending: the destroy is issued by
      * this process, lasts seconds, and ends with the WebSocket close that removes the
      * entry — there is nothing to outlive.
+     *
+     * Also set when the agent itself reports `draining` on `agent.status` (a SIGUSR1
+     * drain, or a single-job agent that accepted its job); see {@link drainReported}.
      */
     draining: boolean;
+    /**
+     * The agent reported `draining` itself. Its drain is terminal for this connection,
+     * so {@link AgentRegistry.clearDraining} (the warm-pool undo) leaves it draining.
+     */
+    drainReported?: boolean;
     /**
      * Epoch ms until which the agent is held out of routing after it rejected a
      * dispatch as busy. Unset when no hold is in force. See {@link AgentRegistry.markBusyHeld}.
@@ -337,8 +345,11 @@ export declare class AgentRegistry {
      */
     isRegistered(agentId: string): boolean;
     /**
-     * Condemn an agent before a warm-pool destroy: it stays registered and finishes its
-     * current work, but takes no new dispatches.
+     * Condemn an agent: it stays registered and keeps finishing its current work,
+     * but takes no new dispatches.
+     *
+     * Called before a warm-pool destroy is issued. An agent that reports its own
+     * drain goes through {@link markDrainReported} instead.
      *
      * @returns the agent's `activeJobs`, so the caller can see a job claimed between its
      *   idle check and this mark and back out; `undefined` when not registered
@@ -382,7 +393,15 @@ export declare class AgentRegistry {
      * free slot now.
      */
     clearExpiredBusyHold(agentId: string, now?: number): void;
-    /** Undo {@link markDraining} — a destroy that was rejected leaves the agent alive. */
+    /**
+     * The agent reported on `agent.status` that it takes no new job: a drain, or a
+     * single-job agent that has accepted its job. Terminal for this connection.
+     */
+    markDrainReported(agentId: string): void;
+    /**
+     * Undo {@link markDraining} — a destroy that was rejected leaves the agent alive.
+     * An agent that reported its own drain stays draining.
+     */
     clearDraining(agentId: string): void;
     get(agentId: string): AgentEntry | undefined;
     getByWs(ws: WsLike): AgentEntry | undefined;

package/dist/cli/commands/shared/container-agent-image-check.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The container-scaler agent image check `kici-admin orchestrator upgrade`
+ * runs before it restarts the service.
+ *
+ * A container scaler spawns each agent from the image its label set names, not
+ * from the upgraded orchestrator. So an upgrade leaves container agents on the
+ * old release when a label set pins an older `kici-agent:<version>`, or names
+ * the moving `:latest` tag with the default `imagePullPolicy: IfNotPresent`: a
+ * host that already pulled `:latest` keeps that image. The check only warns:
+ * it never rewrites the operator's scaler config and never stops the upgrade.
+ */
+import { type ScalerConfig } from '../../../scaler/types.js';
+/** Why a container label set keeps spawning an old agent after the upgrade. */
+export declare enum AgentImageIssue {
+    /** `:latest` (or no tag) with `IfNotPresent`: the host keeps the image it pulled. */
+    MovingTag = "moving-tag",
+    /** A `kici-agent:<version>` older than the release the upgrade installs. */
+    OlderPin = "older-pin"
+}
+export interface AgentImageFinding {
+    issue: AgentImageIssue;
+    scaler: string;
+    labels: string[];
+    image: string;
+    message: string;
+}
+/** An image reference split into its repository, tag and digest. */
+export interface ImageRefParts {
+    repository: string;
+    tag: string | null;
+    digest: string | null;
+}
+/**
+ * Split `[registry/]path/name[:tag][@digest]`. A `:` before the last `/` is a
+ * registry port, not a tag.
+ */
+export declare function parseImageRef(image: string): ImageRefParts;
+export interface CheckAgentImagesArgs {
+    config: ScalerConfig;
+    /** The release the upgrade installs, or null when the caller does not know it. */
+    targetVersion: string | null;
+    /** The main scaler config file, for the remedy text. */
+    scalerConfigPath: string;
+    /** The `KICI_SCALER_CONFIG_DIR` directory, when one is set. */
+    scalerConfigDir?: string;
+}
+/**
+ * Every container-scaler label set whose agent image an upgrade to
+ * `targetVersion` leaves unchanged. An empty result means each agent image is
+ * pinned to the target (or newer), pulled on every spawn, or not a KiCI agent.
+ */
+export declare function checkContainerAgentImages(args: CheckAgentImagesArgs): AgentImageFinding[];
+export interface WarnAgentImagesArgs {
+    envFilePath: string;
+    workingDirectory: string;
+    /** The release the upgrade installs, or null when the caller does not know it. */
+    targetVersion: string | null;
+    warn: (line: string) => void;
+}
+/**
+ * Print one warning per container label set whose agent image the upgrade
+ * leaves unchanged. Never throws, and stays silent when the env file or the
+ * scaler config cannot be read: the bare-metal `binaryPath` check, which runs
+ * first on the same files, already reports that.
+ */
+export declare function warnAboutContainerAgentImages(args: WarnAgentImagesArgs): Promise<void>;
+//# sourceMappingURL=container-agent-image-check.d.ts.map

package/dist/cli/commands/shared/versioned-upgrade.d.ts

@@ -265,13 +265,13 @@ export declare function npmReleaseReadsEnvFile(target: NpmInstallTarget, version
     error: string;
 };
 /**
- * Install `<owningPackage>@<version>` globally under the unit's pinned node, so
- * it lands in the prefix the unit's ExecStart resolves from. npm derives its
- * global prefix from the node that runs npm-cli.js, and the unit's
- * `<pinned>/bin/npm` (an `env node` shebang or a version-manager wrapper)
- * resolves `node` off PATH; run bare it would inherit the shell's active node,
- * the mise/nvm/asdf drift this upgrade fixes. Hence the pinned bin dir goes
- * first on PATH ({@link npmEnv}).
+ * Install `<owningPackage>@<version>` globally into the prefix the unit's
+ * ExecStart resolves from, with the unit's pinned node. Without an explicit
+ * prefix npm derives one from the node that runs npm-cli.js, or takes the
+ * `npm_config_prefix` the caller's environment carries (`npx` exports its
+ * own), so the install would land where the unit never reads it. The pinned
+ * node runs npm-cli.js directly, skipping a version-manager wrapper at
+ * `<pinned>/bin/npm`, which also keeps the shell's active node out of it.
  */
 export declare function installGlobalPackage(target: NpmInstallTarget, version: string, run?: SpawnRunner): {
     ok: boolean;

package/dist/cli/service/instance/manifest.d.ts

@@ -57,16 +57,42 @@ export declare function writeInstallManifest(instanceDir: string, fresh: Instanc
  * Where an npm-source upgrade installs, from a unit's launch spec.
  * `owningPackage` is the top-level global package ExecStart runs (`kici-admin`
  * when the component loads through its nested node_modules, else
- * `@kici-dev/<component>`). `npmPath` sits beside the pinned node, so
- * `npm install -g` lands in the prefix ExecStart resolves from, whatever the
- * shell's active node.
+ * `@kici-dev/<component>`). `globalPrefix` is the npm prefix the launch entry
+ * lives in; every npm call passes it as `--prefix`, because the caller's
+ * environment can name another one (`npx` exports `npm_config_prefix`).
+ * `npmInvocation` runs `npm-cli.js` with the pinned node when it sits beside
+ * that node, so a version-manager wrapper at `npmPath` (mise's reshim needs
+ * mise on PATH) is never started.
  */
 export interface NpmInstallTarget {
     nodeExecPath: string;
     npmPath: string;
     owningPackage: string;
+    globalPrefix: string;
+    npmInvocation: {
+        cmd: string;
+        preArgs: string[];
+    };
 }
+/**
+ * The resolution of a launch spec to an install target. `no-entry` covers an
+ * opaque `--binary` install and a path outside `node_modules`; `not-global`
+ * an entry under a local `node_modules` tree, whose prefix the unit's npm
+ * cannot install into with `-g`.
+ */
+export type NpmInstallResolution = {
+    ok: true;
+    target: NpmInstallTarget;
+} | {
+    ok: false;
+    reason: 'no-entry';
+} | {
+    ok: false;
+    reason: 'not-global';
+    entry: string;
+};
 export declare function resolveNpmInstallTarget(spec: LaunchSpec, component: Component, opts: {
     windows: boolean;
-}): NpmInstallTarget | null;
+    exists?: (p: string) => boolean;
+}): NpmInstallResolution;
 //# sourceMappingURL=manifest.d.ts.map