@agentrux/agentrux-openclaw-plugin 0.3.2

package/dist/index.js

@@ -0,0 +1,345 @@
+"use strict";
+/**
+ * AgenTrux Ingress + Tools plugin for OpenClaw.
+ *
+ * Tools (LLM-callable):
+ *   - agentrux_activate, agentrux_publish, agentrux_read,
+ *     agentrux_send_message, agentrux_redeem_grant
+ *
+ * Ingress (external → OpenClaw):
+ *   - registerHttpRoute("/agentrux/webhook") — AgenTrux Webhook receiver
+ *   - Dispatcher (async loop) — subagent.run() + outbox + waterline cursor
+ *   - SafetyPoller — gap detection fallback
+ *
+ * Credentials: ~/.agentrux/credentials.json (0600)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = default_1;
+const credentials_1 = require("./credentials");
+const http_client_1 = require("./http-client");
+const cursor_1 = require("./cursor");
+const queue_1 = require("./queue");
+const webhook_handler_1 = require("./webhook-handler");
+const dispatcher_1 = require("./dispatcher");
+const poller_1 = require("./poller");
+const sse_listener_1 = require("./sse-listener");
+// Module-level state for tools (shared across tool calls)
+let credentials = null;
+function getCredentials() {
+    if (!credentials) {
+        credentials = (0, credentials_1.loadCredentials)();
+        if (!credentials)
+            throw new Error("Not connected to AgenTrux. Use activate first.");
+    }
+    return credentials;
+}
+async function toolAuthRequest(method, urlPath, body) {
+    return (0, http_client_1.authRequest)(getCredentials(), method, urlPath, body);
+}
+// ---------------------------------------------------------------------------
+// Plugin entry
+// ---------------------------------------------------------------------------
+function default_1(api) {
+    // Ensure logger has all required methods (OpenClaw logger may not match console interface)
+    const rawLogger = api.logger || {};
+    const logger = {
+        info: (...a) => (rawLogger.info || console.log)(...a),
+        warn: (...a) => (rawLogger.warn || console.warn)(...a),
+        error: (...a) => (rawLogger.error || console.error)(...a),
+    };
+    // =======================================================================
+    // TOOLS (available to LLM in all modes)
+    // =======================================================================
+    // --- activate ---
+    api.registerTool({
+        name: "agentrux_activate",
+        description: "Connect to AgenTrux with a one-time activation code. " +
+            "Returns script_id, client_secret, and available topics. " +
+            "Credentials are saved permanently for future sessions.",
+        parameters: {
+            type: "object",
+            properties: {
+                activation_code: { type: "string", description: "One-time activation code (ac_...)" },
+                base_url: { type: "string", description: "AgenTrux API URL (default: https://api.agentrux.com)" },
+            },
+            required: ["activation_code"],
+        },
+        async execute(_id, params) {
+            const baseUrl = params.base_url || "https://api.agentrux.com";
+            const r = await (0, http_client_1.httpJson)("POST", `${baseUrl}/auth/activate`, {
+                activation_code: params.activation_code,
+            });
+            if (r.status !== 200) {
+                return { content: [{ type: "text", text: `Activation failed: ${JSON.stringify(r.data)}` }] };
+            }
+            const creds = { base_url: baseUrl, script_id: r.data.script_id, clientSecret: r.data.client_secret };
+            (0, credentials_1.saveCredentials)(creds);
+            credentials = creds;
+            const grants = (r.data.grants || []).map((g) => `  - ${g.topic_id} (${g.action})`).join("\n");
+            return {
+                content: [{ type: "text", text: `Connected to AgenTrux!\nScript ID: ${r.data.script_id}\nTopics:\n${grants}` }],
+            };
+        },
+    }, { optional: true });
+    // --- publish ---
+    api.registerTool({
+        name: "agentrux_publish",
+        description: "Publish an event to an AgenTrux topic.",
+        parameters: {
+            type: "object",
+            properties: {
+                topic_id: { type: "string", description: "UUID of the topic" },
+                event_type: { type: "string", description: "Event type (e.g. 'message.send')" },
+                payload: { type: "object", description: "JSON payload" },
+                correlation_id: { type: "string", description: "Optional correlation ID" },
+                reply_topic: { type: "string", description: "Optional reply topic UUID" },
+            },
+            required: ["topic_id", "event_type", "payload"],
+        },
+        async execute(_id, params) {
+            const body = { type: params.event_type, payload: params.payload };
+            if (params.correlation_id)
+                body.correlation_id = params.correlation_id;
+            if (params.reply_topic)
+                body.reply_topic = params.reply_topic;
+            const result = await toolAuthRequest("POST", `/topics/${params.topic_id}/events`, body);
+            return { content: [{ type: "text", text: `Event published (event_id: ${result.event_id})` }] };
+        },
+    });
+    // --- read ---
+    api.registerTool({
+        name: "agentrux_read",
+        description: "Read events from an AgenTrux topic.",
+        parameters: {
+            type: "object",
+            properties: {
+                topic_id: { type: "string", description: "UUID of the topic" },
+                limit: { type: "number", description: "Max events to return (default 10)" },
+                event_type: { type: "string", description: "Filter by event type" },
+            },
+            required: ["topic_id"],
+        },
+        async execute(_id, params) {
+            const query = new URLSearchParams();
+            query.set("limit", String(params.limit || 10));
+            if (params.event_type)
+                query.set("type", params.event_type);
+            const result = await toolAuthRequest("GET", `/topics/${params.topic_id}/events?${query}`);
+            const items = result.items || [];
+            if (items.length === 0)
+                return { content: [{ type: "text", text: "No events found." }] };
+            const lines = items.map((e) => `[seq:${e.sequence_no}] ${e.type} — ${JSON.stringify(e.payload)} (${e.correlation_id || "-"})`);
+            return { content: [{ type: "text", text: `${items.length} events:\n${lines.join("\n")}` }] };
+        },
+    });
+    // --- send_message ---
+    api.registerTool({
+        name: "agentrux_send_message",
+        description: "Send a message to another agent and wait for a reply.",
+        parameters: {
+            type: "object",
+            properties: {
+                topic_id: { type: "string", description: "Target agent's topic UUID" },
+                reply_topic: { type: "string", description: "Your topic UUID for replies" },
+                message: { type: "string", description: "Message text" },
+                timeout_seconds: { type: "number", description: "Wait timeout (default 30)" },
+            },
+            required: ["topic_id", "reply_topic", "message"],
+        },
+        async execute(_id, params) {
+            const corrId = `msg-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+            const timeout = (params.timeout_seconds || 30) * 1000;
+            await toolAuthRequest("POST", `/topics/${params.topic_id}/events`, {
+                type: "message.request",
+                payload: { text: params.message },
+                correlation_id: corrId,
+                reply_topic: params.reply_topic,
+            });
+            const start = Date.now();
+            while (Date.now() - start < timeout) {
+                const result = await toolAuthRequest("GET", `/topics/${params.reply_topic}/events?limit=20`);
+                for (const e of result.items || []) {
+                    if (e.correlation_id === corrId) {
+                        return { content: [{ type: "text", text: `Reply:\n${JSON.stringify(e.payload, null, 2)}` }] };
+                    }
+                }
+                await new Promise((r) => setTimeout(r, 2000));
+            }
+            return { content: [{ type: "text", text: `No reply within ${params.timeout_seconds || 30}s.` }] };
+        },
+    });
+    // --- redeem_grant ---
+    api.registerTool({
+        name: "agentrux_redeem_grant",
+        description: "Redeem an invite code for cross-account topic access.",
+        parameters: {
+            type: "object",
+            properties: { invite_code: { type: "string", description: "Invite code (inv_...)" } },
+            required: ["invite_code"],
+        },
+        async execute(_id, params) {
+            const creds = getCredentials();
+            const r = await (0, http_client_1.httpJson)("POST", `${creds.base_url}/auth/redeem-invite-code`, {
+                invite_code: params.invite_code,
+                script_id: creds.script_id,
+                client_secret: creds.clientSecret,
+            });
+            if (r.status >= 400) {
+                return { content: [{ type: "text", text: `Failed: ${JSON.stringify(r.data)}` }] };
+            }
+            (0, http_client_1.invalidateToken)();
+            return {
+                content: [{ type: "text", text: `Access granted! Topic: ${r.data.topic_id} (${r.data.action})` }],
+            };
+        },
+    }, { optional: true });
+    // --- upload ---
+    api.registerTool({
+        name: "agentrux_upload",
+        description: "Upload a local file to AgenTrux and get a download URL. " +
+            "Use this to attach screenshots, logs, or other files to your response.",
+        parameters: {
+            type: "object",
+            properties: {
+                topic_id: { type: "string", description: "Topic UUID to attach the file to" },
+                file_path: { type: "string", description: "Absolute path to the local file" },
+                content_type: { type: "string", description: "MIME type (e.g. image/png, text/plain)" },
+            },
+            required: ["topic_id", "file_path", "content_type"],
+        },
+        async execute(_id, params) {
+            const creds = getCredentials();
+            const result = await (0, http_client_1.uploadFile)(creds, params.topic_id, params.file_path, params.content_type);
+            return {
+                content: [{
+                        type: "text",
+                        text: `File uploaded!\nObject ID: ${result.object_id}\nDownload URL: ${result.download_url}`,
+                    }],
+            };
+        },
+    });
+    // =======================================================================
+    // INGRESS (Webhook + Dispatcher + Poller — only in full registration mode)
+    // =======================================================================
+    if (api.registrationMode !== "full")
+        return;
+    // Prevent multiple ingress starts (plugin loaded multiple times by OpenClaw)
+    if (globalThis.__agentruxIngressStarted)
+        return;
+    globalThis.__agentruxIngressStarted = true;
+    // Clear token cache on startup to pick up latest grant scopes
+    (0, http_client_1.invalidateToken)();
+    // pluginConfig may be undefined if OpenClaw doesn't resolve it due to id mismatch
+    // Fallback: read from api.config (full OpenClaw config)
+    const pluginConfig = api.pluginConfig
+        || api.config?.plugins?.entries?.["agentrux-openclaw-plugin"]?.config
+        || {};
+    const commandTopicId = pluginConfig.commandTopicId;
+    const resultTopicId = pluginConfig.resultTopicId;
+    const webhookSecret = pluginConfig.webhookSecret;
+    const agentId = pluginConfig.agentId;
+    // Skip ingress if not configured
+    if (!commandTopicId || !resultTopicId || !agentId) {
+        logger.info?.("[agentrux] Ingress not configured (missing commandTopicId/resultTopicId/agentId). Tools-only mode.");
+        return;
+    }
+    const creds = (0, credentials_1.loadCredentials)();
+    if (!creds) {
+        logger.warn?.("[agentrux] No credentials found. Run agentrux_activate first. Ingress disabled.");
+        return;
+    }
+    // Initialize components
+    const cursor = (0, cursor_1.loadCursor)();
+    const queue = new queue_1.BoundedQueue(100);
+    const dispatcher = new dispatcher_1.Dispatcher({
+        commandTopicId,
+        resultTopicId,
+        agentId,
+        maxConcurrency: pluginConfig.maxConcurrency || 3,
+        subagentTimeoutMs: pluginConfig.subagentTimeoutMs || 120_000,
+        gatewayPort: 18789, // OpenClaw default gateway port
+    }, creds, cursor, queue, logger);
+    const ingressMode = pluginConfig.ingressMode || "webhook";
+    const poller = new poller_1.SafetyPoller(creds, commandTopicId, cursor, queue, pluginConfig.pollIntervalMs || 60_000, // default 60s
+    logger);
+    // SSE listener (only when ingressMode=sse)
+    const sseListener = ingressMode === "sse"
+        ? new sse_listener_1.SSEListener(creds, commandTopicId, queue, logger)
+        : null;
+    // --- Internal dispatch endpoint (subagent.run() in Gateway request context) ---
+    api.registerHttpRoute({
+        path: "/agentrux/dispatch",
+        auth: "plugin",
+        match: "exact",
+        handler: async (req, res) => {
+            const chunks = [];
+            await new Promise((resolve) => {
+                req.on("data", (c) => chunks.push(c));
+                req.on("end", resolve);
+            });
+            const params = JSON.parse(Buffer.concat(chunks).toString());
+            try {
+                // OpenClaw 2026.3.24+: provider/model override is not authorized
+                // for plugin subagent runs. The agent's configured model is used.
+                const { runId } = await api.runtime.subagent.run({
+                    sessionKey: params.sessionKey,
+                    message: params.message,
+                    idempotencyKey: params.idempotencyKey,
+                    deliver: false,
+                });
+                const waitResult = await api.runtime.subagent.waitForRun({
+                    runId,
+                    timeoutMs: params.timeoutMs || 60_000,
+                });
+                let responseText = "";
+                if (waitResult.status === "ok") {
+                    const { messages } = await api.runtime.subagent.getSessionMessages({
+                        sessionKey: params.sessionKey,
+                    });
+                    const lastAssistant = [...messages].reverse().find((m) => m.role === "assistant");
+                    if (lastAssistant?.content) {
+                        for (const block of lastAssistant.content) {
+                            if (block.type === "text" && block.text)
+                                responseText += block.text;
+                        }
+                    }
+                }
+                res.statusCode = 200;
+                res.setHeader("Content-Type", "application/json");
+                res.end(JSON.stringify({ responseText, status: waitResult.status }));
+            }
+            catch (e) {
+                res.statusCode = 500;
+                res.end(JSON.stringify({ responseText: "", status: "error", error: e.message }));
+            }
+            return true;
+        },
+    });
+    // --- Webhook endpoint (only when ingressMode=webhook) ---
+    if (ingressMode === "webhook" && webhookSecret) {
+        api.registerHttpRoute({
+            path: "/agentrux/webhook",
+            auth: "plugin",
+            match: "exact",
+            handler: (0, webhook_handler_1.createWebhookHandler)(queue, webhookSecret, commandTopicId),
+        });
+        logger.info?.("[agentrux] Webhook endpoint registered: /agentrux/webhook");
+    }
+    else if (ingressMode === "webhook" && !webhookSecret) {
+        logger.warn?.("[agentrux] ingressMode=webhook but webhookSecret not set. Falling back to poll-only.");
+    }
+    // --- Start Dispatcher + (Webhook|SSE) + Poller ---
+    setTimeout(() => {
+        try {
+            dispatcher.start().catch((e) => logger.error("[agentrux] Dispatcher failed:", e));
+            if (sseListener) {
+                sseListener.start().catch((e) => logger.error("[agentrux] SSE failed:", e));
+            }
+            poller.start().catch((e) => logger.error("[agentrux] Poller failed:", e));
+            logger.info(`[agentrux] Ingress started: mode=${ingressMode} topic=${commandTopicId} agent=${agentId} poll@${pluginConfig.pollIntervalMs || 60000}ms`);
+        }
+        catch (e) {
+            logger.error("[agentrux] Ingress startup error:", e);
+        }
+    }, 5000);
+}

package/dist/outbox.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Outbox pattern: decouple subagent completion from result publish.
+ * Entries: pending_publish → published | dead_letter
+ * Published entries are retained for idempotency across restarts.
+ */
+import { type Credentials } from "./credentials";
+export interface OutboxEntry {
+    eventId: string;
+    requestId: string;
+    sequenceNo: number;
+    status: "pending_publish" | "published" | "dead_letter";
+    result: {
+        message: string;
+        status: string;
+        conversationKey?: string;
+        attachments?: Array<{
+            url: string;
+            type: string;
+        }>;
+    };
+    createdAt: string;
+    retryCount: number;
+}
+export declare function addToOutbox(entry: Omit<OutboxEntry, "status" | "retryCount" | "createdAt">): void;
+/**
+ * Find by request_id across all states (pending, published, dead_letter).
+ * Used for application-layer idempotency.
+ */
+export declare function findByRequestId(requestId: string): OutboxEntry | undefined;
+/**
+ * Flush pending_publish entries: attempt publish, move to published or dead_letter.
+ * Returns sequence numbers that were finalized (published or dead_letter).
+ */
+export declare function flushOutbox(creds: Credentials, resultTopicId: string, logger: {
+    error: (...args: any[]) => void;
+    warn: (...args: any[]) => void;
+}): Promise<number[]>;

