@jagilber-org/index-server 1.19.1

package/dist/services/logger.js

@@ -0,0 +1,268 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logError = exports.logWarn = exports.logInfo = exports.logDebug = exports.logTrace = void 0;
+exports.newCorrelationId = newCorrelationId;
+exports.log = log;
+const crypto_1 = __importDefault(require("crypto"));
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const runtimeConfig_1 = require("../config/runtimeConfig");
+/** Numeric priority for log level filtering (lower = more verbose). */
+const LEVEL_PRIORITY = {
+    TRACE: 0,
+    DEBUG: 1,
+    INFO: 2,
+    WARN: 3,
+    ERROR: 4,
+};
+// Simple correlation id helper (call per incoming JSON-RPC if desired)
+/**
+ * Generate a new random correlation ID (16 hex characters).
+ * @returns Hex string suitable for tagging a single request context
+ */
+function newCorrelationId() { return crypto_1.default.randomBytes(8).toString('hex'); }
+let logFileHandle = null;
+function loggingCfg() {
+    return (0, runtimeConfig_1.getRuntimeConfig)().logging;
+}
+/**
+ * Capture V8 call-site stack trace, omitting the logger internals.
+ * Used on WARN/ERROR to populate the `detail` field for Error Trace Flow.
+ */
+function captureCallStack(omitFrames) {
+    const obj = {};
+    Error.captureStackTrace(obj, omitFrames);
+    return obj.stack;
+}
+/** Serialize a detail value to a string for the NDJSON detail field. */
+function serializeDetail(detail) {
+    if (detail === undefined || detail === null)
+        return undefined;
+    if (detail instanceof Error)
+        return detail.stack ?? detail.message;
+    if (typeof detail === 'string')
+        return detail;
+    return JSON.stringify(detail);
+}
+/**
+ * Check whether the given log level passes the configured minimum level.
+ * Returns true if the record should be emitted, false if suppressed.
+ */
+function shouldEmit(level) {
+    const cfg = loggingCfg();
+    const cfgLevel = cfg.level?.toUpperCase() ?? 'INFO';
+    const threshold = LEVEL_PRIORITY[cfgLevel] ?? LEVEL_PRIORITY.INFO;
+    const recordPriority = LEVEL_PRIORITY[level] ?? LEVEL_PRIORITY.INFO;
+    return recordPriority >= threshold;
+}
+// Initialize file logging if INDEX_SERVER_LOG_FILE is specified
+function initializeFileLogging() {
+    const cfg = loggingCfg();
+    const logFile = cfg.file;
+    if (!logFile || logFileHandle)
+        return; // Already initialized or not requested
+    try {
+        // Ensure log directory exists
+        const logDir = path_1.default.dirname(logFile);
+        if (!fs_1.default.existsSync(logDir)) {
+            fs_1.default.mkdirSync(logDir, { recursive: true });
+        }
+        // Create write stream with append mode
+        logFileHandle = fs_1.default.createWriteStream(logFile, {
+            flags: 'a',
+            encoding: 'utf8'
+        });
+        // NDJSON session start record
+        const sessionStart = {
+            ts: new Date().toISOString(),
+            level: 'INFO',
+            msg: '[logger] Session started',
+            pid: process.pid,
+        };
+        const startLine = JSON.stringify(sessionStart);
+        logFileHandle.write(startLine + '\n');
+        // Cleanup on process exit
+        process.on('exit', () => {
+            if (logFileHandle && !logFileHandle.destroyed) {
+                const sessionEnd = {
+                    ts: new Date().toISOString(),
+                    level: 'INFO',
+                    msg: '[logger] Session ended',
+                    pid: process.pid,
+                };
+                logFileHandle.write(JSON.stringify(sessionEnd) + '\n');
+                logFileHandle.end();
+            }
+        });
+        // Emit NDJSON init diagnostic
+        try {
+            const stats = fs_1.default.existsSync(logFile) ? fs_1.default.statSync(logFile) : null;
+            const diag = {
+                ts: new Date().toISOString(),
+                level: 'INFO',
+                msg: '[logger] File logging enabled',
+                pid: process.pid,
+                detail: JSON.stringify({
+                    file: logFile,
+                    size: stats?.size ?? 0,
+                    sentinel: cfg.sentinelRequested,
+                    cwd: process.cwd(),
+                }),
+            };
+            const line = JSON.stringify(diag);
+            console.error(line);
+            if (logFileHandle && !logFileHandle.destroyed) {
+                try {
+                    logFileHandle.write(line + '\n');
+                }
+                catch { /* ignore */ }
+            }
+        }
+        catch { /* ignore diagnostics error */ }
+    }
+    catch (error) {
+        // Fallback to NDJSON on stderr if file logging fails
+        console.error(JSON.stringify({
+            ts: new Date().toISOString(),
+            level: 'ERROR',
+            msg: '[logger] Failed to initialize file logging',
+            detail: String(error),
+            pid: process.pid,
+        }));
+    }
+}
+// Eager initialization: if user supplied a sentinel value ('1', 'true', etc.)
+// we create the log file immediately so external components (dashboard log
+// viewer polling /api/logs) see the file even before the first structured
+// log line is emitted. Without this, very early polling could race the first
+// emit() call and incorrectly report "no log file". Normal explicit paths
+// remain lazy to avoid unnecessary fd usage when logger never used.
+try {
+    const cfg = loggingCfg();
+    if (cfg.file && cfg.sentinelRequested) {
+        initializeFileLogging();
+    }
+}
+catch { /* ignore eager init errors */ }
+function emit(rec) {
+    // Level filtering — suppress records below configured threshold
+    if (!shouldEmit(rec.level))
+        return;
+    // Initialize file logging on first emit (lazy initialization)
+    const cfg = loggingCfg();
+    if (!logFileHandle && cfg.file) {
+        initializeFileLogging();
+    }
+    // Always include pid for multi-process identification
+    if (rec.pid === undefined)
+        rec.pid = process.pid;
+    // Always NDJSON — no plain-text path
+    const out = {
+        ts: rec.ts,
+        level: rec.level,
+        msg: rec.msg,
+    };
+    if (rec.detail)
+        out.detail = rec.detail;
+    if (rec.tool)
+        out.tool = rec.tool;
+    if (rec.ms !== undefined)
+        out.ms = rec.ms;
+    out.pid = rec.pid;
+    if (rec.port)
+        out.port = rec.port;
+    if (rec.correlationId)
+        out.correlationId = rec.correlationId;
+    const logLine = JSON.stringify(out);
+    // Always log to stderr for VS Code output panel
+    console.error(logLine);
+    // Also log to file if configured and available
+    if (logFileHandle && !logFileHandle.destroyed) {
+        try {
+            logFileHandle.write(logLine + '\n');
+            // Optional deterministic flushing for tests / critical observability. Enabled with INDEX_SERVER_LOG_SYNC=1
+            if (cfg.sync) {
+                try {
+                    fs_1.default.fsyncSync(logFileHandle.fd);
+                }
+                catch { /* ignore fsync errors */ }
+            }
+        }
+        catch { /* ignore file write failures */ }
+    }
+}
+/**
+ * Emit a structured NDJSON log record at the specified level.
+ * @param level - TRACE | DEBUG | INFO | WARN | ERROR
+ * @param msg - Message with [module] prefix for heatmap matching
+ * @param fields - Additional fields (detail, tool, ms, correlationId, etc.)
+ */
+function log(level, msg, fields = {}) {
+    emit({ ts: new Date().toISOString(), level, msg, ...fields });
+}
+/** TRACE — function entry/exit tracing and low-level diagnostics.
+ * Use `→ Class.method` / `← Class.method` prefixes for call graph support.
+ * @param msg - Message (use → / ← prefixes for function tracing)
+ * @param detail - Optional data serialized into the detail field
+ */
+const logTrace = (msg, detail) => {
+    log('TRACE', msg, { detail: serializeDetail(detail) });
+};
+exports.logTrace = logTrace;
+/** DEBUG — diagnostic information for development.
+ * @param msg - Message with [module] prefix
+ * @param detail - Optional data serialized into the detail field
+ */
+const logDebug = (msg, detail) => {
+    log('DEBUG', msg, { detail: serializeDetail(detail) });
+};
+exports.logDebug = logDebug;
+/** INFO — normal operational events.
+ * @param msg - Message with [module] prefix
+ * @param detail - Optional data serialized into the detail field
+ */
+const logInfo = (msg, detail) => {
+    log('INFO', msg, { detail: serializeDetail(detail) });
+};
+exports.logInfo = logInfo;
+/** WARN — potential issues. Captures V8 call-site stack into detail for Error Trace Flow.
+ * Error instances use their own stack; non-Error detail is serialized with call-site stack appended.
+ * @param msg - Message with [module] prefix
+ * @param detail - Optional Error, string, or data; Error.stack or V8 call-site stack used
+ */
+const logWarn = (msg, detail) => {
+    let d;
+    if (detail instanceof Error) {
+        d = detail.stack;
+    }
+    else {
+        const stack = captureCallStack(exports.logWarn);
+        d = detail !== undefined
+            ? serializeDetail(detail) + (stack ? '\n' + stack : '')
+            : stack;
+    }
+    log('WARN', msg, { detail: d });
+};
+exports.logWarn = logWarn;
+/** ERROR — failures. Captures V8 call-site stack into detail for Error Trace Flow.
+ * Error instances use their own stack; non-Error detail is serialized with call-site stack appended.
+ * @param msg - Message with [module] prefix
+ * @param detail - Optional Error, string, or data; Error.stack or V8 call-site stack used
+ */
+const logError = (msg, detail) => {
+    let d;
+    if (detail instanceof Error) {
+        d = detail.stack;
+    }
+    else {
+        const stack = captureCallStack(exports.logError);
+        d = detail !== undefined
+            ? serializeDetail(detail) + (stack ? '\n' + stack : '')
+            : stack;
+    }
+    log('ERROR', msg, { detail: d });
+};
+exports.logError = logError;

