@spinabot/brigade 0.1.2 → 1.0.1

package/dist/agents/heartbeat-runner.js

@@ -0,0 +1,268 @@
+/**
+ * Heartbeat runner.
+ *
+ * Brand-scrubbed lift of upstream's `src/infra/heartbeat-runner.ts`, scoped
+ * to what Brigade can DO at this milestone (the LLM-call path lands in
+ * Step 18/25 — until then the runner only does the gating + inbox-drain
+ * portion of the upstream flow).
+ *
+ * Pipeline per wake intent:
+ *
+ *   1. Honour the global enable flag (`areHeartbeatsEnabled()`).
+ *   2. Resolve agent id + session key from the intent (or default).
+ *   3. Gate on the GLOBAL `CommandLane.Main` lane — if the operator's
+ *      primary turn is already pending, skip with `requests-in-flight`.
+ *      The wake layer (Step 13) auto-retries this case.
+ *   4. Gate on the PER-SESSION lane (`session:<sessionKey>`) — same
+ *      contract; an active streaming turn for this session pre-empts
+ *      the heartbeat.
+ *   5. Peek the session inbox. If the wake reason is NOT `interval` AND
+ *      there is nothing surface-able, skip with `no-pending-events`.
+ *      Interval wakes proceed even with an empty inbox so the LLM can
+ *      do periodic heartbeat work.
+ *   6. Consume the inspected events from the inbox + emit a
+ *      `heartbeat-fired` lifecycle hook. The actual LLM turn dispatch
+ *      lands in Step 25; the runner publishes intent + drains, leaving
+ *      the dispatcher to pick up the next step.
+ *
+ * Result contract (matches upstream `HeartbeatRunResult`):
+ *   - `{ status: "ran", durationMs }`    → events consumed + handler fired
+ *   - `{ status: "skipped", reason }`    → no-op (gate triggered)
+ *   - `{ status: "failed", reason }`     → unexpected throw inside the runner
+ *
+ * What this module DOES NOT do (deferred to later steps):
+ *
+ *   - Does NOT call any LLM (Step 18/25 — Pi-kernel dispatch).
+ *   - Does NOT format the events into a prompt block — Step 12's
+ *     `drainFormattedSystemEvents` does that on the LLM side.
+ *   - Does NOT resolve delivery target — Step 25's dispatcher does that
+ *     from the inbox-derived `deliveryContext`.
+ */
+import { createSubsystemLogger } from "../logging/subsystem-logger.js";
+import { resolveGlobalSingleton } from "../shared/global-singleton.js";
+import { CommandLane, getLaneQueueSize, sessionLane } from "../process/lanes.js";
+import { areHeartbeatsEnabled, setHeartbeatWakeHandler, } from "./heartbeat-wake.js";
+import { consumeSystemEventEntries, peekSystemEventEntries, } from "./session-inbox.js";
+import { inspectPendingSessionEvents } from "./session-event-prompt.js";
+import { hasLiveSession } from "./session-registry.js";
+import { resolveAgentIdFromSessionKey } from "./routing/session-key.js";
+import { parseAgentSessionKey } from "../sessions/session-key-utils.js";
+const log = createSubsystemLogger("agents/heartbeat-runner");
+const HEARTBEAT_RUNNER_STATE_KEY = Symbol.for("brigade.heartbeatRunner.state");
+function createState() {
+    return {
+        stopped: false,
+        disposeWakeHandler: null,
+        firedHooks: new Set(),
+        bootAgentId: null,
+    };
+}
+/**
+ * Tell the runner which agentId owns the gateway's primary `Main` lane.
+ * Pass `null` to clear (tests / shutdown). When unset the runner skips
+ * the Main-lane gate entirely (per-session gate still applies).
+ *
+ * Wave L P2#12 — Brigade runs one gateway per process (the Main lane is a
+ * process-wide singleton). Calling this twice with different IDs without
+ * an intervening `null` clear would be a multi-gateway-in-one-process
+ * shape this runner does not support; warn rather than silently overwrite
+ * so the operator sees the misuse. To support that shape, convert
+ * `bootAgentId` to a `Set<string>` and update the targetsBootMain check
+ * to test membership.
+ */
+export function setHeartbeatBootAgentId(id) {
+    const trimmed = id?.trim() || null;
+    const state = getState();
+    if (trimmed !== null &&
+        state.bootAgentId !== null &&
+        state.bootAgentId !== trimmed) {
+        log.warn("setHeartbeatBootAgentId double-set without clear", {
+            previous: state.bootAgentId,
+            next: trimmed,
+        });
+    }
+    state.bootAgentId = trimmed;
+}
+function getState() {
+    return resolveGlobalSingleton(HEARTBEAT_RUNNER_STATE_KEY, createState);
+}
+function skipped(reason) {
+    return { status: "skipped", reason };
+}
+/**
+ * Add a `heartbeat-fired` hook. Called once per successful run with the
+ * consumed events. Returns a disposer that removes ONLY this hook —
+ * idempotent (calling twice is a no-op). Multiple hooks compose
+ * (run sequentially per fire; one throwing does not block the others).
+ *
+ * Use this from anywhere that needs to react to a heartbeat: the
+ * agent-events bridge, the gateway's synthetic-turn dispatcher, tests.
+ */
+export function addHeartbeatFiredHook(hook) {
+    const state = getState();
+    state.firedHooks.add(hook);
+    return () => {
+        state.firedHooks.delete(hook);
+    };
+}
+/**
+ * Legacy single-slot setter. Pass a hook to ADD it (returns void, not a
+ * disposer — call `addHeartbeatFiredHook` for that). Pass `null` to clear
+ * every registered hook (used by tests + `resetAgentEventsForTests`).
+ *
+ * Prefer `addHeartbeatFiredHook` from new wiring so composition is opt-in.
+ */
+export function setHeartbeatFiredHook(hook) {
+    const state = getState();
+    if (hook === null) {
+        state.firedHooks.clear();
+        return;
+    }
+    state.firedHooks.add(hook);
+}
+/**
+ * Process a single wake intent through the gate pipeline. Caller-side
+ * code paths: invoked by the wake handler installed in
+ * `startHeartbeatRunner`, plus directly by tests that want to inject a
+ * synthetic intent.
+ */
+export async function processHeartbeatWakeIntent(intent) {
+    const startedAt = Date.now();
+    const state = getState();
+    if (state.stopped)
+        return skipped("disabled");
+    if (!areHeartbeatsEnabled())
+        return skipped("disabled");
+    const reason = (intent.reason ?? "wake").trim() || "wake";
+    const sessionKey = (intent.sessionKey ?? "").trim();
+    if (!sessionKey)
+        return skipped("no-session");
+    const agentId = (intent.agentId ?? "").trim() || resolveAgentIdFromSessionKey(sessionKey);
+    // Per-session lane gate — an active turn for THIS session pre-empts the
+    // heartbeat; the wake layer retries us in 1s. We no longer gate on the
+    // global `Main` lane unconditionally because non-main sessions now run on
+    // their own per-session lanes; a busy `Main` (operator typing) should
+    // NOT block a heartbeat for a channel session that has its own queue.
+    const sessionLaneKey = sessionLane(sessionKey);
+    if (getLaneQueueSize(sessionLaneKey) > 0) {
+        return skipped("requests-in-flight");
+    }
+    // Main-session heartbeats still need the global gate — those land on
+    // `CommandLane.Main`, so an in-flight operator turn would race a
+    // synthetic heartbeat turn on the same FIFO. Only the BOOT agent's
+    // `:main` session shares the Main lane; other agents' `:main` sessions
+    // route to per-session lanes and are NOT gated against Main here.
+    //
+    // Wave L P2#6 — unify on `parseAgentSessionKey` so the agentId-arm /
+    // rest-arm match (the agentId-arm above already calls
+    // `resolveAgentIdFromSessionKey` which round-trips through the parser).
+    // Raw `split(":")` would return `cron` for `agent:<id>:cron:<job>:run:<runId>`
+    // and miss the parser's lowercasing / segment normalisation.
+    const restPart = parseAgentSessionKey(sessionKey)?.rest ?? "";
+    const bootAgentId = state.bootAgentId;
+    const targetsBootMain = restPart === "main" && bootAgentId !== null && agentId === bootAgentId;
+    if (targetsBootMain && getLaneQueueSize(CommandLane.Main) > 0) {
+        return skipped("requests-in-flight");
+    }
+    // Live-session gate — if the session is registered and currently in
+    // the running state (real turn dispatched but lane is between
+    // queue-pop and stream-start), skip too.
+    if (hasLiveSession(sessionKey)) {
+        const inspect = peekSystemEventEntries(sessionKey);
+        if (inspect.length === 0) {
+            return skipped("session-busy");
+        }
+        // Events are queued but a turn is already streaming. That turn will
+        // NOT pick them up — it drained its inbox prefix at ITS OWN start;
+        // events arriving mid-stream wait for a turn boundary. Returning the
+        // retryable reason makes the wake layer re-fire us on its 1s cooldown
+        // until the live turn ends, at which point the synthetic turn drains
+        // these events. The previous `session-busy` here silently DROPPED the
+        // wake (only `requests-in-flight` retries), so a cron reminder that
+        // fired while the operator's turn was streaming slept until the
+        // operator's next message.
+        return skipped("requests-in-flight");
+    }
+    // Audit 11 — lazy inbox consumption. We INSPECT (non-destructive peek
+    // via `peekSystemEventEntries` under the hood) until every gate has
+    // passed. Skip branches above return without ever calling
+    // `consumeSystemEventEntries`, so a gated wake leaves the inbox intact
+    // for the next attempt — no events lost when the runner can't yet
+    // surface them.
+    const inspection = inspectPendingSessionEvents(sessionKey);
+    const isIntervalReason = reason === "interval";
+    if (!isIntervalReason && !inspection.hasSurfaceable) {
+        return skipped("no-pending-events");
+    }
+    try {
+        // Only NOW do we drain. Atomically remove the inspected prefix from
+        // the inbox. Anything that arrived AFTER `inspectPendingSystemEvents`
+        // stays queued for the next drain. Returns the actual list consumed
+        // so the hook can surface them downstream.
+        const consumed = consumeSystemEventEntries(sessionKey, inspection.events);
+        const params = {
+            reason,
+            agentId,
+            sessionKey,
+            consumedEvents: consumed,
+        };
+        // Fire every registered hook. Snapshot the set so a hook that adds /
+        // removes hooks mid-fire doesn't perturb this run. Each hook is
+        // awaited sequentially; a throwing hook is logged + skipped so one
+        // bad listener doesn't drop events for the others.
+        for (const hook of [...state.firedHooks]) {
+            try {
+                await hook(params);
+            }
+            catch (err) {
+                log.warn("heartbeat-fired hook threw", {
+                    reason,
+                    sessionKey,
+                    error: err?.message,
+                });
+            }
+        }
+        return { status: "ran", durationMs: Date.now() - startedAt };
+    }
+    catch (err) {
+        const message = err?.message ?? String(err);
+        log.error("heartbeat runner failed", { reason, sessionKey, error: message });
+        return { status: "failed", reason: message };
+    }
+}
+/**
+ * Start the heartbeat runner: registers `processHeartbeatWakeIntent` as
+ * the wake handler with Step 13. Returns a handle whose `stop()` clears
+ * the registration + marks the runner stopped (subsequent intents
+ * short-circuit to `skipped("disabled")` until a new runner starts).
+ */
+export function startHeartbeatRunner() {
+    const state = getState();
+    // Two starts in a row → tear the first registration down first.
+    if (state.disposeWakeHandler) {
+        state.disposeWakeHandler();
+        state.disposeWakeHandler = null;
+    }
+    state.stopped = false;
+    const handler = async (params) => processHeartbeatWakeIntent(params);
+    const dispose = setHeartbeatWakeHandler(handler);
+    state.disposeWakeHandler = dispose;
+    return {
+        stop: () => {
+            if (state.stopped)
+                return;
+            state.stopped = true;
+            state.disposeWakeHandler?.();
+            state.disposeWakeHandler = null;
+        },
+    };
+}
+/** Test-only — clear the runner state without unregistering anything. */
+export function resetHeartbeatRunnerStateForTests() {
+    const state = getState();
+    state.stopped = false;
+    state.disposeWakeHandler = null;
+    state.firedHooks.clear();
+    state.bootAgentId = null;
+}
+//# sourceMappingURL=heartbeat-runner.js.map

