@jagilber-org/index-server 1.19.1

package/dist/services/messaging/agentMailbox.js

@@ -0,0 +1,353 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentMailbox = void 0;
+/**
+ * Core messaging service — AgentMailbox.
+ *
+ * In-memory message store with JSONL persistence, TTL sweep,
+ * recipient visibility filtering, and cross-process file watching.
+ *
+ * Messages are NOT stored in the instruction index (A-3).
+ * Config via runtimeConfig (S-4).
+ */
+const path_1 = __importDefault(require("path"));
+const messagingTypes_1 = require("./messagingTypes");
+const messagingPersistence_1 = require("./messagingPersistence");
+let messageCounter = 0;
+const instanceId = `${process.pid}@${path_1.default.basename(process.cwd())}`;
+class AgentMailbox {
+    store = new Map();
+    idIndex = new Map();
+    config;
+    sweepTimer = null;
+    loaded = false;
+    constructor(config) {
+        this.config = config;
+        if (config.sweepIntervalMs > 0) {
+            this.startSweep();
+        }
+    }
+    /** Load messages from disk if not already loaded. */
+    ensureLoaded() {
+        if (this.loaded)
+            return;
+        this.loaded = true;
+        const msgs = (0, messagingPersistence_1.loadMessages)(this.config.dir);
+        for (const msg of msgs) {
+            const key = this.makeKey(msg);
+            this.store.set(key, msg);
+            this.idIndex.set(msg.id, key);
+        }
+    }
+    /** Send a message. Returns the message ID. */
+    async send(opts) {
+        this.ensureLoaded();
+        const id = `msg-${++messageCounter}-${Date.now()}`;
+        const ttl = opts.persistent
+            ? 0
+            : Math.min(Math.max(1, opts.ttlSeconds ?? messagingTypes_1.DEFAULT_TTL_SECONDS), messagingTypes_1.MAX_TTL_SECONDS);
+        const msg = {
+            id,
+            channel: opts.channel,
+            sender: opts.sender,
+            recipients: opts.recipients,
+            body: opts.body,
+            createdAt: new Date().toISOString(),
+            ttlSeconds: ttl,
+            persistent: opts.persistent,
+            readBy: [],
+            payload: opts.payload,
+            priority: opts.priority,
+            parentId: opts.parentId,
+            requiresAck: opts.requiresAck,
+            ackBySeconds: opts.ackBySeconds,
+            tags: opts.tags,
+            origin: instanceId,
+        };
+        const key = this.makeKey(msg);
+        this.store.set(key, msg);
+        this.idIndex.set(id, key);
+        // Persist to JSONL
+        (0, messagingPersistence_1.appendMessage)(msg, this.config.dir);
+        return id;
+    }
+    /** Read messages with visibility filtering. */
+    read(opts = {}) {
+        this.ensureLoaded();
+        let messages = Array.from(this.store.values());
+        // Filter by channel
+        if (opts.channel) {
+            messages = messages.filter(m => m.channel === opts.channel);
+        }
+        // Filter by recipient visibility
+        if (opts.reader) {
+            messages = messages.filter(m => this.isRecipient(m, opts.reader));
+        }
+        // Filter unread-only
+        if (opts.unreadOnly && opts.reader) {
+            messages = messages.filter(m => !m.readBy?.includes(opts.reader));
+        }
+        // Filter by tags (match any)
+        if (opts.tags?.length) {
+            messages = messages.filter(m => m.tags?.some(t => opts.tags.includes(t)));
+        }
+        // Filter by sender
+        if (opts.sender) {
+            messages = messages.filter(m => m.sender === opts.sender);
+        }
+        // Sort by createdAt (oldest first)
+        messages.sort((a, b) => new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime());
+        // Apply limit
+        if (opts.limit && opts.limit > 0) {
+            messages = messages.slice(0, opts.limit);
+        }
+        // Mark as read
+        if (opts.markRead && opts.reader && opts.reader !== '*') {
+            for (const msg of messages) {
+                if (!msg.readBy)
+                    msg.readBy = [];
+                if (!msg.readBy.includes(opts.reader)) {
+                    msg.readBy.push(opts.reader);
+                }
+            }
+            this.persistAll();
+        }
+        return messages;
+    }
+    /** List all channels with message counts. */
+    listChannels() {
+        this.ensureLoaded();
+        const channels = new Map();
+        for (const msg of this.store.values()) {
+            const info = channels.get(msg.channel) || { count: 0, latest: null };
+            info.count++;
+            if (!info.latest || msg.createdAt > info.latest) {
+                info.latest = msg.createdAt;
+            }
+            channels.set(msg.channel, info);
+        }
+        return Array.from(channels.entries()).map(([channel, info]) => ({
+            channel,
+            messageCount: info.count,
+            latestAt: info.latest,
+        }));
+    }
+    /** Acknowledge messages by marking them read. Returns count acknowledged. */
+    ack(messageIds, reader) {
+        this.ensureLoaded();
+        let count = 0;
+        for (const id of messageIds) {
+            const key = this.idIndex.get(id);
+            if (!key)
+                continue;
+            const msg = this.store.get(key);
+            if (!msg)
+                continue;
+            if (!msg.readBy)
+                msg.readBy = [];
+            if (!msg.readBy.includes(reader)) {
+                msg.readBy.push(reader);
+                count++;
+            }
+        }
+        if (count > 0)
+            this.persistAll();
+        return count;
+    }
+    /** Get stats for a reader. */
+    getStats(reader) {
+        this.ensureLoaded();
+        const messages = Array.from(this.store.values());
+        const visible = messages.filter(m => this.isRecipient(m, reader));
+        const unread = visible.filter(m => !m.readBy?.includes(reader));
+        const channelSet = new Set(visible.map(m => m.channel));
+        return {
+            total: visible.length,
+            unread: unread.length,
+            channels: channelSet.size,
+        };
+    }
+    /** Get a single message by ID. */
+    getMessage(id) {
+        this.ensureLoaded();
+        const key = this.idIndex.get(id);
+        return key ? this.store.get(key) : undefined;
+    }
+    /** Update mutable fields of a message. */
+    updateMessage(id, updates) {
+        this.ensureLoaded();
+        const key = this.idIndex.get(id);
+        if (!key)
+            return undefined;
+        const msg = this.store.get(key);
+        if (!msg)
+            return undefined;
+        if (updates.body !== undefined)
+            msg.body = updates.body;
+        if (updates.recipients !== undefined)
+            msg.recipients = updates.recipients;
+        if (updates.payload !== undefined)
+            msg.payload = updates.payload;
+        if (updates.persistent !== undefined) {
+            msg.persistent = updates.persistent;
+            if (updates.persistent)
+                msg.ttlSeconds = 0;
+        }
+        this.persistAll();
+        return msg;
+    }
+    /** Purge all messages. Returns count removed. */
+    purgeAll() {
+        this.ensureLoaded();
+        const count = this.store.size;
+        this.store.clear();
+        this.idIndex.clear();
+        (0, messagingPersistence_1.rewriteMessages)([], this.config.dir);
+        return count;
+    }
+    /** Purge messages by channel. Returns count removed. */
+    purgeChannel(channel) {
+        this.ensureLoaded();
+        let count = 0;
+        for (const [key, msg] of this.store.entries()) {
+            if (msg.channel === channel) {
+                this.store.delete(key);
+                this.idIndex.delete(msg.id);
+                count++;
+            }
+        }
+        if (count > 0)
+            this.persistAll();
+        return count;
+    }
+    /** Delete specific messages by IDs. Returns count removed. */
+    deleteMessages(ids) {
+        this.ensureLoaded();
+        let count = 0;
+        for (const id of ids) {
+            const key = this.idIndex.get(id);
+            if (!key)
+                continue;
+            this.store.delete(key);
+            this.idIndex.delete(id);
+            count++;
+        }
+        if (count > 0)
+            this.persistAll();
+        return count;
+    }
+    /** Remove expired non-persistent messages. */
+    sweepExpired() {
+        this.ensureLoaded();
+        const now = Date.now();
+        let count = 0;
+        for (const [key, msg] of this.store.entries()) {
+            if (msg.persistent)
+                continue;
+            if (msg.ttlSeconds <= 0)
+                continue;
+            const age = now - new Date(msg.createdAt).getTime();
+            if (age > msg.ttlSeconds * 1000) {
+                this.store.delete(key);
+                this.idIndex.delete(msg.id);
+                count++;
+            }
+        }
+        if (count > 0)
+            this.persistAll();
+        return count;
+    }
+    /** Reply to a message, auto-populating channel, parentId, and original recipients. */
+    async reply(parentId, sender, body, opts = {}) {
+        this.ensureLoaded();
+        const parent = this.getMessage(parentId);
+        if (!parent)
+            throw new Error(`Parent message not found: ${parentId}`);
+        let recipients;
+        if (opts.recipients?.length) {
+            recipients = opts.recipients;
+        }
+        else if (opts.replyAll) {
+            // Reply-all: original sender + all recipients, excluding self
+            const all = new Set([parent.sender, ...parent.recipients]);
+            all.delete(sender);
+            all.delete('*');
+            recipients = all.size > 0 ? Array.from(all) : [parent.sender];
+        }
+        else {
+            // Default: reply to sender only
+            recipients = [parent.sender];
+        }
+        const messageId = await this.send({
+            channel: parent.channel,
+            sender,
+            recipients,
+            body,
+            parentId,
+            priority: opts.priority ?? parent.priority,
+            tags: opts.tags,
+            persistent: opts.persistent,
+            payload: opts.payload,
+        });
+        return { messageId, channel: parent.channel, recipients };
+    }
+    /** Get all messages in a thread (by parentId). Returns parent + replies sorted chronologically. */
+    getThread(parentId) {
+        this.ensureLoaded();
+        const results = [];
+        // Include the parent itself
+        const parent = this.getMessage(parentId);
+        if (parent)
+            results.push(parent);
+        // Find all replies (direct and nested)
+        const idSet = new Set([parentId]);
+        let changed = true;
+        while (changed) {
+            changed = false;
+            for (const msg of this.store.values()) {
+                if (msg.parentId && idSet.has(msg.parentId) && !idSet.has(msg.id)) {
+                    results.push(msg);
+                    idSet.add(msg.id);
+                    changed = true;
+                }
+            }
+        }
+        results.sort((a, b) => new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime());
+        return results;
+    }
+    /** Destroy the mailbox, stopping any timers. */
+    destroy() {
+        if (this.sweepTimer) {
+            clearInterval(this.sweepTimer);
+            this.sweepTimer = null;
+        }
+    }
+    // ── Private ────────────────────────────────────────────────────────────
+    makeKey(msg) {
+        return `msg/${msg.channel}/${new Date(msg.createdAt).getTime()}-${msg.id}`;
+    }
+    isRecipient(msg, reader) {
+        if (reader === '*')
+            return true;
+        if (msg.recipients.includes('*'))
+            return true;
+        if (msg.sender === reader)
+            return true;
+        return msg.recipients.includes(reader);
+    }
+    persistAll() {
+        const messages = Array.from(this.store.values());
+        (0, messagingPersistence_1.rewriteMessages)(messages, this.config.dir);
+    }
+    startSweep() {
+        this.sweepTimer = setInterval(() => {
+            this.sweepExpired();
+        }, this.config.sweepIntervalMs);
+        if (this.sweepTimer.unref)
+            this.sweepTimer.unref();
+    }
+}
+exports.AgentMailbox = AgentMailbox;

