sentinel-mcp 0.1.2 → 0.3.0

package/bin/release-hook.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+# SubagentStop hook — writes a signal file for the sentinel-mcp file watcher.
+# Called by Claude Code when a background subagent finishes.
+# Reads hook input JSON from stdin, extracts the event ID, writes signal file.
+
+COMPLETED_DIR="$HOME/.sentinel/completed"
+mkdir -p "$COMPLETED_DIR"
+
+# Read hook input from stdin
+INPUT=$(cat)
+
+# Try to extract SENTINEL_EVENT_ID from the subagent's last message or transcript
+EVENT_ID=$(echo "$INPUT" | grep -o 'SENTINEL_EVENT_ID=[^ "\\]*' | head -1 | cut -d= -f2)
+
+if [ -z "$EVENT_ID" ]; then
+  EVENT_ID="unknown"
+fi
+
+# Write signal file — filename is the event ID
+echo "$(date -u +%Y-%m-%dT%H:%M:%SZ)" > "$COMPLETED_DIR/$EVENT_ID"

package/dist/index.js

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
 import { execSync } from "child_process";
 import fs from "fs";
+import os from "os";
 import path from "path";
 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 +38,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 +63,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
 // ---------------------------------------------------------------------------
@@ -124,6 +143,22 @@ async function mcpToolCall(toolName, args) {
     return rpcResponse.result;
 }
 // ---------------------------------------------------------------------------
