@haywoodmarx/agent-pager 0.1.0

package/dist/src/messaging/notifications.js

@@ -0,0 +1,489 @@
+import { EventEmitter } from "node:events";
+import { isOpaqueId } from "../broker/protocol.js";
+import { PAGER_DEFAULTS } from "../configuration-defaults.js";
+/** Limits the number of accepted operator correlations represented by one body-free wake. */
+export const OPERATOR_CONTROL_CORRELATION_LIMIT = 64;
+/** Limits the aggregate ASCII bytes retained for one body-free operator wake. */
+const OPERATOR_CONTROL_CORRELATION_BYTES_LIMIT = 8 * 1024;
+/** Bounds retained scheduler diagnostics independently from durable state. */
+export const NOTIFICATION_OPERATIONAL_EVENT_LIMIT = 4_096;
+/** Reports a controlled rejection at the body-free notification boundary. */
+export class NotificationValidationError extends Error {
+}
+/** Body-free adapter notification fan-out. */
+export class NotificationHub {
+    #events = new EventEmitter();
+    #epoch;
+    #sequences = new Map();
+    #fanOutQueues = new Map();
+    #subscriberFailureFrames = [];
+    #onSubscriberError;
+    /**
+     * Constructs a notification hub for one broker epoch.
+     * @param epoch - Broker generation used to fence stale sessions.
+     * @param options - Optional non-retaining subscriber-failure observer.
+     */
+    constructor(epoch, options = {}) {
+        this.#epoch = epoch;
+        this.#onSubscriberError = options.onSubscriberError ?? (() => { });
+    }
+    /**
+     * Publish an inbox change without storing message bodies or creating queue state.
+     * @param agentId - Recipient the inbox change is published for.
+     * @param reason - Lifecycle reason attached to the inbox notification.
+     * @param messageId - Message the change names, when it names one.
+     * @returns - Copy of the published event; changing it does not alter what subscribers received.
+     */
+    publish(agentId, reason, messageId) {
+        const sequence = (this.#sequences.get(agentId) ?? 0) + 1;
+        this.#sequences.set(agentId, sequence);
+        const event = {
+            type: "inbox_changed",
+            agentId,
+            sequence,
+            epoch: this.#epoch,
+            reason,
+            ...(messageId ? { messageId } : {}),
+        };
+        this.#fanOut(agentId, event);
+        return cloneInboxChanged(event);
+    }
+    /**
+     * Publish a body-free operator control wake without creating peer delivery state.
+     * @param agentId - Stable identity of the requested target.
+     * @param controlId - Opaque correlation of the primary accepted command.
+     * @param coalescedControlIds - Additional accepted command correlations represented by this wake.
+     * @returns - Copy of the published event; changing it does not alter what subscribers received.
+     */
+    publishOperatorPing(agentId, controlId, coalescedControlIds = []) {
+        const controlIds = validateControlIds([controlId, ...coalescedControlIds]);
+        const sequence = (this.#sequences.get(agentId) ?? 0) + 1;
+        this.#sequences.set(agentId, sequence);
+        const event = {
+            type: "inbox_changed",
+            agentId,
+            sequence,
+            epoch: this.#epoch,
+            reason: "operator_ping",
+            controlId: controlIds[0] ?? controlId,
+            coalescedControlIds: controlIds.slice(1),
+        };
+        this.#fanOut(agentId, event);
+        return cloneInboxChanged(event);
+    }
+    /**
+     * Subscribe an adapter to body-free notification events.
+     * @param agentId - Agent whose operational events the listener receives.
+     * @param listener - Callback invoked for each matching operational event.
+     * @returns - Unsubscribe callback that detaches the registered listener.
+     */
+    subscribe(agentId, listener) {
+        const isolatedListener = (event) => {
+            try {
+                listener(cloneInboxChanged(event));
+            }
+            catch {
+                const failure = { agentId, sequence: event.sequence };
+                const currentFrame = this.#subscriberFailureFrames.at(-1);
+                if (currentFrame)
+                    currentFrame.push(failure);
+                else
+                    this.#reportSubscriberFailure(failure);
+            }
+        };
+        this.#events.on(agentId, isolatedListener);
+        return () => this.#events.off(agentId, isolatedListener);
+    }
+    #fanOut(agentId, event) {
+        const pending = this.#fanOutQueues.get(agentId);
+        if (pending) {
+            pending.push(event);
+            return;
+        }
+        const queue = [event];
+        this.#fanOutQueues.set(agentId, queue);
+        try {
+            for (let next = queue.shift(); next; next = queue.shift()) {
+                const failures = [];
+                this.#subscriberFailureFrames.push(failures);
+                try {
+                    this.#events.emit(agentId, next);
+                }
+                finally {
+                    this.#subscriberFailureFrames.pop();
+                }
+                for (const failure of failures)
+                    this.#reportSubscriberFailure(failure);
+            }
+        }
+        finally {
+            this.#fanOutQueues.delete(agentId);
+        }
+    }
+    #reportSubscriberFailure(failure) {
+        try {
+            this.#onSubscriberError(failure);
+        }
+        catch {
+            // Subscriber failure reporting is isolated from every accepted wake as well.
+        }
+    }
+}
+/** Broker notification scheduler for retry, coalescing, busy deferral, wake and correlation shedding, and operational events. */
+export class NotificationScheduler {
+    #hub;
+    #broker;
+    #wakeBudget;
+    #wakeBudgetWindowMs;
+    #now;
+    #events = [];
+    #busyAgents = new Set();
+    #releasingAgents = new Set();
+    #coalesced = new Map();
+    #wakeHistory = new Map();
+    #liveReservations = new Map();
+    #capabilities = new Map();
+    #operatorAdmissions = new Set();
+    /**
+     * Constructs a scheduler over the notification broker and event hub.
+     * @param broker - Durable broker instance that owns message state.
+     * @param hub - Notification stream used to publish inbox changes.
+     * @param options - Clock, required so this scheduler shares the process's, plus optional policy.
+     */
+    constructor(broker, hub, options) {
+        this.#broker = broker;
+        this.#hub = hub;
+        this.#wakeBudget = options.wakeBudget ?? PAGER_DEFAULTS.wakeBudget;
+        this.#wakeBudgetWindowMs = options.wakeBudgetWindowMs ?? PAGER_DEFAULTS.wakeBudgetWindowMs;
+        this.#now = options.now;
+    }
+    /**
+     * Record adapter-declared capabilities used by the notification scheduler.
+     * @param agentId - Agent whose adapter capabilities are recorded.
+     * @param capabilities - Delivery capabilities reported by the adapter.
+     */
+    declareAdapter(agentId, capabilities) {
+        this.#capabilities.set(agentId, capabilities);
+    }
+    /**
+     * Notify an agent of durable inbox state without creating a second message queue.
+     * @param agentId - Agent notified of the inbox change.
+     * @param reason - Lifecycle reason attached to the inbox notification.
+     * @returns - Wake event when budget and capability policy allow delivery, otherwise null.
+     */
+    notify(agentId, reason = "queued") {
+        return this.notifyMessage(undefined, agentId, reason);
+    }
+    /**
+     * Notify one message recipient and append adapter lifecycle outcomes for its receipt.
+     * @param messageId - Message the notification concerns.
+     * @param agentId - Recipient notified of the message.
+     * @param reason - Lifecycle reason attached to the inbox notification.
+     * @returns - Wake event tied to the durable message, or null when policy suppresses it.
+     */
+    notifyMessage(messageId, agentId, reason = "queued") {
+        if (this.#busyAgents.has(agentId) && this.#capabilities.get(agentId)?.coalescing === true) {
+            const existing = this.#coalesced.get(agentId);
+            if (!existing?.message && !this.#reserveWakeBudget(agentId)) {
+                this.#recordEvent({ type: "wake_shed", agentId, reason: "wake_budget", ...(messageId ? { messageId } : {}) });
+                this.#hub.publish(agentId, "shed", messageId);
+                if (messageId)
+                    this.#broker.recordNotification(messageId, "shed");
+                return null;
+            }
+            const pending = existing ?? this.#pendingWake(agentId);
+            pending.message = coalescePendingMessage(pending.message, messageId, reason);
+            this.#recordEvent({ type: "wake_deferred", agentId });
+            return null;
+        }
+        if (!this.#consumeWakeBudget(agentId)) {
+            this.#recordEvent({ type: "wake_shed", agentId, reason: "wake_budget", ...(messageId ? { messageId } : {}) });
+            this.#hub.publish(agentId, "shed", messageId);
+            if (messageId)
+                this.#broker.recordNotification(messageId, "shed");
+            return null;
+        }
+        const event = this.#hub.publish(agentId, reason, messageId);
+        this.#recordEvent({ type: "wake_sent", agentId, sequence: event.sequence });
+        return event;
+    }
+    /**
+     * Admit a body-free operator ping without creating message delivery state.
+     * @param agentId - Stable identity of the requested target.
+     * @param controlId - Durable opaque correlation created with command acceptance.
+     * @param commitAcceptance - Synchronous durable acceptance performed after preflight and before scheduler mutation.
+     * @param resolveExisting - Read-only durable retry resolution performed before a rejected preflight becomes observable.
+     * @returns The admission outcome; `accepted` carries the published wake.
+     */
+    notifyOperatorPing(agentId, controlId, commitAcceptance, resolveExisting) {
+        const [validatedControlId] = validateControlIds([controlId]);
+        if (!validatedControlId)
+            throw new Error("Validated operator control id is unavailable");
+        if (this.#operatorAdmissions.has(agentId)) {
+            if (resolveExistingOperatorCommand(resolveExisting)) {
+                return { status: "already_accepted", controlId: validatedControlId };
+            }
+            return { status: "correlation_rejected", controlId: validatedControlId, reason: "admission_in_progress" };
+        }
+        this.#operatorAdmissions.add(agentId);
+        try {
+            if (this.#busyAgents.has(agentId) && this.#capabilities.get(agentId)?.coalescing === true) {
+                return this.#admitCoalescedOperatorPing(agentId, validatedControlId, commitAcceptance, resolveExisting);
+            }
+            if (!this.#hasWakeBudget(agentId)) {
+                return this.#rejectOperatorPing(agentId, validatedControlId, resolveExisting, "wake_budget");
+            }
+            if (commitAcceptance() === "existing") {
+                return { status: "already_accepted", controlId: validatedControlId };
+            }
+            return this.#publishOperatorPings(agentId, [validatedControlId]);
+        }
+        finally {
+            this.#operatorAdmissions.delete(agentId);
+        }
+    }
+    /**
+     * Admit or reject one operator ping against a busy, coalescing-capable agent, appending its
+     * control id to the pending wake rather than publishing immediately.
+     * @param agentId - Busy agent the ping targets.
+     * @param controlId - Validated control id correlating the request.
+     * @param commitAcceptance - Synchronous durable acceptance performed after preflight.
+     * @param resolveExisting - Read-only durable retry resolution performed before a rejected
+     * preflight becomes observable.
+     * @returns - `coalesced` when the id joined the pending wake, `already_accepted` on a durable retry, otherwise a rejection.
+     */
+    #admitCoalescedOperatorPing(agentId, controlId, commitAcceptance, resolveExisting) {
+        const existing = this.#coalesced.get(agentId);
+        if (existing?.controlIdSet.has(controlId) === true) {
+            return this.#rejectOperatorPing(agentId, controlId, resolveExisting, "duplicate_control_id");
+        }
+        if (existing && !canAppendControlId(existing, controlId)) {
+            return this.#rejectOperatorPing(agentId, controlId, resolveExisting, "pending_control_limit");
+        }
+        const needsReservation = !existing || existing.controlIds.length === 0;
+        if (needsReservation && !this.#hasWakeBudget(agentId)) {
+            return this.#rejectOperatorPing(agentId, controlId, resolveExisting, "wake_budget");
+        }
+        if (commitAcceptance() === "existing") {
+            return { status: "already_accepted", controlId };
+        }
+        if (needsReservation && !this.#reserveWakeBudget(agentId)) {
+            throw new Error("Preflighted operator wake budget became unavailable");
+        }
+        const pending = existing ?? this.#pendingWake(agentId);
+        pending.controlIds.push(controlId);
+        pending.controlIdSet.add(controlId);
+        pending.controlBytes += controlId.length;
+        this.#recordEvent({ type: "wake_deferred", agentId, controlIds: [controlId] });
+        return { status: "coalesced", controlId };
+    }
+    /**
+     * Resolve an existing durable acceptance first, otherwise record a shed event and reject.
+     * @param agentId - Affected agent.
+     * @param controlId - Validated control id correlating the rejected request.
+     * @param resolveExisting - Read-only durable retry resolution performed before the rejection
+     * becomes observable.
+     * @param shedReason - Policy that sheds the wake, also naming the correlation rejection's reason
+     * when it is not a wake-budget rejection.
+     * @returns Already-accepted admission when a durable retry resolved one, otherwise the rejection.
+     */
+    #rejectOperatorPing(agentId, controlId, resolveExisting, shedReason) {
+        if (resolveExistingOperatorCommand(resolveExisting)) {
+            return { status: "already_accepted", controlId };
+        }
+        this.#recordEvent({ type: "wake_shed", agentId, reason: shedReason, controlIds: [controlId] });
+        return shedReason === "wake_budget"
+            ? { status: "budget_rejected", controlId }
+            : { status: "correlation_rejected", controlId, reason: shedReason };
+    }
+    /**
+     * Record recipient delivery availability and coalesce many arrivals to one pending wake.
+     * @param agentId - Agent whose delivery availability changed.
+     * @param busy - Whether the agent is currently occupied.
+     * @returns - Every released message/control member, or null when no state changed.
+     */
+    setBusy(agentId, busy) {
+        if (busy) {
+            this.#busyAgents.add(agentId);
+            return null;
+        }
+        if (this.#releasingAgents.has(agentId))
+            return null;
+        this.#busyAgents.delete(agentId);
+        const pending = this.#coalesced.get(agentId);
+        if (!pending)
+            return null;
+        this.#releasingAgents.add(agentId);
+        try {
+            const messageWake = pending.message ? this.#releasePendingMessage(agentId, pending) : null;
+            const controlWake = !this.#busyAgents.has(agentId) && pending.controlIds.length > 0
+                ? this.#releasePendingOperatorPings(agentId, pending)
+                : null;
+            if (!pending.message && pending.controlIds.length === 0)
+                this.#coalesced.delete(agentId);
+            if (!messageWake && !controlWake)
+                return null;
+            return { type: "busy_wake_release", message: messageWake, operatorPing: controlWake };
+        }
+        finally {
+            this.#releasingAgents.delete(agentId);
+        }
+    }
+    /**
+     * Retry a dropped wake while durable messages remain unclaimed.
+     * @param agentId - Agent whose dropped wake is retried.
+     * @returns - Retry wake when queued work remains, otherwise null.
+     */
+    retryUnclaimed(agentId) {
+        if (!this.#broker.hasQueuedMessages(agentId))
+            return null;
+        return this.notify(agentId, "redelivery");
+    }
+    #consumeWakeBudget(agentId) {
+        const history = this.#currentWakeHistory(agentId);
+        if (history.length + (this.#liveReservations.get(agentId) ?? 0) >= this.#wakeBudget)
+            return false;
+        history.push(this.#now());
+        this.#wakeHistory.set(agentId, history);
+        return true;
+    }
+    #hasWakeBudget(agentId) {
+        const history = this.#currentWakeHistory(agentId);
+        return history.length + (this.#liveReservations.get(agentId) ?? 0) < this.#wakeBudget;
+    }
+    #reserveWakeBudget(agentId) {
+        const history = this.#currentWakeHistory(agentId);
+        const reservations = this.#liveReservations.get(agentId) ?? 0;
+        if (history.length + reservations >= this.#wakeBudget)
+            return false;
+        this.#liveReservations.set(agentId, reservations + 1);
+        return true;
+    }
+    #currentWakeHistory(agentId) {
+        const cutoff = this.#now() - this.#wakeBudgetWindowMs;
+        const history = (this.#wakeHistory.get(agentId) ?? []).filter((at) => at > cutoff);
+        this.#wakeHistory.set(agentId, history);
+        return history;
+    }
+    #completeReservedWake(agentId) {
+        const reservations = this.#liveReservations.get(agentId) ?? 0;
+        if (reservations < 1)
+            throw new Error("Reserved notification wake is unavailable");
+        if (reservations === 1)
+            this.#liveReservations.delete(agentId);
+        else
+            this.#liveReservations.set(agentId, reservations - 1);
+        const history = this.#currentWakeHistory(agentId);
+        history.push(this.#now());
+        this.#wakeHistory.set(agentId, history);
+    }
+    #publishOperatorPings(agentId, controlIds) {
+        const validated = validateControlIds(controlIds);
+        const controlId = validated[0];
+        if (!controlId)
+            throw new Error("Validated operator control id is unavailable");
+        if (!this.#consumeWakeBudget(agentId)) {
+            this.#recordEvent({ type: "wake_shed", agentId, reason: "wake_budget", controlIds: validated });
+            return { status: "budget_rejected", controlId };
+        }
+        const coalescedControlIds = validated.slice(1);
+        const event = this.#hub.publishOperatorPing(agentId, controlId, coalescedControlIds);
+        this.#recordEvent({ type: "wake_sent", agentId, sequence: event.sequence, controlIds: validated });
+        return { status: "accepted", controlId, wake: event };
+    }
+    #releasePendingMessage(agentId, pending) {
+        const message = pending.message;
+        if (!message)
+            throw new Error("Pending message wake is unavailable");
+        delete pending.message;
+        const messageId = message.correlation === "single" ? message.messageId : undefined;
+        if (messageId)
+            this.#broker.recordNotification(messageId, "deferred");
+        const event = this.#hub.publish(agentId, message.reason, messageId);
+        this.#completeReservedWake(agentId);
+        this.#recordEvent({ type: "wake_sent", agentId, sequence: event.sequence });
+        return event;
+    }
+    #releasePendingOperatorPings(agentId, pending) {
+        const controlIds = [...pending.controlIds];
+        pending.controlIds.length = 0;
+        pending.controlIdSet.clear();
+        pending.controlBytes = 0;
+        const validated = validateControlIds(controlIds);
+        const controlId = validated[0];
+        if (!controlId)
+            throw new Error("Validated operator control id is unavailable");
+        const event = this.#hub.publishOperatorPing(agentId, controlId, validated.slice(1));
+        this.#completeReservedWake(agentId);
+        this.#recordEvent({ type: "wake_sent", agentId, sequence: event.sequence, controlIds: validated });
+        return event;
+    }
+    #pendingWake(agentId) {
+        const existing = this.#coalesced.get(agentId);
+        if (existing)
+            return existing;
+        const pending = { controlIds: [], controlIdSet: new Set(), controlBytes: 0 };
+        this.#coalesced.set(agentId, pending);
+        return pending;
+    }
+    /**
+     * Return operational notification events.
+     * @returns - Copy of accumulated operational events, safe for caller inspection.
+     */
+    operationalEvents() {
+        return [...this.#events];
+    }
+    #recordEvent(event) {
+        this.#events.push(event);
+        if (this.#events.length > NOTIFICATION_OPERATIONAL_EVENT_LIMIT)
+            this.#events.shift();
+    }
+}
+function resolveExistingOperatorCommand(resolveExisting) {
+    const resolution = resolveExisting();
+    if (resolution === "existing")
+        return true;
+    if (resolution === "absent")
+        return false;
+    throw new Error("Operator command resolver returned an invalid result");
+}
+function validateControlIds(values) {
+    if (values.length > OPERATOR_CONTROL_CORRELATION_LIMIT) {
+        throw new NotificationValidationError("Operator control correlation count exceeds the bounded limit");
+    }
+    const output = [];
+    const seen = new Set();
+    let bytes = 0;
+    for (const value of values) {
+        if (!isOpaqueId(value))
+            throw new NotificationValidationError("Operator control id is invalid");
+        if (seen.has(value))
+            throw new NotificationValidationError("Operator control ids must be unique");
+        bytes += value.length;
+        if (bytes > OPERATOR_CONTROL_CORRELATION_BYTES_LIMIT) {
+            throw new NotificationValidationError("Operator control correlation bytes exceed the bounded limit");
+        }
+        seen.add(value);
+        output.push(value);
+    }
+    if (output.length === 0)
+        throw new NotificationValidationError("At least one operator control id is required");
+    return output;
+}
+function canAppendControlId(pending, controlId) {
+    return (pending.controlIds.length < OPERATOR_CONTROL_CORRELATION_LIMIT &&
+        pending.controlBytes + controlId.length <= OPERATOR_CONTROL_CORRELATION_BYTES_LIMIT);
+}
+function coalescePendingMessage(existing, messageId, reason) {
+    if (!existing)
+        return messageId ? { correlation: "single", reason, messageId } : { correlation: "generic", reason };
+    if (existing.correlation === "generic" || messageId === undefined || existing.messageId !== messageId) {
+        return { correlation: "generic", reason: existing.reason };
+    }
+    return existing;
+}
+function cloneInboxChanged(event) {
+    return event.reason === "operator_ping"
+        ? { ...event, coalescedControlIds: [...event.coalescedControlIds] }
+        : { ...event };
+}

