@sigrun/ext-gateway 0.0.0-stage → 0.1.1

package/dist/state/ledger.d.ts

@@ -0,0 +1,152 @@
+/**
+ * The durable delivery ledger (spec §8.6): every outbound send's state
+ * machine — `pending` → `attempting` → `delivered` (receipt) or
+ * `failed` — persisted at `<stateDir>/gateway/ledger.json` through
+ * {@link JsonFile} (0600, atomic, serialized updates).
+ *
+ * File bytes are NEVER ledgered: an entry whose message carries `files`
+ * stores a WORKSPACE PATH + conversation id instead, and the delivery
+ * worker re-reads the bytes through `host.conversations.readFile` at
+ * send time (the brief's rule — `files` bytes would bloat the ledger
+ * and pin upload bytes into engine state).
+ *
+ * Restart recovery: `pending` entries are sent as-is; `attempting`
+ * entries become `pending` with the `recovered` flag (the platform may
+ * already hold them — the worker prefixes the marker). Tag dedupe:
+ * enqueueing a tag that already exists returns undefined (the
+ * re-delivery no-op).
+ */
+import type { ChatRef, MessageRef, OutboundMessage, SigrunHost } from "@sigrun/sigrun/extension";
+import type { EngineLog } from "../log.js";
+/** The persisted (JSON-safe) outbound message: `files` become a path. */
+export interface SerializedOutbound {
+    readonly chat: ChatRef;
+    readonly text: string;
+    readonly replyTo?: string;
+    readonly buttons?: OutboundMessage["buttons"];
+    /**
+     * The workspace path + conversation id of each file (the send-time
+     * re-read's `readFile` arguments) — never the bytes.
+     */
+    readonly files?: readonly {
+        readonly conversationId: number;
+        readonly path: string;
+        readonly name: string;
+        readonly mime?: string;
+    }[];
+}
+/** One ledger row's lifecycle. */
+export type LedgerState = "pending" | "attempting" | "delivered" | "failed";
+/** What the entry is for (the worker's send-shape discrimination). */
+export type LedgerKind = "final" | "notice" | "interaction" | "edit";
+/**
+ * One ledger entry. `tag` is the dedupe key (e.g.
+ * `final:<conversationId>:<answerEntryId>:<bindingKey>`) — a replayed
+ * settle (the platform redelivered, a restart re-ran a handler)
+ * enqueues nothing.
+ */
+export interface LedgerEntry {
+    readonly id: string;
+    /** The channel id (the per-channel worker's queue key). */
+    readonly channel: string;
+    /** The binding key the entry rides (dead-marking on chat_gone). */
+    readonly bindingKey?: string;
+    readonly chat: ChatRef;
+    readonly kind: LedgerKind;
+    readonly message: SerializedOutbound;
+    /** The edit target (kind "edit" only). */
+    readonly ref?: MessageRef;
+    readonly state: LedgerState;
+    readonly attempts: number;
+    readonly createdAt: number;
+    /** When the entry entered its CURRENT state (clock ms) — the failure
+     *  window reads THIS, never `createdAt`: an old entry failing NOW is
+     *  a fresh health signal, not yesterday's. Absent on entries written
+     *  before the field existed (created-at is the fallback). */
+    readonly stateSince?: number;
+    /** Platform message ids of the delivered send. */
+    readonly receipt?: string[];
+    readonly tag?: string;
+    /** Set by restart recovery: the platform may already hold this entry. */
+    readonly recovered?: boolean;
+}
+/**
+ * Enqueue's input: everything the caller owns (id, state, attempts,
+ * createdAt, recovered are the ledger's to stamp).
+ */
+export type LedgerInput = Omit<LedgerEntry, "id" | "state" | "attempts" | "createdAt" | "recovered" | "message"> & {
+    /** The full (bytes-bearing) message — the ledger serializes it. */
+    readonly message: OutboundMessage;
+    /**
+     * The workspace file records backing the message's files: the
+     * conversation id + workspace path the worker re-reads at send time
+     * through `resolveFiles`. Absent when the entry has no files.
+     */
+    readonly files?: readonly {
+        readonly conversationId: number;
+        readonly path: string;
+        readonly name: string;
+        readonly mime?: string;
+    }[];
+};
+/** The ledger's injectable options (tests inject a fake clock). */
+export interface LedgerOptions {
+    /** Clock ms for createdAt/prune decisions. Default: real. */
+    readonly now?: () => number;
+    readonly log?: EngineLog;
+}
+/** Delivered-entry retention (spec §8.6: pruned after 7 days). */
+export declare const PRUNE_AFTER_MS = 604800000;
+/**
+ * The delivery ledger, one instance per engine. Reads
+ * (`nextPending`/`failedSince`) serve the in-memory mirror loaded at
+ * construction and refreshed inside every queued mutation — the
+ * synchronous read contract the delivery worker's loop needs (its
+ * `nextPending` call cannot await inside its tick).
+ */
+export declare class Ledger {
+    private readonly file;
+    private readonly now;
+    private readonly log;
+    private entries;
+    constructor(path: string, opts?: LedgerOptions);
+    /** A snapshot of the entries (dedupe and status reads). */
+    list(): readonly LedgerEntry[];
+    /**
+     * Enqueue one entry (state `pending`, stamped id/createdAt). Returns
+     * undefined when `tag` is already present (the dedupe no-op) — the
+     * caller logs nothing; the replay was harmless.
+     */
+    enqueue(entry: LedgerInput): Promise<LedgerEntry | undefined>;
+    /**
+     * The oldest pending entry for `channel`, or undefined. Synchronous
+     * (the worker's loop is a tick, not an await point).
+     */
+    nextPending(channel: string): LedgerEntry | undefined;
+    /** Transition one entry's state (attempting/delivered/failed). */
+    mark(id: string, state: LedgerState, receipt?: readonly string[]): Promise<void>;
+    /**
+     * Restart recovery: every `attempting` entry becomes `pending` with
+     * the `recovered` flag (the worker prefixes the marker at send time).
+     * `pending` and terminal entries are untouched.
+     */
+    recoverAfterRestart(): Promise<void>;
+    /** How many entries are `failed` having FAILED within the window —
+     *  the state transition's clock, not creation: an old entry failing
+     *  NOW still degrades health. */
+    failedSince(ts: number): number;
+    /**
+     * Prune DELIVERED entries older than `PRUNE_AFTER_MS` (7 days), except
+     * job tags: those are the permanent one-shot delivery record, so age
+     * must never re-enable delivery. Failed and pending entries are never
+     * pruned — a failed entry is the health signal (§8.6: "nothing is
+     * dropped silently"), a pending entry is undelivered work.
+     */
+    prune(now: number): Promise<void>;
+    /**
+     * Re-read one entry's file bytes at send time (the `files` path →
+     * `readFile` rule). Returns the send-shaped files array, or undefined
+     * when the entry has none.
+     */
+    resolveFiles(host: SigrunHost, entry: LedgerEntry): Promise<OutboundMessage["files"] | undefined>;
+}

