sentinel-mcp 0.1.2 → 0.2.0

package/dist/index.js

@@ -6,6 +6,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { WsClient, decodeInstallationId } from "./ws-client.js";
+import { EventQueue } from "./queue.js";
 // ---------------------------------------------------------------------------
 // Config from environment
 // ---------------------------------------------------------------------------
@@ -36,6 +37,8 @@ try {
 catch {
     log("WARNING: Could not resolve repo name from git remote — events will not be filtered by repo");
 }
+const MAX_CONCURRENCY = parseInt(process.env.SENTINEL_MAX_CONCURRENCY ?? "3", 10);
+const eventQueue = new EventQueue({ maxConcurrency: MAX_CONCURRENCY, recoverActive: true });
 // ---------------------------------------------------------------------------
 // MCP server setup
 // ---------------------------------------------------------------------------
@@ -59,6 +62,21 @@ function pushNotification(content, meta) {
         log(`Failed to push notification: ${err.message}`);
     });
 }
+function updateEventStatus(usageId, status) {
+    if (!usageId)
+        return;
+    const httpUrl = RELAY_URL.replace("wss://", "https://").replace("ws://", "http://");
+    fetch(`${httpUrl}/api/dashboard/events/${usageId}/status`, {
+        method: "PUT",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${SENTINEL_TOKEN}`,
+        },
+        body: JSON.stringify({ status }),
+    }).catch((err) => {
+        log(`Failed to update event status: ${err.message}`);
+    });
+}
 // ---------------------------------------------------------------------------
 // GitHub token management
 // ---------------------------------------------------------------------------
@@ -131,16 +149,22 @@ const wsClient = new WsClient({
     relayUrl: RELAY_URL,
     repo: REPO_NAME || undefined,
     log,
-    onEvent: (id, payload, notification) => {
-        // Use pre-built notification from relay if available, otherwise build a simple one
-        if (notification) {
-            pushNotification(notification.content, notification.meta);
+    onEvent: (id, payload, notification, usageId) => {
+        const added = eventQueue.enqueue(id, usageId ?? null, payload, notification ?? null);
+        if (!added) {
+            log(`Duplicate event ${id}, skipping`);
         }
         else {
-            const issueNum = payload.type === "pr_merged" ? payload.issue_number : payload.issue?.number;
-            pushNotification(`${payload.type} event for #${issueNum} in ${payload.repo}`, { type: payload.type, repo: payload.repo, issue: String(issueNum) });
+            updateEventStatus(usageId ?? null, "pending");
+            log(`Queued event ${id} (${payload.type} #${payload.type === "pr_merged" ? payload.issue_number : payload.issue?.number}) — queue: ${eventQueue.queueLength()}`);
         }
+        // ACK immediately (relay considers it delivered to MCP client)
         wsClient.ack(id);
+        // If capacity available, nudge Claude
+        if (eventQueue.hasCapacity() && eventQueue.queueLength() > 0) {
+            const issueNum = payload.type === "pr_merged" ? payload.issue_number : payload.issue?.number;
+            pushNotification(`New event queued: issue #${issueNum} in ${payload.repo} (${payload.type}). Call claim_event to start processing.`, { type: "queue_nudge", queueLength: String(eventQueue.queueLength()) });
+        }
     },
     onDisplaced: (reason) => {
         pushNotification(`Sentinel disconnected: ${reason}`, { type: "displaced" });
@@ -235,6 +259,51 @@ server.registerTool("get_skill", {
     const result = await mcpToolCall("get_skill", { name });
     return { content: [{ type: "text", text: JSON.stringify(result) }] };
 });
+server.registerTool("claim_event", {
+    description: "Claim the next queued event for processing. Returns event details or null if queue is empty.",
+}, async () => {
+    const event = eventQueue.claim();
+    if (!event) {
+        return { content: [{ type: "text", text: JSON.stringify(null) }] };
+    }
+    updateEventStatus(event.usageId, "processing");
+    return {
+        content: [{
+                type: "text",
+                text: JSON.stringify({
+                    id: event.id,
+                    usageId: event.usageId,
+                    notification: event.notification,
+                    payload: event.payload,
+                }),
+            }],
+    };
+});
+server.registerTool("release_event", {
+    description: "Release an event after processing completes (success or failure). Triggers next event if queue is non-empty.",
+    inputSchema: {
+        id: z.string().describe("Event ID returned by claim_event"),
+    },
+}, async ({ id }) => {
+    const released = eventQueue.release(id);
+    if (!released) {
+        return { content: [{ type: "text", text: JSON.stringify({ error: "Event not found in active list" }) }] };
+    }
+    // If queue has items and capacity available, nudge Claude
+    if (eventQueue.hasCapacity() && eventQueue.queueLength() > 0) {
+        const status = eventQueue.status();
+        const next = status.queue[0];
+        pushNotification(`Event released. Next in queue: issue #${next.issueNumber} in ${next.repo} (${next.eventType}). Call claim_event to process.`, { type: "queue_nudge", queueLength: String(status.queueLength) });
+    }
+    return { content: [{ type: "text", text: JSON.stringify({ released: true }) }] };
+});
+server.registerTool("queue_status", {
+    description: "Get the current event queue status — queue length, active count, and details.",
+}, async () => {
+    return {
+        content: [{ type: "text", text: JSON.stringify(eventQueue.status(), null, 2) }],
+    };
+});
 // ---------------------------------------------------------------------------
 // Startup
 // ---------------------------------------------------------------------------

package/dist/queue.d.ts

@@ -0,0 +1,40 @@
+import type { QueuedEvent, SentinelEvent } from "./types.js";
+export interface EventQueueOptions {
+    queueFilePath?: string;
+    maxConcurrency?: number;
+    recoverActive?: boolean;
+}
+export declare class EventQueue {
+    private state;
+    private filePath;
+    constructor(opts?: EventQueueOptions);
+    enqueue(id: string, usageId: string | null, payload: SentinelEvent, notification: {
+        content: string;
+        meta: Record<string, string>;
+    } | null): boolean;
+    claim(): QueuedEvent | null;
+    release(id: string): boolean;
+    hasCapacity(): boolean;
+    queueLength(): number;
+    status(): {
+        queueLength: number;
+        activeCount: number;
+        maxConcurrency: number;
+        queue: Array<{
+            id: string;
+            eventType: string;
+            repo: string;
+            issueNumber: number;
+            priority: string;
+            enqueuedAt: string;
+        }>;
+        active: Array<{
+            id: string;
+            repo: string;
+            issueNumber: number;
+            startedAt: string;
+        }>;
+    };
+    private load;
+    private persist;
+}

package/dist/queue.js

@@ -0,0 +1,123 @@
+import fs from "fs";
+import path from "path";
+import os from "os";
+export class EventQueue {
+    state;
+    filePath;
+    constructor(opts = {}) {
+        this.filePath = opts.queueFilePath ?? path.join(os.homedir(), ".sentinel", "queue.json");
+        const maxConcurrency = opts.maxConcurrency ?? 3;
+        this.state = this.load(maxConcurrency);
+        if (opts.recoverActive && this.state.active.length > 0) {
+            for (const active of this.state.active) {
+                this.state.queue.unshift({
+                    id: active.id,
+                    usageId: active.usageId,
+                    priority: "high",
+                    eventType: active.payload.type,
+                    repo: active.repo,
+                    issueNumber: active.issueNumber,
+                    notification: active.notification,
+                    payload: active.payload,
+                    enqueuedAt: new Date().toISOString(),
+                });
+            }
+            this.state.active = [];
+            this.persist();
+        }
+    }
+    enqueue(id, usageId, payload, notification) {
+        if (this.state.queue.some((e) => e.id === id) || this.state.active.some((e) => e.id === id)) {
+            return false;
+        }
+        const issueNumber = payload.type === "pr_merged" ? payload.issue_number : payload.issue.number;
+        const isFollowUp = this.state.active.some((a) => a.issueNumber === issueNumber && a.repo === payload.repo);
+        const priority = isFollowUp ? "high" : "normal";
+        const entry = {
+            id,
+            usageId,
+            priority,
+            eventType: payload.type,
+            repo: payload.repo,
+            issueNumber,
+            notification,
+            payload,
+            enqueuedAt: new Date().toISOString(),
+        };
+        if (priority === "high") {
+            const firstNormal = this.state.queue.findIndex((e) => e.priority === "normal");
+            if (firstNormal === -1) {
+                this.state.queue.push(entry);
+            }
+            else {
+                this.state.queue.splice(firstNormal, 0, entry);
+            }
+        }
+        else {
+            this.state.queue.push(entry);
+        }
+        this.persist();
+        return true;
+    }
+    claim() {
+        if (this.state.queue.length === 0)
+            return null;
+        const event = this.state.queue.shift();
+        this.state.active.push({
+            id: event.id,
+            usageId: event.usageId,
+            issueNumber: event.issueNumber,
+            repo: event.repo,
+            notification: event.notification,
+            payload: event.payload,
+            startedAt: new Date().toISOString(),
+        });
+        this.persist();
+        return event;
+    }
+    release(id) {
+        const idx = this.state.active.findIndex((e) => e.id === id);
+        if (idx === -1)
+            return false;
+        this.state.active.splice(idx, 1);
+        this.persist();
+        return true;
+    }
+    hasCapacity() {
+        return this.state.active.length < this.state.maxConcurrency;
+    }
+    queueLength() {
+        return this.state.queue.length;
+    }
+    status() {
+        return {
+            queueLength: this.state.queue.length,
+            activeCount: this.state.active.length,
+            maxConcurrency: this.state.maxConcurrency,
+            queue: this.state.queue.map((e) => ({
+                id: e.id, eventType: e.eventType, repo: e.repo,
+                issueNumber: e.issueNumber, priority: e.priority, enqueuedAt: e.enqueuedAt,
+            })),
+            active: this.state.active.map((e) => ({
+                id: e.id, repo: e.repo, issueNumber: e.issueNumber, startedAt: e.startedAt,
+            })),
+        };
+    }
+    load(maxConcurrency) {
+        try {
+            const data = fs.readFileSync(this.filePath, "utf-8");
+            const parsed = JSON.parse(data);
+            return { ...parsed, maxConcurrency: parsed.maxConcurrency ?? maxConcurrency };
+        }
+        catch {
+            return { queue: [], active: [], maxConcurrency };
+        }
+    }
+    persist() {
+        const dir = path.dirname(this.filePath);
+        fs.mkdirSync(dir, { recursive: true });
+        const tmpPath = this.filePath + ".tmp";
+        fs.writeFileSync(tmpPath, JSON.stringify(this.state, null, 2));
+        fs.renameSync(tmpPath, this.filePath);
+    }
+}

package/dist/types.d.ts

@@ -1,5 +1,5 @@
 export interface IssueEvent {
-    type: "issue_opened" | "issue_comment" | "issue_closed";
+    type: "issue_opened" | "issue_labeled" | "issue_comment" | "issue_closed";
     repo: string;
     issue: {
         number: number;
@@ -29,6 +29,7 @@ export type ServerMessage = {
     type: "event";
     id: string;
     payload: SentinelEvent;
+    usageId?: string;
     notification?: {
         content: string;
         meta: Record<string, string>;
@@ -56,3 +57,34 @@ export type ClientMessage = {
     issue: number;
     session_id: string;
 };
+export interface QueuedEvent {
+    id: string;
+    usageId: string | null;
+    priority: "high" | "normal";
+    eventType: string;
+    repo: string;
+    issueNumber: number;
+    notification: {
+        content: string;
+        meta: Record<string, string>;
+    } | null;
+    payload: SentinelEvent;
+    enqueuedAt: string;
+}
+export interface ActiveEvent {
+    id: string;
+    usageId: string | null;
+    issueNumber: number;
+    repo: string;
+    notification: {
+        content: string;
+        meta: Record<string, string>;
+    } | null;
+    payload: SentinelEvent;
+    startedAt: string;
+}
+export interface QueueState {
+    queue: QueuedEvent[];
+    active: ActiveEvent[];
+    maxConcurrency: number;
+}

package/dist/ws-client.d.ts

@@ -20,7 +20,7 @@ export interface WsClientOptions {
     onEvent: (id: string, payload: any, notification?: {
         content: string;
         meta: Record<string, string>;
-    }) => void;
+    }, usageId?: string) => void;
     onDisplaced: (reason: string) => void;
     onLimitReached?: (message: string) => void;
     log: (msg: string) => void;

package/dist/ws-client.js

@@ -89,7 +89,7 @@ export class WsClient {
                 return;
             }
             if (msg.type === "event") {
-                this.opts.onEvent(msg.id, msg.payload, msg.notification);
+                this.opts.onEvent(msg.id, msg.payload, msg.notification, msg.usageId);
             }
             else if (msg.type === "ping") {
                 this.send({ type: "pong" });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sentinel-mcp",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Sentinel MCP server — connects GitHub issues to Claude Code sessions",
   "type": "module",
   "main": "dist/index.js",