agent-tempo 1.0.1

package/dist/http/aggregate.d.ts

@@ -0,0 +1,319 @@
+import type { TempoClient } from '../client/interface';
+import type { HostProfile, EnsembleChatMessage, ScheduleEntry } from '../types';
+import { EnsembleEventBus, type EventBus } from './event-bus';
+import { SeqAllocator } from './event-id';
+import type { PlayerSummaryV1 } from './event-types';
+/** Default cadence per spec §8. */
+export declare const DEFAULT_POLL_INTERVAL_MS = 750;
+/**
+ * #336/#529 site 6 — correctness deadline for `listEnsemblesBounded()`
+ * inside `collect()`. 500ms < 750ms cadence leaves ≥250ms headroom for
+ * `applyDiff()` + per-ensemble fan-out + emission. Architect's call:
+ * the 15s `tickWatchdogMs` is the *liveness* guard; this 500ms is the
+ * *correctness* guard preventing partial-input ensemble diffs.
+ */
+export declare const AGGREGATE_LIST_DEADLINE_MS = 500;
+/**
+ * #550 — consecutive-failure cap for the per-ensemble fan-out
+ * carry-forward. After this many `'failed'` outcomes in a row, the
+ * ensemble is promoted from `'failed'` (carry-forward in liveNames) to
+ * `'gone'` (excluded → emits `ensemble.destroyed`). Matches the
+ * 15s tick watchdog ceiling at 750ms cadence: 20 ticks × 750ms ≈ 15s.
+ * Operator-coherent: "can't observe → eventually treat as gone."
+ *
+ * Counted as the threshold to EXCEED (cf > K) so the spec table holds:
+ * 20 consecutive `'failed'` ticks stay 'failed'; the 21st promotes.
+ */
+export declare const MAX_CONSECUTIVE_FAILURES = 20;
+/**
+ * #336/#529 site 6 — sentinel thrown by `collect()` when the
+ * visibility-iterator deadline trips. `tick()`'s catch logs it calmly
+ * and SKIPS `applyDiff()`, preserving `knownEnsembles` so the next
+ * successful tick diffs against the truthful prior set rather than
+ * emitting phantom `ensemble.destroyed` events.
+ *
+ * Modeled as a distinct error class so the catch can branch
+ * informatively (`if (err instanceof TickSkipped)`) without parsing
+ * error messages — and so callers downstream don't accidentally
+ * propagate it as a fatal error.
+ */
+export declare class TickSkipped extends Error {
+    readonly name = "TickSkipped";
+    constructor(reason: string);
+}
+/** Per-ensemble tracking state across ticks. */
+interface EnsembleTrack {
+    bus: EnsembleEventBus;
+    /**
+     * #550 — consecutive `'failed'` outcomes since the last `'ok'` in
+     * `collect()`'s per-ensemble fan-out. Reset to 0 on a successful
+     * fan-out; incremented on `'failed'`. When it exceeds
+     * {@link MAX_CONSECUTIVE_FAILURES} the ensemble is promoted to
+     * `'gone'` and its track torn down by `applyDiff`. While this
+     * counter is `> 0` the cluster diff still treats the ensemble as
+     * alive (no phantom `ensemble.destroyed`).
+     */
+    consecutiveFailures: number;
+    /** Last seen player phase, keyed by playerId. */
+    playerPhases: Map<string, string | undefined>;
+    /**
+     * Adapter family per playerId — used to faithfully reconstruct the
+     * prior `AggregateEnsembleSnapshot` view at tick boundaries (see #535).
+     * Pre-#535 the prior carried a hardcoded `agentType: 'claude'` because
+     * the wire union was closed at `'claude' | 'copilot' | 'mock'`; once the
+     * union mirrors `AgentType`, the prior must carry a real adapter type
+     * so the type system can't be blindsided by a future entry. Set in
+     * lockstep with `playerPhases` (`player.added` → `set`, `player.removed`
+     * → `delete`); agentType is treated as immutable for a player's
+     * lifetime (matches `MaestroPlayerInfo` semantics).
+     */
+    playerAgentTypes: Map<string, PlayerSummaryV1['agentType']>;
+    /** Last (paused, held) tuple. */
+    flags: {
+        paused: boolean;
+        held: boolean;
+    } | null;
+    /** SHA-256 of last emitted schedules JSON. */
+    schedulesHash: string | null;
+    /** Recently-emitted chat ids — bounded LRU set. */
+    chatIds: Set<string>;
+    /** Insertion-order list backing the LRU eviction. */
+    chatIdOrder: string[];
+}
+/** Aggregate-level snapshot — small projection of `EnsembleStateV1` plus the bits we diff. */
+export interface AggregateEnsembleSnapshot {
+    ensemble: string;
+    hasConductor: boolean;
+    flags: {
+        paused: boolean;
+        held: boolean;
+    };
+    players: PlayerSummaryV1[];
+    schedules: ScheduleEntry[];
+    chat: EnsembleChatMessage[];
+}
+/**
+ * #550 — Per-ensemble fan-out outcome. The discriminated union lets
+ * `collect()` distinguish "we observed full state" (`'ok'`) from
+ * "ensemble is genuinely destroyed per Temporal" (`'gone'`, only on
+ * `EnsembleNotFoundError`) from "we couldn't observe this tick — try
+ * again next time" (`'failed'`, any other error).
+ *
+ * The classification decision lives in `collect()`'s `Promise.all`
+ * body; `applyDiff` stays ignorant of the failure mode and just
+ * consumes the resulting `AggregateSnapshot.liveEnsembleNames` set
+ * plus the `'ok'`-only `ensembles` array.
+ *
+ * Why this matters: lumping both into `null` (pre-#550 behavior)
+ * caused the cluster diff to emit `ensemble.destroyed` for ensembles
+ * whose fan-out merely timed out, producing phantom destroy events
+ * to every SSE subscriber every time a single per-ensemble query
+ * stalled.
+ */
+export type FanoutResult = {
+    kind: 'ok';
+    snapshot: AggregateEnsembleSnapshot;
+} | {
+    kind: 'gone';
+    name: string;
+} | {
+    kind: 'failed';
+    name: string;
+};
+/** Aggregate cluster snapshot — what one tick gathers. */
+export interface AggregateSnapshot {
+    capturedAt: string;
+    /**
+     * Only `'ok'` fan-out results — i.e. ensembles for which we observed
+     * full per-ensemble state this tick. `applyDiff` iterates this for
+     * per-ensemble diff events (player.added, flags.changed, …).
+     */
+    ensembles: AggregateEnsembleSnapshot[];
+    /**
+     * #550 — Cluster-diff input. Slim `{ensemble, hasConductor}` entries
+     * for the union of `'ok'` + `'failed'` outcomes (`'gone'` results
+     * excluded — they're the only kind that should trigger
+     * `ensemble.destroyed`).
+     *
+     * `hasConductor` for `'ok'` entries reflects the truthful
+     * fresh-this-tick value from `buildEnsembleSnapshot`; for `'failed'`
+     * entries it carries forward from the listEnsembles prelude (the
+     * cluster-list result already knew `hasConductor` per ensemble,
+     * even if the per-ensemble fan-out timed out). This keeps
+     * `ensemble.created` payloads truthful even when the very first
+     * tick for a new ensemble is a fan-out failure (researcher's
+     * "one-tick-delayed" carry-forward semantics).
+     *
+     * `applyDiff` consumes this directly without re-classifying the
+     * failure mode — the carry-forward decision is fully encoded by
+     * `collect()` upstream (architect's spec).
+     */
+    livePrelude: Array<{
+        ensemble: string;
+        hasConductor: boolean;
+    }>;
+    hostProfiles: Record<string, HostProfile>;
+}
+/**
+ * Stable JSON canonicalization — keys sorted, no extraneous whitespace.
+ * Used for SHA-256 diff suppression so reordered key emits don't
+ * produce false-positive `*.changed` events.
+ */
+export declare function canonicalize(value: unknown): string;
+/** SHA-256 of `canonicalize(value)`. */
+export declare function hashOf(value: unknown): string;
+/**
+ * Diff two AggregateEnsembleSnapshots and the prior tracking state to
+ * produce the events the bus should emit. Pure function — no I/O,
+ * easily unit-testable.
+ *
+ * Mutates `track` to reflect the post-emit state (this is intentional;
+ * the caller calls `emit` for each returned event and trusts the
+ * tracker is now current).
+ */
+export interface DiffEvent {
+    type: import('./event-types').SseEventKind;
+    payload: unknown;
+}
+export declare function diffEnsembleSnapshot(prev: AggregateEnsembleSnapshot | null, next: AggregateEnsembleSnapshot, track: Pick<EnsembleTrack, 'playerPhases' | 'playerAgentTypes' | 'flags' | 'schedulesHash' | 'chatIds' | 'chatIdOrder'>, capturedAt: string): DiffEvent[];
+/**
+ * Diff host profiles map → per-host events. Pure function.
+ */
+export declare function diffHostProfiles(prevHashes: Map<string, string>, nextProfiles: Record<string, HostProfile>): {
+    events: DiffEvent[];
+    hashes: Map<string, string>;
+};
+/**
+ * Diff ensemble-name set → ensemble.created / ensemble.destroyed events.
+ *
+ * #550 — accepts the slim `{ensemble, hasConductor}` shape rather than
+ * a full `AggregateEnsembleSnapshot[]`. The full-snapshot type still
+ * satisfies it structurally, so existing tests passing
+ * `AggregateEnsembleSnapshot[]` continue to compile. The slimmer
+ * input lets `applyDiff` feed the `livePrelude` carry-forward set
+ * (which contains stub entries for `'failed'` outcomes that have no
+ * full snapshot this tick).
+ */
+export declare function diffEnsembleSet(prev: ReadonlySet<string>, nextEnsembles: ReadonlyArray<{
+    ensemble: string;
+    hasConductor: boolean;
+}>, capturedAt: string): {
+    events: DiffEvent[];
+    names: Set<string>;
+};
+export interface AggregateRunnerOptions {
+    client: TempoClient;
+    /** Shared per-process bootEpoch — same value used everywhere. */
+    bootEpoch: number;
+    /** Default 750 ms; tests pin lower values. */
+    pollIntervalMs?: number;
+    /** Test seam — defaults to `Date.now`. */
+    now?: () => number;
+    /** Per-ensemble bus override (mainly tests). Default constructs `EnsembleEventBus`. */
+    busFactory?: (ensemble: string, allocator: SeqAllocator) => EnsembleEventBus;
+    /**
+     * Issue #433 — watchdog ceiling for an in-flight tick. If a tick exceeds
+     * this without finishing, the watchdog force-clears `inFlight` so the
+     * next scheduled tick can run. Defaults to `20 × pollIntervalMs` (15s
+     * at the production default). Tests pin a small value to assert the
+     * unwedge behavior.
+     */
+    tickWatchdogMs?: number;
+}
+/**
+ * Coordinates the poll loop and owns the per-ensemble + global buses.
+ * Daemon constructs one of these after `runDaemonBoot`. Hot path is
+ * `tick()` — production schedules it on a timer, tests call it
+ * directly for deterministic diffing.
+ */
+export declare class AggregateRunner {
+    private readonly client;
+    readonly bootEpoch: number;
+    private readonly pollIntervalMs;
+    private readonly now;
+    private readonly busFactory;
+    /** Per-ensemble bus + tracking state. */
+    private readonly tracks;
+    /** Global bus — handles `ensemble.created/destroyed` + `host_profile.changed`. */
+    private readonly _globalBus;
+    private readonly globalSeqAllocator;
+    /** Last seen ensemble names + host profile hashes for diff. */
+    private knownEnsembles;
+    private hostHashes;
+    /** Loop state. */
+    private timer;
+    private inFlight;
+    private skipCount;
+    /** Last skip-warning emit time — rate-limited so a wedged Temporal doesn't drown the log. */
+    private lastSkipWarn;
+    private stopped;
+    /**
+     * Issue #433 — tick generation counter. Incremented each time a tick
+     * starts. The watchdog stamps the current generation when it force-clears
+     * `inFlight`; a late-arriving completion checks `myGen === currentGen`
+     * before resetting state so it doesn't clobber a fresh tick that the
+     * watchdog already handed to the loop.
+     */
+    private tickGen;
+    /**
+     * Watchdog ceiling — if a tick exceeds this without finishing, the
+     * watchdog force-clears `inFlight` so the next scheduled tick can run.
+     * Default: 20 × poll interval (15s at the 750ms default). Should be
+     * comfortably larger than `pollIntervalMs × DEFAULT_QUERY_TIMEOUT_MS /
+     * pollInterval` so `queryHandleWithTimeout`-bounded ticks finish well
+     * inside the watchdog window in normal operation.
+     */
+    private readonly tickWatchdogMs;
+    constructor(opts: AggregateRunnerOptions);
+    /**
+     * Begin polling on the configured cadence.
+     *
+     * **One-shot by design**: a single `start()` schedules the first
+     * tick immediately and chains subsequent ticks via `setTimeout` —
+     * each tick reschedules the next as it completes. Repeated
+     * `start()` calls are no-ops once the chain is running (and after
+     * `stop()` flips `stopped = true`, future `start()` calls are
+     * also no-ops). Tests that want to drive ticks deterministically
+     * skip `start()` and call `tick()` directly. PR #324 review nit
+     * folded in.
+     */
+    start(): void;
+    /** Stop polling. Buses stay alive — daemon owns their close lifecycle. */
+    stop(): void;
+    /** Drain every bus + clear tracking. */
+    close(): void;
+    /** The global bus — exposed for the SSE handler's `/v1/events` route. */
+    globalBus(): EventBus;
+    /**
+     * Look up (or lazily build) the per-ensemble bus. SSE handler uses
+     * this to subscribe a new client; aggregate diff uses it to emit
+     * `player.added`-and-friends.
+     */
+    getOrCreateEnsembleBus(ensemble: string): EnsembleEventBus;
+    /** Returns the bus for an ensemble if one exists, else `null`. */
+    getEnsembleBus(ensemble: string): EnsembleEventBus | null;
+    /** Total live subscriber count across all buses — `/v1/health.subscriberCount`. */
+    totalSubscriberCount(): number;
+    /**
+     * Run one diff pass. Production schedules this on a timer; tests
+     * call it directly. Serial-with-skip per §8 — if a previous tick
+     * is still in flight, this one skips with a warn-log.
+     *
+     * **Watchdog (#433)**. Each tick takes a generation stamp. After
+     * `tickWatchdogMs` elapses without completion, the watchdog bumps
+     * the generation and clears `inFlight` so the next scheduled tick
+     * can run. The hung tick's eventual completion checks its own
+     * generation against the current one; if it's stale (watchdog
+     * already advanced past it), it returns without touching `inFlight`
+     * — the new tick owns that flag now.
+     */
+    tick(): Promise<void>;
+    /** Fetch the current cluster state via `TempoClient`. */
+    collect(): Promise<AggregateSnapshot>;
+    /** Apply diff and emit events — exposed for tests that want to inject fixtures. */
+    applyDiff(snapshot: AggregateSnapshot): void;
+    private ensureTrack;
+    /** Test-only — skip count for assertions. */
+    get _skipCount(): number;
+}
+export {};