sentinel-mcp 0.1.0

package/dist/image-server.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+export declare function isAllowedUrl(url: string): boolean;
+export declare function fetchImage(url: string): Promise<{
+    ok: true;
+    data: string;
+    mimeType: string;
+} | {
+    ok: false;
+    error: string;
+}>;

package/dist/image-server.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+const MAX_IMAGE_SIZE = 10 * 1024 * 1024; // 10MB
+const ALLOWED_PATTERNS = [
+    /^https:\/\/github\.com\/user-attachments\/assets\//,
+    /^https:\/\/[a-z0-9-]+\.githubusercontent\.com\//,
+];
+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 async function fetchImage(url) {
+    if (!isAllowedUrl(url)) {
+        return {
+            ok: false,
+            error: "URL not allowed. Only github.com/user-attachments/assets/* and *.githubusercontent.com/* URLs are permitted.",
+        };
+    }
+    let res;
+    try {
+        res = await fetch(url);
+    }
+    catch (err) {
+        return { ok: false, error: `Failed to fetch image: ${err.message}` };
+    }
+    if (!res.ok) {
+        return { ok: false, error: `Failed to fetch image: HTTP ${res.status}` };
+    }
+    // Early size check from Content-Length header (avoid buffering large responses)
+    const contentLength = res.headers.get("content-length");
+    if (contentLength && parseInt(contentLength) > MAX_IMAGE_SIZE) {
+        return {
+            ok: false,
+            error: `Image too large (${(parseInt(contentLength) / 1024 / 1024).toFixed(1)}MB). Max allowed: 10MB.`,
+        };
+    }
+    const contentType = res.headers.get("content-type") ?? "image/png";
+    if (!contentType.startsWith("image/")) {
+        return {
+            ok: false,
+            error: `Response is not an image (content-type: ${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). Max allowed: 10MB.`,
+        };
+    }
+    const base64 = Buffer.from(buffer).toString("base64");
+    const mimeType = contentType.split(";")[0].trim();
+    return { ok: true, data: base64, mimeType };
+}
+const server = new McpServer({
+    name: "sentinel-image",
+    version: "0.1.0",
+});
+server.registerTool("fetch_image", {
+    description: "Fetch an image from a GitHub issue. Pass the image URL from markdown ![alt](url) syntax.",
+    inputSchema: { url: z.string().url() },
+}, async ({ url }) => {
+    const result = await fetchImage(url);
+    if (!result.ok) {
+        return {
+            content: [{ type: "text", text: result.error }],
+            isError: true,
+        };
+    }
+    return {
+        content: [
+            {
+                type: "image",
+                data: result.data,
+                mimeType: result.mimeType,
+            },
+        ],
+    };
+});
+// Only start the server when run as a script, not when imported for testing
+const isMain = process.argv[1] &&
+    import.meta.url === new URL(process.argv[1], "file://").href;
+if (isMain) {
+    const transport = new StdioServerTransport();
+    server.connect(transport).catch((err) => {
+        console.error(`Fatal: ${err.message}`);
+        process.exit(1);
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+import { execSync } from "child_process";
+import fs from "fs";
+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";
+// ---------------------------------------------------------------------------
+// Config from environment
+// ---------------------------------------------------------------------------
+const SENTINEL_TOKEN = process.env.SENTINEL_TOKEN;
+if (!SENTINEL_TOKEN) {
+    console.error("FATAL: SENTINEL_TOKEN environment variable is required");
+    process.exit(1);
+}
+const RELAY_URL = process.env.SENTINEL_RELAY_URL ?? "wss://api.usesentinel.tools";
+const REPO_PATH = process.env.SENTINEL_REPO_PATH ?? process.cwd();
+// ---------------------------------------------------------------------------
+// Logger — must use stderr (stdout is reserved for MCP stdio transport)
+// ---------------------------------------------------------------------------
+function log(msg) {
+    console.error(`[sentinel] ${msg}`);
+}
+// ---------------------------------------------------------------------------
+// Resolve repo name (owner/repo) from git remote
+// ---------------------------------------------------------------------------
+let REPO_NAME = "";
+try {
+    const remoteUrl = execSync("git remote get-url origin", { cwd: REPO_PATH, encoding: "utf-8" }).trim();
+    const match = remoteUrl.match(/github\.com[:/]([^/]+\/[^/.]+)/);
+    if (match) {
+        REPO_NAME = match[1];
+    }
+}
+catch {
+    log("WARNING: Could not resolve repo name from git remote — events will not be filtered by repo");
+}
+// ---------------------------------------------------------------------------
+// MCP server setup
+// ---------------------------------------------------------------------------
+const server = new McpServer({ name: "sentinel", version: "0.2.0" }, {
+    capabilities: {
+        experimental: { "claude/channel": {} },
+    },
+    instructions: "Events from this channel arrive as <channel source=\"sentinel\" ...>. They contain GitHub issue and PR events for repos you monitor. Act on them according to the instructions in the event content.",
+});
+const transport = new StdioServerTransport();
+// ---------------------------------------------------------------------------
+// Channel notifications — push events from relay → Claude Code via stdio
+// ---------------------------------------------------------------------------
+function pushNotification(content, meta) {
+    server.server
+        .notification({
+        method: "notifications/claude/channel",
+        params: { content, meta },
+    })
+        .catch((err) => {
+        log(`Failed to push notification: ${err.message}`);
+    });
+}
+// ---------------------------------------------------------------------------
+// GitHub token management
+// ---------------------------------------------------------------------------
+let installationId;
+try {
+    installationId = decodeInstallationId(SENTINEL_TOKEN);
+}
+catch (err) {
+    console.error(`FATAL: Cannot decode installation ID from token: ${err.message}`);
+    process.exit(1);
+}
+let githubToken = "";
+let tokenRefreshTimer = null;
+async function refreshGithubToken() {
+    const httpUrl = RELAY_URL.replace("wss://", "https://").replace("ws://", "http://");
+    const tokenUrl = `${httpUrl}/api/token/${installationId}`;
+    try {
+        const res = await fetch(tokenUrl, {
+            headers: { Authorization: `Bearer ${SENTINEL_TOKEN}` },
+        });
+        if (!res.ok) {
+            throw new Error(`HTTP ${res.status}: ${await res.text()}`);
+        }
+        const data = (await res.json());
+        githubToken = data.token;
+        // Write token to ~/.sentinel/github-token for CLI tools
+        const dir = path.join(process.env.HOME ?? "~", ".sentinel");
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(path.join(dir, "github-token"), githubToken, { mode: 0o600 });
+        log("GitHub token refreshed");
+    }
+    catch (err) {
+        log(`Failed to refresh GitHub token: ${err.message}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// API helper — proxy tool calls to remote worker API
+// ---------------------------------------------------------------------------
+async function apiCall(endpoint, body) {
+    const httpUrl = RELAY_URL.replace("wss://", "https://").replace("ws://", "http://");
+    const res = await fetch(`${httpUrl}${endpoint}`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${SENTINEL_TOKEN}`,
+        },
+        body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`API error ${res.status}: ${text}`);
+    }
+    return res.json();
+}
+// ---------------------------------------------------------------------------
+// WebSocket client — receives events from relay, pushes as channel notifications
+// ---------------------------------------------------------------------------
+const wsClient = new WsClient({
+    token: SENTINEL_TOKEN,
+    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) });
+        }
+        wsClient.ack(id);
+    },
+    onDisplaced: (reason) => {
+        pushNotification(`Sentinel disconnected: ${reason}`, { type: "displaced" });
+    },
+    onLimitReached: (message) => {
+        pushNotification(message, { type: "limit_reached" });
+    },
+});
+// ---------------------------------------------------------------------------
+// MCP tools — proxy to remote API
+// ---------------------------------------------------------------------------
+server.registerTool("sentinel_status", {
+    description: "Get Sentinel connection status",
+}, async () => {
+    return {
+        content: [{
+                type: "text",
+                text: JSON.stringify({
+                    connected: wsClient.isConnected(),
+                    relayUrl: RELAY_URL,
+                    installationId,
+                    repo: REPO_NAME,
+                }, null, 2),
+            }],
+    };
+});
+server.registerTool("post_issue_comment", {
+    description: "Post a comment on a GitHub issue",
+    inputSchema: {
+        repo: z.string().describe("Repository in owner/repo format"),
+        issue_number: z.number().describe("Issue number"),
+        body: z.string().describe("Comment body (markdown)"),
+    },
+}, async ({ repo, issue_number, body }) => {
+    const result = await apiCall("/api/mcp/tools/post_issue_comment", { repo, issue_number, body });
+    return { content: [{ type: "text", text: JSON.stringify(result) }] };
+});
+server.registerTool("create_pull_request", {
+    description: "Create a pull request on GitHub",
+    inputSchema: {
+        repo: z.string().describe("Repository in owner/repo format"),
+        title: z.string().describe("PR title"),
+        body: z.string().describe("PR body (markdown)"),
+        head: z.string().describe("Branch name to merge from"),
+        base: z.string().describe("Branch name to merge into").default("main"),
+    },
+}, async ({ repo, title, body, head, base }) => {
+    const result = await apiCall("/api/mcp/tools/create_pull_request", { repo, title, body, head, base });
+    return { content: [{ type: "text", text: JSON.stringify(result) }] };
+});
+server.registerTool("update_worktree", {
+    description: "Update worktree status for an issue (active, pr_open, cleaned_up)",
+    inputSchema: {
+        repo: z.string().describe("Repository in owner/repo format"),
+        issue_number: z.number().describe("Issue number"),
+        branch: z.string().describe("Branch name"),
+        worktree_path: z.string().describe("Local worktree path"),
+        status: z.enum(["active", "pr_open", "cleaned_up"]).describe("Worktree status"),
+        pr_number: z.number().optional().describe("PR number if status is pr_open"),
+    },
+}, async ({ repo, issue_number, branch, worktree_path, status, pr_number }) => {
+    const result = await apiCall("/api/mcp/tools/update_worktree", {
+        repo, issue_number, branch, worktree_path, status, pr_number,
+    });
+    return { content: [{ type: "text", text: JSON.stringify(result) }] };
+});
+server.registerTool("get_skill", {
+    description: "Load a Sentinel skill's full instructions by name",
+    inputSchema: {
+        name: z.string().describe("Skill name"),
+    },
+}, async ({ name }) => {
+    const result = await apiCall("/api/mcp/tools/get_skill", { name });
+    return { content: [{ type: "text", text: JSON.stringify(result) }] };
+});
+// ---------------------------------------------------------------------------
+// Startup
+// ---------------------------------------------------------------------------
+async function main() {
+    await server.connect(transport);
+    log("MCP server connected via stdio");
+    await refreshGithubToken();
+    tokenRefreshTimer = setInterval(refreshGithubToken, 50 * 60 * 1000);
+    wsClient.connect();
+    log("Sentinel MCP bridge running");
+}
+main().catch((err) => {
+    log(`Fatal: ${err.message}`);
+    process.exit(1);
+});
+// ---------------------------------------------------------------------------
+// Graceful shutdown
+// ---------------------------------------------------------------------------
+function shutdown() {
+    log("Shutting down...");
+    if (tokenRefreshTimer)
+        clearInterval(tokenRefreshTimer);
+    wsClient.disconnect();
+    server.close().catch(() => { });
+    process.exit(0);
+}
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);