package/dist/src/messaging/push-delivery.d.ts

@@ -0,0 +1,77 @@
+import type { Broker } from "../broker/broker.js";
+import { type AgentId } from "../broker/protocol.js";
+import type { HostPushNotificationCapability } from "../implementations/model.js";
+import type { NotificationHub, NotificationScheduler } from "./notifications.js";
+/** Broker operations the push service reaches, narrowed so a test can hand it a recording fake. */
+export type PushDeliveryBroker = Pick<Broker, "fetch" | "releaseClaims" | "recordNotification" | "implementationForAgent" | "hasQueuedMessages">;
+/** Scheduler operations the push service reaches. */
+export type PushDeliveryScheduler = Pick<NotificationScheduler, "declareAdapter" | "setBusy" | "notify">;
+/** Supplies every collaborator the push service reaches outside its own state. */
+export type PushDeliveryDependencies = {
+    /** Claims, releases, and records against durable message state. */
+    broker: PushDeliveryBroker;
+    /** Publishes the wakes this service turns into deliveries. */
+    hub: Pick<NotificationHub, "subscribe">;
+    /** Owns busy coalescing and the wake budget for every recipient. */
+    scheduler: PushDeliveryScheduler;
+    /**
+     * Resolve the host-push capability of one implementation, or nothing when it has no notification capability.
+     * @param implementationId - Implementation recorded for the recipient at registration.
+     * @returns - Capability owning address parsing and transport, or undefined.
+     */
+    capabilityFor(implementationId: string): HostPushNotificationCapability | undefined;
+    /** Writes one diagnostic the operator can read; never reaches a model. */
+    report(message: string): void;
+    /**
+     * Read wall-clock time for stamping a push attempt.
+     *
+     * Required rather than defaulted, so this service cannot stamp its attempts from a clock the
+     * broker whose rows it is acting on does not share.
+     * @returns - Epoch milliseconds.
+     */
+    now: () => number;
+};
+/** Reports what registering an address changed. */
+export type DeliveryAddressRegistration = "registered" | "unchanged" | "rejected" | "not_push";
+/**
+ * Turns wakes for host-push recipients into deliveries written by their implementation.
+ *
+ * The service claims on the recipient's behalf immediately before writing, so a message is never
+ * held by a session that has not been handed it. A wake for a recipient without a registered
+ * address is left to the redelivery schedule, which offers it again once an address arrives.
+ */
+export declare class PushDeliveryService {
+    #private;
+    /**
+     * Construct the service over injected broker, hub, scheduler, and capability resolution.
+     * @param dependencies - Collaborators the service reaches outside its own state.
+     */
+    constructor(dependencies: PushDeliveryDependencies);
+    /**
+     * Hold the address a session registered, and deliver anything already waiting for it.
+     *
+     * An unchanged address is a no-op.
+     * @param agentId - Recipient whose session supplied the address.
+     * @param raw - Untrusted address text exactly as the session supplied it.
+     * @returns - What the registration changed.
+     */
+    registerAddress(agentId: AgentId, raw: string): DeliveryAddressRegistration;
+    /**
+     * Drop a recipient's address so no further wake is written to it.
+     * @param agentId - Recipient whose address is no longer usable.
+     */
+    forget(agentId: AgentId): void;
+    /**
+     * Report whether a recipient currently has an address to deliver to.
+     * @param agentId - Recipient to check.
+     * @returns - Whether a delivery address is held for the recipient.
+     */
+    hasAddress(agentId: AgentId): boolean;
+    /**
+     * Resolve once every delivery in flight, and every one released by their completion, has finished.
+     * @returns - Settles when no delivery chain remains.
+     */
+    settled(): Promise<void>;
+    /** Drop every address and stop listening for wakes. */
+    close(): void;
+}