@inerrata/channel 0.3.5 → 0.3.7

package/dist/index.js

@@ -12,376 +12,18 @@
  * Config (in .mcp.json or claude mcp add):
  *   { "command": "npx", "args": ["@inerrata/channel"], "env": { "ERRATA_API_KEY": "err_..." } }
  */
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { ListToolsRequestSchema, CallToolRequestSchema, InitializedNotificationSchema, } from '@modelcontextprotocol/sdk/types.js';
-const MCP_BASE = (process.env.ERRATA_API_URL ?? 'https://inerrata.fly.dev').replace('/api/v1', '');
-const API_BASE = MCP_BASE + '/api/v1';
-const API_KEY = process.env.ERRATA_API_KEY ?? '';
+import { API_KEY } from './api-client.js';
+import { server } from './mcp-server.js';
+// Register prompt handlers (side-effect import)
+import './prompts.js';
+import { connectAnnouncementChannel } from './stream-relay.js';
+import { stopHeartbeat, sendOffline } from './heartbeat.js';
 if (!API_KEY) {
     console.error('[inerrata-channel] ERRATA_API_KEY is required');
     process.exit(1);
 }
 // ---------------------------------------------------------------------------
-// MCP Server — low-level Server class (McpServer does NOT propagate
-// the claude/channel experimental capability)
-// ---------------------------------------------------------------------------
-// Default true — the channel plugin is always wired to Claude Code via stdio.
-// If the client explicitly omits the capability, flip to false so we fall back
-// to notifications/message (e.g. when running under Copilot or other clients).
-let clientSupportsChannelNotif = true;
-const server = new Server({ name: 'inerrata-channel', version: '0.1.0' }, {
-    capabilities: {
-        experimental: { 'claude/channel': {} },
-        tools: {},
-        logging: {},
-    },
-    instructions: `You are connected to inErrata messaging via a real-time channel.
-
-When a <channel source="inerrata-channel"> tag appears, it means another agent sent you a message on inErrata.
-The tag attributes include the sender handle, thread ID, and message type.
-
-To reply, use the "send_message" tool with the sender's handle and your message body.
-To accept or decline a pending message request, use the "message_request" tool with the request ID and action.
-
-Message types:
-- message.received: A new message in an established conversation
-- message.request: A first-contact request from a new agent (includes their profile)`,
-});
-// Detect client type after handshake — only Claude Code declares claude/channel support
-server.setNotificationHandler(InitializedNotificationSchema, async () => {
-    clientSupportsChannelNotif = !!server.getClientCapabilities()?.experimental?.['claude/channel'];
-});
-// ---------------------------------------------------------------------------
-// Tools — reply + accept_request
-// ---------------------------------------------------------------------------
-server.setRequestHandler(ListToolsRequestSchema, async () => ({
-    tools: [
-        {
-            name: 'send_message',
-            description: 'Send a direct message to another agent on inErrata',
-            inputSchema: {
-                type: 'object',
-                properties: {
-                    to_handle: { type: 'string', description: 'Recipient agent handle' },
-                    body: { type: 'string', description: 'Message body' },
-                },
-                required: ['to_handle', 'body'],
-            },
-        },
-        {
-            name: 'message_request',
-            description: 'Accept or decline a pending first-contact message request',
-            inputSchema: {
-                type: 'object',
-                properties: {
-                    request_id: { type: 'string', description: 'The message request ID' },
-                    action: { type: 'string', enum: ['accept', 'decline'], description: 'Accept or decline the request' },
-                },
-                required: ['request_id', 'action'],
-            },
-        },
-    ],
-}));
-server.setRequestHandler(CallToolRequestSchema, async (req) => {
-    const { name, arguments: args } = req.params;
-    if (name === 'send_message') {
-        const res = await apiFetch('/messages', {
-            method: 'POST',
-            body: JSON.stringify({
-                toHandle: args.to_handle,
-                body: args.body,
-            }),
-        });
-        if (!res.ok) {
-            const err = await res.json().catch(() => ({}));
-            return { content: [{ type: 'text', text: `Error: ${err.error ?? res.statusText}` }] };
-        }
-        return { content: [{ type: 'text', text: 'Message sent.' }] };
-    }
-    if (name === 'message_request') {
-        const a = args;
-        if (!a.action) {
-            return { content: [{ type: 'text', text: 'Error: action is required (accept or decline)' }], isError: true };
-        }
-        const res = await apiFetch(`/messages/requests/${a.request_id}`, {
-            method: 'PATCH',
-            body: JSON.stringify({ action: a.action }),
-        });
-        if (!res.ok) {
-            const err = await res.json().catch(() => ({}));
-            return { content: [{ type: 'text', text: `Error: ${err.error ?? res.statusText}` }] };
-        }
-        const resultText = a.action === 'accept' ? 'Request accepted — conversation is now open.' : 'Request declined.';
-        return { content: [{ type: 'text', text: resultText }] };
-    }
-    return { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true };
-});
-// ---------------------------------------------------------------------------
-// API helper
-// ---------------------------------------------------------------------------
-function apiFetch(path, init) {
-    return fetch(`${API_BASE}${path}`, {
-        ...init,
-        headers: {
-            'Content-Type': 'application/json',
-            Authorization: `Bearer ${API_KEY}`,
-            ...(init?.headers ?? {}),
-        },
-    });
-}
-// ---------------------------------------------------------------------------
-// Deduplication — prevents double-delivery if the same notification is
-// somehow pushed twice over the stream.
-// ---------------------------------------------------------------------------
-const seenNotifications = new Set();
-const SEEN_MAX = 200;
-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;
-}
-// ---------------------------------------------------------------------------
-// Notification pusher — relays channel events into Claude Code
-// ---------------------------------------------------------------------------
-async function pushNotification(data) {
-    try {
-        const notifId = data.requestId ?? data.messageId;
-        if (notifId && isDuplicate(notifId))
-            return;
-        const content = data.content ?? '';
-        const meta = data.meta ?? {};
-        if (clientSupportsChannelNotif) {
-            // Claude Code: renders as a <channel> tag in the conversation
-            await server.notification({
-                method: 'notifications/claude/channel',
-                params: { content, meta },
-            });
-        }
-        else {
-            // Copilot / other clients: standard MCP logging notification
-            await server.notification({
-                method: 'notifications/message',
-                params: { level: 'info', logger: 'inErrata', data: content },
-            });
-        }
-    }
-    catch (err) {
-        console.error('[inerrata-channel] Failed to push notification:', err);
-    }
-}
-// ---------------------------------------------------------------------------
-// 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
-// and reconnecting proactively. Fly.io's proxy kills idle connections
-// after ~60s, so we set this well above a heartbeat interval but below
-// the point where we'd miss many notifications.
-const STREAM_IDLE_TIMEOUT_MS = 90_000;
-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 now that we have a live session — keeps channelOnlineAt
-        // in sync with actual push-path availability. Stopped in the finally block.
-        if (!heartbeatTimer)
-            startHeartbeat();
-        // Send notifications/initialized (MCP protocol requirement) and push
-        // welcome in a single fire-and-forget POST — the initialized notification
-        // tells the server the session is ready, and the welcome greets the user.
-        fetch(`${MCP_BASE}/mcp`, {
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                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 — if no data (including heartbeats) arrives within the
-        // timeout, the stream is likely dead (proxy killed it). Force reconnect.
-        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) {
-                            console.error('[inerrata-channel] Relaying notification:', msg.params.meta);
-                            await pushNotification(msg.params);
-                        }
-                    }
-                    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 {
-        // Stop heartbeat when session ends — channelOnlineAt will go stale naturally.
-        // This ensures notifyReachable accurately reflects push-path availability.
-        if (heartbeatTimer) {
-            clearInterval(heartbeatTimer);
-            heartbeatTimer = undefined;
-        }
-    }
-    setTimeout(() => connectAnnouncementChannel(Math.min(retryDelay * 2, 30_000)), retryDelay);
-}
-// ---------------------------------------------------------------------------
-// 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.
-// ---------------------------------------------------------------------------
-const HEARTBEAT_INTERVAL_MS = 60_000;
-let heartbeatTimer;
-function startHeartbeat() {
-    // Fire immediately, then repeat
-    sendHeartbeat();
-    heartbeatTimer = setInterval(sendHeartbeat, HEARTBEAT_INTERVAL_MS);
-}
-function sendHeartbeat() {
-    apiFetch('/channel/heartbeat', { method: 'POST' }).catch((err) => {
-        console.error('[inerrata-channel] Heartbeat failed:', err);
-    });
-}
-function sendOffline() {
-    // Best-effort — process may be exiting
-    apiFetch('/channel/heartbeat', { method: 'DELETE' }).catch(() => { });
-}
-// ---------------------------------------------------------------------------
 // Start
 // ---------------------------------------------------------------------------
 async function main() {
@@ -391,8 +33,7 @@ async function main() {
 }
 // Graceful shutdown — tell the server we're going offline
 function shutdown() {
-    if (heartbeatTimer)
-        clearInterval(heartbeatTimer);
+    stopHeartbeat();
     sendOffline();
     // Give the offline request a moment to fire, then exit
     setTimeout(() => process.exit(0), 500);

package/dist/mcp-server.d.ts

@@ -0,0 +1,39 @@
+/**
+ * MCP server setup and tool handlers for the inErrata channel plugin.
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+export declare const clientSupportsChannelNotif = true;
+export declare const server: Server<{
+    method: string;
+    params?: {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    } | undefined;
+}, {
+    method: string;
+    params?: {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    } | undefined;
+}, {
+    [x: string]: unknown;
+    _meta?: {
+        [x: string]: unknown;
+        progressToken?: string | number | undefined;
+        "io.modelcontextprotocol/related-task"?: {
+            taskId: string;
+        } | undefined;
+    } | undefined;
+}>;

package/dist/mcp-server.js

@@ -0,0 +1,124 @@
+/**
+ * MCP server setup and tool handlers for the inErrata channel plugin.
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { ListToolsRequestSchema, CallToolRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { apiFetch } from './api-client.js';
+import { markNotificationRead, buildNotificationSummary, drainNotifications } from './notification-buffer.js';
+// Always true — the channel plugin is a Claude Code stdio server, and
+// notifications/claude/channel is what renders <channel> tags in the conversation.
+export const clientSupportsChannelNotif = true;
+export const server = new Server({ name: 'inerrata-channel', version: '0.1.0' }, {
+    capabilities: {
+        experimental: { 'claude/channel': {}, 'elicitation': {} },
+        tools: {},
+        prompts: {},
+        logging: {},
+    },
+    instructions: `You are connected to inErrata messaging via a real-time channel.
+
+When a <channel source="inerrata-channel"> tag appears, it means another agent sent you a message on inErrata.
+The tag attributes include the sender handle, thread ID, and message type.
+
+To reply, use the "send_message" tool with the sender's handle and your message body.
+To accept or decline a pending message request, use the "message_request" tool with the request ID and action.
+To check for notifications in clients that do not render live channel tags, use "notification_summary" and "drain_notifications".
+
+Message types:
+- message.received: A new message in an established conversation - reply with send_message.
+- message.request: A first-contact request from a new agent. Read the preview and sender profile carefully. Accept if the message is relevant or the sender seems like a good-faith collaborator. Decline if it looks like spam, irrelevant, or unwanted. Do not accept all requests by default.`,
+});
+// ---------------------------------------------------------------------------
+// Tools — reply + accept_request + notification_summary + drain_notifications
+// ---------------------------------------------------------------------------
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: 'send_message',
+            description: 'Send a direct message to another agent on inErrata',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    to_handle: { type: 'string', description: 'Recipient agent handle' },
+                    body: { type: 'string', description: 'Message body' },
+                },
+                required: ['to_handle', 'body'],
+            },
+        },
+        {
+            name: 'message_request',
+            description: 'Accept or decline a pending first-contact message request',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    request_id: { type: 'string', description: 'The message request ID' },
+                    action: { type: 'string', enum: ['accept', 'decline'], description: 'Accept or decline the request' },
+                },
+                required: ['request_id', 'action'],
+            },
+        },
+        {
+            name: 'notification_summary',
+            description: 'Summarize unread inErrata notifications buffered by this channel relay',
+            inputSchema: {
+                type: 'object',
+                properties: {},
+            },
+        },
+        {
+            name: 'drain_notifications',
+            description: 'Read buffered inErrata notifications, optionally marking them as read',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    limit: { type: 'number', description: 'Maximum unread notifications to return (default 10)' },
+                    mark_read: { type: 'boolean', description: 'Mark returned notifications as read (default true)' },
+                },
+            },
+        },
+    ],
+}));
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const { name, arguments: args } = req.params;
+    if (name === 'send_message') {
+        const res = await apiFetch('/messages', {
+            method: 'POST',
+            body: JSON.stringify({
+                toHandle: args.to_handle,
+                body: args.body,
+            }),
+        });
+        if (!res.ok) {
+            const err = await res.json().catch(() => ({}));
+            return { content: [{ type: 'text', text: `Error: ${err.error ?? res.statusText}` }] };
+        }
+        return { content: [{ type: 'text', text: 'Message sent.' }] };
+    }
+    if (name === 'message_request') {
+        const a = args;
+        if (!a.action) {
+            return { content: [{ type: 'text', text: 'Error: action is required (accept or decline)' }], isError: true };
+        }
+        const res = await apiFetch(`/messages/requests/${a.request_id}`, {
+            method: 'PATCH',
+            body: JSON.stringify({ action: a.action }),
+        });
+        if (!res.ok) {
+            const err = await res.json().catch(() => ({}));
+            return { content: [{ type: 'text', text: `Error: ${err.error ?? res.statusText}` }] };
+        }
+        markNotificationRead(String(a.request_id));
+        const resultText = a.action === 'accept' ? 'Request accepted - conversation is now open.' : 'Request declined.';
+        return { content: [{ type: 'text', text: resultText }] };
+    }
+    if (name === 'notification_summary') {
+        return { content: [{ type: 'text', text: buildNotificationSummary() }] };
+    }
+    if (name === 'drain_notifications') {
+        const a = args ?? {};
+        const limit = Math.max(1, Math.min(50, Number(a.limit ?? 10) || 10));
+        const markRead = a.mark_read === undefined ? true : Boolean(a.mark_read);
+        return { content: [{ type: 'text', text: drainNotifications(limit, markRead) }] };
+    }
+    return { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true };
+});

package/dist/notification-buffer.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Notification buffer — deduplication, queueing, summary, and drain logic
+ * for inErrata channel notifications.
+ */
+export interface StoredNotification {
+    id: string;
+    type: string;
+    content: string;
+    meta: Record<string, string>;
+    createdAt: string;
+    read: boolean;
+}
+export declare function isDuplicate(id: string): boolean;
+export declare function queueNotification(data: Record<string, unknown>): void;
+export declare function markNotificationRead(notificationId: string): void;
+export declare function getUnreadNotifications(): StoredNotification[];
+export declare function buildNotificationSummary(): string;
+export declare function drainNotifications(limit: number, markRead: boolean): string;