@songsid/agend 2.1.4-beta.9 → 2.1.4

package/dist/storm-window.js

@@ -0,0 +1,251 @@
+import { EventEmitter } from "node:events";
+const STORM_INCIDENT_KINDS = new Set([
+    "crash_respawn",
+    "mcp_died",
+    "mcp_auto_restart",
+    "snapshot_failed",
+    "hang",
+    "health_check_error",
+]);
+/**
+ * Fleet-wide tmux-server storm state.
+ *
+ * A server death is counted on an observed alive -> dead transition, not once
+ * per daemon report. Health ticks are deliberately out of phase, so a time
+ * window cannot distinguish thirty reports of one death from a real second
+ * crash sixteen seconds later.
+ */
+export class StormWindow extends EventEmitter {
+    now;
+    setTimer;
+    clearTimer;
+    backoffsMs;
+    stableResetMs;
+    recoveryTimeoutMs;
+    phase = "closed";
+    generation = 0;
+    crashLevel = 0;
+    crashCount = 0;
+    backoffMs = 0;
+    retryAt = null;
+    serverDown = false;
+    serverPid = null;
+    affected = new Set();
+    recovered = new Set();
+    suppressed = new Map();
+    backoffTimer = null;
+    stableTimer = null;
+    recoveryTimer = null;
+    spawnWaiters = new Set();
+    deliveryWaiters = new Map();
+    stopped = false;
+    constructor(options = {}) {
+        super();
+        this.now = options.now ?? Date.now;
+        this.setTimer = options.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+        this.clearTimer = options.clearTimer ?? clearTimeout;
+        this.backoffsMs = options.backoffsMs ?? [30_000, 2 * 60_000, 10 * 60_000];
+        this.stableResetMs = options.stableResetMs ?? 10 * 60_000;
+        this.recoveryTimeoutMs = options.recoveryTimeoutMs ?? 10 * 60_000;
+    }
+    snapshot() {
+        return {
+            phase: this.phase,
+            generation: this.generation,
+            crashLevel: this.crashLevel,
+            crashCount: this.crashCount,
+            backoffMs: this.backoffMs,
+            retryAt: this.retryAt,
+            affected: [...this.affected],
+            recovered: [...this.recovered],
+            suppressed: Object.fromEntries(this.suppressed),
+            serverPid: this.serverPid,
+        };
+    }
+    isActive() { return this.phase !== "closed"; }
+    isStopped() { return this.stopped; }
+    isSpawnBlocked() { return !this.stopped && this.phase === "backing_off"; }
+    isDeliveryHeld(name) {
+        if (this.stopped || this.phase === "closed")
+            return false;
+        if (this.phase === "backing_off" || name == null)
+            return true;
+        return this.needsRecovery(name);
+    }
+    needsRecovery(name) {
+        return this.isActive() && this.affected.has(name) && !this.recovered.has(name);
+    }
+    /** Record a confirmed tmux-server absence. Returns true for a new transition. */
+    recordServerDead(reporter, affected) {
+        for (const name of affected)
+            this.affected.add(name);
+        this.affected.add(reporter);
+        this.recovered.delete(reporter);
+        if (this.serverDown)
+            return false;
+        this.serverDown = true;
+        this.serverPid = null;
+        this.recordDistinctCrash();
+        return true;
+    }
+    /**
+     * Mark the server alive. A changed PID re-arms the generation latch. If a
+     * storm is already open, an unexpected PID swap is itself evidence that a
+     * crash/restart transition occurred between probes.
+     */
+    observeServerAlive(pid) {
+        const changed = pid != null && this.serverPid != null && pid !== this.serverPid;
+        const wasDown = this.serverDown;
+        this.serverDown = false;
+        if (pid != null)
+            this.serverPid = pid;
+        if (changed && !wasDown)
+            this.recordDistinctCrash();
+        return changed && !wasDown;
+    }
+    addAffected(name) {
+        if (!this.isActive())
+            return;
+        this.affected.add(name);
+        this.recovered.delete(name);
+    }
+    markRecovered(name) {
+        if (!this.isActive() || !this.affected.has(name))
+            return;
+        this.recovered.add(name);
+        this.releaseDelivery(name);
+        this.emit("progress", this.snapshot());
+        if (this.phase === "recovering" && this.recovered.size >= this.affected.size) {
+            this.closeWindow("recovered");
+        }
+    }
+    shouldSuppress(kind) {
+        if (!this.isActive() || !STORM_INCIDENT_KINDS.has(kind))
+            return false;
+        this.suppressed.set(kind, (this.suppressed.get(kind) ?? 0) + 1);
+        return true;
+    }
+    waitForSpawnAllowed() {
+        if (!this.isSpawnBlocked())
+            return Promise.resolve();
+        return new Promise(resolve => this.spawnWaiters.add(resolve));
+    }
+    waitForDeliveryAllowed(name) {
+        if (!this.isDeliveryHeld(name))
+            return Promise.resolve();
+        return new Promise(resolve => {
+            let waiters = this.deliveryWaiters.get(name);
+            if (!waiters) {
+                waiters = new Set();
+                this.deliveryWaiters.set(name, waiters);
+            }
+            waiters.add(resolve);
+        });
+    }
+    shutdown() {
+        this.stopped = true;
+        this.clearAllTimers();
+        this.release(this.spawnWaiters);
+        this.releaseAllDelivery();
+        this.phase = "closed";
+    }
+    recordDistinctCrash() {
+        const now = this.now();
+        const wasClosed = this.phase === "closed";
+        this.generation++;
+        this.crashCount++;
+        this.crashLevel = Math.min(this.crashLevel + 1, this.backoffsMs.length);
+        this.backoffMs = this.backoffsMs[Math.max(0, this.crashLevel - 1)] ?? this.backoffsMs.at(-1);
+        this.retryAt = now + this.backoffMs;
+        this.phase = "backing_off";
+        this.recovered.clear();
+        if (this.backoffTimer)
+            this.clearTimer(this.backoffTimer);
+        if (this.recoveryTimer) {
+            this.clearTimer(this.recoveryTimer);
+            this.recoveryTimer = null;
+        }
+        this.backoffTimer = this.setTimer(() => this.beginRecovery(), this.backoffMs);
+        this.backoffTimer?.unref?.();
+        // A storm is not stable merely because the current backoff itself lasts ten
+        // minutes. The reset clock begins only after recovery closes the window.
+        if (this.stableTimer) {
+            this.clearTimer(this.stableTimer);
+            this.stableTimer = null;
+        }
+        this.emit(wasClosed ? "opened" : "extended", this.snapshot());
+    }
+    beginRecovery() {
+        this.backoffTimer = null;
+        if (this.stopped || this.phase !== "backing_off")
+            return;
+        this.phase = "recovering";
+        this.retryAt = null;
+        this.release(this.spawnWaiters);
+        // A delivery may have parked during backoff for an instance which was not
+        // running (and therefore not in `affected`). Once the server is available,
+        // that instance can follow its normal wake path immediately; do not make it
+        // wait for unrelated recovery stragglers to close the whole window.
+        for (const name of [...this.deliveryWaiters.keys()]) {
+            if (!this.isDeliveryHeld(name))
+                this.releaseDelivery(name);
+        }
+        this.emit("recovery_due", this.snapshot());
+        this.recoveryTimer = this.setTimer(() => this.closeWindow("timeout"), this.recoveryTimeoutMs);
+        this.recoveryTimer?.unref?.();
+    }
+    closeWindow(reason) {
+        if (this.phase === "closed")
+            return;
+        if (this.backoffTimer) {
+            this.clearTimer(this.backoffTimer);
+            this.backoffTimer = null;
+        }
+        if (this.recoveryTimer) {
+            this.clearTimer(this.recoveryTimer);
+            this.recoveryTimer = null;
+        }
+        this.phase = "closed";
+        this.retryAt = null;
+        const snapshot = this.snapshot();
+        this.release(this.spawnWaiters);
+        this.releaseAllDelivery();
+        this.emit("closed", snapshot, reason);
+        this.affected.clear();
+        this.recovered.clear();
+        this.suppressed.clear();
+        this.stableTimer = this.setTimer(() => {
+            if (this.phase !== "closed")
+                return;
+            this.crashLevel = 0;
+            this.crashCount = 0;
+            this.stableTimer = null;
+            this.emit("stable", this.snapshot());
+        }, this.stableResetMs);
+        this.stableTimer?.unref?.();
+    }
+    release(waiters) {
+        for (const resolve of waiters)
+            resolve();
+        waiters.clear();
+    }
+    releaseDelivery(name) {
+        const waiters = this.deliveryWaiters.get(name);
+        if (!waiters)
+            return;
+        this.release(waiters);
+        this.deliveryWaiters.delete(name);
+    }
+    releaseAllDelivery() {
+        for (const name of [...this.deliveryWaiters.keys()])
+            this.releaseDelivery(name);
+    }
+    clearAllTimers() {
+        for (const timer of [this.backoffTimer, this.stableTimer, this.recoveryTimer]) {
+            if (timer)
+                this.clearTimer(timer);
+        }
+        this.backoffTimer = this.stableTimer = this.recoveryTimer = null;
+    }
+}
+//# sourceMappingURL=storm-window.js.map