package/dist/state/ledger.js

@@ -0,0 +1,207 @@
+/**
+ * The durable delivery ledger (spec §8.6): every outbound send's state
+ * machine — `pending` → `attempting` → `delivered` (receipt) or
+ * `failed` — persisted at `<stateDir>/gateway/ledger.json` through
+ * {@link JsonFile} (0600, atomic, serialized updates).
+ *
+ * File bytes are NEVER ledgered: an entry whose message carries `files`
+ * stores a WORKSPACE PATH + conversation id instead, and the delivery
+ * worker re-reads the bytes through `host.conversations.readFile` at
+ * send time (the brief's rule — `files` bytes would bloat the ledger
+ * and pin upload bytes into engine state).
+ *
+ * Restart recovery: `pending` entries are sent as-is; `attempting`
+ * entries become `pending` with the `recovered` flag (the platform may
+ * already hold them — the worker prefixes the marker). Tag dedupe:
+ * enqueueing a tag that already exists returns undefined (the
+ * re-delivery no-op).
+ */
+import { randomUUID } from "node:crypto";
+import { JsonFile } from "./json-file.js";
+/** Delivered-entry retention (spec §8.6: pruned after 7 days). */
+export const PRUNE_AFTER_MS = 604_800_000;
+/**
+ * The delivery ledger, one instance per engine. Reads
+ * (`nextPending`/`failedSince`) serve the in-memory mirror loaded at
+ * construction and refreshed inside every queued mutation — the
+ * synchronous read contract the delivery worker's loop needs (its
+ * `nextPending` call cannot await inside its tick).
+ */
+export class Ledger {
+    file;
+    now;
+    log;
+    entries = [];
+    constructor(path, opts = {}) {
+        this.file = new JsonFile(path, () => ({ entries: [] }));
+        this.now = opts.now ?? Date.now;
+        this.log = opts.log;
+        // The mirror loads SYNCHRONOUSLY at construction (readSync): the
+        // queue is empty here, so nothing can interleave; a second instance
+        // over the same file (the restart path) observes the persisted
+        // entries from its first read.
+        this.entries = this.file.readSync().entries;
+    }
+    /** A snapshot of the entries (dedupe and status reads). */
+    list() {
+        return [...this.entries];
+    }
+    /**
+     * Enqueue one entry (state `pending`, stamped id/createdAt). Returns
+     * undefined when `tag` is already present (the dedupe no-op) — the
+     * caller logs nothing; the replay was harmless.
+     */
+    async enqueue(entry) {
+        const serialized = serializeMessage(entry.message, entry.files);
+        const { message: _message, files: _files, ...rest } = entry;
+        const stored = {
+            ...rest,
+            message: serialized,
+            id: randomUUID(),
+            state: "pending",
+            attempts: 0,
+            createdAt: this.now(),
+            stateSince: this.now(),
+        };
+        const state = await this.file.update((draft) => {
+            if (entry.tag !== undefined &&
+                draft.entries.some((row) => row.tag === entry.tag)) {
+                return;
+            }
+            draft.entries.push(stored);
+            this.entries = draft.entries;
+        });
+        // The update's draft mutates in place; the tag-dedupe path left the
+        // entry out (detect by id presence in the written state).
+        const written = state.entries.some((row) => row.id === stored.id);
+        return written ? stored : undefined;
+    }
+    /**
+     * The oldest pending entry for `channel`, or undefined. Synchronous
+     * (the worker's loop is a tick, not an await point).
+     */
+    nextPending(channel) {
+        return this.entries.find((entry) => entry.channel === channel && entry.state === "pending");
+    }
+    /** Transition one entry's state (attempting/delivered/failed). */
+    async mark(id, state, receipt) {
+        await this.file.update((draft) => {
+            const index = draft.entries.findIndex((row) => row.id === id);
+            if (index === -1)
+                return;
+            const row = draft.entries[index];
+            const next = {
+                ...row,
+                state,
+                // An attempt transition counts the attempt; delivered/failed
+                // keep the count the attempts produced.
+                attempts: state === "attempting" ? row.attempts + 1 : row.attempts,
+                // The state transition stamps its own clock (the failure
+                // window reads it — an old entry failing NOW is fresh).
+                stateSince: this.now(),
+                ...(receipt === undefined ? {} : { receipt: [...receipt] }),
+            };
+            draft.entries[index] = next;
+            this.entries = draft.entries;
+        });
+    }
+    /**
+     * Restart recovery: every `attempting` entry becomes `pending` with
+     * the `recovered` flag (the worker prefixes the marker at send time).
+     * `pending` and terminal entries are untouched.
+     */
+    async recoverAfterRestart() {
+        const recovered = await this.file.update((draft) => {
+            for (let index = 0; index < draft.entries.length; index++) {
+                const row = draft.entries[index];
+                if (row.state !== "attempting")
+                    continue;
+                draft.entries[index] = { ...row, state: "pending", recovered: true };
+            }
+            return;
+        });
+        if (recovered.entries.some((row) => row.recovered === true)) {
+            this.log?.info("ledger: recovered attempting entries after restart");
+        }
+        this.entries = recovered.entries;
+    }
+    /** How many entries are `failed` having FAILED within the window —
+     *  the state transition's clock, not creation: an old entry failing
+     *  NOW still degrades health. */
+    failedSince(ts) {
+        return this.entries.filter((entry) => entry.state === "failed" &&
+            (entry.stateSince ?? entry.createdAt) >= ts).length;
+    }
+    /**
+     * Prune DELIVERED entries older than `PRUNE_AFTER_MS` (7 days), except
+     * job tags: those are the permanent one-shot delivery record, so age
+     * must never re-enable delivery. Failed and pending entries are never
+     * pruned — a failed entry is the health signal (§8.6: "nothing is
+     * dropped silently"), a pending entry is undelivered work.
+     */
+    async prune(now) {
+        const pruned = await this.file.update((draft) => {
+            const before = draft.entries.length;
+            const kept = draft.entries.filter((entry) => entry.state !== "delivered" ||
+                entry.tag?.startsWith("job:") === true ||
+                now - entry.createdAt < PRUNE_AFTER_MS);
+            // In-place array replacement keeps the draft object identity.
+            draft.entries.length = 0;
+            draft.entries.push(...kept);
+            if (kept.length !== before) {
+                this.log?.debug(`ledger: pruned ${before - kept.length} delivered entries`);
+            }
+        });
+        this.entries = pruned.entries;
+    }
+    /**
+     * Re-read one entry's file bytes at send time (the `files` path →
+     * `readFile` rule). Returns the send-shaped files array, or undefined
+     * when the entry has none.
+     */
+    async resolveFiles(host, entry) {
+        const specs = entry.message.files;
+        if (specs === undefined || specs.length === 0)
+            return undefined;
+        const files = [];
+        for (const spec of specs) {
+            const read = await host.conversations.readFile(spec.conversationId, spec.path);
+            files.push({
+                name: spec.name,
+                ...(spec.mime === undefined ? {} : { mime: spec.mime }),
+                bytes: read.bytes,
+            });
+        }
+        return files;
+    }
+}
+/**
+ * Strip the bytes out of an outbound message for persistence: the
+ * `files` array is replaced by the workspace-path records the worker
+ * re-reads through `resolveFiles`. A message carrying bytes WITHOUT a
+ * file spec (the caller sent ephemeral buffers) drops them — the ledger
+ * never persists bytes, and the send would need the path spec anyway.
+ */
+function serializeMessage(message, files) {
+    if (files === undefined || files.length === 0) {
+        return { chat: message.chat, text: message.text, ...pickOptional(message) };
+    }
+    return {
+        chat: message.chat,
+        text: message.text,
+        ...pickOptional(message),
+        files: files.map((file) => ({
+            conversationId: file.conversationId,
+            path: file.path,
+            name: file.name,
+            ...(file.mime === undefined ? {} : { mime: file.mime }),
+        })),
+    };
+}
+/** The optional outbound fields, copied when present. */
+function pickOptional(message) {
+    return {
+        ...(message.replyTo === undefined ? {} : { replyTo: message.replyTo }),
+        ...(message.buttons === undefined ? {} : { buttons: message.buttons }),
+    };
+}