package/dist/prompts.d.ts

@@ -0,0 +1,19 @@
+import type { SentinelEvent } from "./types.js";
+export interface PromptSettings {
+    behavior: "pr" | "push";
+    autoClose: boolean;
+    branchPattern: string;
+    claudeMdTemplate?: string;
+}
+export interface IssuePromptInput {
+    repo: string;
+    issue: SentinelEvent["issue"];
+    settings: PromptSettings;
+}
+export interface CommentPromptInput {
+    repo: string;
+    issue: SentinelEvent["issue"];
+    comment: NonNullable<SentinelEvent["comment"]>;
+}
+export declare function buildIssuePrompt(input: IssuePromptInput): string;
+export declare function buildCommentPrompt(input: CommentPromptInput): string;

package/dist/prompts.js

@@ -0,0 +1,68 @@
+export function buildIssuePrompt(input) {
+    const { repo, issue, settings } = input;
+    const { behavior, autoClose, branchPattern, claudeMdTemplate } = settings;
+    const branchName = branchPattern.replace("{number}", String(issue.number));
+    const labelsText = issue.labels.length > 0 ? issue.labels.join(", ") : "(none)";
+    const deliveryInstructions = behavior === "pr"
+        ? `- Create a new branch named \`${branchName}\` from the default branch.
+- Commit your changes to that branch.
+- Open a pull request using \`gh pr create\` targeting the default branch with a clear title and description linking to issue #${issue.number}.`
+        : `- Commit your changes and push directly to the default branch (do not open a pull request).`;
+    const closeInstructions = autoClose
+        ? `- After the fix is merged/pushed, close the issue with \`gh issue close ${issue.number}\`.`
+        : `- After the fix is merged/pushed, post a brief summary comment on the issue explaining what was changed. Do NOT close the issue.`;
+    const claudeMdSection = claudeMdTemplate
+        ? `\n## Project Guidelines (CLAUDE.md)\n\n${claudeMdTemplate}\n`
+        : "";
+    const toolsSection = `## Available Tools
+
+- **fetch_image**: Before beginning your investigation, check if the issue body or comments contain any image markdown (\`![...](...)\`). If so, call \`fetch_image\` for each image URL to view screenshots or visuals that help you understand the bug report.
+
+`;
+    return `You are Sentinel, an autonomous bug-fixing agent. Your job is to investigate and fix the GitHub issue described below, then deliver the fix according to the configured workflow.
+${claudeMdSection}
+## Issue Details
+
+- **Repository:** ${repo}
+- **Issue:** #${issue.number} — ${issue.title}
+- **Author:** @${issue.author}
+- **Labels:** ${labelsText}
+- **URL:** ${issue.url}
+
+### Issue Body
+
+${issue.body}
+
+## Workflow Instructions
+
+${deliveryInstructions}
+${closeInstructions}
+
+${toolsSection}
+## General Rules
+
+- If you need clarification before proceeding, ask ONE focused question by posting a comment with \`gh issue comment ${issue.number} --body "<your question>"\`. Never post more than one comment per turn.
+- Do not ask for clarification if you already have enough information to begin.
+- Always work inside the repository at \`${repo}\`.
+- Write clean, minimal changes that address only the reported issue.
+
+Begin by exploring the codebase to understand the problem, then implement the fix.`;
+}
+export function buildCommentPrompt(input) {
+    const { repo, issue, comment } = input;
+    return `You are Sentinel, an autonomous bug-fixing agent. You are continuing work on issue #${issue.number} in repository ${repo}.
+
+## Human Reply
+
+**@${comment.author}** commented:
+
+${comment.body}
+
+---
+
+## Available Tools
+
+- **fetch_image**: If the comment contains images (markdown \`![...](...)\`), call \`fetch_image\` with the image URL to view them.
+
+Review the comment above and continue fixing the issue. If the comment answers a previous question or provides new information, incorporate it into your approach and proceed with the fix. If you still need one more clarification, ask a single focused question using \`gh issue comment ${issue.number} --body "<your question>"\`. Never post more than one comment per turn.`;
+}