package/dist/outbox.js

@@ -0,0 +1,142 @@
+"use strict";
+/**
+ * Outbox pattern: decouple subagent completion from result publish.
+ * Entries: pending_publish → published | dead_letter
+ * Published entries are retained for idempotency across restarts.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addToOutbox = addToOutbox;
+exports.findByRequestId = findByRequestId;
+exports.flushOutbox = flushOutbox;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const http_client_1 = require("./http-client");
+const HOME = process.env.HOME || process.env.USERPROFILE || "~";
+const OUTBOX_PATH = path.join(HOME, ".agentrux", "outbox.json");
+const MAX_RETRIES = 3;
+const MAX_PUBLISHED_HISTORY = 500;
+function loadStore() {
+    try {
+        if (fs.existsSync(OUTBOX_PATH)) {
+            const raw = JSON.parse(fs.readFileSync(OUTBOX_PATH, "utf-8"));
+            return {
+                entries: raw.entries || [],
+                published: raw.published || [],
+                deadLetter: raw.deadLetter || [],
+            };
+        }
+    }
+    catch { }
+    return { entries: [], published: [], deadLetter: [] };
+}
+function persistStore(store) {
+    const dir = path.dirname(OUTBOX_PATH);
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const tmpPath = OUTBOX_PATH + ".tmp." + process.pid;
+    fs.writeFileSync(tmpPath, JSON.stringify(store, null, 2), { mode: 0o600 });
+    try {
+        fs.fsyncSync(fs.openSync(tmpPath, "r"));
+    }
+    catch { }
+    fs.renameSync(tmpPath, OUTBOX_PATH);
+}
+function addToOutbox(entry) {
+    const store = loadStore();
+    store.entries.push({
+        ...entry,
+        status: "pending_publish",
+        retryCount: 0,
+        createdAt: new Date().toISOString(),
+    });
+    persistStore(store);
+}
+/**
+ * Find by request_id across all states (pending, published, dead_letter).
+ * Used for application-layer idempotency.
+ */
+function findByRequestId(requestId) {
+    const store = loadStore();
+    return (store.entries.find((e) => e.requestId === requestId) ||
+        store.published.find((e) => e.requestId === requestId) ||
+        store.deadLetter.find((e) => e.requestId === requestId));
+}
+/**
+ * Flush pending_publish entries: attempt publish, move to published or dead_letter.
+ * Returns sequence numbers that were finalized (published or dead_letter).
+ */
+async function flushOutbox(creds, resultTopicId, logger) {
+    const store = loadStore();
+    const finalized = [];
+    for (const entry of store.entries) {
+        if (entry.status !== "pending_publish")
+            continue;
+        try {
+            await (0, http_client_1.publishEvent)(creds, resultTopicId, "openclaw.response", {
+                request_id: entry.requestId,
+                conversation_key: entry.result.conversationKey,
+                status: entry.result.status,
+                message: entry.result.message,
+            });
+            entry.status = "published";
+            store.published.push({ ...entry });
+            finalized.push(entry.sequenceNo);
+        }
+        catch (e) {
+            entry.retryCount++;
+            if (entry.retryCount >= MAX_RETRIES) {
+                entry.status = "dead_letter";
+                store.deadLetter.push({ ...entry });
+                finalized.push(entry.sequenceNo);
+                logger.warn(`Outbox dead_letter: requestId=${entry.requestId} seq=${entry.sequenceNo}`);
+            }
+            else {
+                logger.error(`Outbox publish retry ${entry.retryCount}/${MAX_RETRIES}: ${e.message}`);
+            }
+        }
+    }
+    // Remove finalized from entries (keep only pending)
+    store.entries = store.entries.filter((e) => e.status === "pending_publish");
+    // Cap published history
+    if (store.published.length > MAX_PUBLISHED_HISTORY) {
+        store.published = store.published.slice(-MAX_PUBLISHED_HISTORY);
+    }
+    if (store.deadLetter.length > 1000) {
+        store.deadLetter = store.deadLetter.slice(-1000);
+    }
+    persistStore(store);
+    return finalized;
+}