package/dist/services/manifestManager.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Runtime manifest management.
+ * Format (version 1):
+ * {
+ *   version: 1,
+ *   generatedAt: ISO string,
+ *   count: number,
+ *   entries: [ { id, sourceHash, bodyHash } ]
+ * }
+ *
+ * Design notes:
+ * - We intentionally keep entries minimal (id + hashes) to reduce churn risk.
+ * - Recomputing the manifest from the in‑memory index after a mutation is O(N) and
+ *   acceptable for current index sizes (< few hundred). This favors simplicity & correctness
+ *   over incremental append complexity (which can be added later if needed).
+ * - Atomicity: write to tmp then rename to avoid partial file visibility.
+ *
+ * Phase F (simplification):
+ * - Removed debounce / max-delay scheduling. Writes are now synchronous & deterministic.
+ * - Added no-op short circuit: if projected manifest JSON unchanged, skip write.
+ * - attemptManifestUpdate() is now a thin alias of scheduleManifestUpdate() which performs
+ *   immediate write (naming preserved for backward compatibility with existing call sites).
+ */
+export interface ManifestEntry {
+    id: string;
+    sourceHash?: string;
+    bodyHash?: string;
+}
+export interface IndexManifest {
+    $schema?: string;
+    version: 1;
+    generatedAt: string;
+    count: number;
+    entries: ManifestEntry[];
+}
+/**
+ * Load the manifest from disk.
+ * @returns The parsed {@link IndexManifest}, or `null` if the file is absent or unparseable
+ */
+export declare function loadManifest(): IndexManifest | null;
+/**
+ * Write a fresh manifest reflecting the current in-memory index state.
+ * Skips the write when the content is unchanged (stable `generatedAt` semantics).
+ * No-op when `INDEX_SERVER_MANIFEST_WRITE=0`.
+ * @returns The computed {@link IndexManifest}, or `null` when writing is disabled
+ */
+export declare function writeManifestFromIndex(): IndexManifest | null;
+export interface DriftDetail {
+    id: string;
+    change: 'added' | 'removed' | 'hash-mismatch';
+}
+export interface ManifestDriftReport {
+    present: boolean;
+    drift: number;
+    details: DriftDetail[];
+}
+/**
+ * Compare the on-disk manifest against the live in-memory index and report any drift.
+ * @returns A {@link ManifestDriftReport} describing added, removed, or hash-mismatched entries
+ */
+export declare function computeManifestDrift(): ManifestDriftReport;
+/**
+ * Repair the manifest by rewriting it from the current in-memory index when drift is detected.
+ * @returns Object with `repaired` flag and drift counts before and after repair
+ */
+export declare function repairManifest(): {
+    repaired: boolean;
+    driftBefore: number;
+    driftAfter: number;
+};
+/** Synchronously write the manifest from the current in-memory index state. */
+export declare function scheduleManifestUpdate(): void;
+/** Alias for {@link scheduleManifestUpdate}; called after any index mutation. */
+export declare function onIndexMutationManifestUpdate(): void;
+/** Conditionally write the manifest; only executes when `INDEX_SERVER_MANIFEST_WRITE=1`. */
+export declare function attemptManifestUpdate(): void;
+/**
+ * Check whether manifest fast-load mode is active (`INDEX_SERVER_MANIFEST_FASTLOAD=1`).
+ * In fast-load mode, drift detection skips per-entry hash comparison when entry counts match.
+ * @returns `true` when fast-load is enabled
+ */
+export declare function manifestFastLoadEnabled(): boolean;