package/dist/storm-window.js.map

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

package/dist/tips.d.ts

@@ -0,0 +1,44 @@
+import type { DailySummaryConfig } from "./types.js";
+export type TipLevel = "beginner" | "intermediate" | "advanced";
+/**
+ * Usage tips surfaced to users, graded by experience level.
+ *
+ * Beginner copy follows the user's own vocabulary: short, direct conclusions,
+ * `term = consequence` comparisons, and practical pitfalls. It introduces an
+ * AgEnD term only to explain what changes for the person using the chat.
+ * Intermediate and Advanced retain the deeper conceptual and operational
+ * material for later rollout stages.
+ *
+ * Any command, tool, or config key named here is verified against the command
+ * registry, outbound tool schemas, and `types.ts` rather than written from
+ * memory. When a capability is backend-specific (`/btw` is Claude Code only),
+ * the tip says so rather than implying it works everywhere.
+ *
+ * The Chinese text is written natively, not translated from the English — the
+ * two convey the same fact, and neither reads as a translation of the other.
+ */
+export interface Tip {
+    id: string;
+    level: TipLevel;
+    text_en: string;
+    text_zh: string;
+    /** Backend-specific tips are shown only when one of these backends is active. */
+    tags?: string[];
+}
+export declare const ADVANCED_TIP_UNLOCK_THRESHOLD = 60;
+/** Temporary rollout gate: keep authored higher tiers without selecting them yet. */
+export declare const TIPS_MAX_VISIBLE_LEVEL: TipLevel;
+export declare const TIPS: Tip[];
+export declare function canUnlockAdvancedTips(dismissedIds: ReadonlySet<string>): boolean;
+export declare function visibleTipLevels(advancedUnlocked?: boolean): ReadonlySet<TipLevel>;
+export declare function selectTip(dismissedIds: ReadonlySet<string>, random?: () => number, advancedUnlocked?: boolean, activeBackends?: ReadonlySet<string>): Tip | null;
+/** Fleet-internal daily trigger. It is intentionally not persisted in fleet.yaml. */
+export declare class DailyTipScheduler {
+    private readonly config;
+    private readonly timezone;
+    private readonly onTip;
+    private job;
+    constructor(config: DailySummaryConfig, timezone: string, onTip: () => void | Promise<void>);
+    start(): void;
+    stop(): void;
+}