sentinel-mcp 0.2.0 → 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,6 +1,7 @@
 #!/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";
@@ -142,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({
@@ -150,21 +167,30 @@ const wsClient = new WsClient({
     repo: REPO_NAME || undefined,
     log,
     onEvent: (id, payload, notification, usageId) => {
-        const added = eventQueue.enqueue(id, usageId ?? null, payload, notification ?? null);
-        if (!added) {
-            log(`Duplicate event ${id}, skipping`);
-        }
-        else {
-            updateEventStatus(usageId ?? null, "pending");
-            log(`Queued event ${id} (${payload.type} #${payload.type === "pr_merged" ? payload.issue_number : payload.issue?.number}) — queue: ${eventQueue.queueLength()}`);
+        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 (relay considers it delivered to MCP client)
+        // ACK immediately
         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" });
@@ -259,51 +285,6 @@ 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
 // ---------------------------------------------------------------------------
@@ -313,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) => {
@@ -326,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

@@ -1,4 +1,4 @@
-import type { QueuedEvent, SentinelEvent } from "./types.js";
+import type { ActiveEvent, SentinelEvent, EnqueueResult } from "./types.js";
 export interface EventQueueOptions {
     queueFilePath?: string;
     maxConcurrency?: number;
@@ -7,13 +7,15 @@ export interface EventQueueOptions {
 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): boolean;
-    claim(): QueuedEvent | null;
-    release(id: string): boolean;
+    } | null): EnqueueResult;
+    activate(): ActiveEvent | null;
+    releaseById(id: string): ActiveEvent | null;
     hasCapacity(): boolean;
     queueLength(): number;
     status(): {
@@ -35,6 +37,11 @@ export declare class EventQueue {
             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

@@ -4,6 +4,8 @@ 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;
@@ -27,16 +29,17 @@ export class EventQueue {
         }
     }
     enqueue(id, usageId, payload, notification) {
+        // Deduplicate
         if (this.state.queue.some((e) => e.id === id) || this.state.active.some((e) => e.id === id)) {
-            return false;
+            return { action: "duplicate" };
         }
         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 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,
+            priority: "normal",
             eventType: payload.type,
             repo: payload.repo,
             issueNumber,
@@ -44,7 +47,21 @@ export class EventQueue {
             payload,
             enqueuedAt: new Date().toISOString(),
         };
-        if (priority === "high") {
+        // 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);
@@ -52,18 +69,21 @@ export class EventQueue {
             else {
                 this.state.queue.splice(firstNormal, 0, entry);
             }
+            this.persist();
+            return { action: "enqueued", event: entry };
         }
-        else {
-            this.state.queue.push(entry);
-        }
+        // Normal priority: new issue
+        this.state.queue.push(entry);
         this.persist();
-        return true;
+        return { action: "enqueued", event: entry };
     }
-    claim() {
+    activate() {
         if (this.state.queue.length === 0)
             return null;
+        if (!this.hasCapacity())
+            return null;
         const event = this.state.queue.shift();
-        this.state.active.push({
+        const active = {
             id: event.id,
             usageId: event.usageId,
             issueNumber: event.issueNumber,
@@ -71,17 +91,26 @@ export class EventQueue {
             notification: event.notification,
             payload: event.payload,
             startedAt: new Date().toISOString(),
-        });
+        };
+        this.state.active.push(active);
         this.persist();
-        return event;
+        return active;
     }
-    release(id) {
+    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 false;
-        this.state.active.splice(idx, 1);
+            return null;
+        const released = this.state.active.splice(idx, 1)[0];
         this.persist();
-        return true;
+        return released;
     }
     hasCapacity() {
         return this.state.active.length < this.state.maxConcurrency;
@@ -103,6 +132,58 @@ export class EventQueue {
             })),
         };
     }
+    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");

package/dist/types.d.ts

@@ -88,3 +88,15 @@ export interface QueueState {
     active: ActiveEvent[];
     maxConcurrency: number;
 }
+export type EnqueueResult = {
+    action: "enqueued";
+    event: QueuedEvent;
+} | {
+    action: "duplicate";
+} | {
+    action: "bypass";
+    event: QueuedEvent;
+} | {
+    action: "dequeue";
+    removedId: string;
+};

package/package.json

@@ -1,14 +1,16 @@
 {
   "name": "sentinel-mcp",
-  "version": "0.2.0",
+  "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",