package/dist/state/seen.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The seen set (spec §8.4 step 2): the 24-hour message dedupe, persisted
+ * at `<stateDir>/gateway/seen.json`. IN-FLIGHT-AWARE: a claimed id
+ * stays unclaimable until its admission settles (commit on success,
+ * release on engine failure), so a platform webhook retry racing the
+ * first `receive` resolves `"dropped"` — never a double submission
+ * (Review Focus 1). Entries older than 86 400 000 ms are dropped on
+ * every write (the window sweep rides the write; no timers).
+ */
+/**
+ * The dedupe set, one instance per engine. `claim`/`release` are
+ * synchronous (the in-flight set is memory-only); `commit` persists.
+ * The window prune runs inside every `commit`'s queued write, so the
+ * file never grows past a day of ids even on a long-lived engine.
+ */
+export declare class SeenSet {
+    private readonly file;
+    private readonly inFlight;
+    constructor(path: string);
+    /**
+     * Try to claim `id` as of `now`: true when neither in flight nor
+     * committed inside the window; false otherwise. A true claim marks
+     * the id in flight until `commit` or `release`.
+     */
+    claim(id: string, now: number): boolean;
+    /** Release an in-flight claim (the admission failed — the platform
+     *  redelivers, so the id must be claimable again). */
+    release(id: string): void;
+    /** Durably mark `id` seen at `now` (the admission settled). */
+    commit(id: string, now: number): Promise<void>;
+    /** Is `id` committed within the window of `now`? (In-memory read of
+     *  the last observed state; the file is re-read inside `commit`'s
+     *  queue — the constructor cannot await, so the first commit loads.) */
+    private committedWithin;
+    /**
+     * The committed view: loaded at construction (readSync) and refreshed
+     * after every queued `commit` (the update's written draft IS the new
+     * committed state).
+     */
+    private observed;
+}