package/dist/poller.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Safety poller: fixed-interval Pull API to detect gaps and complement Webhook.
+ * Only enqueues events not already processed or in-flight.
+ */
+import { type Credentials } from "./credentials";
+import { type CursorState } from "./cursor";
+import { type BoundedQueue } from "./queue";
+export declare class SafetyPoller {
+    private creds;
+    private commandTopicId;
+    private cursor;
+    private queue;
+    private intervalMs;
+    private logger;
+    private stopped;
+    private running;
+    constructor(creds: Credentials, commandTopicId: string, cursor: CursorState, queue: BoundedQueue, intervalMs: number, logger: {
+        info: (...a: any[]) => void;
+        error: (...a: any[]) => void;
+    });
+    start(): Promise<void>;
+    stop(): void;
+    private loop;
+    private poll;
+}

package/dist/poller.js

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * Safety poller: fixed-interval Pull API to detect gaps and complement Webhook.
+ * Only enqueues events not already processed or in-flight.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SafetyPoller = void 0;
+const http_client_1 = require("./http-client");
+const cursor_1 = require("./cursor");
+class SafetyPoller {
+    constructor(creds, commandTopicId, cursor, queue, intervalMs, logger) {
+        this.creds = creds;
+        this.commandTopicId = commandTopicId;
+        this.cursor = cursor;
+        this.queue = queue;
+        this.intervalMs = intervalMs;
+        this.logger = logger;
+        this.stopped = false;
+        this.running = false;
+    }
+    async start() {
+        if (this.running)
+            return;
+        this.running = true;
+        this.stopped = false;
+        this.loop();
+    }
+    stop() {
+        this.stopped = true;
+    }
+    async loop() {
+        try {
+            while (!this.stopped) {
+                try {
+                    await this.poll();
+                }
+                catch (e) {
+                    this.logger.error("Safety poller error:", e.message);
+                }
+                await sleep(this.intervalMs);
+            }
+        }
+        finally {
+            this.running = false;
+        }
+    }
+    async poll() {
+        const events = await (0, http_client_1.pullEvents)(this.creds, this.commandTopicId, this.cursor.waterline, 20);
+        let enqueued = 0;
+        for (const evt of events) {
+            const seq = evt.sequence_no;
+            // Skip already processed
+            if (seq <= this.cursor.waterline)
+                continue;
+            if (this.cursor.completed.has(seq))
+                continue;
+            if (this.cursor.inFlight.has(seq))
+                continue;
+            if ((0, cursor_1.isEventProcessed)(this.cursor, evt.event_id))
+                continue;
+            const ok = this.queue.enqueue({
+                topicId: this.commandTopicId,
+                latestSequenceNo: seq,
+                eventId: evt.event_id,
+                timestamp: Date.now(),
+            });
+            if (ok)
+                enqueued++;
+        }
+        if (enqueued > 0) {
+            this.logger.info(`Safety poller: enqueued ${enqueued} new events`);
+        }
+    }
+}
+exports.SafetyPoller = SafetyPoller;
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}

package/dist/queue.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Bounded in-memory queue for event hints.
+ */
+export interface QueueItem {
+    topicId: string;
+    latestSequenceNo: number;
+    eventId?: string;
+    timestamp: number;
+}
+export declare class BoundedQueue {
+    private items;
+    private maxSize;
+    constructor(maxSize?: number);
+    enqueue(item: QueueItem): boolean;
+    dequeue(count: number): QueueItem[];
+    get size(): number;
+    get isFull(): boolean;
+}

package/dist/queue.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * Bounded in-memory queue for event hints.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BoundedQueue = void 0;
+class BoundedQueue {
+    constructor(maxSize = 100) {
+        this.items = [];
+        this.maxSize = maxSize;
+    }
+    enqueue(item) {
+        if (this.items.length >= this.maxSize) {
+            return false; // queue full — caller should return 503
+        }
+        this.items.push(item);
+        return true;
+    }
+    dequeue(count) {
+        return this.items.splice(0, Math.min(count, this.items.length));
+    }
+    get size() {
+        return this.items.length;
+    }
+    get isFull() {
+        return this.items.length >= this.maxSize;
+    }
+}
+exports.BoundedQueue = BoundedQueue;