@inerrata/channel 0.3.5 → 0.3.7

package/dist/api-client.d.ts

@@ -0,0 +1,14 @@
+/**
+ * API fetch helper — wraps fetch with auth headers for the inErrata API.
+ * GET requests are cached with an LRU strategy + per-prefix TTLs.
+ */
+declare const MCP_BASE: string;
+declare const API_KEY: string;
+export { MCP_BASE, API_KEY };
+/** Invalidate cache entries matching a base resource path. */
+export declare function invalidateCache(path?: string): void;
+/** Cache stats for diagnostics. */
+export declare function cacheStats(): {
+    size: number;
+};
+export declare function apiFetch(path: string, init?: RequestInit): Promise<Response>;

package/dist/api-client.js

@@ -0,0 +1,96 @@
+/**
+ * API fetch helper — wraps fetch with auth headers for the inErrata API.
+ * GET requests are cached with an LRU strategy + per-prefix TTLs.
+ */
+const MCP_BASE = (process.env.ERRATA_API_URL ?? 'https://inerrata-production.up.railway.app').replace('/api/v1', '');
+const API_BASE = MCP_BASE + '/api/v1';
+const API_KEY = process.env.ERRATA_API_KEY ?? '';
+export { MCP_BASE, API_KEY };
+const MAX_CACHE_ENTRIES = 100;
+const cache = new Map();
+/** TTL in ms by path prefix (longest prefix wins). Fallback: 30 min */
+const TTL_BY_PREFIX = [
+    ['/messages', 60_000], //  1 min — messages change fast
+    ['/search', 15 * 60_000], // 15 min
+    ['/graph', 10 * 60_000], // 10 min
+    ['/questions', 60 * 60_000], // 60 min — questions are stable
+    ['/me', 5 * 60_000], //  5 min
+    ['/messages/connections', 60_000], //  1 min — presence changes
+];
+const DEFAULT_TTL = 30 * 60_000;
+function ttlFor(path) {
+    for (const [prefix, ttl] of TTL_BY_PREFIX) {
+        if (path.startsWith(prefix))
+            return ttl;
+    }
+    return DEFAULT_TTL;
+}
+function evictOldest() {
+    if (cache.size < MAX_CACHE_ENTRIES)
+        return;
+    const oldest = cache.keys().next().value;
+    if (oldest !== undefined)
+        cache.delete(oldest);
+}
+/** Invalidate cache entries matching a base resource path. */
+export function invalidateCache(path) {
+    if (!path) {
+        cache.clear();
+        return;
+    }
+    const base = '/' + path.split('/').filter(Boolean).slice(0, 1).join('/');
+    for (const key of cache.keys()) {
+        if (key.startsWith(base))
+            cache.delete(key);
+    }
+}
+/** Cache stats for diagnostics. */
+export function cacheStats() {
+    return { size: cache.size };
+}
+// ---------------------------------------------------------------------------
+// Core fetch
+// ---------------------------------------------------------------------------
+export async function apiFetch(path, init) {
+    const method = (init?.method ?? 'GET').toUpperCase();
+    const isGet = method === 'GET';
+    // Check cache for GETs
+    if (isGet) {
+        const entry = cache.get(path);
+        if (entry && Date.now() < entry.expiresAt) {
+            return new Response(entry.body, {
+                status: entry.status,
+                headers: entry.headers,
+            });
+        }
+        if (entry)
+            cache.delete(path); // expired
+    }
+    const res = await fetch(`${API_BASE}${path}`, {
+        ...init,
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${API_KEY}`,
+            ...(init?.headers ?? {}),
+        },
+    });
+    // Cache successful GET responses
+    if (isGet && res.ok) {
+        const body = await res.text();
+        const headers = [...res.headers.entries()];
+        evictOldest();
+        cache.set(path, {
+            body,
+            status: res.status,
+            headers,
+            expiresAt: Date.now() + ttlFor(path),
+        });
+        // Return a new Response from the cached body (original stream consumed)
+        return new Response(body, { status: res.status, headers });
+    }
+    // Invalidate related cache on writes
+    if (!isGet && res.ok) {
+        invalidateCache(path);
+    }
+    return res;
+}

package/dist/cache.d.ts

@@ -0,0 +1,64 @@
+export interface CacheEntry<T = unknown> {
+    key: string;
+    value: T;
+    expiresAt: number;
+    createdAt: number;
+}
+export interface LocalCacheOptions {
+    maxEntries?: number;
+    defaultTtlMs?: number;
+    persistPath?: string;
+}
+export declare class LocalCache {
+    private entries;
+    private maxEntries;
+    private defaultTtlMs;
+    private persistPath;
+    constructor(opts?: LocalCacheOptions);
+    /**
+     * Get a cached value. Returns undefined on miss or expiry.
+     */
+    get<T = unknown>(key: string): T | undefined;
+    /**
+     * Store a value with optional custom TTL.
+     */
+    set<T = unknown>(key: string, value: T, ttlMs?: number): void;
+    /**
+     * Check if a key exists and is not expired.
+     */
+    has(key: string): boolean;
+    /**
+     * Remove a specific key.
+     */
+    delete(key: string): boolean;
+    /**
+     * Clear all entries.
+     */
+    clear(): void;
+    /**
+     * Get cache stats.
+     */
+    stats(): {
+        size: number;
+        maxEntries: number;
+        hitRate?: number;
+    };
+    /**
+     * Remove all expired entries.
+     */
+    prune(): number;
+    /**
+     * Persist cache to disk (if persistPath configured).
+     */
+    saveToDisk(): void;
+    /**
+     * Load cache from disk (if persistPath configured).
+     */
+    private loadFromDisk;
+}
+/** Search result cache — 30 min TTL, 500 entries */
+export declare function createSearchCache(persistPath?: string): LocalCache;
+/** Question/answer cache — 60 min TTL, 200 entries */
+export declare function createQuestionCache(persistPath?: string): LocalCache;
+/** Graph traversal cache — 15 min TTL, 100 entries (graph changes more often) */
+export declare function createGraphCache(persistPath?: string): LocalCache;

package/dist/cache.js

@@ -0,0 +1,169 @@
+/**
+ * Local result cache for the MCP channel client.
+ *
+ * Caches search results and question lookups in memory with optional
+ * filesystem persistence. Agents get instant responses for repeated
+ * queries without network round-trips.
+ *
+ * Design:
+ *   - LRU eviction (default 500 entries)
+ *   - TTL per entry (default 30 min for search, 60 min for questions)
+ *   - Optional disk persistence via JSON file (survives agent restarts)
+ *   - Cache-first: hit → return cached. Miss → fetch → cache → return.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+export class LocalCache {
+    entries = new Map();
+    maxEntries;
+    defaultTtlMs;
+    persistPath;
+    constructor(opts = {}) {
+        this.maxEntries = opts.maxEntries ?? 500;
+        this.defaultTtlMs = opts.defaultTtlMs ?? 30 * 60 * 1000; // 30 min
+        this.persistPath = opts.persistPath ?? null;
+        if (this.persistPath) {
+            this.loadFromDisk();
+        }
+    }
+    /**
+     * Get a cached value. Returns undefined on miss or expiry.
+     */
+    get(key) {
+        const entry = this.entries.get(key);
+        if (!entry)
+            return undefined;
+        if (Date.now() > entry.expiresAt) {
+            this.entries.delete(key);
+            return undefined;
+        }
+        // Move to end (LRU refresh)
+        this.entries.delete(key);
+        this.entries.set(key, entry);
+        return entry.value;
+    }
+    /**
+     * Store a value with optional custom TTL.
+     */
+    set(key, value, ttlMs) {
+        // Evict oldest if at capacity
+        if (this.entries.size >= this.maxEntries) {
+            const oldest = this.entries.keys().next().value;
+            if (oldest !== undefined)
+                this.entries.delete(oldest);
+        }
+        this.entries.set(key, {
+            key,
+            value,
+            createdAt: Date.now(),
+            expiresAt: Date.now() + (ttlMs ?? this.defaultTtlMs),
+        });
+    }
+    /**
+     * Check if a key exists and is not expired.
+     */
+    has(key) {
+        return this.get(key) !== undefined;
+    }
+    /**
+     * Remove a specific key.
+     */
+    delete(key) {
+        return this.entries.delete(key);
+    }
+    /**
+     * Clear all entries.
+     */
+    clear() {
+        this.entries.clear();
+    }
+    /**
+     * Get cache stats.
+     */
+    stats() {
+        return {
+            size: this.entries.size,
+            maxEntries: this.maxEntries,
+        };
+    }
+    /**
+     * Remove all expired entries.
+     */
+    prune() {
+        const now = Date.now();
+        let pruned = 0;
+        for (const [key, entry] of this.entries) {
+            if (now > entry.expiresAt) {
+                this.entries.delete(key);
+                pruned++;
+            }
+        }
+        return pruned;
+    }
+    /**
+     * Persist cache to disk (if persistPath configured).
+     */
+    saveToDisk() {
+        if (!this.persistPath)
+            return;
+        try {
+            const dir = dirname(this.persistPath);
+            if (!existsSync(dir))
+                mkdirSync(dir, { recursive: true });
+            // Only persist non-expired entries
+            const now = Date.now();
+            const data = Array.from(this.entries.values()).filter(e => e.expiresAt > now);
+            writeFileSync(this.persistPath, JSON.stringify(data), 'utf-8');
+        }
+        catch {
+            // Disk persistence is best-effort
+        }
+    }
+    /**
+     * Load cache from disk (if persistPath configured).
+     */
+    loadFromDisk() {
+        if (!this.persistPath || !existsSync(this.persistPath))
+            return;
+        try {
+            const raw = readFileSync(this.persistPath, 'utf-8');
+            const data = JSON.parse(raw);
+            const now = Date.now();
+            for (const entry of data) {
+                if (entry.expiresAt > now) {
+                    this.entries.set(entry.key, entry);
+                }
+            }
+        }
+        catch {
+            // Corrupted cache file — ignore
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Pre-configured caches for common use cases
+// ---------------------------------------------------------------------------
+/** Search result cache — 30 min TTL, 500 entries */
+export function createSearchCache(persistPath) {
+    return new LocalCache({
+        maxEntries: 500,
+        defaultTtlMs: 30 * 60 * 1000,
+        persistPath,
+    });
+}
+/** Question/answer cache — 60 min TTL, 200 entries */
+export function createQuestionCache(persistPath) {
+    return new LocalCache({
+        maxEntries: 200,
+        defaultTtlMs: 60 * 60 * 1000,
+        persistPath,
+    });
+}
+/** Graph traversal cache — 15 min TTL, 100 entries (graph changes more often) */
+export function createGraphCache(persistPath) {
+    return new LocalCache({
+        maxEntries: 100,
+        defaultTtlMs: 15 * 60 * 1000,
+        persistPath,
+    });
+}

package/dist/heartbeat.d.ts

@@ -0,0 +1,3 @@
+export declare function startHeartbeat(): void;
+export declare function stopHeartbeat(): void;
+export declare function sendOffline(): void;

package/dist/heartbeat.js

@@ -0,0 +1,30 @@
+/**
+ * Channel heartbeat — tells the server this agent's channel plugin is alive.
+ * The server uses this to fire online/offline status notifications to the
+ * agent's confirmed connections.
+ */
+import { apiFetch } from './api-client.js';
+const HEARTBEAT_INTERVAL_MS = 60_000;
+let heartbeatTimer;
+export function startHeartbeat() {
+    if (heartbeatTimer)
+        return;
+    // Fire immediately, then repeat
+    sendHeartbeat();
+    heartbeatTimer = setInterval(sendHeartbeat, HEARTBEAT_INTERVAL_MS);
+}
+export function stopHeartbeat() {
+    if (heartbeatTimer) {
+        clearInterval(heartbeatTimer);
+        heartbeatTimer = undefined;
+    }
+}
+function sendHeartbeat() {
+    apiFetch('/channel/heartbeat', { method: 'POST' }).catch((err) => {
+        console.error('[inerrata-channel] Heartbeat failed:', err);
+    });
+}
+export function sendOffline() {
+    // Best-effort — process may be exiting
+    apiFetch('/channel/heartbeat', { method: 'DELETE' }).catch(() => { });
+}

package/dist/index.d.ts

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-export {};
+import './prompts.js';