package/dist/state/seen.js

@@ -0,0 +1,77 @@
+/**
+ * The seen set (spec §8.4 step 2): the 24-hour message dedupe, persisted
+ * at `<stateDir>/gateway/seen.json`. IN-FLIGHT-AWARE: a claimed id
+ * stays unclaimable until its admission settles (commit on success,
+ * release on engine failure), so a platform webhook retry racing the
+ * first `receive` resolves `"dropped"` — never a double submission
+ * (Review Focus 1). Entries older than 86 400 000 ms are dropped on
+ * every write (the window sweep rides the write; no timers).
+ */
+import { JsonFile } from "./json-file.js";
+/** The dedupe window (ms) — the plan's pinned 24 h. */
+const WINDOW_MS = 86_400_000;
+/**
+ * The dedupe set, one instance per engine. `claim`/`release` are
+ * synchronous (the in-flight set is memory-only); `commit` persists.
+ * The window prune runs inside every `commit`'s queued write, so the
+ * file never grows past a day of ids even on a long-lived engine.
+ */
+export class SeenSet {
+    file;
+    inFlight = new Set();
+    constructor(path) {
+        this.file = new JsonFile(path, () => ({}));
+        // The committed view loads SYNCHRONOUSLY at construction: a second
+        // instance over the same file (the restart path) must reject a
+        // redelivered id from its first `claim` — the constructor cannot
+        // await, and the queue is empty here so nothing can interleave.
+        this.observed = this.file.readSync();
+    }
+    /**
+     * Try to claim `id` as of `now`: true when neither in flight nor
+     * committed inside the window; false otherwise. A true claim marks
+     * the id in flight until `commit` or `release`.
+     */
+    claim(id, now) {
+        if (this.inFlight.has(id))
+            return false;
+        if (this.committedWithin(id, now))
+            return false;
+        this.inFlight.add(id);
+        return true;
+    }
+    /** Release an in-flight claim (the admission failed — the platform
+     *  redelivers, so the id must be claimable again). */
+    release(id) {
+        this.inFlight.delete(id);
+    }
+    /** Durably mark `id` seen at `now` (the admission settled). */
+    async commit(id, now) {
+        this.inFlight.delete(id);
+        const draft = await this.file.update((state) => {
+            state[id] = now;
+            // The window sweep: entries older than the window are dropped on
+            // every write, so the file carries at most one day of ids.
+            for (const [key, at] of Object.entries(state)) {
+                if (now - at > WINDOW_MS)
+                    delete state[key];
+            }
+        });
+        // The post-write state IS the committed view a later claim reads
+        // (the update returned the written draft).
+        this.observed = draft;
+    }
+    /** Is `id` committed within the window of `now`? (In-memory read of
+     *  the last observed state; the file is re-read inside `commit`'s
+     *  queue — the constructor cannot await, so the first commit loads.) */
+    committedWithin(id, now) {
+        const at = this.observed[id];
+        return at !== undefined && now - at <= WINDOW_MS;
+    }
+    /**
+     * The committed view: loaded at construction (readSync) and refreshed
+     * after every queued `commit` (the update's written draft IS the new
+     * committed state).
+     */
+    observed = {};
+}

