ralph-hero-mcp-server 2.5.142 → 2.5.149

package/dist/index.js

@@ -31,6 +31,7 @@ import { registerDecomposeTools } from "./tools/decompose-tools.js";
 import { registerViewTools } from "./tools/view-tools.js";
 import { registerPlanGraphTools } from "./tools/plan-graph-tools.js";
 import { registerActivityTools } from "./tools/activity-tools.js";
+import { registerDelegationTools } from "./tools/delegation-tools.js";
 import { registerTrendsTools } from "./tools/trends-tools.js";
 /**
  * Initialize the GitHub client from environment variables.
@@ -445,6 +446,8 @@ async function main() {
     registerPlanGraphTools(server, client);
     // Activity log reader (recent_activity tool — pure filesystem, no GitHub client)
     registerActivityTools(server);
+    // Delegation telemetry reader (delegation_stats tool — pure filesystem, no GitHub client)
+    registerDelegationTools(server);
     // Trends tools (capture_snapshot — JSONL persistence under ~/.ralph-hero/snapshots/)
     registerTrendsTools(server, client, fieldCache);
     // Debug tools (only when RALPH_DEBUG=true)

package/dist/lib/delegation-log.js

@@ -0,0 +1,199 @@
+/**
+ * Pure read library for the local ralph-delegate JSONL audit log.
+ *
+ * The log lives at `~/.ralph-hero/delegate.log` (overridable via
+ * `RALPH_DELEGATE_LOG_PATH`). One JSON object per line, append-only,
+ * written by `plugin/ralph-hero/scripts/ralph-delegate.sh`. This library
+ * only reads — it never writes.
+ *
+ * Schema versioning: F1 (issue #1185) does NOT emit an explicit
+ * `schemaVersion` field on each line. F5 treats lines containing the
+ * required fields `{ts, task, status, ms}` as **implicit v1**. A future
+ * issue MAY add an explicit `schemaVersion >= 2` — when that happens, the
+ * shape-check should be expanded to honor it. TODO: revisit when the
+ * producer side emits `schemaVersion`.
+ *
+ * Determinism: pure functions. Filesystem reads are the only side effect.
+ * Missing log file resolves to a zero-state result with no throw, matching
+ * the activity.ts precedent (the steady state for opt-out users).
+ */
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+// ---------------------------------------------------------------------------
+// Test hook + default path resolution
+// ---------------------------------------------------------------------------
+/**
+ * Optional override used only by tests. Production code never sets this.
+ * Mirrors `__setSnapshotRoot` in `snapshots.ts`.
+ */
+let delegateLogPathOverride = null;
+/** Test hook: override the default log path. Pass `null` to restore. */
+export function __setDelegateLogPath(path) {
+    delegateLogPathOverride = path;
+}
+/**
+ * Resolve the default log path: env var override, then `~/.ralph-hero/delegate.log`.
+ * Expands a leading `~/` (mirrors `ralph-delegate.sh:208-211`).
+ */
+export function defaultDelegationLogPath() {
+    if (delegateLogPathOverride !== null)
+        return delegateLogPathOverride;
+    const fromEnv = process.env.RALPH_DELEGATE_LOG_PATH;
+    if (fromEnv && fromEnv.length > 0) {
+        return expandHome(fromEnv);
+    }
+    return path.join(os.homedir(), ".ralph-hero", "delegate.log");
+}
+function expandHome(p) {
+    if (p.startsWith("~/")) {
+        return path.join(os.homedir(), p.slice(2));
+    }
+    return p;
+}
+// ---------------------------------------------------------------------------
+// Reader
+// ---------------------------------------------------------------------------
+/**
+ * Read the delegation audit log. Returns a zero-state result with
+ * `fileExists: false` when the file is missing — never throws on ENOENT.
+ * Lines that fail JSON.parse OR lack required fields are skipped and
+ * counted in `skippedLines`; each skip emits a `console.warn` with a
+ * truncated prefix of the offending line.
+ */
+export async function readDelegationLog(config) {
+    const logPath = config.logPath;
+    let content;
+    try {
+        content = await fs.readFile(logPath, "utf8");
+    }
+    catch (e) {
+        if (e &&
+            typeof e === "object" &&
+            "code" in e &&
+            e.code === "ENOENT") {
+            return { events: [], skippedLines: 0, fileExists: false, logPath };
+        }
+        throw e;
+    }
+    const events = [];
+    let skipped = 0;
+    for (const raw of content.split("\n")) {
+        const line = raw.trim();
+        if (line.length === 0)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            skipped++;
+            console.warn(`[delegation-log] Skipping malformed line in ${logPath}: ${line.slice(0, 80)}`);
+            continue;
+        }
+        if (!isDelegationEventShape(parsed)) {
+            skipped++;
+            console.warn(`[delegation-log] Skipping line with missing required fields in ${logPath}: ${line.slice(0, 80)}`);
+            continue;
+        }
+        events.push(parsed);
+    }
+    return { events, skippedLines: skipped, fileExists: true, logPath };
+}
+/**
+ * Implicit-v1 shape check: presence of `{ts, task, status, ms}` with
+ * correct primitive types. A future explicit `schemaVersion >= 2` may
+ * extend this gate.
+ */
+function isDelegationEventShape(v) {
+    if (!v || typeof v !== "object")
+        return false;
+    const o = v;
+    return (typeof o.ts === "string" &&
+        typeof o.task === "string" &&
+        typeof o.status === "string" &&
+        typeof o.ms === "number");
+}
+// ---------------------------------------------------------------------------
+// Aggregator
+// ---------------------------------------------------------------------------
+/**
+ * Aggregate parsed events into per-task + totals. Pure function — does
+ * no I/O. Percentiles use the nearest-rank method against successful
+ * (status=ok) calls only.
+ */
+export function aggregateDelegationStats(events) {
+    const byTask = {};
+    const okMsByTask = {};
+    let totalCalls = 0;
+    let totalFallbacks = 0;
+    let totalBytesIn = 0;
+    let totalBytesOut = 0;
+    for (const ev of events) {
+        const task = ev.task;
+        if (!byTask[task]) {
+            byTask[task] = {
+                calls: 0,
+                fallbacks: 0,
+                p50Ms: null,
+                p99Ms: null,
+                bytesIn: 0,
+                bytesOut: 0,
+                tokens: null,
+            };
+            okMsByTask[task] = [];
+        }
+        byTask[task].calls += 1;
+        totalCalls += 1;
+        if (isFallbackStatus(ev.status)) {
+            byTask[task].fallbacks += 1;
+            totalFallbacks += 1;
+        }
+        const bIn = typeof ev.bytes_in === "number" ? ev.bytes_in : 0;
+        const bOut = typeof ev.bytes_out === "number" ? ev.bytes_out : 0;
+        byTask[task].bytesIn += bIn;
+        byTask[task].bytesOut += bOut;
+        totalBytesIn += bIn;
+        totalBytesOut += bOut;
+        if (ev.status === "ok") {
+            okMsByTask[task].push(ev.ms);
+        }
+    }
+    // Compute percentiles
+    for (const task of Object.keys(byTask)) {
+        const samples = okMsByTask[task];
+        byTask[task].p50Ms = percentile(samples, 0.5);
+        byTask[task].p99Ms = percentile(samples, 0.99);
+    }
+    return {
+        totals: {
+            calls: totalCalls,
+            fallbacks: totalFallbacks,
+            bytesIn: totalBytesIn,
+            bytesOut: totalBytesOut,
+        },
+        byTask,
+    };
+}
+/**
+ * A fallback is any non-`ok`, non-`dry_run` status: timeout, unreachable,
+ * parse_error, http_*. `dry_run` is operator-driven and not a real
+ * delegation failure, so it does not count.
+ */
+function isFallbackStatus(status) {
+    return status !== "ok" && status !== "dry_run";
+}
+/**
+ * Nearest-rank percentile: `sorted[ceil(q * n) - 1]`. Returns `null`
+ * when the sample is empty.
+ */
+function percentile(samples, q) {
+    if (samples.length === 0)
+        return null;
+    const sorted = [...samples].sort((a, b) => a - b);
+    const rank = Math.ceil(q * sorted.length);
+    // Guard the edge case q=0 (would index -1)
+    const idx = Math.max(0, rank - 1);
+    return sorted[idx];
+}
+//# sourceMappingURL=delegation-log.js.map