package/dist/agents/heartbeat-runner.js.map

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

package/dist/agents/heartbeat-scheduler.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Per-agent heartbeat interval scheduler.
+ *
+ * Brigade-native analogue of upstream's wall-clock heartbeat scheduler.
+ * Reads `cfg.agents.<id>.heartbeat.intervalMs` (and the `defaults` fallback)
+ * to build a `Map<agentId, AgentSchedule>` of agents that opt into
+ * periodic heartbeats. On each tick the scheduler invokes the supplied
+ * `onInterval(agentId)` callback for every agent whose `nextDueMs` has
+ * elapsed; the callback is expected to call into Step 13's
+ * `requestHeartbeatNow(...)` which the runner picks up.
+ *
+ * Phase offsets are deterministic per agent (SHA-256 of a fixed seed +
+ * the agent id, mod intervalMs) so a Brigade restart resumes its agents
+ * on the same phase rather than thundering at the same instant. The
+ * seed defaults to a stable string; tests can override via
+ * `BRIGADE_HEARTBEAT_SEED` env to nail down phase positions.
+ *
+ * Lifecycle:
+ *
+ *   const sched = createHeartbeatScheduler({ onInterval });
+ *   sched.updateConfig(cfg);     // seed the per-agent map
+ *   sched.start();               // arm the wall-clock timer
+ *   // ... gateway runs ...
+ *   sched.stop();                // clear the timer
+ *
+ * Hot config reload is supported: `updateConfig(cfg)` recomputes the
+ * agent map. Agents whose interval changed get a new `nextDueMs`;
+ * agents whose interval stayed the same keep their existing schedule
+ * so the phase doesn't reset.
+ */
+import type { BrigadeConfig } from "../config/types.js";
+export interface HeartbeatSchedulerDeps {
+    /**
+     * Invoked when an agent's `nextDueMs` elapses. Implementation should
+     * call `requestHeartbeatNow({reason: "interval", agentId, sessionKey})`
+     * from Step 13's wake layer so the runner picks up the intent.
+     */
+    onInterval: (params: {
+        agentId: string;
+        sessionKey?: string;
+    }) => void;
+}
+export interface HeartbeatScheduler {
+    start: () => void;
+    stop: () => void;
+    updateConfig: (cfg: BrigadeConfig) => void;
+    getScheduleSnapshot: () => Array<{
+        agentId: string;
+        intervalMs: number;
+        nextDueMs: number;
+    }>;
+}
+export declare function createHeartbeatScheduler(deps: HeartbeatSchedulerDeps): HeartbeatScheduler;
+/** Test-only — clear scheduler state. */
+export declare function resetHeartbeatSchedulerForTests(): void;
+//# sourceMappingURL=heartbeat-scheduler.d.ts.map

package/dist/agents/heartbeat-scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeat-scheduler.d.ts","sourceRoot":"","sources":["../../src/agents/heartbeat-scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAMH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAuBxD,MAAM,WAAW,sBAAsB;IACtC;;;;OAIG;IACH,UAAU,EAAE,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;CACvE;AAED,MAAM,WAAW,kBAAkB;IAClC,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,YAAY,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,IAAI,CAAC;IAC3C,mBAAmB,EAAE,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC7F;AA+MD,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,sBAAsB,GAAG,kBAAkB,CA6HzF;AAED,yCAAyC;AACzC,wBAAgB,+BAA+B,IAAI,IAAI,CAMtD"}