package/dist/services/messaging/messagingPersistence.d.ts

@@ -0,0 +1,20 @@
+import type { AgentMessage } from './messagingTypes';
+/** Returns the path to messages.jsonl in the given directory. */
+export declare function getMessagingFilePath(dir: string): string;
+/**
+ * Append a single message to the JSONL file.
+ * Deduplicates by message ID within this process session.
+ */
+export declare function appendMessage(msg: AgentMessage, dir: string): void;
+/**
+ * Load all messages from the JSONL file.
+ * Skips corrupt/empty lines and deduplicates by ID.
+ */
+export declare function loadMessages(dir: string): AgentMessage[];
+/**
+ * Rewrite the JSONL file with the provided messages (atomic via temp+rename).
+ * Used after TTL sweep or purge operations.
+ */
+export declare function rewriteMessages(messages: AgentMessage[], dir: string): void;
+/** Reset dedup state (for testing). */
+export declare function _resetDedupState(): void;

package/dist/services/messaging/messagingPersistence.js

@@ -0,0 +1,111 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getMessagingFilePath = getMessagingFilePath;
+exports.appendMessage = appendMessage;
+exports.loadMessages = loadMessages;
+exports.rewriteMessages = rewriteMessages;
+exports._resetDedupState = _resetDedupState;
+/**
+ * JSONL-based messaging persistence.
+ *
+ * Stores messages one-per-line in `messages.jsonl`. Provides append, load,
+ * and rewrite operations with deduplication and corruption tolerance.
+ *
+ * Follows the atomic write pattern from `atomicFs.ts` for rewrite operations.
+ */
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+const crypto_1 = __importDefault(require("crypto"));
+const FILENAME = 'messages.jsonl';
+/** Track appended IDs per directory to prevent cross-process duplicates within a session. */
+const appendedIds = new Map();
+/** Returns the path to messages.jsonl in the given directory. */
+function getMessagingFilePath(dir) {
+    return path_1.default.join(dir, FILENAME);
+}
+/**
+ * Append a single message to the JSONL file.
+ * Deduplicates by message ID within this process session.
+ */
+function appendMessage(msg, dir) {
+    if (!appendedIds.has(dir))
+        appendedIds.set(dir, new Set());
+    const seen = appendedIds.get(dir);
+    if (seen.has(msg.id))
+        return;
+    const filePath = getMessagingFilePath(dir);
+    if (!fs_1.default.existsSync(dir))
+        fs_1.default.mkdirSync(dir, { recursive: true });
+    fs_1.default.appendFileSync(filePath, JSON.stringify(msg) + os_1.default.EOL, 'utf8');
+    seen.add(msg.id);
+}
+/**
+ * Load all messages from the JSONL file.
+ * Skips corrupt/empty lines and deduplicates by ID.
+ */
+function loadMessages(dir) {
+    const filePath = getMessagingFilePath(dir);
+    if (!fs_1.default.existsSync(filePath))
+        return [];
+    const content = fs_1.default.readFileSync(filePath, 'utf8');
+    const lines = content.split('\n');
+    const messages = [];
+    const seenIds = new Set();
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const msg = JSON.parse(trimmed);
+            if (msg.id && !seenIds.has(msg.id)) {
+                seenIds.add(msg.id);
+                messages.push(msg);
+            }
+        }
+        catch {
+            // Skip corrupt lines (DI-2: graceful corruption handling)
+        }
+    }
+    // Seed the append dedup set so we don't re-append loaded messages
+    if (!appendedIds.has(dir))
+        appendedIds.set(dir, new Set());
+    const seen = appendedIds.get(dir);
+    for (const msg of messages)
+        seen.add(msg.id);
+    return messages;
+}
+/**
+ * Rewrite the JSONL file with the provided messages (atomic via temp+rename).
+ * Used after TTL sweep or purge operations.
+ */
+function rewriteMessages(messages, dir) {
+    const filePath = getMessagingFilePath(dir);
+    if (!fs_1.default.existsSync(dir))
+        fs_1.default.mkdirSync(dir, { recursive: true });
+    const data = messages.map(m => JSON.stringify(m)).join(os_1.default.EOL) + (messages.length ? os_1.default.EOL : '');
+    const tmp = path_1.default.join(dir, `.${path_1.default.basename(filePath)}.${crypto_1.default.randomBytes(6).toString('hex')}.tmp`);
+    try {
+        fs_1.default.writeFileSync(tmp, data, 'utf8');
+        fs_1.default.renameSync(tmp, filePath);
+    }
+    catch {
+        // Fallback: direct write if rename fails (Windows/network FS)
+        try {
+            if (fs_1.default.existsSync(tmp))
+                fs_1.default.unlinkSync(tmp);
+        }
+        catch { /* ignore */ }
+        fs_1.default.writeFileSync(filePath, data, 'utf8');
+    }
+    // Reset dedup set to match current state
+    const seen = new Set(messages.map(m => m.id));
+    appendedIds.set(dir, seen);
+}
+/** Reset dedup state (for testing). */
+function _resetDedupState() {
+    appendedIds.clear();
+}