package/dist/tools/delegation-tools.js

@@ -0,0 +1,44 @@
+/**
+ * Registers the `ralph_hero__delegation_stats` MCP tool. Pure read-only
+ * surface over the JSONL audit log written by `ralph-delegate.sh` (F1).
+ *
+ * Follows the same registration convention as `activity-tools.ts`: no
+ * GitHub client argument, defaults pulled from env var with a homedir
+ * fallback, returns `toolSuccess` on missing-file (zero-state) so callers
+ * can render a dashboard without an error path.
+ */
+import { z } from "zod";
+import { readDelegationLog, aggregateDelegationStats, defaultDelegationLogPath, } from "../lib/delegation-log.js";
+import { toolSuccess, toolError } from "../types.js";
+const TOKENS_REASON = "F1 audit-log does not capture token usage; bytes used as a proxy";
+export function registerDelegationTools(server) {
+    server.tool("ralph_hero__delegation_stats", "Read-only telemetry over the local ralph-delegate JSONL audit log. Returns per-task call counts, fallback counts (non-ok/non-dry_run), p50/p99 latency from successful calls, and bytes_in/bytes_out aggregates. Reads RALPH_DELEGATE_LOG_PATH (default ~/.ralph-hero/delegate.log). Missing log file returns a zero-state result, never errors.", {
+        logPath: z
+            .string()
+            .optional()
+            .describe("Optional override for the JSONL log path. Defaults to RALPH_DELEGATE_LOG_PATH or ~/.ralph-hero/delegate.log."),
+    }, async (params) => {
+        try {
+            const resolvedPath = params.logPath ?? defaultDelegationLogPath();
+            const read = await readDelegationLog({ logPath: resolvedPath });
+            const stats = aggregateDelegationStats(read.events);
+            return toolSuccess({
+                logPath: read.logPath,
+                fileExists: read.fileExists,
+                totals: {
+                    calls: stats.totals.calls,
+                    fallbacks: stats.totals.fallbacks,
+                    bytesIn: stats.totals.bytesIn,
+                    bytesOut: stats.totals.bytesOut,
+                    skippedLines: read.skippedLines,
+                },
+                byTask: stats.byTask,
+                tokensReason: TOKENS_REASON,
+            });
+        }
+        catch (err) {
+            return toolError(err instanceof Error ? err.message : String(err));
+        }
+    });
+}
+//# sourceMappingURL=delegation-tools.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-hero-mcp-server",
-  "version": "2.5.142",
+  "version": "2.5.149",
   "description": "MCP server for GitHub Projects V2 - Ralph workflow automation",
   "type": "module",
   "main": "dist/index.js",