+// Auto-push — deliver next event from queue when capacity is available
+// ---------------------------------------------------------------------------
+function autoPush() {
+    while (eventQueue.hasCapacity() && eventQueue.queueLength() > 0) {
+        const active = eventQueue.activate();
+        if (!active)
+            break;
+        updateEventStatus(active.usageId, "processing");
+        if (active.notification) {
+            const content = `SENTINEL_EVENT_ID=${active.id}\n${active.notification.content}`;
+            pushNotification(content, active.notification.meta);
+        }
+        log(`Activated event ${active.id} (#${active.issueNumber} in ${active.repo})`);
+    }
+}
+// ---------------------------------------------------------------------------
 // WebSocket client — receives events from relay, pushes as channel notifications
 // ---------------------------------------------------------------------------
 const wsClient = new WsClient({
@@ -131,15 +166,30 @@ 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);
-        }
-        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) });
+    onEvent: (id, payload, notification, usageId) => {
+        const result = eventQueue.enqueue(id, usageId ?? null, payload, notification ?? null);
+        switch (result.action) {
+            case "duplicate":
+                log(`Duplicate event ${id}, skipping`);
+                break;
+            case "bypass":
+                // Comment/lifecycle for active issue — push directly, no slot consumed
+                updateEventStatus(usageId ?? null, "processing");
+                if (result.event.notification) {
+                    pushNotification(`SENTINEL_EVENT_ID=${result.event.id}\n${result.event.notification.content}`, result.event.notification.meta);
+                }
+                log(`Bypass event ${id} (follow-up for active issue #${result.event.issueNumber})`);
+                break;
+            case "dequeue":
+                log(`Dequeued event ${result.removedId} — issue resolved before processing`);
+                break;
+            case "enqueued":
+                updateEventStatus(usageId ?? null, "pending");
+                log(`Queued event ${id} (${payload.type} #${payload.type === "pr_merged" ? payload.issue_number : payload.issue?.number}) — queue: ${eventQueue.queueLength()}`);
+                autoPush();
+                break;
         }
+        // ACK immediately
         wsClient.ack(id);
     },
     onDisplaced: (reason) => {
@@ -244,6 +294,23 @@ async function main() {
     await refreshGithubToken();
     tokenRefreshTimer = setInterval(refreshGithubToken, 50 * 60 * 1000);
     wsClient.connect();
+    // Start file watcher for deterministic release
+    const completedDir = path.join(os.homedir(), ".sentinel", "completed");
+    eventQueue.startFileWatcher(completedDir, (eventId, usageId) => {
+        log(`Released event ${eventId} via hook signal`);
+        updateEventStatus(usageId, "delivered");
+        autoPush();
+    });
+    // Start timeout checker (every 60s, 30-min timeout)
+    setInterval(() => {
+        const released = eventQueue.checkTimeouts(30 * 60 * 1000);
+        for (const event of released) {
+            log(`Timeout: auto-released stale event ${event.id}`);
+            updateEventStatus(event.usageId, "delivered");
+        }
+        if (released.length > 0)
+            autoPush();
+    }, 60 * 1000);
     log("Sentinel MCP bridge running");
 }
 main().catch((err) => {
@@ -257,6 +324,7 @@ function shutdown() {
     log("Shutting down...");
     if (tokenRefreshTimer)
         clearInterval(tokenRefreshTimer);
+    eventQueue.stopFileWatcher();
     wsClient.disconnect();
     server.close().catch(() => { });
     process.exit(0);

package/dist/queue.d.ts

@@ -0,0 +1,47 @@
+import type { ActiveEvent, SentinelEvent, EnqueueResult } from "./types.js";
+export interface EventQueueOptions {
+    queueFilePath?: string;
+    maxConcurrency?: number;
+    recoverActive?: boolean;
+}
+export declare class EventQueue {
+    private state;
+    private filePath;
+    private watcher;
+    private completedDir;
+    constructor(opts?: EventQueueOptions);
+    enqueue(id: string, usageId: string | null, payload: SentinelEvent, notification: {
+        content: string;
+        meta: Record<string, string>;
+    } | null): EnqueueResult;
+    activate(): ActiveEvent | null;
+    releaseById(id: string): ActiveEvent | null;
+    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;
+        }>;
+    };
+    getActiveEvents(): ActiveEvent[];
+    checkTimeouts(timeoutMs: number): ActiveEvent[];
+    startFileWatcher(completedDir: string, onRelease: (eventId: string, usageId: string | null) => void): void;
+    stopFileWatcher(): void;
+    private processSignalFiles;
+    private load;
+    private persist;
+}

package/dist/queue.js

@@ -0,0 +1,204 @@
+import fs from "fs";
+import path from "path";
+import os from "os";
+export class EventQueue {
+    state;
+    filePath;
+    watcher = null;
+    completedDir = "";
+    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) {
+        // Deduplicate
+        if (this.state.queue.some((e) => e.id === id) || this.state.active.some((e) => e.id === id)) {
+            return { action: "duplicate" };
+        }
+        const issueNumber = payload.type === "pr_merged" ? payload.issue_number : payload.issue.number;
+        const isActiveIssue = this.state.active.some((a) => a.issueNumber === issueNumber && a.repo === payload.repo);
+        const isQueuedIssue = this.state.queue.some((q) => q.issueNumber === issueNumber && q.repo === payload.repo);
+        const entry = {
+            id,
+            usageId,
+            priority: "normal",
+            eventType: payload.type,
+            repo: payload.repo,
+            issueNumber,
+            notification,
+            payload,
+            enqueuedAt: new Date().toISOString(),
+        };
+        // Bypass: comment/lifecycle events for already-active issues — push directly, no slot
+        if (isActiveIssue && (payload.type === "issue_comment" || payload.type === "pr_merged" || payload.type === "issue_closed")) {
+            return { action: "bypass", event: entry };
+        }
+        // Dequeue: pr_merged/issue_closed for queued-but-not-active issues — remove the queued event
+        if (isQueuedIssue && (payload.type === "pr_merged" || payload.type === "issue_closed")) {
+            const idx = this.state.queue.findIndex((q) => q.issueNumber === issueNumber && q.repo === payload.repo);
+            const removed = this.state.queue[idx];
+            this.state.queue.splice(idx, 1);
+            this.persist();
+            return { action: "dequeue", removedId: removed.id };
+        }
+        // High priority: comment for queued-but-not-active issue
+        if (isQueuedIssue && payload.type === "issue_comment") {
+            entry.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);
+            }
+            this.persist();
+            return { action: "enqueued", event: entry };
+        }
+        // Normal priority: new issue
+        this.state.queue.push(entry);
+        this.persist();
+        return { action: "enqueued", event: entry };
+    }
+    activate() {
+        if (this.state.queue.length === 0)
+            return null;
+        if (!this.hasCapacity())
+            return null;
+        const event = this.state.queue.shift();
+        const active = {
+            id: event.id,
+            usageId: event.usageId,
+            issueNumber: event.issueNumber,
+            repo: event.repo,
+            notification: event.notification,
+            payload: event.payload,
+            startedAt: new Date().toISOString(),
+        };
+        this.state.active.push(active);
+        this.persist();
+        return active;
+    }
+    releaseById(id) {
+        // Fallback: "unknown" releases oldest active event (FIFO)
+        if (id === "unknown") {
+            if (this.state.active.length === 0)
+                return null;
+            const released = this.state.active.shift();
+            this.persist();
+            return released;
+        }
+        const idx = this.state.active.findIndex((e) => e.id === id);
+        if (idx === -1)
+            return null;
+        const released = this.state.active.splice(idx, 1)[0];
+        this.persist();
+        return released;
+    }
+    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,
+            })),
+        };
+    }
+    getActiveEvents() {
+        return [...this.state.active];
+    }
+    checkTimeouts(timeoutMs) {
+        const now = Date.now();
+        const released = [];
+        const timedOut = this.state.active.filter((e) => now - new Date(e.startedAt).getTime() > timeoutMs);
+        for (const event of timedOut) {
+            const rel = this.releaseById(event.id);
+            if (rel)
+                released.push(rel);
+        }
+        return released;
+    }
+    startFileWatcher(completedDir, onRelease) {
+        this.completedDir = completedDir;
+        fs.mkdirSync(completedDir, { recursive: true });
+        // Process any existing signal files first
+        this.processSignalFiles(onRelease);
+        this.watcher = fs.watch(completedDir, () => {
+            this.processSignalFiles(onRelease);
+        });
+    }
+    stopFileWatcher() {
+        if (this.watcher) {
+            this.watcher.close();
+            this.watcher = null;
+        }
+    }
+    processSignalFiles(onRelease) {
+        let files;
+        try {
+            files = fs.readdirSync(this.completedDir);
+        }
+        catch {
+            return;
+        }
+        for (const file of files) {
+            const eventId = file;
+            const filePath = path.join(this.completedDir, file);
+            const released = this.releaseById(eventId);
+            try {
+                fs.unlinkSync(filePath);
+            }
+            catch {
+                // File may already be deleted; ignore
+            }
+            if (released) {
+                onRelease(eventId, released.usageId);
+            }
+        }
+    }
+    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,46 @@ 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;
+}
+export type EnqueueResult = {
+    action: "enqueued";
+    event: QueuedEvent;
+} | {
+    action: "duplicate";
+} | {
+    action: "bypass";
+    event: QueuedEvent;
+} | {
+    action: "dequeue";
+    removedId: string;
+};

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,14 +1,16 @@
 {
   "name": "sentinel-mcp",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "Sentinel MCP server — connects GitHub issues to Claude Code sessions",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
-    "sentinel-mcp": "dist/index.js"
+    "sentinel-mcp": "dist/index.js",
+    "sentinel-mcp-release": "bin/release-hook.sh"
   },
   "files": [
-    "dist"
+    "dist",
+    "bin"
   ],
   "scripts": {
     "build": "tsc",