package/dist/services/manifestManager.js

@@ -0,0 +1,200 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadManifest = loadManifest;
+exports.writeManifestFromIndex = writeManifestFromIndex;
+exports.computeManifestDrift = computeManifestDrift;
+exports.repairManifest = repairManifest;
+exports.scheduleManifestUpdate = scheduleManifestUpdate;
+exports.onIndexMutationManifestUpdate = onIndexMutationManifestUpdate;
+exports.attemptManifestUpdate = attemptManifestUpdate;
+exports.manifestFastLoadEnabled = manifestFastLoadEnabled;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const crypto_1 = __importDefault(require("crypto"));
+const indexContext_1 = require("./indexContext");
+const tracing_1 = require("./tracing");
+const features_1 = require("./features");
+const logger_1 = require("./logger");
+const runtimeConfig_1 = require("../config/runtimeConfig");
+const MANIFEST_RELATIVE = path_1.default.join('snapshots', 'index-manifest.json');
+function getManifestPath() { return path_1.default.join(process.cwd(), MANIFEST_RELATIVE); }
+/**
+ * Load the manifest from disk.
+ * @returns The parsed {@link IndexManifest}, or `null` if the file is absent or unparseable
+ */
+function loadManifest() {
+    const fp = getManifestPath();
+    try {
+        if (!fs_1.default.existsSync(fp))
+            return null;
+        const data = JSON.parse(fs_1.default.readFileSync(fp, 'utf8'));
+        if (data && data.version === 1 && Array.isArray(data.entries))
+            return data;
+    }
+    catch { /* ignore */ }
+    return null;
+}
+/**
+ * Write a fresh manifest reflecting the current in-memory index state.
+ * Skips the write when the content is unchanged (stable `generatedAt` semantics).
+ * No-op when `INDEX_SERVER_MANIFEST_WRITE=0`.
+ * @returns The computed {@link IndexManifest}, or `null` when writing is disabled
+ */
+function writeManifestFromIndex() {
+    if (!(0, runtimeConfig_1.getRuntimeConfig)().instructions.manifest.writeEnabled)
+        return null; // feature disabled
+    const started = Date.now();
+    const st = (0, indexContext_1.ensureLoaded)();
+    const entries = st.list.map(e => ({
+        id: e.id,
+        sourceHash: e.sourceHash,
+        bodyHash: crypto_1.default.createHash('sha256').update(e.body || '', 'utf8').digest('hex')
+    })).sort((a, b) => a.id.localeCompare(b.id));
+    // We perform a two-phase write to enable generatedAt stability on no-op content:
+    // 1. Build a draft manifest with a placeholder timestamp.
+    // 2. If existing file content (ignoring generatedAt) is identical, we reuse the prior generatedAt
+    //    so downstream processes observing timestamp do not treat the manifest as changed.
+    const draftGeneratedAt = new Date().toISOString();
+    let previousParsed = null;
+    const fp = getManifestPath();
+    if (fs_1.default.existsSync(fp)) {
+        try {
+            previousParsed = JSON.parse(fs_1.default.readFileSync(fp, 'utf8'));
+        }
+        catch {
+            previousParsed = null;
+        }
+    }
+    const manifest = {
+        $schema: '../schemas/manifest.schema.json',
+        version: 1,
+        generatedAt: draftGeneratedAt,
+        count: entries.length,
+        entries
+    };
+    // If previous manifest exists and structural content (excluding generatedAt) matches, reuse old timestamp.
+    if (previousParsed) {
+        try {
+            const prevComparable = { ...previousParsed, generatedAt: undefined };
+            const nextComparable = { ...manifest, generatedAt: undefined };
+            if (JSON.stringify(prevComparable) === JSON.stringify(nextComparable)) {
+                // Reuse timestamp to provide full stability rather than rewriting with new time.
+                manifest.generatedAt = previousParsed.generatedAt;
+            }
+        }
+        catch { /* ignore comparison errors */ }
+    }
+    // fp already declared above
+    try {
+        const dir = path_1.default.dirname(fp);
+        if (!fs_1.default.existsSync(dir))
+            fs_1.default.mkdirSync(dir, { recursive: true });
+        // No-op short circuit: if existing manifest content is byte-identical we skip write.
+        let previous;
+        if (fs_1.default.existsSync(fp)) {
+            try {
+                previous = fs_1.default.readFileSync(fp, 'utf8');
+            }
+            catch { /* ignore */ }
+        }
+        const nextJson = JSON.stringify(manifest, null, 2);
+        if (previous && previous === nextJson) {
+            (0, features_1.incrementCounter)('manifest:skipNoChange');
+            if ((0, tracing_1.traceEnabled)(2))
+                (0, tracing_1.emitTrace)('[trace:manifest:skip-nochange]', { count: manifest.count });
+            return manifest; // treat as success (hash stable)
+        }
+        const tmp = fp + '.tmp';
+        fs_1.default.writeFileSync(tmp, nextJson);
+        fs_1.default.renameSync(tmp, fp);
+        (0, features_1.incrementCounter)('manifest:write');
+        (0, logger_1.logInfo)(`[manifest] wrote index-manifest.json count=${manifest.count} ms=${Date.now() - started}`);
+        if ((0, tracing_1.traceEnabled)(1))
+            (0, tracing_1.emitTrace)('[trace:manifest:write]', { count: manifest.count, ms: Date.now() - started, path: fp });
+    }
+    catch (err) {
+        (0, features_1.incrementCounter)('manifest:writeFailed');
+        (0, logger_1.logWarn)('[manifest] write failed', err);
+        if ((0, tracing_1.traceEnabled)(1))
+            (0, tracing_1.emitTrace)('[trace:manifest:write-error]', { error: err.message });
+    }
+    return manifest;
+}
+/**
+ * Compare the on-disk manifest against the live in-memory index and report any drift.
+ * @returns A {@link ManifestDriftReport} describing added, removed, or hash-mismatched entries
+ */
+function computeManifestDrift() {
+    const st = (0, indexContext_1.ensureLoaded)();
+    const manifest = loadManifest();
+    if (!manifest)
+        return { present: false, drift: st.list.length ? st.list.length : 0, details: st.list.map(e => ({ id: e.id, change: 'added' })) };
+    // FASTLOAD SHORTCUT: if enabled and counts match we trust the manifest without recomputing hashes.
+    // Rationale: On typical startup we only need to know "is there obvious drift?" to skip O(N) hashing.
+    // If a subsequent mutation occurs we will rewrite manifest anyway. Safety: if counts differ we fall through
+    // to full verification.
+    const fastEnabled = manifestFastLoadEnabled();
+    if (fastEnabled && manifest.count === st.list.length) {
+        if ((0, tracing_1.traceEnabled)(2))
+            (0, tracing_1.emitTrace)('[trace:manifest:fastload]', { count: st.list.length });
+        return { present: true, drift: 0, details: [] };
+    }
+    const map = new Map(manifest.entries.map(e => [e.id, e]));
+    const details = [];
+    for (const e of st.list) {
+        const m = map.get(e.id);
+        const bodyHash = crypto_1.default.createHash('sha256').update(e.body || '', 'utf8').digest('hex');
+        if (!m)
+            details.push({ id: e.id, change: 'added' });
+        else if (m.sourceHash !== e.sourceHash || m.bodyHash !== bodyHash)
+            details.push({ id: e.id, change: 'hash-mismatch' });
+    }
+    for (const id of map.keys()) {
+        if (!st.byId.has(id))
+            details.push({ id, change: 'removed' });
+    }
+    const report = { present: true, drift: details.length, details };
+    if ((0, tracing_1.traceEnabled)(1))
+        (0, tracing_1.emitTrace)('[trace:manifest:drift]', { drift: report.drift, added: report.details.filter(d => d.change === 'added').length, removed: report.details.filter(d => d.change === 'removed').length, mismatch: report.details.filter(d => d.change === 'hash-mismatch').length, count: st.list.length, manifestCount: manifest.count });
+    return report;
+}
+/**
+ * Repair the manifest by rewriting it from the current in-memory index when drift is detected.
+ * @returns Object with `repaired` flag and drift counts before and after repair
+ */
+function repairManifest() {
+    const before = computeManifestDrift();
+    if (before.drift === 0) {
+        return { repaired: false, driftBefore: 0, driftAfter: 0 };
+    }
+    writeManifestFromIndex();
+    const after = computeManifestDrift();
+    if ((0, tracing_1.traceEnabled)(1))
+        (0, tracing_1.emitTrace)('[trace:manifest:repair]', { driftBefore: before.drift, driftAfter: after.drift });
+    return { repaired: true, driftBefore: before.drift, driftAfter: after.drift };
+}
+// Phase F: simplified scheduling; we keep exported names for backward compatibility.
+/** Synchronously write the manifest from the current in-memory index state. */
+function scheduleManifestUpdate() {
+    // Single synchronous write (fast for current index sizes). Future high-churn mode could reintroduce batching behind env flag.
+    writeManifestFromIndex();
+}
+/** Alias for {@link scheduleManifestUpdate}; called after any index mutation. */
+function onIndexMutationManifestUpdate() { scheduleManifestUpdate(); }
+// attemptManifestUpdate previously always invoked a write regardless of the INDEX_SERVER_MANIFEST_WRITE flag
+// which caused tests expecting stability under INDEX_SERVER_MANIFEST_WRITE=0 to observe a timestamp change.
+// We now explicitly no-op unless write mode is enabled, making "attempt" semantics truly conditional.
+/** Conditionally write the manifest; only executes when `INDEX_SERVER_MANIFEST_WRITE=1`. */
+function attemptManifestUpdate() {
+    if ((0, runtimeConfig_1.getRuntimeConfig)().instructions.manifest.writeEnabled)
+        scheduleManifestUpdate();
+}
+/**
+ * Check whether manifest fast-load mode is active (`INDEX_SERVER_MANIFEST_FASTLOAD=1`).
+ * In fast-load mode, drift detection skips per-entry hash comparison when entry counts match.
+ * @returns `true` when fast-load is enabled
+ */
+function manifestFastLoadEnabled() { return (0, runtimeConfig_1.getRuntimeConfig)().instructions.manifest.fastload; }

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

