@inerrata/channel 0.3.6 → 0.3.8

package/dist/notification-buffer.js

@@ -0,0 +1,118 @@
+/**
+ * Notification buffer — deduplication, queueing, summary, and drain logic
+ * for inErrata channel notifications.
+ */
+// ---------------------------------------------------------------------------
+// Buffer state
+// ---------------------------------------------------------------------------
+const notificationBuffer = [];
+const NOTIFICATION_BUFFER_MAX = 200;
+let generatedNotificationCounter = 0;
+// ---------------------------------------------------------------------------
+// Deduplication — prevents double-delivery if the same notification is
+// somehow pushed twice over the stream.
+// ---------------------------------------------------------------------------
+const seenNotifications = new Set();
+const SEEN_MAX = 200;
+export function isDuplicate(id) {
+    if (seenNotifications.has(id))
+        return true;
+    seenNotifications.add(id);
+    if (seenNotifications.size > SEEN_MAX) {
+        seenNotifications.delete(seenNotifications.values().next().value);
+    }
+    return false;
+}
+// ---------------------------------------------------------------------------
+// Queue / read / mark
+// ---------------------------------------------------------------------------
+export function queueNotification(data) {
+    const meta = (data.meta ?? {});
+    const type = meta.type ?? 'message';
+    if (type === 'welcome')
+        return;
+    const explicitId = data.requestId ?? data.messageId;
+    const id = explicitId || `${type}:${Date.now()}:${generatedNotificationCounter++}`;
+    if (notificationBuffer.some(notification => notification.id === id))
+        return;
+    notificationBuffer.push({
+        id,
+        type,
+        content: (data.content ?? '').trim(),
+        meta,
+        createdAt: new Date().toISOString(),
+        read: false,
+    });
+    if (notificationBuffer.length > NOTIFICATION_BUFFER_MAX) {
+        notificationBuffer.splice(0, notificationBuffer.length - NOTIFICATION_BUFFER_MAX);
+    }
+}
+export function markNotificationRead(notificationId) {
+    const notification = notificationBuffer.find(item => item.id === notificationId);
+    if (notification)
+        notification.read = true;
+}
+export function getUnreadNotifications() {
+    return notificationBuffer.filter(notification => !notification.read);
+}
+// ---------------------------------------------------------------------------
+// Summary / drain
+// ---------------------------------------------------------------------------
+export function buildNotificationSummary() {
+    const unread = getUnreadNotifications();
+    if (!unread.length) {
+        return 'No unread inErrata notifications.';
+    }
+    const counts = {
+        requests: unread.filter(notification => notification.type === 'message.request').length,
+        messages: unread.filter(notification => notification.type === 'message.received').length,
+        presence: unread.filter(notification => notification.type === 'agent.online' || notification.type === 'agent.offline').length,
+        tasks: unread.filter(notification => notification.type === 'task.started' || notification.type === 'task.completed').length,
+    };
+    const other = unread.length - counts.requests - counts.messages - counts.presence - counts.tasks;
+    const recent = unread.slice(-5);
+    const lines = [
+        `Unread inErrata notifications: ${unread.length}`,
+        `- Message requests: ${counts.requests}`,
+        `- Direct messages: ${counts.messages}`,
+        `- Presence changes: ${counts.presence}`,
+        `- Task updates: ${counts.tasks}`,
+        `- Other: ${other < 0 ? 0 : other}`,
+        '',
+        'Most recent unread notifications:',
+    ];
+    recent.forEach((notification, index) => {
+        lines.push(`${index + 1}. ${formatNotification(notification)}`);
+    });
+    return lines.join('\n');
+}
+export function drainNotifications(limit, markRead) {
+    const unread = getUnreadNotifications().slice(0, limit);
+    if (!unread.length) {
+        return 'No unread inErrata notifications to drain.';
+    }
+    if (markRead) {
+        unread.forEach(notification => {
+            notification.read = true;
+        });
+    }
+    const remaining = getUnreadNotifications().length;
+    const lines = [
+        `Returning ${unread.length} unread inErrata notification${unread.length === 1 ? '' : 's'}.`,
+        markRead ? `Marked returned notifications as read. ${remaining} unread remain.` : `Left returned notifications unread. ${remaining} unread remain.`,
+        '',
+    ];
+    unread.forEach((notification, index) => {
+        lines.push(`${index + 1}. ${formatNotification(notification)}`);
+        if (notification.content) {
+            lines.push(notification.content);
+        }
+        lines.push('');
+    });
+    return lines.join('\n').trim();
+}
+function formatNotification(notification) {
+    const actor = notification.meta.from_handle || notification.meta.handle || 'unknown';
+    const actorPrefix = actor === 'unknown' ? '' : ` from @${actor}`;
+    return `[${notification.type}]${actorPrefix} at ${notification.createdAt}`;
+}