package/dist/session-manager.d.ts

@@ -0,0 +1,30 @@
+import type { SentinelEvent } from "./types.js";
+export interface SessionManagerOptions {
+    maxConcurrent: number;
+    repoPath: string;
+    githubToken: string;
+    log: (msg: string) => void;
+    onSessionUpdate?: (issue: number, sessionId: string) => void;
+    onSessionComplete?: (issue: number, success: boolean) => void;
+}
+export declare class SessionManager {
+    private active;
+    private issueQueues;
+    private globalQueue;
+    private opts;
+    constructor(opts: SessionManagerOptions);
+    setGithubToken(token: string): void;
+    canSpawn(): boolean;
+    getActiveSessions(): Array<{
+        issue: number;
+        sessionId: string | null;
+        status: string;
+    }>;
+    getQueueLength(): number;
+    getIssueQueueLength(issue: number): number;
+    enqueue(event: SentinelEvent): void;
+    spawnSession(event: SentinelEvent): void;
+    killSession(issueNumber: number): void;
+    private drainGlobalQueue;
+    private postErrorComment;
+}

package/dist/session-manager.js

@@ -0,0 +1,221 @@
+import { spawn } from "child_process";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { fileURLToPath } from "url";
+import { buildIssuePrompt, buildCommentPrompt } from "./prompts.js";
+export class SessionManager {
+    active = new Map();
+    issueQueues = new Map();
+    globalQueue = [];
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    setGithubToken(token) {
+        this.opts.githubToken = token;
+    }
+    canSpawn() {
+        return this.active.size < this.opts.maxConcurrent;
+    }
+    getActiveSessions() {
+        return Array.from(this.active.entries()).map(([issue, session]) => ({
+            issue,
+            sessionId: session.sessionId,
+            status: "running",
+        }));
+    }
+    getQueueLength() {
+        return this.globalQueue.length;
+    }
+    getIssueQueueLength(issue) {
+        return this.issueQueues.get(issue)?.length ?? 0;
+    }
+    enqueue(event) {
+        const issueNumber = event.issue.number;
+        // Handle issue_closed: kill session + cleanup
+        if (event.type === "issue_closed") {
+            if (this.active.has(issueNumber)) {
+                this.killSession(issueNumber);
+            }
+            return;
+        }
+        // If issue has an active session, queue per-issue
+        if (this.active.has(issueNumber)) {
+            const queue = this.issueQueues.get(issueNumber) ?? [];
+            queue.push(event);
+            this.issueQueues.set(issueNumber, queue);
+            this.opts.log(`Queued event per-issue for #${issueNumber} (queue size: ${queue.length})`);
+            return;
+        }
+        // If at capacity, queue globally
+        if (!this.canSpawn()) {
+            this.globalQueue.push(event);
+            this.opts.log(`Queued event globally for #${issueNumber} (global queue size: ${this.globalQueue.length})`);
+            return;
+        }
+        // Otherwise spawn
+        this.spawnSession(event);
+    }
+    spawnSession(event) {
+        const issueNumber = event.issue.number;
+        const settings = {
+            behavior: "pr",
+            autoClose: true,
+            branchPattern: "sentinel/issue-{number}",
+        };
+        // Build prompt based on event type
+        let prompt;
+        if (event.type === "issue_comment" && event.comment) {
+            prompt = buildCommentPrompt({
+                repo: event.repo,
+                issue: event.issue,
+                comment: event.comment,
+            });
+        }
+        else {
+            prompt = buildIssuePrompt({
+                repo: event.repo,
+                issue: event.issue,
+                settings,
+            });
+        }
+        // Write temp MCP config for image server
+        const __dirname = path.dirname(fileURLToPath(import.meta.url));
+        const imageServerPath = path.join(__dirname, "image-server.js");
+        const mcpConfigPath = path.join(os.tmpdir(), `sentinel-mcp-${issueNumber}.json`);
+        fs.writeFileSync(mcpConfigPath, JSON.stringify({
+            mcpServers: {
+                "sentinel-image": {
+                    command: "node",
+                    args: [imageServerPath],
+                },
+            },
+        }));
+        // Build spawn args
+        const args = [
+            "-p", prompt,
+            "--output-format", "json",
+            "--mcp-config", mcpConfigPath,
+        ];
+        // Resume if we have a session ID from a previous run
+        const existing = this.active.get(issueNumber);
+        if (existing?.sessionId) {
+            args.push("--resume", existing.sessionId);
+        }
+        this.opts.log(`Spawning claude session for issue #${issueNumber}`);
+        const proc = spawn("claude", args, {
+            cwd: this.opts.repoPath,
+            env: {
+                ...process.env,
+                GITHUB_TOKEN: this.opts.githubToken,
+            },
+        });
+        const session = {
+            process: proc,
+            sessionId: existing?.sessionId ?? null,
+            issueNumber,
+            stdout: "",
+        };
+        this.active.set(issueNumber, session);
+        // Collect stdout
+        proc.stdout?.on("data", (data) => {
+            session.stdout += data.toString();
+        });
+        proc.stderr?.on("data", (data) => {
+            this.opts.log(`[issue #${issueNumber} stderr] ${data.toString()}`);
+        });
+        proc.on("close", (code) => {
+            // Clean up temp MCP config
+            try {
+                fs.unlinkSync(mcpConfigPath);
+            }
+            catch {
+                // best-effort
+            }
+            const success = code === 0;
+            // Try to parse session_id from stdout
+            try {
+                const output = JSON.parse(session.stdout);
+                if (output.session_id) {
+                    session.sessionId = output.session_id;
+                    this.opts.onSessionUpdate?.(issueNumber, output.session_id);
+                }
+            }
+            catch {
+                // stdout may not be valid JSON, that's fine
+            }
+            // Remove from active
+            this.active.delete(issueNumber);
+            this.opts.log(`Session for issue #${issueNumber} closed (code=${code}, success=${success})`);
+            // Notify completion
+            this.opts.onSessionComplete?.(issueNumber, success);
+            // On failure, post error comment (best-effort)
+            if (!success) {
+                this.postErrorComment(issueNumber, event.repo);
+            }
+            // Process per-issue queue first (priority)
+            const issueQueue = this.issueQueues.get(issueNumber);
+            if (issueQueue && issueQueue.length > 0) {
+                const next = issueQueue.shift();
+                if (issueQueue.length === 0) {
+                    this.issueQueues.delete(issueNumber);
+                }
+                this.spawnSession(next);
+                return;
+            }
+            // Then drain global queue
+            this.drainGlobalQueue();
+        });
+    }
+    killSession(issueNumber) {
+        const session = this.active.get(issueNumber);
+        if (session) {
+            session.process.kill();
+            // Clean up temp MCP config (belt-and-suspenders — close handler also cleans up)
+            const configPath = path.join(os.tmpdir(), `sentinel-mcp-${issueNumber}.json`);
+            try {
+                fs.unlinkSync(configPath);
+            }
+            catch {
+                // best-effort
+            }
+            this.active.delete(issueNumber);
+            this.opts.log(`Killed session for issue #${issueNumber}`);
+        }
+        // Clear per-issue queue
+        this.issueQueues.delete(issueNumber);
+        // Drain global queue since a slot opened
+        this.drainGlobalQueue();
+    }
+    drainGlobalQueue() {
+        while (this.canSpawn() && this.globalQueue.length > 0) {
+            const next = this.globalQueue.shift();
+            this.spawnSession(next);
+        }
+    }
+    postErrorComment(issueNumber, repo) {
+        try {
+            const proc = spawn("gh", [
+                "issue",
+                "comment",
+                String(issueNumber),
+                "--repo",
+                repo,
+                "--body",
+                `Sentinel encountered an error while processing this issue. A maintainer may need to investigate.`,
+            ], {
+                env: {
+                    ...process.env,
+                    GITHUB_TOKEN: this.opts.githubToken,
+                },
+            });
+            proc.on("error", () => {
+                // best-effort, ignore
+            });
+        }
+        catch {
+            // best-effort, ignore
+        }
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,58 @@
+export interface IssueEvent {
+    type: "issue_opened" | "issue_comment" | "issue_closed";
+    repo: string;
+    issue: {
+        number: number;
+        title: string;
+        body: string;
+        author: string;
+        labels: string[];
+        url: string;
+    };
+    comment?: {
+        body: string;
+        author: string;
+        url: string;
+    };
+    timestamp: string;
+}
+export interface PrMergedEvent {
+    type: "pr_merged";
+    repo: string;
+    pr_number: number;
+    branch: string;
+    issue_number: number;
+    timestamp: string;
+}
+export type SentinelEvent = IssueEvent | PrMergedEvent;
+export type ServerMessage = {
+    type: "event";
+    id: string;
+    payload: SentinelEvent;
+    notification?: {
+        content: string;
+        meta: Record<string, string>;
+    };
+} | {
+    type: "ping";
+} | {
+    type: "displaced";
+    reason: string;
+} | {
+    type: "limit_reached";
+    message: string;
+};
+export type ClientMessage = {
+    type: "auth";
+    token: string;
+    repo?: string;
+} | {
+    type: "ack";
+    id: string;
+} | {
+    type: "pong";
+} | {
+    type: "session_update";
+    issue: number;
+    session_id: string;
+};

package/dist/types.js

@@ -0,0 +1,2 @@
+// Mirror the server types — keep in sync with sentinel-worker/src/types.ts
+export {};

package/dist/ws-client.d.ts

@@ -0,0 +1,43 @@
+import type { ClientMessage, ServerMessage } from "./types.js";
+/**
+ * Decode the installation ID from a JWT token.
+ * Extracts the `sub` claim from the JWT payload without verifying the signature.
+ */
+export declare function decodeInstallationId(jwt: string): string;
+/**
+ * Decode the user ID from a JWT token.
+ * Extracts the `uid` claim from the JWT payload without verifying the signature.
+ */
+export declare function decodeUserId(jwt: string): string;
+/**
+ * Parse a raw JSON string into a typed ServerMessage.
+ */
+export declare function parseServerMessage(raw: string): ServerMessage;
+export interface WsClientOptions {
+    token: string;
+    relayUrl: string;
+    repo?: string;
+    onEvent: (id: string, payload: any, notification?: {
+        content: string;
+        meta: Record<string, string>;
+    }) => void;
+    onDisplaced: (reason: string) => void;
+    onLimitReached?: (message: string) => void;
+    log: (msg: string) => void;
+}
+export declare class WsClient {
+    private ws;
+    private reconnectDelay;
+    private maxReconnectDelay;
+    private shouldReconnect;
+    private userId;
+    private opts;
+    constructor(opts: WsClientOptions);
+    connect(): void;
+    send(msg: ClientMessage): void;
+    ack(eventId: string): void;
+    updateSession(issue: number, sessionId: string): void;
+    isConnected(): boolean;
+    disconnect(): void;
+    private scheduleReconnect;
+}

package/dist/ws-client.js

@@ -0,0 +1,152 @@
+import WebSocket from "ws";
+/**
+ * Decode the installation ID from a JWT token.
+ * Extracts the `sub` claim from the JWT payload without verifying the signature.
+ */
+export function decodeInstallationId(jwt) {
+    const parts = jwt.split(".");
+    if (parts.length !== 3) {
+        throw new Error(`Invalid JWT format: expected 3 parts separated by '.', got ${parts.length}`);
+    }
+    const payloadPart = parts[1];
+    let parsed;
+    try {
+        const decoded = Buffer.from(payloadPart, "base64").toString("utf-8");
+        parsed = JSON.parse(decoded);
+    }
+    catch {
+        throw new Error("Invalid JWT: failed to decode or parse payload");
+    }
+    if (typeof parsed !== "object" ||
+        parsed === null ||
+        !("sub" in parsed) ||
+        typeof parsed.sub !== "string") {
+        throw new Error("Invalid JWT: missing or invalid 'sub' claim");
+    }
+    return parsed.sub;
+}
+/**
+ * Decode the user ID from a JWT token.
+ * Extracts the `uid` claim from the JWT payload without verifying the signature.
+ */
+export function decodeUserId(jwt) {
+    const parts = jwt.split(".");
+    if (parts.length !== 3) {
+        throw new Error(`Invalid JWT format: expected 3 parts separated by '.', got ${parts.length}`);
+    }
+    const payloadPart = parts[1];
+    let parsed;
+    try {
+        const decoded = Buffer.from(payloadPart, "base64").toString("utf-8");
+        parsed = JSON.parse(decoded);
+    }
+    catch {
+        throw new Error("Invalid JWT: failed to decode or parse payload");
+    }
+    if (typeof parsed !== "object" ||
+        parsed === null ||
+        !("uid" in parsed) ||
+        typeof parsed.uid !== "string") {
+        throw new Error("Invalid JWT: missing or invalid 'uid' claim");
+    }
+    return parsed.uid;
+}
+/**
+ * Parse a raw JSON string into a typed ServerMessage.
+ */
+export function parseServerMessage(raw) {
+    return JSON.parse(raw);
+}
+export class WsClient {
+    ws = null;
+    reconnectDelay = 1000;
+    maxReconnectDelay = 60000;
+    shouldReconnect = true;
+    userId;
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+        this.userId = decodeUserId(opts.token);
+    }
+    connect() {
+        const url = `${this.opts.relayUrl}/api/connect/${this.userId}`;
+        this.opts.log(`Connecting to ${url}`);
+        const ws = new WebSocket(url);
+        this.ws = ws;
+        ws.on("open", () => {
+            this.opts.log("WebSocket connected");
+            this.reconnectDelay = 1000;
+            this.send({ type: "auth", token: this.opts.token, repo: this.opts.repo });
+        });
+        ws.on("message", (data) => {
+            const raw = data.toString();
+            let msg;
+            try {
+                msg = parseServerMessage(raw);
+            }
+            catch {
+                this.opts.log(`Failed to parse server message: ${raw}`);
+                return;
+            }
+            if (msg.type === "event") {
+                this.opts.onEvent(msg.id, msg.payload, msg.notification);
+            }
+            else if (msg.type === "ping") {
+                this.send({ type: "pong" });
+            }
+            else if (msg.type === "displaced") {
+                this.opts.log(`Displaced: ${msg.reason}`);
+                this.shouldReconnect = false;
+                this.opts.onDisplaced(msg.reason);
+            }
+            else if (msg.type === "limit_reached") {
+                this.opts.onLimitReached?.(msg.message);
+            }
+        });
+        ws.on("close", (code, reason) => {
+            this.ws = null;
+            if (code === 4001) {
+                this.opts.log(`Connection closed with displacement code 4001: ${reason.toString()}`);
+                this.shouldReconnect = false;
+                this.opts.onDisplaced(reason.toString() || "Displaced by server (code 4001)");
+                return;
+            }
+            this.opts.log(`Connection closed (code ${code}). shouldReconnect=${this.shouldReconnect}`);
+            if (this.shouldReconnect) {
+                this.scheduleReconnect();
+            }
+        });
+        ws.on("error", (err) => {
+            this.opts.log(`WebSocket error: ${err.message}`);
+        });
+    }
+    send(msg) {
+        if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+            this.ws.send(JSON.stringify(msg));
+        }
+    }
+    ack(eventId) {
+        this.send({ type: "ack", id: eventId });
+    }
+    updateSession(issue, sessionId) {
+        this.send({ type: "session_update", issue, session_id: sessionId });
+    }
+    isConnected() {
+        return this.ws !== null && this.ws.readyState === WebSocket.OPEN;
+    }
+    disconnect() {
+        this.shouldReconnect = false;
+        if (this.ws) {
+            this.ws.close();
+        }
+    }
+    scheduleReconnect() {
+        this.opts.log(`Reconnecting in ${this.reconnectDelay}ms...`);
+        setTimeout(() => {
+            if (this.shouldReconnect) {
+                this.connect();
+            }
+        }, this.reconnectDelay);
+        this.reconnectDelay = Math.min(this.reconnectDelay * 2, this.maxReconnectDelay);
+    }
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "sentinel-mcp",
+  "version": "0.1.0",
+  "description": "Sentinel MCP server — connects GitHub issues to Claude Code sessions",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "sentinel-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": ["mcp", "sentinel", "claude", "github", "automation"],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "ws": "^8.18.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.0",
+    "@types/ws": "^8.5.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.1.0"
+  }
+}