agent-nuvira 3.5.0 → 3.5.2

package/dist/learning/retry-patience.js

@@ -0,0 +1,169 @@
+/**
+ * Blip patience — how long to STAY on the pair that just failed, and whether
+ * walking away is even a remedy.
+ *
+ * THE OBSERVED PROBLEM THIS ENCODES. A cloud provider does not go down for a
+ * turn: it returns 200, then a few empty/5xx responses for a handful of seconds,
+ * then serves normally again (measured repeatedly on `deepseek`). Two opposite
+ * mistakes are available, and the codebase has made both:
+ *
+ *   - FAIL FAST: give up after seconds and fold onto the next candidate — which
+ *     for that blip means silently dropping from a strong model to a weak one.
+ *     The result is answered, badly, by a model the user did not choose.
+ *   - WAIT BLINDLY: sit out a long fixed backoff on a pair that is actually
+ *     dead, and make every user of a broken provider pay for it.
+ *
+ * A timeout cannot tell those apart, so a fixed schedule is the wrong shape
+ * either way. What CAN tell them apart is the evidence already in hand:
+ *
+ *   1. THE ALTERNATIVES. Walking away is only a remedy when it does not cost
+ *      quality. If every alternative sits in a LOWER capability band, then
+ *      "fail over" means "de-escalate", and for a blip that is the worse trade —
+ *      so we wait instead. If a same-or-better band is reachable, failing over is
+ *      free and waiting is pure waste.
+ *   2. THE PAIR'S TRACK RECORD. A pair that has served real traffic with a low
+ *      error rate earns patience; a never-proven id does not.
+ *   3. THE SHAPE OF THE FAILURE. One failing step is a blip. The SAME pair
+ *      failing two steps in a row is not — patience collapses there, whatever
+ *      the alternatives look like.
+ *
+ * And the schedule's SHAPE matters as much as its total: a 2-second blink is
+ * caught by a retry at t≈1s, not at t=5s, so the early delays are dense and the
+ * late ones sparse ({@link TRANSIENT_BLIP_DELAYS_MS} → attempts at ≈1, 3, 7, 15,
+ * 30, 60s). That rides out both a blink and a real minute-long spike.
+ *
+ * PURE AND DETERMINISTIC. This module reads no clock, no registry and no config:
+ * the caller gathers the evidence (it has the registry and the ranked pool) and
+ * gets back a plan it can log. That is what makes the policy reviewable and
+ * testable one row at a time — see the table in the tests.
+ */
+import { bandRank, capabilityClassOf } from './model-capability.js';
+/**
+ * Transient (server/network/timeout) backoff, dense early and sparse late:
+ * attempts at ≈1s, 3s, 7s, 15s, 30s, 60s. Used exactly when WAITING beats
+ * walking away — no alternative, or only degrading ones.
+ */
+export const TRANSIENT_BLIP_DELAYS_MS = [1_000, 2_000, 4_000, 8_000, 15_000, 30_000];
+/**
+ * Transient backoff when a same-or-better-band candidate IS reachable: a short
+ * courtesy retry (two blinks' worth, <2s) and then the walk. Spending longer is
+ * waste — the replacement costs nothing in quality.
+ */
+export const TRANSIENT_FREE_ALTERNATIVE_DELAYS_MS = [500, 1_500];
+/**
+ * Transient backoff for a pair we have no reason to trust and no alternative to:
+ * a token wait (≈5s), then the honest failure.
+ */
+export const TRANSIENT_LAST_RESORT_DELAYS_MS = [1_000, 4_000];
+/** Empty-response patience for a proven pair — the "final verse" case. */
+export const EMPTY_PATIENCE_MS = [2_000, 5_000];
+/**
+ * Empty-response patience when EVERY alternative would de-escalate. Longer, and
+ * deliberately so: this is the one situation where the choice is literally
+ * "wait a few more seconds" vs "answer with a weaker model".
+ */
+export const EMPTY_PATIENCE_WAIT_BEATS_FOLDING_MS = [2_000, 5_000, 10_000];
+/**
+ * Error rate at or below which a verified pair counts as a proven track record.
+ * Above it the pair has failed roughly 1 call in 5, which is not something a
+ * blip explains away.
+ */
+export const PROVEN_ERROR_RATE_MAX = 0.2;
+/** Is the registry evidence strong enough to grant a pair extra patience? */
+function hasProvenTrackRecord(evidence) {
+    if (!evidence?.verified)
+        return false;
+    if ((evidence.errorRate ?? 0) > PROVEN_ERROR_RATE_MAX)
+        return false;
+    // A `probe` (catalog listing) is not evidence about answers; `telemetry` and
+    // `spot-check` are.
+    return evidence.source !== 'probe';
+}
+/**
+ * Decide how patient to be with the pair that just failed, and say why.
+ *
+ * The whole policy, in order (see the tests for each row):
+ *
+ *   1. The pair already failed an earlier step of this turn → NOT a blip. One
+ *      token wait, no empty patience.
+ *   2. Nothing to gain by patience: a same-or-better band is reachable → short
+ *      transient retry; empty patched only for a proven pair (a good pair's
+ *      first blink is still worth two short waits).
+ *   3. A PROVEN pair facing only degrading alternatives (or none) → long, dense
+ *      transient patience, and extended empty patience. This is the row that
+ *      stops a blinking strong model from being replaced by a weak one.
+ *   4. An UNPROVEN pair with nowhere better to go → a token wait; the walk (or
+ *      the honest failure) is the remedy, not optimism about a stranger.
+ */
+export function planBlipPatience(input) {
+    const currentBand = capabilityClassOf(input.current.model);
+    const currentRank = bandRank(currentBand);
+    let bestRank = -1;
+    let bestAlternativeBand;
+    for (const alternative of input.alternatives) {
+        if (!alternative?.model)
+            continue;
+        const band = capabilityClassOf(alternative.model);
+        const rank = bandRank(band);
+        if (rank > bestRank) {
+            bestRank = rank;
+            bestAlternativeBand = band;
+        }
+    }
+    const hasAlternative = bestRank >= 0;
+    const sameOrBetterReachable = bestRank >= currentRank;
+    const foldingWouldDegrade = hasAlternative && !sameOrBetterReachable;
+    const proven = hasProvenTrackRecord(input.evidence) || input.deliveredWorkThisTurn === true;
+    // 1. Two failing steps in a row is a pattern, not a blip.
+    if (input.failedEarlierStep) {
+        return {
+            transientDelaysMs: TRANSIENT_LAST_RESORT_DELAYS_MS,
+            emptyResponseDelaysMs: [],
+            bestAlternativeBand,
+            foldingWouldDegrade: false,
+            reason: `${input.current.provider}/${input.current.model} failed an earlier step too — not a blip, so no patience`,
+        };
+    }
+    // 2. A same-or-better candidate is reachable: failing over costs no quality.
+    if (sameOrBetterReachable) {
+        return {
+            transientDelaysMs: TRANSIENT_FREE_ALTERNATIVE_DELAYS_MS,
+            emptyResponseDelaysMs: proven ? EMPTY_PATIENCE_MS : [],
+            bestAlternativeBand,
+            foldingWouldDegrade: false,
+            reason: `a ${bestAlternativeBand}-band candidate is reachable — failing over costs no quality`,
+        };
+    }
+    // 3. Waiting beats folding down a band.
+    if (foldingWouldDegrade && proven) {
+        return {
+            transientDelaysMs: TRANSIENT_BLIP_DELAYS_MS,
+            emptyResponseDelaysMs: EMPTY_PATIENCE_WAIT_BEATS_FOLDING_MS,
+            bestAlternativeBand,
+            foldingWouldDegrade: true,
+            reason: `waiting on ${input.current.provider}/${input.current.model} (${currentBand}) rather than ` +
+                `de-escalating to ${bestAlternativeBand} — a blip is not a reason to downgrade`,
+        };
+    }
+    // 3b. Nowhere else to go, but the pair has a track record: waiting is the only remedy.
+    if (!hasAlternative && proven) {
+        return {
+            transientDelaysMs: TRANSIENT_BLIP_DELAYS_MS,
+            emptyResponseDelaysMs: EMPTY_PATIENCE_WAIT_BEATS_FOLDING_MS,
+            bestAlternativeBand,
+            foldingWouldDegrade: false,
+            reason: `no alternative is configured — waiting on ${input.current.provider}/${input.current.model} is the only remedy`,
+        };
+    }
+    // 4. Unproven pair: a token wait, then the walk or the honest failure.
+    return {
+        transientDelaysMs: TRANSIENT_LAST_RESORT_DELAYS_MS,
+        emptyResponseDelaysMs: hasAlternative ? [] : EMPTY_PATIENCE_MS,
+        bestAlternativeBand,
+        foldingWouldDegrade,
+        reason: hasAlternative
+            ? `${input.current.provider}/${input.current.model} has no track record — the walk is the remedy`
+            : `nothing is proven for ${input.current.provider}/${input.current.model} and there is no alternative`,
+    };
+}
+//# sourceMappingURL=retry-patience.js.map