package/dist/services/messaging/messagingTypes.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Messaging types, Zod schemas, and constants.
+ *
+ * Defines the data model for the inter-agent messaging system.
+ * Messages are short-term, ephemeral (not stored in the instruction index)
+ * but persist across instances/sessions via JSONL files.
+ */
+import { z } from 'zod';
+/** Maximum time-to-live in seconds (24 hours). */
+export declare const MAX_TTL_SECONDS = 86400;
+/** Default time-to-live in seconds (1 hour). */
+export declare const DEFAULT_TTL_SECONDS = 3600;
+/** Sweep interval in milliseconds (60 seconds). */
+export declare const SWEEP_INTERVAL_MS = 60000;
+/** Maximum body size in characters (100KB). */
+export declare const MAX_BODY_LENGTH = 100000;
+/** Maximum messages per read response. */
+export declare const MAX_READ_LIMIT = 500;
+export declare const MESSAGE_PRIORITIES: readonly ["low", "normal", "high", "critical"];
+export type MessagePriority = (typeof MESSAGE_PRIORITIES)[number];
+export declare const AgentMessageSchema: z.ZodObject<{
+    id: z.ZodString;
+    channel: z.ZodString;
+    sender: z.ZodString;
+    recipients: z.ZodArray<z.ZodString, "many">;
+    body: z.ZodString;
+    createdAt: z.ZodString;
+    ttlSeconds: z.ZodNumber;
+    persistent: z.ZodOptional<z.ZodBoolean>;
+    readBy: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    payload: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    priority: z.ZodOptional<z.ZodEnum<["low", "normal", "high", "critical"]>>;
+    parentId: z.ZodOptional<z.ZodString>;
+    requiresAck: z.ZodOptional<z.ZodBoolean>;
+    ackBySeconds: z.ZodOptional<z.ZodNumber>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    origin: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    id: string;
+    body: string;
+    channel: string;
+    createdAt: string;
+    sender: string;
+    recipients: string[];
+    ttlSeconds: number;
+    priority?: "normal" | "low" | "high" | "critical" | undefined;
+    origin?: string | undefined;
+    parentId?: string | undefined;
+    persistent?: boolean | undefined;
+    readBy?: string[] | undefined;
+    payload?: Record<string, unknown> | undefined;
+    requiresAck?: boolean | undefined;
+    ackBySeconds?: number | undefined;
+    tags?: string[] | undefined;
+}, {
+    id: string;
+    body: string;
+    channel: string;
+    createdAt: string;
+    sender: string;
+    recipients: string[];
+    ttlSeconds: number;
+    priority?: "normal" | "low" | "high" | "critical" | undefined;
+    origin?: string | undefined;
+    parentId?: string | undefined;
+    persistent?: boolean | undefined;
+    readBy?: string[] | undefined;
+    payload?: Record<string, unknown> | undefined;
+    requiresAck?: boolean | undefined;
+    ackBySeconds?: number | undefined;
+    tags?: string[] | undefined;
+}>;
+export type AgentMessage = z.infer<typeof AgentMessageSchema>;
+export declare const SendMessageOptionsSchema: z.ZodObject<{
+    channel: z.ZodString;
+    sender: z.ZodString;
+    recipients: z.ZodArray<z.ZodString, "many">;
+    body: z.ZodString;
+    ttlSeconds: z.ZodOptional<z.ZodNumber>;
+    persistent: z.ZodOptional<z.ZodBoolean>;
+    payload: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    priority: z.ZodOptional<z.ZodEnum<["low", "normal", "high", "critical"]>>;
+    parentId: z.ZodOptional<z.ZodString>;
+    requiresAck: z.ZodOptional<z.ZodBoolean>;
+    ackBySeconds: z.ZodOptional<z.ZodNumber>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    body: string;
+    channel: string;
+    sender: string;
+    recipients: string[];
+    priority?: "normal" | "low" | "high" | "critical" | undefined;
+    parentId?: string | undefined;
+    ttlSeconds?: number | undefined;
+    persistent?: boolean | undefined;
+    payload?: Record<string, unknown> | undefined;
+    requiresAck?: boolean | undefined;
+    ackBySeconds?: number | undefined;
+    tags?: string[] | undefined;
+}, {
+    body: string;
+    channel: string;
+    sender: string;
+    recipients: string[];
+    priority?: "normal" | "low" | "high" | "critical" | undefined;
+    parentId?: string | undefined;
+    ttlSeconds?: number | undefined;
+    persistent?: boolean | undefined;
+    payload?: Record<string, unknown> | undefined;
+    requiresAck?: boolean | undefined;
+    ackBySeconds?: number | undefined;
+    tags?: string[] | undefined;
+}>;
+export type SendMessageOptions = z.infer<typeof SendMessageOptionsSchema>;
+export declare const ReadMessagesOptionsSchema: z.ZodObject<{
+    channel: z.ZodOptional<z.ZodString>;
+    reader: z.ZodOptional<z.ZodString>;
+    unreadOnly: z.ZodOptional<z.ZodBoolean>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    markRead: z.ZodOptional<z.ZodBoolean>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    sender: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    channel?: string | undefined;
+    limit?: number | undefined;
+    sender?: string | undefined;
+    reader?: string | undefined;
+    tags?: string[] | undefined;
+    unreadOnly?: boolean | undefined;
+    markRead?: boolean | undefined;
+}, {
+    channel?: string | undefined;
+    limit?: number | undefined;
+    sender?: string | undefined;
+    reader?: string | undefined;
+    tags?: string[] | undefined;
+    unreadOnly?: boolean | undefined;
+    markRead?: boolean | undefined;
+}>;
+export type ReadMessagesOptions = z.infer<typeof ReadMessagesOptionsSchema>;
+export interface ChannelInfo {
+    channel: string;
+    messageCount: number;
+    latestAt: string | null;
+}
+export interface MessagingStats {
+    total: number;
+    unread: number;
+    channels: number;
+}