sentinel-mcp 0.2.0 → 0.4.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/image-server.d.ts

@@ -0,0 +1,16 @@
+export declare function isAllowedUrl(url: string): boolean;
+export declare function findImageInHtml(html: string, uuid: string): string | null;
+interface IssueContext {
+    repo: string;
+    issueNumber: number;
+}
+type FetchResult = {
+    ok: true;
+    data: string;
+    mimeType: string;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function fetchImage(url: string, token?: string, context?: IssueContext): Promise<FetchResult>;
+export {};

package/dist/image-server.js

@@ -0,0 +1,122 @@
+const ALLOWED_PATTERNS = [
+    /^https:\/\/github\.com\/user-attachments\/assets\//,
+    /^https:\/\/[a-z0-9-]+\.githubusercontent\.com\//,
+];
+const MAX_IMAGE_SIZE = 10 * 1024 * 1024; // 10 MB
+export function isAllowedUrl(url) {
+    try {
+        const parsed = new URL(url);
+        if (parsed.protocol !== "https:")
+            return false;
+        return ALLOWED_PATTERNS.some((p) => p.test(url));
+    }
+    catch {
+        return false;
+    }
+}
+export function findImageInHtml(html, uuid) {
+    const imgPattern = /<img[^>]+src="([^"]+)"/g;
+    let match;
+    // First pass: match by UUID
+    while ((match = imgPattern.exec(html)) !== null) {
+        const src = match[1].replace(/&amp;/g, "&");
+        if (src.includes(uuid))
+            return src;
+    }
+    // Second pass: fallback to first private-user-images URL
+    imgPattern.lastIndex = 0;
+    while ((match = imgPattern.exec(html)) !== null) {
+        const src = match[1].replace(/&amp;/g, "&");
+        if (src.includes("private-user-images.githubusercontent.com"))
+            return src;
+    }
+    return null;
+}
+async function fetchAndEncode(url, headers) {
+    let res;
+    try {
+        res = await fetch(url, { headers });
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: `Fetch failed: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    if (!res.ok) {
+        return { ok: false, error: `HTTP ${res.status}` };
+    }
+    const contentType = res.headers.get("content-type") ?? "";
+    if (!contentType.startsWith("image/")) {
+        return { ok: false, error: `Response is not an image (${contentType})` };
+    }
+    const buffer = await res.arrayBuffer();
+    if (buffer.byteLength > MAX_IMAGE_SIZE) {
+        return {
+            ok: false,
+            error: `Image too large (${(buffer.byteLength / 1024 / 1024).toFixed(1)}MB)`,
+        };
+    }
+    const data = Buffer.from(buffer).toString("base64");
+    const mimeType = contentType.split(";")[0].trim();
+    return { ok: true, data, mimeType };
+}
+async function resolveImageFromIssueHtml(targetUrl, repo, issueNumber, token) {
+    const headers = {
+        Authorization: `token ${token}`,
+        Accept: "application/vnd.github.full+json",
+        "User-Agent": "sentinel-mcp/1.0",
+        "X-GitHub-Api-Version": "2022-11-28",
+    };
+    const uuidMatch = targetUrl.match(/\/assets\/([a-f0-9-]+)/);
+    if (!uuidMatch)
+        return null;
+    const uuid = uuidMatch[1];
+    const [issueRes, commentsRes] = await Promise.all([
+        fetch(`https://api.github.com/repos/${repo}/issues/${issueNumber}`, { headers }),
+        fetch(`https://api.github.com/repos/${repo}/issues/${issueNumber}/comments?per_page=100`, { headers }),
+    ]);
+    if (issueRes.ok) {
+        const issue = (await issueRes.json());
+        if (issue.body_html) {
+            const found = findImageInHtml(issue.body_html, uuid);
+            if (found)
+                return found;
+        }
+    }
+    if (commentsRes.ok) {
+        const comments = (await commentsRes.json());
+        for (const comment of comments) {
+            if (comment.body_html) {
+                const found = findImageInHtml(comment.body_html, uuid);
+                if (found)
+                    return found;
+            }
+        }
+    }
+    return null;
+}
+export async function fetchImage(url, token, context) {
+    if (!isAllowedUrl(url)) {
+        return { ok: false, error: "URL not allowed" };
+    }
+    const headers = {
+        "User-Agent": "sentinel-mcp/1.0",
+    };
+    if (token) {
+        headers["Authorization"] = `token ${token}`;
+    }
+    const result = await fetchAndEncode(url, headers);
+    // If direct fetch failed and it's a user-attachments URL, try resolving via GitHub Issues API
+    if (!result.ok &&
+        /github\.com\/user-attachments\/assets\//.test(url) &&
+        token &&
+        context?.repo &&
+        context?.issueNumber) {
+        const resolvedUrl = await resolveImageFromIssueHtml(url, context.repo, context.issueNumber, token);
+        if (resolvedUrl) {
+            return fetchAndEncode(resolvedUrl, { "User-Agent": "sentinel-mcp/1.0" });
+        }
+    }
+    return result;
+}

package/dist/index.js

@@ -1,12 +1,14 @@
 #!/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";
+import { fetchImage } from "./image-server.js";
 // ---------------------------------------------------------------------------
 // Config from environment
 // ---------------------------------------------------------------------------
@@ -142,6 +144,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 +168,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" });
@@ -235,8 +262,16 @@ server.registerTool("fetch_image", {
         issue_number: z.number().describe("Issue number where the image was posted"),
     },
 }, async ({ url, repo, issue_number }) => {
-    const result = await mcpToolCall("fetch_image", { url, repo, issue_number });
-    return { content: [{ type: "text", text: JSON.stringify(result) }] };
+    const result = await fetchImage(url, githubToken, { repo, issueNumber: issue_number });
+    if (!result.ok) {
+        return {
+            content: [{ type: "text", text: `${result.error}. Ask the user to describe the image or paste it as text.` }],
+            isError: true,
+        };
+    }
+    return {
+        content: [{ type: "image", data: result.data, mimeType: result.mimeType }],
+    };
 });
 server.registerTool("register_worktree", {
     description: "Register a new worktree for persistent subagent tracking. Call this after creating a worktree with git.",
@@ -259,51 +294,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 +303,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 +333,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.4.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",