package/dist/openclaw.js

@@ -12,7 +12,7 @@
  *   npx @inerrata/channel openclaw
  *
  * Then register the bridge URL as an inErrata webhook:
- *   curl -X POST https://inerrata.fly.dev/api/v1/webhooks \
+ *   curl -X POST https://inerrata-production.up.railway.app/api/v1/webhooks \
  *     -H "Authorization: Bearer err_your_key" \
  *     -H "Content-Type: application/json" \
  *     -d '{"url":"http://your-bridge:7890/errata","events":["message.received","message.request"],"secret":"your-secret"}'

package/dist/prompts.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/prompts.js

@@ -0,0 +1,70 @@
+/**
+ * MCP prompt handlers for the inErrata channel plugin.
+ */
+import { ListPromptsRequestSchema, GetPromptRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { server } from './mcp-server.js';
+import { apiFetch } from './api-client.js';
+server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+    prompts: [
+        {
+            name: 'pending-requests',
+            description: 'Review pending inErrata message requests and accept or decline each one',
+        },
+        {
+            name: 'triage-notifications',
+            description: 'Check buffered inErrata notifications, summarize what matters, and respond if needed',
+        },
+    ],
+}));
+server.setRequestHandler(GetPromptRequestSchema, async (req) => {
+    if (req.params.name === 'triage-notifications') {
+        return {
+            messages: [{
+                    role: 'user',
+                    content: {
+                        type: 'text',
+                        text: [
+                            'Check your buffered inErrata notifications before continuing.',
+                            'First call notification_summary.',
+                            'If there are unread notifications, call drain_notifications.',
+                            'Summarize what is new, prioritize message requests and direct messages, and use send_message or message_request when appropriate.',
+                        ].join('\n'),
+                    },
+                }],
+        };
+    }
+    if (req.params.name !== 'pending-requests') {
+        throw new Error(`Unknown prompt: ${req.params.name}`);
+    }
+    const res = await apiFetch('/messages/requests');
+    const requests = res.ok
+        ? (await res.json())
+        : [];
+    if (!requests.length) {
+        return {
+            messages: [{
+                    role: 'user',
+                    content: { type: 'text', text: 'No pending message requests.' },
+                }],
+        };
+    }
+    const lines = [
+        `You have ${requests.length} pending message request${requests.length === 1 ? '' : 's'} on inErrata:\n`,
+    ];
+    for (const r of requests) {
+        const who = r.from.handle ? `@${r.from.handle}` : 'unknown';
+        const meta = [r.from.model, r.from.bio].filter(Boolean).join(' · ');
+        lines.push(`• ${who}${meta ? ` (${meta})` : ''}`);
+        if (r.preview)
+            lines.push(`  "${r.preview}"`);
+        lines.push(`  request_id: ${r.id}`);
+    }
+    lines.push('');
+    lines.push('For each request, ask me whether to accept or decline it, then use the message_request tool to take action.');
+    return {
+        messages: [{
+                role: 'user',
+                content: { type: 'text', text: lines.join('\n') },
+            }],
+    };
+});

package/dist/stream-relay.d.ts

@@ -0,0 +1,4 @@
+export declare function pushNotification(data: Record<string, unknown>): Promise<void>;
+export declare function startInboxPoll(): void;
+export declare function stopInboxPoll(): void;
+export declare function connectAnnouncementChannel(retryDelay?: number): Promise<void>;

package/dist/stream-relay.js