package/dist/status-route.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The admin status route (spec §8.12): `GET /v1/ext/gateway/status` →
+ * `{ channels, pairing }`. Auth is declared `admin` — core's route
+ * mount enforces the principal's admin flag (403 otherwise); this
+ * module only renders the read it is handed.
+ *
+ * `pairing` ships empty until Task 4 (the pairing store lands there);
+ * the field is present from day one so clients see a stable shape.
+ * Sender ids in the pairing rows are HASHED (8-hex, spec §8.12's log
+ * rule generalized to operator output) — Task 4 fills the rows.
+ */
+import type { ExtensionRouteContribution } from "@sigrun/sigrun/extension";
+import type { ChannelStatus } from "./supervisor.js";
+/** One pending pairing request (admin view, WITHOUT the code). */
+export interface StatusPairingRow {
+    readonly channel: string;
+    /** The hashed sender id — never the raw platform id. */
+    readonly sender: string;
+    readonly createdAt: number;
+}
+/** The status route's response body. */
+export interface GatewayStatus {
+    readonly channels: Readonly<Record<string, ChannelStatus>>;
+    readonly pairing: readonly StatusPairingRow[];
+}
+/** The engine-side read the route renders (fresh per request). */
+export type StatusRead = () => GatewayStatus;
+/**
+ * Build the status route over a status read. The handler is a pure
+ * render: the engine owns the rows, the route never touches the host.
+ */
+export declare function createStatusRoute(read: StatusRead): ExtensionRouteContribution;

package/dist/status-route.js

@@ -0,0 +1,26 @@
+/**
+ * The admin status route (spec §8.12): `GET /v1/ext/gateway/status` →
+ * `{ channels, pairing }`. Auth is declared `admin` — core's route
+ * mount enforces the principal's admin flag (403 otherwise); this
+ * module only renders the read it is handed.
+ *
+ * `pairing` ships empty until Task 4 (the pairing store lands there);
+ * the field is present from day one so clients see a stable shape.
+ * Sender ids in the pairing rows are HASHED (8-hex, spec §8.12's log
+ * rule generalized to operator output) — Task 4 fills the rows.
+ */
+/**
+ * Build the status route over a status read. The handler is a pure
+ * render: the engine owns the rows, the route never touches the host.
+ */
+export function createStatusRoute(read) {
+    return {
+        method: "GET",
+        path: "status",
+        auth: "admin",
+        handler: async () => new Response(`${JSON.stringify(read())}\n`, {
+            status: 200,
+            headers: { "content-type": "application/json" },
+        }),
+    };
+}