package/dist/learning/retry-patience.js.map

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

package/dist/tools/process-liveness.d.ts

@@ -0,0 +1,227 @@
+/**
+ * Process liveness — is a long-running command WORKING, or is it HUNG?
+ *
+ * WHY THIS EXISTS. Handing a command to monitoring instead of killing it at a
+ * clock (see `run-terminal.ts`) removed the false failure, but it left the
+ * opposite hole open: a command that is genuinely STUCK — waiting on a prompt
+ * with no stdin, holding a lock, blocked on a socket that will never answer —
+ * now runs forever, and "it is still running" is not a diagnosis. Silence alone
+ * cannot tell the two apart, because a real test suite can be quiet for minutes
+ * while it works. The signal that separates them is CPU:
+ *
+ *   - producing output                → it is doing something
+ *   - burning CPU with no output      → it is computing (a build, a solver)
+ *   - NO output AND NO CPU for a long time → it is waiting for something that is
+ *     never coming. That is a hang, and it is a FACT about the process, not a
+ *     guess from a stopwatch.
+ *
+ * So this module samples the process TREE (the shell `spawn(..., { shell: true })`
+ * creates plus everything under it) for cumulative CPU time, and classifies a
+ * run into `working` / `stalled` / `hung` with the evidence attached. Callers
+ * decide what to do with the verdict; the one rule this module enforces is that
+ * `hung` requires POSITIVE evidence (measurable CPU that is not advancing) —
+ * when CPU cannot be measured, a long silence is reported as `stalled`, never as
+ * `hung`, because an unmeasurable process must not be reaped on a guess.
+ *
+ * Platform: on POSIX the table comes from `ps` (macOS + Linux), the same tool
+ * `src/cli/process-control.ts` already relies on. On Windows it comes from ONE
+ * `Get-CimInstance Win32_Process` query — which reports `ParentProcessId` AND
+ * `KernelModeTime` + `UserModeTime` (CPU, in 100ns units) — so the same rule
+ * works there instead of degrading to silence-only: the tree walk and the
+ * zero-CPU evidence are both available, with `wmic` as the fallback the rest of
+ * this repo already uses.
+ *
+ * One Windows semantic difference is worth stating plainly, because `kill`
+ * implies something it cannot deliver there: Windows has no graceful SIGTERM.
+ * `process.kill(pid, 'SIGTERM')` is an immediate termination, so the
+ * SIGTERM→grace→SIGKILL ladder is a POSIX-only refinement.
+ */
+/** How a long run is doing: the state a clock alone cannot distinguish. */
+export type Liveness = 'finished' | 'starting' | 'working' | 'stalled' | 'hung';
+/** The thresholds the classification is made from (ms). */
+export interface LivenessThresholds {
+    /** Silence after which a run is worth *reporting* as stalled. */
+    stallQuietMs: number;
+    /** Silence after which, WITH no CPU, a run is HUNG. */
+    hangQuietMs: number;
+    /** CPU ms over one sample window that counts as "it is computing". */
+    hangCpuFloorMs: number;
+}
+export declare const DEFAULT_LIVENESS_THRESHOLDS: LivenessThresholds;
+/**
+ * The thresholds, with env overrides — read at CALL time, not module load, so a
+ * test (or an operator) can change them without re-importing.
+ *
+ * `NUVIRA_HANG_QUIET_MS` is the one that matters operationally: it is how long a
+ * command may be silent AND idle before the agent is told it is hung.
+ */
+export declare function livenessThresholds(env?: NodeJS.ProcessEnv): LivenessThresholds;
+/**
+ * Parse a `ps -o time=` value into milliseconds of cumulative CPU.
+ *
+ * Formats seen in the wild: `MM:SS.cc` (macOS), `HH:MM:SS` (Linux), and
+ * `DD-HH:MM:SS` (BSD, for a long-lived process). A value that does not parse is
+ * `null` — the caller must treat "no reading" differently from "no CPU", or a
+ * formatting change would read as a hang.
+ */
+export declare function parseCpuTime(text: string): number | null;
+export interface ProcessTreeSample {
+    /** The root pid was found in the process table. */
+    found: boolean;
+    /** Cumulative CPU (ms) of the root AND every descendant; null = unmeasurable. */
+    cpuMs: number | null;
+    /** The tree, root first, children after (deepest last) — the kill order. */
+    pids: number[];
+}
+/** One row of the process table. */
+export interface ProcessRow {
+    ppid: number;
+    /** Cumulative CPU (user+sys) ms of THIS process; null = unmeasurable. */
+    cpuMs: number | null;
+    /** The process line, when the platform reports one (used for identity checks). */
+    command: string | null;
+    /**
+     * When the OS says this process STARTED, as an opaque per-platform token —
+     * `lstart` text on POSIX, Windows file-time ticks. `null` = unreadable.
+     *
+     * It exists to answer one question a pid cannot: is this the SAME process?
+     * A pid is a number the kernel reuses (Windows recycles aggressively, Linux
+     * wraps at a few million), so `pid === 1234` is not identity — it is a hint.
+     * This is a VALUE the kernel will not hand to two different processes, which
+     * is what makes it a witness. Kept as the raw token rather than a parsed date
+     * on purpose: two reads of the same process produce the same token, and
+     * comparing tokens cannot be skewed by a clock step, a timezone change or a
+     * rounding error. Unknown stays `null`, never a fabricated value.
+     */
+    startedAtText: string | null;
+}
+export type ProcessTable = Map<number, ProcessRow>;
+/**
+ * Parse a POSIX process table: `ps -eo pid=,ppid=,time=,lstart=,command=` — and
+ * the older `…,command=` shape, which parses identically minus the start token.
+ *
+ * The command column is LAST on purpose: it may contain spaces and anything else,
+ * so everything after the known fields is taken verbatim.
+ */
+export declare function parsePosixProcessTable(stdout: string): ProcessTable;
+/**
+ * Parse the Windows probe: `<pid>|<ppid>|<kernel 100ns>|<user 100ns>|<command>`.
+ *
+ * The pipe-delimited shape is the one `src/cli/process-control.ts` already uses
+ * for the same reason: it survives command lines that contain spaces, commas or
+ * quotes. A process whose CPU counters are unreadable (`KernelModeTime` is null
+ * for some system processes) yields an EMPTY field, which must stay
+ * "unmeasurable" — not zero — or an unreadable counter would read as a hang.
+ *
+ * 100ns units are converted to ms (÷10 000), the same unit `ps` reports in.
+ */
+export declare function parseWindowsProcessTable(stdout: string): ProcessTable;
+/**
+ * Parse the `wmic … /format:csv` fallback.
+ *
+ * Header-driven, because wmic emits its columns in QUERY order and the values
+ * themselves can contain commas — so the header is the only reliable index.
+ */
+export declare function parseWmicProcessTable(stdout: string): ProcessTable;
+/**
+ * One process table read, for a caller that needs the SAME view several times.
+ *
+ * A sample tick asks about every monitored run and then signals some of them, and
+ * on Windows each read costs a PowerShell start — so the tick reads the table ONCE
+ * and threads it through, instead of N times.
+ *
+ * Deliberately NOT a time-based cache. A cached table can answer about a snapshot
+ * taken before a process existed, and the answer it gives is "not found" — which
+ * a caller reads as "it is gone". That is the one direction this module must never
+ * guess in.
+ */
+export declare function processTableSnapshot(): ProcessTable | null;
+/**
+ * Sample the process tree rooted at `pid`: whether it exists, what it has cost
+ * in CPU so far, and every pid in it.
+ *
+ * The tree is the point. `spawn(command, { shell: true })` means the REAL work
+ * is a child of the shell we hold the handle to, so a sample (and a stop) that
+ * only looked at the root would report the shell's own ~0 CPU while the build
+ * underneath burned a core — the exact false hang this must not produce.
+ */
+export declare function processTreeOf(table: ProcessTable, pid: number): ProcessTreeSample;
+export declare function sampleProcessTree(pid: number, table?: ProcessTable | null): ProcessTreeSample;
+/**
+ * Is this pid running? `null` means THIS PLATFORM CANNOT TELL.
+ *
+ * The distinction is load-bearing for a run recovered from disk: "not found"
+ * must never be read as "finished" on a platform where the process table is not
+ * readable, or a restart would declare live work dead (and a dead run's recorded
+ * exit code would be reported as its verdict).
+ */
+export declare function processAlive(pid: number): boolean | null;
+/**
+ * `processAlive`, answered from a table the caller ALREADY read — so a tick that
+ * samples every monitored run (and reconciles the recovered ones) costs one
+ * process listing, not one per run.
+ */
+export declare function tableAlive(table: ProcessTable | null, pid: number): boolean | null;
+/**
+ * One process's row, cross-platform: `null` when the platform cannot read the
+ * table at all, `{ found: false }` when the pid is simply not there.
+ *
+ * The distinction matters to a caller that has to decide whether a pid is still
+ * OURS: "gone" is an answer, "cannot tell" is not.
+ */
+export declare function lookupProcess(pid: number): {
+    found: boolean;
+    command: string | null;
+    startedAtText: string | null;
+} | null;
+export interface LivenessInput {
+    /** The run still exists (the registry has not seen it exit). */
+    alive: boolean;
+    /** Bytes produced since the run started. */
+    bytes: number;
+    /** ms since the last output byte (or since the start when nothing came). */
+    quietMs: number;
+    /** ms since the run started. */
+    ageMs: number;
+    /** CPU ms now, and at the previous sample (null = unmeasurable). */
+    cpuMs: number | null;
+    prevCpuMs: number | null;
+    /** ms between the two CPU samples. */
+    sampleWindowMs: number;
+}
+export interface LivenessVerdict {
+    verdict: Liveness;
+    /** The evidence, in words — this is what the agent and the operator read. */
+    why: string;
+}
+/** `45s` / `3m 05s` — how long, for a human reading a message. */
+export declare function formatSpan(ms: number): string;
+/**
+ * Classify a run from its evidence. Deterministic and pure, so the decision can
+ * be asserted directly instead of inferred from a message.
+ *
+ * Order matters, and it is deliberately "innocent until proven hung":
+ * output recently → working; CPU advancing → working; only then, silence PLUS a
+ * measurable absence of CPU → hung. Anything we cannot prove lands in `stalled`,
+ * which is reported but never reaped.
+ */
+export declare function classifyLiveness(input: LivenessInput, thresholds?: LivenessThresholds): LivenessVerdict;
+/**
+ * Stop a process TREE, deepest first — the shell we spawned and the real work
+ * under it.
+ *
+ * A plain `child.kill()` reaches only the shell, which is why a "stopped" hung
+ * build can keep running: the shell dies, the compiler it launched does not.
+ * Best-effort throughout — a pid that exited between the sample and the signal
+ * must not throw, and a failed signal falls back to the child handle.
+ *
+ * On Windows the tree comes from WMI (`Get-CimInstance`), so this genuinely
+ * reaches grandchildren there too; if that probe is unavailable the tree is just
+ * the root, which is the old behaviour rather than a regression. Note that a
+ * Windows "signal" takes effect immediately — there is no graceful SIGTERM to
+ * follow with a SIGKILL.
+ */
+export declare function killProcessTree(pid: number, signal: NodeJS.Signals, child?: {
+    kill(signal?: NodeJS.Signals | number): boolean;
+}, table?: ProcessTable | null): number[];
+//# sourceMappingURL=process-liveness.d.ts.map

package/dist/tools/process-liveness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-liveness.d.ts","sourceRoot":"","sources":["../../src/tools/process-liveness.ts"],"names":[],"mappings":"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"}