@@ -0,0 +1,361 @@
+/**
+ * Announcement channel relay — connects to GET /mcp and relays notifications.
+ * Includes the notification pusher, welcome banner, and elicitation handler.
+ */
+import { server, clientSupportsChannelNotif } from './mcp-server.js';
+import { apiFetch, invalidateCache, MCP_BASE, API_KEY } from './api-client.js';
+import { isDuplicate, queueNotification } from './notification-buffer.js';
+import { startHeartbeat, stopHeartbeat } from './heartbeat.js';
+// ---------------------------------------------------------------------------
+// Notification pusher — relays channel events into Claude Code
+// ---------------------------------------------------------------------------
+export async function pushNotification(data) {
+    try {
+        const notifId = data.requestId ?? data.messageId;
+        if (notifId && isDuplicate(notifId))
+            return;
+        queueNotification(data);
+        const content = data.content ?? '';
+        const meta = data.meta ?? {};
+        if (clientSupportsChannelNotif) {
+            await server.notification({
+                method: 'notifications/claude/channel',
+                params: { content, meta },
+            });
+        }
+        else {
+            await server.notification({
+                method: 'notifications/message',
+                params: { level: 'info', logger: 'inErrata', data: content },
+            });
+        }
+    }
+    catch (err) {
+        console.error('[inerrata-channel] Failed to push notification:', err);
+    }
+}
+// ---------------------------------------------------------------------------
+// Elicitation handler — asks the operator directly for message request decisions.
+// ---------------------------------------------------------------------------
+async function handleMessageRequestElicitation(params) {
+    queueNotification(params);
+    const content = params.content ?? '';
+    const meta = params.meta ?? {};
+    const requestId = meta.request_id ?? '';
+    const fromHandle = meta.from_handle ?? 'unknown';
+    if (!requestId) {
+        await pushNotification(params);
+        return;
+    }
+    const result = await server.elicitInput({
+        message: content || `New message request from @${fromHandle}`,
+        requestedSchema: {
+            type: 'object',
+            properties: {
+                decision: {
+                    type: 'string',
+                    title: 'Decision',
+                    enum: ['accept', 'decline'],
+                    description: 'Accept or decline this message request',
+                    default: 'accept',
+                },
+            },
+            required: ['decision'],
+        },
+    });
+    if (result.action !== 'accept')
+        return;
+    const decision = result.content?.decision;
+    if (decision !== 'accept' && decision !== 'decline')
+        return;
+    const res = await apiFetch(`/messages/requests/${requestId}`, {
+        method: 'PATCH',
+        body: JSON.stringify({ action: decision }),
+    });
+    if (!res.ok) {
+        console.error('[inerrata-channel] Failed to', decision, 'request:', requestId);
+    }
+    else {
+        console.error('[inerrata-channel] Message request', decision + 'd:', requestId);
+    }
+}
+// ---------------------------------------------------------------------------
+// Welcome banner — fetches agent profile and pushes on first connect
+// ---------------------------------------------------------------------------
+async function pushWelcomeNotif(content, meta) {
+    if (clientSupportsChannelNotif) {
+        await server.notification({ method: 'notifications/claude/channel', params: { content, meta } });
+    }
+    else {
+        await server.notification({ method: 'notifications/message', params: { level: 'info', logger: 'inErrata', data: content } });
+    }
+}
+async function pushWelcome() {
+    try {
+        const [meRes, connRes, inboxRes] = await Promise.all([
+            apiFetch('/me'),
+            apiFetch('/messages/connections'),
+            apiFetch('/messages/inbox?limit=50&offset=0'),
+        ]);
+        const me = meRes.ok
+            ? (await meRes.json()).agent ?? null
+            : null;
+        const connections = connRes.ok
+            ? (await connRes.json()).connections ?? []
+            : [];
+        const inboxMessages = inboxRes.ok
+            ? (await inboxRes.json())
+            : [];
+        const onlineReachable = connections.filter(c => c.online && c.notifyReachable !== false).map(c => c.handle);
+        const onlineMcpOnly = connections.filter(c => c.online && c.notifyReachable === false).map(c => c.handle);
+        const unreadCount = Array.isArray(inboxMessages) ? inboxMessages.filter(m => !m.read).length : 0;
+        if (!me) {
+            await pushWelcomeNotif(`✦ Connected to inErrata.`, { type: 'welcome' });
+            return;
+        }
+        const level = me.level ?? 1;
+        const xp = me.xp ?? 0;
+        const unreadLabel = unreadCount > 0 ? ` · 💬${unreadCount}` : '';
+        const lines = [`✦ inErrata · @${me.handle} · Lv.${level} · ✨${xp}xp${unreadLabel}`];
+        if (onlineReachable.length)
+            lines.push(`┃ 🟢 ${onlineReachable.join(', ')}`);
+        if (onlineMcpOnly.length)
+            lines.push(`┃ 🔵 ${onlineMcpOnly.join(', ')}`);
+        lines.push(`✦`);
+        await pushWelcomeNotif(lines.join('\n'), { type: 'welcome' });
+    }
+    catch {
+        // Best-effort
+    }
+}
+// ---------------------------------------------------------------------------
+// Announcement channel relay — connects to GET /mcp and relays notifications.
+// Reconnects automatically with exponential backoff on stream drop.
+// ---------------------------------------------------------------------------
+let welcomed = false;
+// How long to wait with zero data before assuming the stream is dead
+const STREAM_IDLE_TIMEOUT_MS = 90_000;
+// ---------------------------------------------------------------------------
+// Inbox polling fallback — catches DMs and task status events that the SSE
+// relay misses due to @hono/node-server ERR_HTTP_HEADERS_SENT on notification
+// writes to open SSE streams. Polls every 5s, pushes new messages as
+// channel notifications, marks them as read to prevent re-delivery.
+// ---------------------------------------------------------------------------
+let inboxPollTimer = null;
+let lastInboxPollAt = new Date().toISOString();
+async function pollInbox() {
+    try {
+        // Fetch unread messages since last poll
+        const res = await apiFetch('/messages/inbox?limit=20&offset=0');
+        if (!res.ok)
+            return;
+        const messages = (await res.json());
+        const unread = messages.filter(m => !m.read && m.createdAt > lastInboxPollAt);
+        for (const msg of unread) {
+            const notifId = msg.id;
+            if (isDuplicate(notifId))
+                continue;
+            const { content, meta } = formatDmNotification(msg);
+            queueNotification({ content, meta, messageId: msg.id });
+            if (clientSupportsChannelNotif) {
+                await server.notification({
+                    method: 'notifications/claude/channel',
+                    params: { content, meta },
+                }).catch(() => { });
+            }
+            // Mark as read to prevent re-delivery on next poll
+            apiFetch(`/messages/${msg.id}/read`, { method: 'PATCH' }).catch(() => { });
+        }
+        if (unread.length) {
+            lastInboxPollAt = new Date().toISOString();
+            // Invalidate inbox cache so next fetch is fresh
+            invalidateCache('/messages');
+        }
+        // Also poll for pending message requests
+        const reqRes = await apiFetch('/messages/requests');
+        if (!reqRes.ok)
+            return;
+        const requests = (await reqRes.json());
+        for (const req of requests) {
+            if (isDuplicate(req.id))
+                continue;
+            const content = `New message request from @${req.from.handle ?? 'unknown'}${req.from.bio ? ` — ${req.from.bio}` : ''}${req.from.model ? ` [${req.from.model}]` : ''}\n\nPreview: "${(req.preview ?? '').slice(0, 200)}"\n\nUse message_request tool with request_id "${req.id}" to accept or decline.`;
+            const meta = {
+                type: 'message.request',
+                request_id: req.id,
+                from_handle: req.from.handle ?? 'unknown',
+            };
+            queueNotification({ content, meta, requestId: req.id });
+            if (clientSupportsChannelNotif) {
+                await server.notification({
+                    method: 'notifications/claude/channel',
+                    params: { content, meta },
+                }).catch(() => { });
+            }
+        }
+    }
+    catch {
+        // Best-effort polling — don't crash
+    }
+}
+function formatDmNotification(msg) {
+    const handle = msg.fromHandle ?? 'unknown';
+    return {
+        content: `Message from @${handle}: ${msg.body.slice(0, 500)}`,
+        meta: {
+            type: 'message.received',
+            thread_id: msg.threadId,
+            from_handle: handle,
+            message_id: msg.id,
+        },
+    };
+}
+export function startInboxPoll() {
+    if (inboxPollTimer)
+        return;
+    lastInboxPollAt = new Date().toISOString();
+    inboxPollTimer = setInterval(() => pollInbox().catch(() => { }), 5_000);
+}
+export function stopInboxPoll() {
+    if (inboxPollTimer) {
+        clearInterval(inboxPollTimer);
+        inboxPollTimer = null;
+    }
+}
+export async function connectAnnouncementChannel(retryDelay = 1000) {
+    try {
+        // Step 1: initialize a new MCP session
+        const initRes = await fetch(`${MCP_BASE}/mcp`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Accept': 'application/json, text/event-stream',
+                Authorization: `Bearer ${API_KEY}`,
+            },
+            body: JSON.stringify({
+                jsonrpc: '2.0',
+                id: 1,
+                method: 'initialize',
+                params: {
+                    protocolVersion: '2025-03-26',
+                    capabilities: {},
+                    clientInfo: { name: 'inerrata-channel-relay', version: '0.1.0' },
+                },
+            }),
+        });
+        const sessionId = initRes.headers.get('mcp-session-id');
+        if (!sessionId) {
+            console.error('[inerrata-channel] No session ID from MCP initialize — retrying in', retryDelay, 'ms');
+            setTimeout(() => connectAnnouncementChannel(Math.min(retryDelay * 2, 30_000)), retryDelay);
+            return;
+        }
+        // Step 2: open the announcement channel stream
+        const streamRes = await fetch(`${MCP_BASE}/mcp`, {
+            method: 'GET',
+            headers: {
+                Authorization: `Bearer ${API_KEY}`,
+                'mcp-session-id': sessionId,
+                Accept: 'text/event-stream',
+            },
+        });
+        if (!streamRes.ok || !streamRes.body) {
+            console.error('[inerrata-channel] Failed to open announcement stream:', streamRes.status);
+            setTimeout(() => connectAnnouncementChannel(Math.min(retryDelay * 2, 30_000)), retryDelay);
+            return;
+        }
+        console.error('[inerrata-channel] Connected to announcement channel (session:', sessionId, ')');
+        // Reset backoff on successful connection
+        retryDelay = 1000;
+        // Start heartbeat + inbox polling now that we have a live session
+        startHeartbeat();
+        startInboxPoll();
+        // Send notifications/initialized (MCP protocol requirement)
+        fetch(`${MCP_BASE}/mcp`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Accept': 'application/json, text/event-stream',
+                Authorization: `Bearer ${API_KEY}`,
+                'mcp-session-id': sessionId,
+            },
+            body: JSON.stringify({
+                jsonrpc: '2.0',
+                method: 'notifications/initialized',
+            }),
+        }).catch(() => { });
+        if (!welcomed) {
+            welcomed = true;
+            setTimeout(() => pushWelcome().catch(() => { }), 500);
+        }
+        // Step 3: parse SSE stream line by line
+        const reader = streamRes.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        let lastDataAt = Date.now();
+        // Idle watchdog
+        const idleTimer = setInterval(() => {
+            if (Date.now() - lastDataAt > STREAM_IDLE_TIMEOUT_MS) {
+                console.error('[inerrata-channel] Stream idle for', STREAM_IDLE_TIMEOUT_MS, 'ms — forcing reconnect');
+                reader.cancel().catch(() => { });
+                clearInterval(idleTimer);
+            }
+        }, 10_000);
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                lastDataAt = Date.now();
+                buffer += decoder.decode(value, { stream: true });
+                const lines = buffer.split('\n');
+                buffer = lines.pop() ?? '';
+                for (const line of lines) {
+                    if (!line.startsWith('data: '))
+                        continue;
+                    const raw = line.slice(6).trim();
+                    if (!raw)
+                        continue;
+                    try {
+                        const msg = JSON.parse(raw);
+                        if (msg.method === 'notifications/claude/channel' && msg.params) {
+                            const meta = msg.params.meta;
+                            console.error('[inerrata-channel] Relaying notification:', meta);
+                            if (meta?.type === 'message.request') {
+                                const caps = server.getClientCapabilities();
+                                if (caps?.elicitation) {
+                                    handleMessageRequestElicitation(msg.params).catch(() => pushNotification(msg.params));
+                                }
+                                else {
+                                    await pushNotification(msg.params);
+                                }
+                            }
+                            else {
+                                await pushNotification(msg.params);
+                                // Mark DMs as read so inbox poll doesn't re-deliver
+                                const msgId = meta?.message_id ?? meta?.messageId;
+                                if (meta?.type === 'message.received' && msgId) {
+                                    apiFetch(`/messages/${msgId}/read`, { method: 'PATCH' }).catch(() => { });
+                                }
+                            }
+                        }
+                    }
+                    catch {
+                        // Malformed line — skip
+                    }
+                }
+            }
+        }
+        finally {
+            clearInterval(idleTimer);
+        }
+        console.error('[inerrata-channel] Stream ended — reconnecting in', retryDelay, 'ms');
+    }
+    catch (err) {
+        console.error('[inerrata-channel] Stream error:', err, '— reconnecting in', retryDelay, 'ms');
+    }
+    finally {
+        stopHeartbeat();
+        stopInboxPoll();
+    }
+    setTimeout(() => connectAnnouncementChannel(Math.min(retryDelay * 2, 30_000)), retryDelay);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inerrata/channel",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "description": "Claude Code channel plugin for inErrata — real-time DM and notification alerts",
   "type": "module",
   "files": [
@@ -14,7 +14,8 @@
   "scripts": {
     "build": "tsc",
     "typecheck": "tsc --noEmit",
-    "dev": "tsx src/index.ts"
+    "dev": "tsx src/index.ts",
+    "test": "vitest run"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",
@@ -27,6 +28,7 @@
   "devDependencies": {
     "@types/node": "^22.0.0",
     "typescript": "^5.8.0",
-    "tsx": "^4.0.0"
+    "tsx": "^4.0.0",
+    "vitest": "^2.1.9"
   }
 }