@@ -0,0 +1,60 @@
+import { type AgentMessage, type SendMessageOptions, type ReadMessagesOptions, type ChannelInfo, type MessagingStats } from './messagingTypes';
+import type { MessagingConfig } from '../../config/runtimeConfig';
+export declare class AgentMailbox {
+    private readonly store;
+    private readonly idIndex;
+    private readonly config;
+    private sweepTimer;
+    private loaded;
+    constructor(config: MessagingConfig);
+    /** Load messages from disk if not already loaded. */
+    ensureLoaded(): void;
+    /** Send a message. Returns the message ID. */
+    send(opts: SendMessageOptions): Promise<string>;
+    /** Read messages with visibility filtering. */
+    read(opts?: ReadMessagesOptions): AgentMessage[];
+    /** List all channels with message counts. */
+    listChannels(): ChannelInfo[];
+    /** Acknowledge messages by marking them read. Returns count acknowledged. */
+    ack(messageIds: string[], reader: string): number;
+    /** Get stats for a reader. */
+    getStats(reader: string): MessagingStats;
+    /** Get a single message by ID. */
+    getMessage(id: string): AgentMessage | undefined;
+    /** Update mutable fields of a message. */
+    updateMessage(id: string, updates: {
+        body?: string;
+        recipients?: string[];
+        payload?: Record<string, unknown>;
+        persistent?: boolean;
+    }): AgentMessage | undefined;
+    /** Purge all messages. Returns count removed. */
+    purgeAll(): number;
+    /** Purge messages by channel. Returns count removed. */
+    purgeChannel(channel: string): number;
+    /** Delete specific messages by IDs. Returns count removed. */
+    deleteMessages(ids: string[]): number;
+    /** Remove expired non-persistent messages. */
+    sweepExpired(): number;
+    /** Reply to a message, auto-populating channel, parentId, and original recipients. */
+    reply(parentId: string, sender: string, body: string, opts?: {
+        replyAll?: boolean;
+        recipients?: string[];
+        priority?: string;
+        tags?: string[];
+        persistent?: boolean;
+        payload?: Record<string, unknown>;
+    }): Promise<{
+        messageId: string;
+        channel: string;
+        recipients: string[];
+    }>;
+    /** Get all messages in a thread (by parentId). Returns parent + replies sorted chronologically. */
+    getThread(parentId: string): AgentMessage[];
+    /** Destroy the mailbox, stopping any timers. */
+    destroy(): void;
+    private makeKey;
+    private isRecipient;
+    private persistAll;
+    private startSweep;
+}