@stratusagent/gateway 0.13.7 → 0.14.0

package/dist/events.d.ts

@@ -0,0 +1,256 @@
+import type { InboundEvent } from '@stratusagent/agents';
+import { type SqliteScheduleStoreOptions } from './schedules.ts';
+/** Accepted ids are remembered this long: longer than GitHub's 3-day manual redelivery. */
+export declare const EVENT_DEDUP_WINDOW_MS: number;
+/** Delivery rows listed at most: the newest this many, within the dedup window. */
+export declare const EVENT_DELIVERY_ROW_CAP = 10000;
+/** A firing's rendered event block, and so the event text a turn sees, is at most this many bytes. */
+export declare const EVENT_BLOCK_MAX_BYTES: number;
+/** What happened to one request that had a good signature. */
+export type EventDeliveryStatus = 'refused' | 'duplicate' | 'unmatched' | 'matched';
+/**
+ * Where one trigger's firing for one delivery stands. `pending`, `held`,
+ * `rate_limited` and `firing` are open and keep their event block; the rest
+ * are finished and keep none.
+ */
+export type EventFiringStatus = 'pending' | 'held' | 'rate_limited' | 'firing' | 'fired' | 'failed' | 'superseded' | 'expired';
+export interface EventDeliveryRow {
+    seq: number;
+    source: string;
+    eventId: string;
+    type: string;
+    subject?: string;
+    status: EventDeliveryStatus;
+    reason?: string;
+    receivedAt: string;
+}
+export interface EventFiringRow {
+    id: string;
+    deliverySeq: number;
+    triggerId: string;
+    agentId: string;
+    source: string;
+    eventId: string;
+    coalescingKey: string;
+    sessionId: string;
+    /** This firing's own idempotency key: `eventDispatchKey` of its trigger, source and event. */
+    dispatchKey: string;
+    /**
+     * The key the batch this firing was claimed in goes out under. Set by the
+     * claim and never changed after: a claimed batch is fixed, so a recovered
+     * one can't come back under another key and start a second turn.
+     */
+    batchKey?: string;
+    status: EventFiringStatus;
+    /** When its batch was first claimed to go out: what the hourly limit counts from. */
+    startedAt?: string;
+    /** The rendered event block, kept only while the firing is open. */
+    block?: string;
+    reason?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * What one source has been doing, from the rows (`SqliteEventStore.activity`).
+ * Requests refused before they could leave a row (bad signature, too large,
+ * over the rate) aren't here: only the running listener counts those.
+ */
+export interface EventSourceActivity {
+    /** The newest delivery row, whatever its status. */
+    lastDelivery?: {
+        at: string;
+        type: string;
+        subject?: string;
+        status: EventDeliveryStatus;
+    };
+    /** The newest signed delivery whose body was refused, and why. */
+    lastRefused?: {
+        at: string;
+        reason: string;
+    };
+    /** Delivery rows received since the cutoff, by status. Of the rows still kept (the newest 10,000). */
+    deliveries: Partial<Record<EventDeliveryStatus, number>>;
+    /**
+     * Firings by status: finished ones that reached it since the cutoff, and
+     * every open one however old, since it is waiting now.
+     */
+    firings: Partial<Record<EventFiringStatus, number>>;
+}
+/** One trigger's match on a delivery, as the listener hands it to `accept`. */
+export interface NewEventFiring {
+    triggerId: string;
+    agentId: string;
+    coalescingKey: string;
+    sessionId: string;
+    dispatchKey: string;
+    block: string;
+}
+export interface AcceptedEventDelivery {
+    source: string;
+    eventId: string;
+    type: string;
+    subject?: string;
+    receivedAt: string;
+    /** Empty when no trigger matched. */
+    firings: NewEventFiring[];
+}
+export interface RefusedEventDelivery {
+    source: string;
+    eventId: string;
+    type?: string;
+    subject?: string;
+    reason: string;
+    receivedAt: string;
+}
+/**
+ * What sessions, holds and rate limits group by: source + subject when the
+ * event has one, so every Codex round on one PR is one conversation, and
+ * source + id when it doesn't, so subjectless events never share a bucket.
+ * JSON, so no subject can be spelled to collide with an id key.
+ */
+export declare const eventCoalescingKey: (sourceId: string, event: Pick<InboundEvent, "attributes">) => string;
+/**
+ * A trigger's session for one coalescing key. In the reserved `schedule:`
+ * namespace, which the gateway refuses to dispatch into from outside, so the
+ * only turns on it are the trigger's own firings.
+ */
+export declare const eventSessionId: (triggerId: string, coalescingKey: string) => string;
+/**
+ * The gateway idempotency key for one trigger's firing on one event: a
+ * repeat never starts a second turn, and a turn whose process died continues
+ * once. Hashed when over the gateway's bound, as channel-slack does, because
+ * a sender picks the event id's length.
+ */
+export declare const eventDispatchKey: (triggerId: string, sourceId: string, eventId: string) => string;
+/**
+ * What a firing's turn sees after the trigger's prompt. Rendered when the
+ * delivery is matched and stored with the firing, so a firing that goes out
+ * hours later needs neither the request body nor a second match. Attributes
+ * and data are JSON, so a newline in a sender's subject or comment can't pass
+ * for a line of the block. Capped at `EVENT_BLOCK_MAX_BYTES` with a note: the
+ * agent fetches the rest with its own tools (`gh` for a PR).
+ */
+export declare const renderEventBlock: (sourceId: string, event: InboundEvent) => string;
+/**
+ * Deliveries, dedup tombstones and firings, durable in `fleet.db`. Its own
+ * connection, like the schedule store's. `stratus events` reads through the
+ * running daemon instead of this file, because the requests refused before
+ * a row are counted only in the listener.
+ *
+ * Every method that changes more than one row does it in one transaction,
+ * and every one that moves a firing between statuses is all-or-nothing and
+ * conditional on the statuses it expects: a delivery and its firings are
+ * committed together before the sender hears 2xx, a batch is claimed whole
+ * before its dispatch, and a refused transition changes nothing.
+ */
+export declare class SqliteEventStore {
+    private readonly db;
+    constructor(filePath: string, options?: SqliteScheduleStoreOptions);
+    private transaction;
+    private insertDelivery;
+    /**
+     * Record a delivery whose signature checked out and whose body parsed:
+     * `duplicate` when its (source, id) was accepted within the dedup window,
+     * else `matched` with one `pending` firing per match, or `unmatched`. One
+     * write, made before the sender hears 2xx. Accepted deliveries leave a
+     * tombstone that outlives the row cap, so dedup never depends on it.
+     */
+    accept(delivery: AcceptedEventDelivery): {
+        status: Exclude<EventDeliveryStatus, 'refused'>;
+        seq: number;
+        firings: EventFiringRow[];
+    };
+    /**
+     * Record a signed delivery the listener refused (a form-encoded body, a
+     * malformed event). No tombstone: the sender can fix it and retry with the
+     * same id. Unsigned requests never reach here; they leave no row at all.
+     */
+    refuse(delivery: RefusedEventDelivery): EventDeliveryRow;
+    /** Delivery rows, newest first. */
+    deliveries(options?: {
+        limit?: number;
+        source?: string;
+    }): EventDeliveryRow[];
+    /**
+     * Per source with any row: its last delivery, its last refused one, and
+     * counts since `sinceIso` (`stratus events`, `/health`). Grouped in the
+     * database, so the cost doesn't grow with the 7 days of rows kept.
+     */
+    activity(sinceIso: string): Record<string, EventSourceActivity>;
+    firing(id: string): EventFiringRow | undefined;
+    /**
+     * Every open firing (`pending`, `held`, `rate_limited`, `firing`), oldest
+     * first, with its block and batch key: what the startup sweep recovers and
+     * what a hold releases. A `firing` row is a claim whose dispatch may or may
+     * not have reached the gateway; its batch goes out again as stored, and the
+     * idempotency key decides whether that starts or continues a turn.
+     */
+    open(): EventFiringRow[];
+    /**
+     * Run `update` on exactly `ids`, all or nothing: false, with nothing
+     * changed, unless `precheck` (inside the same transaction) passes and
+     * every row matched the update's own conditions.
+     */
+    private allOrNothing;
+    /**
+     * Claim firings to go out as one turn under `batchKey`, in one write
+     * before the dispatch. Either every row is free and they become a new
+     * batch, or `ids` is exactly an existing batch under exactly its key,
+     * which is how recovery resends one. A batch is fixed once claimed: no
+     * row joins it later, and it never changes key. False, with nothing
+     * changed, for anything else, or if any row is finished.
+     *
+     * With `triggerId`, also false unless that schedule row still exists, in
+     * the same transaction: `stratus schedules cancel` deletes from another
+     * process, and a trigger cancelled after the scan read it must not fire,
+     * as a timed schedule's conditional slot claim already guarantees.
+     */
+    claim(ids: readonly string[], batchKey: string, nowIso: string, options?: {
+        triggerId?: string;
+    }): boolean;
+    /**
+     * Hold open firings for quiet hours or paused intake (`held`) or over the
+     * trigger's hourly limit (`rate_limited`). The block and any batch key
+     * stay, so a held batch still goes out only as itself.
+     */
+    hold(ids: readonly string[], status: 'held' | 'rate_limited', nowIso: string): boolean;
+    /**
+     * Finish claimed firings after their dispatch, clearing the block in the
+     * same write: from here the payload lives only in the session it fired.
+     * Only a `firing` row can finish, so nothing is marked fired that wasn't
+     * claimed first.
+     */
+    finish(ids: readonly string[], outcome: {
+        status: 'fired';
+    } | {
+        status: 'failed';
+        reason: string;
+    }, nowIso: string): boolean;
+    /**
+     * Retire open firings that will never go out: `superseded` by newer ones
+     * for the same key, or `expired` (held over 24 hours, or their trigger was
+     * cancelled). Clears their blocks. Returns how many were retired; a
+     * finished firing is left as it is.
+     */
+    retire(ids: readonly string[], status: 'superseded' | 'expired', reason: string, nowIso: string): number;
+    /**
+     * Turns a trigger has started since `sinceIso`, for its hourly limit,
+     * counted from when each batch was first claimed (a two-hour turn doesn't
+     * hold the hour for two more): a batch running now, one that finished,
+     * and one that failed all count,
+     * since each was a turn started unattended. A failing provider would
+     * otherwise let every new event start another. A batch is one turn, so
+     * this counts batch keys, not rows; `exceptBatchKey` leaves out a batch
+     * being re-sent after a restart, which must not count against itself.
+     */
+    turnsStartedSince(triggerId: string, sinceIso: string, exceptBatchKey?: string): number;
+    /**
+     * Drop what the dedup window and the row cap no longer cover: tombstones
+     * and delivery rows past 7 days, delivery rows past the newest 10,000, and
+     * finished firings past 7 days. An open firing is never pruned: it holds
+     * the only copy of an event that hasn't gone out.
+     */
+    prune(nowIso: string): void;
+    close(): void;
+}
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

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