ralph-hero-mcp-server 2.5.130 → 2.5.140

package/dist/github-client.js

@@ -6,9 +6,33 @@
  * rateLimit fragment for continuous tracking.
  */
 import { graphql } from "@octokit/graphql";
+import { trace, SpanStatusCode } from "@opentelemetry/api";
 import { RateLimiter } from "./lib/rate-limiter.js";
 import { SessionCache } from "./lib/cache.js";
 import { extractOperationName, sanitize } from "./lib/debug-logger.js";
+/**
+ * Classify a GraphQL error into one of: "rate_limit" | "network" | "graphql".
+ *
+ * - `rate_limit` — HTTP 403 with a `retry-after` header (GitHub's secondary
+ *   rate limit signal). Plain 403s without retry-after fall through to
+ *   `graphql` since they're more commonly permission errors.
+ * - `network` — no `status` field on the error (fetch-level failure, DNS,
+ *   socket reset, etc.)
+ * - `graphql` — everything else (GraphQL validation errors, 4xx, 5xx).
+ */
+function classifyGraphQLError(error) {
+    if (!error || typeof error !== "object") {
+        return "graphql";
+    }
+    const e = error;
+    if (typeof e.status !== "number") {
+        return "network";
+    }
+    if (e.status === 403 && e.headers?.["retry-after"]) {
+        return "rate_limit";
+    }
+    return "graphql";
+}
 /**
  * The rateLimit fragment to include in every query for proactive tracking.
  */
@@ -44,6 +68,11 @@ export function createGitHubClient(clientConfig, debugLogger) {
     const cache = new SessionCache();
     /**
      * Execute a raw GraphQL request and handle rate limit tracking.
+     *
+     * Wraps the request in a `ralph_hero.graphql` OpenTelemetry span when a
+     * tracer is available. When `RALPH_DEBUG` is unset and the SDK has not been
+     * initialized, `@opentelemetry/api` returns a no-op tracer/span — calls are
+     * essentially free.
      */
     async function executeGraphQL(queryString, variables, graphqlFn = graphqlWithAuth) {
         await rateLimiter.checkBeforeRequest();
@@ -62,53 +91,88 @@ export function createGitHubClient(clientConfig, debugLogger) {
                         fullQuery.slice(insertPos);
             }
         }
-        const t0 = Date.now();
-        try {
-            const response = await graphqlFn(fullQuery, variables || {});
-            // Update rate limit tracker from response
-            if (response && typeof response === "object" && "rateLimit" in response) {
-                const rl = response.rateLimit;
-                if (rl) {
-                    rateLimiter.update(rl);
+        const tracer = trace.getTracer("ralph-hero");
+        const operation = extractOperationName(fullQuery);
+        return tracer.startActiveSpan("ralph_hero.graphql", async (span) => {
+            if (operation) {
+                span.setAttribute("ralph_hero.operation", operation);
+            }
+            const t0 = Date.now();
+            try {
+                const response = await graphqlFn(fullQuery, variables || {});
+                // Update rate limit tracker from response
+                if (response && typeof response === "object" && "rateLimit" in response) {
+                    const rl = response.rateLimit;
+                    if (rl) {
+                        rateLimiter.update(rl);
+                        if (typeof rl.remaining === "number") {
+                            span.setAttribute("ralph_hero.rate_limit.remaining", rl.remaining);
+                        }
+                        if (typeof rl.cost === "number") {
+                            span.setAttribute("ralph_hero.rate_limit.cost", rl.cost);
+                        }
+                    }
                 }
+                debugLogger?.logGraphQL({
+                    operation,
+                    variables: sanitize(variables),
+                    durationMs: Date.now() - t0,
+                    status: 200,
+                    rateLimitRemaining: response
+                        .rateLimit?.remaining,
+                    rateLimitCost: response.rateLimit
+                        ?.cost,
+                });
+                return response;
             }
-            debugLogger?.logGraphQL({
-                operation: extractOperationName(fullQuery),
-                variables: sanitize(variables),
-                durationMs: Date.now() - t0,
-                status: 200,
-                rateLimitRemaining: response.rateLimit?.remaining,
-                rateLimitCost: response.rateLimit?.cost,
-            });
-            return response;
-        }
-        catch (error) {
-            debugLogger?.logGraphQL({
-                operation: extractOperationName(fullQuery),
-                variables: sanitize(variables),
-                durationMs: Date.now() - t0,
-                status: error && typeof error === "object" && "status" in error
-                    ? error.status
-                    : 500,
-                error: error instanceof Error ? error.message : String(error),
-            });
-            // Handle rate limit errors (403)
-            if (error &&
-                typeof error === "object" &&
-                "status" in error &&
-                error.status === 403) {
-                const retryAfter = error && typeof error === "object" && "headers" in error
+            catch (error) {
+                // Detect rate-limit retry-able case FIRST. On the retry path we
+                // intentionally do NOT mark this span ERROR (or log a 500-shaped
+                // entry) — the retry may succeed and we don't want Langfuse to
+                // show a permanently-failed parent for a request that eventually
+                // returned 200. Only the non-retry path mutates span status.
+                const is403 = error &&
+                    typeof error === "object" &&
+                    "status" in error &&
+                    error.status === 403;
+                const retryAfter = is403 && error && typeof error === "object" && "headers" in error
                     ? error.headers?.["retry-after"]
                     : undefined;
                 if (retryAfter) {
                     const waitMs = parseInt(retryAfter, 10) * 1000;
                     console.error(`[github-client] Rate limited. Waiting ${retryAfter}s before retry.`);
                     await new Promise((resolve) => setTimeout(resolve, waitMs));
-                    return executeGraphQL(queryString, variables, graphqlFn);
+                    // `await` is critical: in an async fn, `finally { span.end() }`
+                    // runs as soon as the return expression evaluates. Without
+                    // `await`, the inner Promise would still be pending while
+                    // `span.end()` fires, exporting a half-finished outer span.
+                    return await executeGraphQL(queryString, variables, graphqlFn);
                 }
+                // Non-retry error path: mark span ERROR, log, rethrow.
+                const errorType = classifyGraphQLError(error);
+                span.setAttribute("ralph_hero.error_type", errorType);
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+                if (error instanceof Error) {
+                    span.recordException(error);
+                }
+                debugLogger?.logGraphQL({
+                    operation,
+                    variables: sanitize(variables),
+                    durationMs: Date.now() - t0,
+                    status: error && typeof error === "object" && "status" in error
+                        ? error.status
+                        : 500,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                throw error;
             }
-            throw error;
-        }
+            finally {
+                span.end();
+            }
+        });
     }
     return {
         config: clientConfig,

package/dist/index.js

@@ -14,6 +14,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { createGitHubClient } from "./github-client.js";
 import { FieldOptionCache } from "./lib/cache.js";
 import { createDebugLogger, wrapServerToolWithLogging } from "./lib/debug-logger.js";
+import { initTelemetry } from "./lib/telemetry.js";
 import { toolSuccess, resolveProjectOwner } from "./types.js";
 import { resolveRepoFromProject } from "./lib/helpers.js";
 import { detectOrphanRepoIssues } from "./lib/health.js";
@@ -360,6 +361,21 @@ function registerCoreTools(server, client) {
  */
 async function main() {
     console.error("[ralph-hero] Starting MCP server...");
+    // OTel SDK init MUST happen before initGitHubClient so the first GraphQL
+    // call from the client (repo inference) is captured as a span. initTelemetry
+    // returns null when RALPH_DEBUG !== "true" — no SDK objects allocated and
+    // no exporter threads in that path.
+    const sdk = (await initTelemetry());
+    if (sdk) {
+        console.error("[ralph-hero] OTel telemetry enabled");
+        // Best-effort flush on graceful shutdown. Errors swallowed because by the
+        // time SIGTERM fires we're already on the way out — partial trace loss is
+        // acceptable. SIGINT is not wired because Claude Code's stdio transport
+        // already cleans up on EOF.
+        process.on("SIGTERM", () => {
+            void sdk.shutdown().catch(() => undefined);
+        });
+    }
     const debugLogger = createDebugLogger();
     if (debugLogger) {
         console.error("[ralph-hero] Debug logging enabled (RALPH_DEBUG=true)");

package/dist/lib/error-signature.js

@@ -0,0 +1,194 @@
+/**
+ * Error-signature normalization and grouping for Langfuse OTel spans.
+ *
+ * Used by `ralph_hero__collate_debug` to collapse noisy, near-identical
+ * error spans into a small set of "signatures." Each signature is hashed to
+ * an 8-char ID that survives across runs, so Phase 3b's GitHub dedup can
+ * match an incoming group to an existing issue body by the hash marker.
+ *
+ * The normalization rules deliberately strip *dynamic* details (issue
+ * numbers, timestamps, UUIDs, hashes, quoted paths/names) while preserving
+ * the *structural* shape of the message. Two errors that differ only in
+ * which issue number triggered them collapse to the same signature.
+ */
+import { createHash } from "node:crypto";
+// ---------------------------------------------------------------------------
+// Normalization
+// ---------------------------------------------------------------------------
+const ISO_TIMESTAMP_RE = /\b\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})?\b/g;
+const UUID_RE = /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/gi;
+const HEX_HASH_RE = /\b[0-9a-f]{8,}\b/gi;
+const ISSUE_NUMBER_RE = /#\d+/g;
+// Match runs of digits anywhere — without word boundaries so embedded
+// numbers like "60s" or "v2" collapse too. ISSUE_NUMBER_RE runs first so
+// "#42" becomes "#N" before this fires.
+const BARE_NUMBER_RE = /\d+/g;
+// Match double-quoted or single-quoted strings (non-greedy).
+const QUOTED_STRING_RE = /"[^"\n]*"|'[^'\n]*'/g;
+/**
+ * Normalize an error message into a comparable signature fragment.
+ *
+ * Order of replacements matters:
+ *   1. Quoted strings first (so a quoted ISO timestamp becomes `<STR>` not
+ *      `<TS>`).
+ *   2. ISO timestamps before UUIDs (timestamps can contain colons / dashes).
+ *   3. UUIDs before generic hex hashes (UUID format is stricter).
+ *   4. Issue numbers (`#NNN`) before bare numbers.
+ *   5. Bare numbers last.
+ *   6. Whitespace collapsed and result truncated to 200 chars.
+ */
+export function normalizeErrorMessage(msg) {
+    if (!msg)
+        return "";
+    let out = msg;
+    out = out.replace(QUOTED_STRING_RE, "<STR>");
+    out = out.replace(ISO_TIMESTAMP_RE, "<TS>");
+    out = out.replace(UUID_RE, "<ID>");
+    out = out.replace(HEX_HASH_RE, "<HASH>");
+    out = out.replace(ISSUE_NUMBER_RE, "#N");
+    out = out.replace(BARE_NUMBER_RE, "<N>");
+    out = out.replace(/\s+/g, " ").trim();
+    return out.slice(0, 200);
+}
+/**
+ * Build the signature key (pre-hash). Format:
+ *   `${spanName}:${errorType}:${normalizedMessage}`
+ */
+export function buildSignatureKey(spanName, errorType, normalizedMsg) {
+    return `${spanName}:${errorType}:${normalizedMsg}`;
+}
+/**
+ * SHA256 hash truncated to 8 hex chars. Stable across runs, suitable for
+ * dedup body markers like `**Hash**: \`a1b2c3d4\``.
+ */
+export function hashSignature(key) {
+    return createHash("sha256").update(key).digest("hex").slice(0, 8);
+}
+// ---------------------------------------------------------------------------
+// Span helpers
+// ---------------------------------------------------------------------------
+/**
+ * Extract the `ralph_hero.error_type` attribute from a span's metadata, with
+ * fallback to a hoisted `errorType` field. Returns `"unknown"` if neither is
+ * present.
+ */
+export function getErrorType(span) {
+    if (span.errorType)
+        return span.errorType;
+    const meta = span.metadata ?? {};
+    const fromMeta = meta["ralph_hero.error_type"] ??
+        meta.error_type ??
+        meta.errorType;
+    if (typeof fromMeta === "string" && fromMeta.length > 0)
+        return fromMeta;
+    return "unknown";
+}
+/**
+ * Extract the error message from a span. Prefers `message` (Langfuse
+ * `statusMessage`), then `metadata.exception.message`, then `metadata.error`.
+ */
+export function getErrorMessage(span) {
+    if (span.message)
+        return span.message;
+    const meta = span.metadata ?? {};
+    const exception = meta.exception;
+    if (exception &&
+        typeof exception === "object" &&
+        "message" in exception &&
+        typeof exception.message === "string") {
+        return exception.message;
+    }
+    if (typeof meta.error === "string")
+        return meta.error;
+    if (typeof meta.message === "string")
+        return meta.message;
+    return "";
+}
+/**
+ * Convert a `LangfuseObservation` to a `SignatureSpan`. Hoists the
+ * `ralph_hero.error_type` attribute up to the top level.
+ */
+export function observationToSpan(obs) {
+    const meta = obs.metadata ?? {};
+    const errorType = typeof meta["ralph_hero.error_type"] === "string"
+        ? meta["ralph_hero.error_type"]
+        : undefined;
+    return {
+        name: obs.name,
+        traceId: obs.traceId,
+        startTime: obs.startTime,
+        endTime: obs.endTime,
+        metadata: meta,
+        errorType,
+        message: obs.statusMessage,
+        level: obs.level,
+    };
+}
+// ---------------------------------------------------------------------------
+// Grouping
+// ---------------------------------------------------------------------------
+function buildTraceUrl(langfuseHost, projectId, traceId) {
+    const host = (langfuseHost ?? "http://localhost:3100").replace(/\/+$/, "");
+    const project = projectId ?? "<defaultProjectId>";
+    return `${host}/project/${project}/traces/${traceId}`;
+}
+/**
+ * Group spans by signature. Returns groups sorted by `count` descending.
+ *
+ * Spans below `minOccurrences` (default 3) are filtered out. Each group's
+ * `sampleSpans` contains up to 3 representative spans, most-recent first.
+ */
+export function groupSpansBySignature(spans, opts = {}) {
+    const minOccurrences = opts.minOccurrences ?? 3;
+    const buckets = new Map();
+    for (const span of spans) {
+        const errorType = getErrorType(span);
+        const normalized = normalizeErrorMessage(getErrorMessage(span));
+        const signature = buildSignatureKey(span.name, errorType, normalized);
+        const hash = hashSignature(signature);
+        const existing = buckets.get(hash);
+        if (existing) {
+            existing.count += 1;
+            if (span.startTime > existing.lastSeen) {
+                existing.lastSeen = span.startTime;
+                existing.latestTraceId = span.traceId;
+            }
+            if (span.startTime < existing.firstSeen) {
+                existing.firstSeen = span.startTime;
+            }
+            existing.spans.push(span);
+        }
+        else {
+            buckets.set(hash, {
+                signature,
+                hash,
+                count: 1,
+                firstSeen: span.startTime,
+                lastSeen: span.startTime,
+                latestTraceId: span.traceId,
+                spans: [span],
+            });
+        }
+    }
+    const groups = [];
+    for (const bucket of buckets.values()) {
+        if (bucket.count < minOccurrences)
+            continue;
+        // Sort sample spans by startTime desc, keep up to 3.
+        const sampleSpans = [...bucket.spans]
+            .sort((a, b) => (b.startTime > a.startTime ? 1 : -1))
+            .slice(0, 3);
+        groups.push({
+            signature: bucket.signature,
+            hash: bucket.hash,
+            count: bucket.count,
+            firstSeen: bucket.firstSeen,
+            lastSeen: bucket.lastSeen,
+            exampleTraceUrl: buildTraceUrl(opts.langfuseHost, opts.projectId, bucket.latestTraceId),
+            sampleSpans,
+        });
+    }
+    groups.sort((a, b) => b.count - a.count);
+    return groups;
+}
+//# sourceMappingURL=error-signature.js.map

package/dist/lib/langfuse-client.js

@@ -0,0 +1,95 @@
+/**
+ * Minimal Langfuse HTTP client for querying traces and observations.
+ *
+ * Used by `ralph_hero__collate_debug` to fetch error spans emitted by the
+ * MCP server's OTel pipeline (see `telemetry.ts`). Authenticates via HTTP
+ * basic auth with `LANGFUSE_PUBLIC_KEY` and `LANGFUSE_SECRET_KEY`.
+ *
+ * No SDK dependency — uses Node's native `fetch` (Node 20+).
+ *
+ * Reference: https://langfuse.com/docs/api
+ */
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+const DEFAULT_HOST = "http://localhost:3100";
+function buildAuthHeader(publicKey, secretKey) {
+    const credentials = `${publicKey}:${secretKey}`;
+    // Node 20+ provides global Buffer
+    const encoded = Buffer.from(credentials, "utf-8").toString("base64");
+    return `Basic ${encoded}`;
+}
+function appendQueryParams(url, params) {
+    if (!params)
+        return;
+    for (const [key, value] of Object.entries(params)) {
+        if (value === undefined || value === null)
+            continue;
+        url.searchParams.set(key, String(value));
+    }
+}
+/**
+ * Create a Langfuse HTTP client.
+ *
+ * Throws on construction if `publicKey` or `secretKey` are missing (in args
+ * and in env), because every endpoint requires authentication.
+ */
+export function createLangfuseClient(options = {}) {
+    const host = (options.host ?? process.env.LANGFUSE_HOST ?? DEFAULT_HOST)
+        .replace(/\/+$/, "");
+    const publicKey = options.publicKey ?? process.env.LANGFUSE_PUBLIC_KEY;
+    const secretKey = options.secretKey ?? process.env.LANGFUSE_SECRET_KEY;
+    const fetchImpl = options.fetchImpl ?? fetch;
+    if (!publicKey || !secretKey) {
+        throw new Error("Langfuse credentials missing: set LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY (or pass via options).");
+    }
+    const authHeader = buildAuthHeader(publicKey, secretKey);
+    async function request(path, params) {
+        const url = new URL(`${host}${path}`);
+        appendQueryParams(url, params);
+        const response = await fetchImpl(url.toString(), {
+            method: "GET",
+            headers: {
+                Authorization: authHeader,
+                Accept: "application/json",
+            },
+        });
+        if (!response.ok) {
+            const bodyText = await response.text().catch(() => "");
+            throw new Error(`Langfuse request failed: ${response.status} ${response.statusText}` +
+                (bodyText ? ` — ${bodyText.slice(0, 200)}` : ""));
+        }
+        return (await response.json());
+    }
+    async function queryTraces(params = {}) {
+        return request("/api/public/traces", params);
+    }
+    async function queryObservations(params = {}) {
+        return request("/api/public/observations", params);
+    }
+    async function queryAllObservations(params = {}, maxPages = 10) {
+        const all = [];
+        const limit = params.limit ?? 100;
+        let page = params.page ?? 1;
+        for (let i = 0; i < maxPages; i++) {
+            const result = await queryObservations({ ...params, page, limit });
+            if (!result.data || result.data.length === 0)
+                break;
+            all.push(...result.data);
+            const totalPages = result.meta?.totalPages;
+            if (totalPages !== undefined && page >= totalPages)
+                break;
+            if (result.data.length < limit)
+                break;
+            page += 1;
+        }
+        return all;
+    }
+    return {
+        host,
+        queryTraces,
+        queryObservations,
+        queryAllObservations,
+    };
+}
+//# sourceMappingURL=langfuse-client.js.map

package/dist/lib/telemetry.js

@@ -0,0 +1,156 @@
+/**
+ * OpenTelemetry initialization for the ralph-hero MCP server.
+ *
+ * Lazy-initialized when `RALPH_DEBUG=true`. When the env var is unset or any
+ * value other than the literal string `"true"`, `initTelemetry()` returns
+ * `null` and no OpenTelemetry SDK objects are constructed — zero overhead.
+ *
+ * The OTLP HTTP exporter reads its endpoint from `OTEL_EXPORTER_OTLP_ENDPOINT`
+ * (standard OTel convention). Auto-instrumentation is explicitly OFF — only
+ * the explicit `ralph_hero.graphql` spans emitted from `github-client.ts`
+ * appear in the resulting trace.
+ *
+ * A custom `SpanProcessor` redacts token-shaped attribute values at span
+ * start so secrets never reach the exporter. See `redactTokenAttributes()`.
+ */
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+/**
+ * Attribute value matching `^gh[ps]_` (GitHub PAT/server-to-server token shape)
+ * and key matching `_TOKEN$` (case-insensitive) or `^authorization$` are
+ * replaced with this sentinel before the span is exported.
+ */
+const REDACTED = "[REDACTED]";
+const TOKEN_VALUE_RE = /^gh[ps]_/;
+const TOKEN_KEY_RE = /(_TOKEN$|^authorization$)/i;
+/**
+ * Pure function — exported for unit tests. Returns a shallow copy of `attrs`
+ * with any token-shaped value or key replaced by `[REDACTED]`.
+ *
+ * Keys are matched case-insensitively against `_TOKEN$` and `^authorization$`.
+ * Values are matched (when they are strings) against `^gh[ps]_`.
+ *
+ * Non-matching attributes (including non-string values like numbers and
+ * booleans) pass through unchanged.
+ */
+export function redactTokenAttributes(attrs) {
+    if (!attrs)
+        return {};
+    const out = {};
+    for (const [key, value] of Object.entries(attrs)) {
+        if (TOKEN_KEY_RE.test(key)) {
+            out[key] = REDACTED;
+            continue;
+        }
+        if (typeof value === "string" && TOKEN_VALUE_RE.test(value)) {
+            out[key] = REDACTED;
+            continue;
+        }
+        out[key] = value;
+    }
+    return out;
+}
+/**
+ * SpanProcessor that scrubs token-shaped attributes from each span.
+ *
+ * The scrub runs on `onEnd` rather than `onStart` because we need to see the
+ * full set of attributes that any caller has set on the span. Crucially, once
+ * a span has ended, `span.setAttribute()` is a documented no-op — the only
+ * way to mutate the final exported attribute set is to write directly to the
+ * `attributes` object. TypeScript types it as readonly but the runtime
+ * representation is a plain mutable object owned by the span instance.
+ *
+ * Order matters: this processor must be registered BEFORE the exporting
+ * processor (`BatchSpanProcessor` or `SimpleSpanProcessor`) so the mutation
+ * is visible by the time the export call reads `attributes`.
+ */
+export class TokenScrubbingSpanProcessor {
+    onStart(_span, _parentContext) {
+        // No-op — attributes set on an active span go through `setAttribute`,
+        // not the readable snapshot. We catch them all in `onEnd`.
+    }
+    onEnd(span) {
+        const attrs = span.attributes;
+        if (!attrs)
+            return;
+        // attrs is `Attributes` (readonly per the type) but mutable at runtime.
+        // Mutate in-place so downstream processors see the redacted values.
+        const mut = attrs;
+        for (const [key, value] of Object.entries(mut)) {
+            if (TOKEN_KEY_RE.test(key)) {
+                mut[key] = REDACTED;
+            }
+            else if (typeof value === "string" && TOKEN_VALUE_RE.test(value)) {
+                mut[key] = REDACTED;
+            }
+        }
+    }
+    async shutdown() {
+        // No-op — this processor holds no resources.
+    }
+    async forceFlush() {
+        // No-op — this processor performs no async work.
+    }
+}
+/**
+ * Read the MCP server semver from package.json next to this module.
+ *
+ * Falls back to `"unknown"` if the file is missing or unreadable so the SDK
+ * still starts up — the version is informational, not load-bearing.
+ */
+function resolveServiceVersion() {
+    try {
+        // In ESM, __dirname isn't defined; compute it from import.meta.url.
+        const here = dirname(fileURLToPath(import.meta.url));
+        // Walk up from src/lib (or dist/lib at runtime) to the package root.
+        const pkgPath = resolve(here, "..", "..", "package.json");
+        const raw = readFileSync(pkgPath, "utf8");
+        const pkg = JSON.parse(raw);
+        return pkg.version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+/**
+ * Initialize the OpenTelemetry NodeSDK when `RALPH_DEBUG=true`.
+ *
+ * - Returns `null` (zero overhead) when `process.env.RALPH_DEBUG !== "true"`.
+ * - When enabled: configures an OTLP/HTTP trace exporter, no auto-instrumentation,
+ *   a `TokenScrubbingSpanProcessor` ahead of the default batch processor, and
+ *   resource attrs `service.name = "ralph-hero"`, `service.version = <semver>`.
+ *
+ * Caller is responsible for calling `sdk.shutdown()` (e.g., on SIGTERM) to
+ * flush in-flight spans.
+ */
+export async function initTelemetry() {
+    if (process.env.RALPH_DEBUG !== "true") {
+        return null;
+    }
+    // Dynamic imports keep zero-overhead in the disabled path — when RALPH_DEBUG
+    // is unset, none of these modules are loaded into memory.
+    const { NodeSDK } = await import("@opentelemetry/sdk-node");
+    const { OTLPTraceExporter } = await import("@opentelemetry/exporter-trace-otlp-http");
+    const { Resource } = await import("@opentelemetry/resources");
+    const { SEMRESATTRS_SERVICE_NAME, SEMRESATTRS_SERVICE_VERSION, } = await import("@opentelemetry/semantic-conventions");
+    const { BatchSpanProcessor } = await import("@opentelemetry/sdk-trace-base");
+    const endpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT ??
+        "http://localhost:3100/api/public/otel/v1/traces";
+    const exporter = new OTLPTraceExporter({ url: endpoint });
+    const sdk = new NodeSDK({
+        resource: new Resource({
+            [SEMRESATTRS_SERVICE_NAME]: "ralph-hero",
+            [SEMRESATTRS_SERVICE_VERSION]: resolveServiceVersion(),
+        }),
+        spanProcessors: [
+            new TokenScrubbingSpanProcessor(),
+            new BatchSpanProcessor(exporter),
+        ],
+        // No auto-instrumentation — only explicit ralph_hero.* spans are emitted.
+        instrumentations: [],
+    });
+    sdk.start();
+    return sdk;
+}
+//# sourceMappingURL=telemetry.js.map

package/dist/lib/workflow-states.js

@@ -129,6 +129,6 @@ export const WORKFLOW_STATE_TO_STATUS = {
     "In Review": "In Progress",
     "Done": "Done",
     "Canceled": "Done",
-    "Human Needed": "Done",
+    "Human Needed": "Todo",
 };
 //# sourceMappingURL=workflow-states.js.map

package/dist/tools/debug-tools.js

@@ -1,10 +1,15 @@
 /**
  * MCP tools for debug log collation and statistics.
  *
- * Provides `ralph_hero__collate_debug` (error grouping + GitHub issue creation)
- * and `ralph_hero__debug_stats` (tool call aggregation metrics).
+ * Provides:
+ *   - `ralph_hero__collate_debug` (v2 — queries Langfuse for error spans,
+ *     groups by normalized signature, returns the grouped report; GitHub
+ *     issue creation lands in Phase 3b / GH-1100)
+ *   - `ralph_hero__debug_stats` (v1 — aggregates JSONL logs; preserved for
+ *     backward compat, not extended)
  *
- * Only registered when RALPH_DEBUG=true. Reads JSONL logs written by DebugLogger.
+ * Only registered when `RALPH_DEBUG=true`. JSONL helpers below still back
+ * `debug_stats`; the new Langfuse path is fully separate.
  */
 import { readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
@@ -13,6 +18,8 @@ import { createHash } from "node:crypto";
 import { z } from "zod";
 import { toolSuccess, toolError } from "../types.js";
 import { zBoolish } from "../lib/zod-helpers.js";
+import { createLangfuseClient, } from "../lib/langfuse-client.js";
+import { groupSpansBySignature, observationToSpan, } from "../lib/error-signature.js";
 // ---------------------------------------------------------------------------
 // JSONL Parsing
 // ---------------------------------------------------------------------------
@@ -174,123 +181,97 @@ export function aggregateStats(events, groupBy) {
         groups,
     };
 }
-// ---------------------------------------------------------------------------
-// Register Debug Tools
-// ---------------------------------------------------------------------------
+let langfuseClientFactory = () => createLangfuseClient();
+/**
+ * Override the Langfuse client factory. Returns a disposer that restores the
+ * previous factory (used by tests).
+ */
+export function setLangfuseClientFactory(factory) {
+    const prev = langfuseClientFactory;
+    langfuseClientFactory = factory;
+    return () => {
+        langfuseClientFactory = prev;
+    };
+}
 export function registerDebugTools(server, client) {
     const logDir = join(homedir(), ".ralph-hero", "logs");
+    // `client` is referenced by `debug_stats` (legacy) and reserved for Phase 3b
+    // (GH-1100), which will use it for GitHub dedup + issue creation.
+    void client;
     // -------------------------------------------------------------------------
-    // ralph_hero__collate_debug
+    // ralph_hero__collate_debug (v2 — Langfuse path)
     // -------------------------------------------------------------------------
-    server.tool("ralph_hero__collate_debug", "Collate debug log errors into GitHub issues. Reads JSONL logs, groups errors by normalized signature, deduplicates against existing `debug-auto` labeled issues, and creates/updates issues. Returns: summary of issues created, updated, and total occurrences.", {
+    server.tool("ralph_hero__collate_debug", "Query Langfuse for error spans in a time window, normalize messages, and group by signature. Phase 3a returns the grouped report only (dryRun forced true); Phase 3b (GH-1100) adds GitHub issue dedup + create/comment. Returns: { since, errorGroups, totalOccurrences, dryRun, groups[] }.", {
         since: z
             .string()
             .optional()
-            .describe("ISO date string. Only process events after this time (default: 24h ago)"),
+            .describe("ISO date string. Only spans whose startTime >= this value are considered (default: 24h ago)."),
         dryRun: zBoolish()
             .optional()
-            .default(false)
-            .describe("If true, report what would be created/updated without making changes"),
+            .default(true)
+            .describe("Phase 3a only honors dryRun=true; passing false returns a stub error until Phase 3b lands."),
+        minOccurrences: z
+            .number()
+            .int()
+            .min(1)
+            .optional()
+            .default(3)
+            .describe("Filter out signatures with fewer occurrences (default: 3)."),
         projectNumber: z
             .number()
             .optional()
-            .describe("Project number override (defaults to configured project)"),
+            .describe("Project number override (reserved for Phase 3b)."),
     }, async (args) => {
         try {
+            const dryRun = args.dryRun ?? true;
+            if (!dryRun) {
+                return toolError("dryRun=false requires GH-1100 (Phase 3b) — not yet implemented");
+            }
+            const minOccurrences = args.minOccurrences ?? 3;
             const sinceDate = args.since
                 ? new Date(args.since)
                 : new Date(Date.now() - 24 * 60 * 60 * 1000);
-            const { events, sessionsAnalyzed } = await readLogEvents(logDir, sinceDate);
-            const errorGroups = groupErrors(events);
-            if (errorGroups.length === 0) {
-                return toolSuccess({
-                    message: "No errors found in the specified time window.",
-                    sessionsAnalyzed,
-                    since: sinceDate.toISOString(),
-                });
+            if (Number.isNaN(sinceDate.getTime())) {
+                return toolError(`Invalid 'since' value: ${args.since}`);
             }
-            let issuesCreated = 0;
-            let issuesUpdated = 0;
-            let totalOccurrences = 0;
-            const owner = client.config.owner;
-            const repo = client.config.repo;
-            for (const group of errorGroups) {
-                totalOccurrences += group.count;
-                if (args.dryRun)
-                    continue;
-                if (!owner || !repo) {
-                    return toolError("RALPH_GH_OWNER and RALPH_GH_REPO must be set for issue creation");
-                }
-                // Search for existing issue with this hash
-                const searchQuery = `repo:${owner}/${repo} is:issue is:open label:debug-auto "${group.hash}" in:body`;
-                let existingIssueNumber;
-                try {
-                    const searchResult = await client.query(`query SearchDebugIssues($q: String!) {
-                search(query: $q, type: ISSUE, first: 1) {
-                  nodes {
-                    ... on Issue { number }
-                  }
-                }
-              }`, { q: searchQuery });
-                    existingIssueNumber = searchResult.search.nodes[0]?.number;
-                }
-                catch {
-                    // Search failed, treat as no existing issue
-                }
-                if (existingIssueNumber) {
-                    // Add occurrence comment
-                    await client.mutate(`mutation AddComment($subjectId: ID!, $body: String!) {
-                addComment(input: { subjectId: $subjectId, body: $body }) {
-                  commentEdge { node { id } }
-                }
-              }`, {
-                        subjectId: `issue:${existingIssueNumber}`,
-                        body: `## Occurrence Report\n\n- Count: ${group.count}\n- Period: ${group.firstSeen} — ${group.lastSeen}\n- Signature: \`${group.signature}\``,
-                    }).catch(() => {
-                        // Best-effort comment
-                    });
-                    issuesUpdated++;
-                }
-                else {
-                    // Create new issue
-                    try {
-                        await client.mutate(`mutation CreateIssue($repoId: ID!, $title: String!, $body: String!) {
-                  createIssue(input: { repositoryId: $repoId, title: $title, body: $body }) {
-                    issue { number }
-                  }
-                }`, {
-                            repoId: `placeholder`, // Would need actual repo ID
-                            title: `[debug-auto] ${getEventName(group.sample)} ${getErrorType(group.sample)}`,
-                            body: `## Debug Auto-Report\n\n**Hash**: \`${group.hash}\`\n**Signature**: \`${group.signature}\`\n**Occurrences**: ${group.count}\n**First seen**: ${group.firstSeen}\n**Last seen**: ${group.lastSeen}\n\n### Sample Error\n\n\`\`\`json\n${JSON.stringify(group.sample, null, 2)}\n\`\`\`\n\n---\n_Auto-generated by ralph_hero__collate_debug_`,
-                        }).catch(() => {
-                            // Best-effort issue creation
-                        });
-                        issuesCreated++;
-                    }
-                    catch {
-                        // Skip failed creations
-                    }
-                }
+            let langfuse;
+            try {
+                langfuse = langfuseClientFactory();
             }
+            catch (error) {
+                return toolError(`Langfuse client unavailable: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            const fromStartTime = sinceDate.toISOString();
+            const observations = await langfuse.queryAllObservations({
+                type: "SPAN",
+                level: "ERROR",
+                fromStartTime,
+                limit: 100,
+            });
+            const spans = observations.map(observationToSpan);
+            const groups = groupSpansBySignature(spans, {
+                minOccurrences,
+                langfuseHost: langfuse.host,
+            });
+            const totalOccurrences = groups.reduce((sum, g) => sum + g.count, 0);
             return toolSuccess({
-                since: sinceDate.toISOString(),
-                sessionsAnalyzed,
-                errorGroups: errorGroups.length,
+                since: fromStartTime,
+                errorGroups: groups.length,
                 totalOccurrences,
-                issuesCreated: args.dryRun ? 0 : issuesCreated,
-                issuesUpdated: args.dryRun ? 0 : issuesUpdated,
-                dryRun: args.dryRun,
-                groups: errorGroups.map((g) => ({
-                    hash: g.hash,
+                dryRun: true,
+                groups: groups.map((g) => ({
                     signature: g.signature,
+                    hash: g.hash,
                     count: g.count,
                     firstSeen: g.firstSeen,
                     lastSeen: g.lastSeen,
+                    exampleTraceUrl: g.exampleTraceUrl,
+                    sampleSpans: g.sampleSpans.slice(0, 3),
                 })),
             });
         }
         catch (error) {
-            return toolError(`Failed to collate debug logs: ${error instanceof Error ? error.message : String(error)}`);
+            return toolError(`Failed to collate debug spans: ${error instanceof Error ? error.message : String(error)}`);
         }
     });
     // -------------------------------------------------------------------------

package/dist/tools/issue-tools.js

@@ -25,7 +25,7 @@ export function registerIssueTools(server, client, fieldCache) {
     // -------------------------------------------------------------------------
     // ralph_hero__list_issues
     // -------------------------------------------------------------------------
-    server.tool("ralph_hero__list_issues", "List issues from a GitHub repository with optional filters. Fetches all project items (full project scan, no silent 500-cap) and applies filters client-side, so items at any board position are visible regardless of default ordering. Returns: number, title, state, workflowState, estimate, priority, iteration, labels, assignees. Use workflowState filter to find issues in a specific phase. Use iteration filter with @current/@next or sprint title. Recovery: if no results, broaden filters or check that issues exist in the project.", {
+    server.tool("ralph_hero__list_issues", "List issues from a GitHub repository with optional filters. Fetches all project items (full project scan, no silent 500-cap) and applies filters client-side, so items at any board position are visible regardless of default ordering. By default returns issues in any state (both OPEN and CLOSED) so visibility matches the dashboard family (pipeline_dashboard, next_actions, project_hygiene); pass the `state` parameter (\"OPEN\" or \"CLOSED\") to narrow. Returns: number, title, state, workflowState, estimate, priority, iteration, labels, assignees. Use workflowState filter to find issues in a specific phase. Use iteration filter with @current/@next or sprint title. Recovery: if no results, broaden filters or check that issues exist in the project.", {
         owner: z
             .string()
             .optional()
@@ -68,8 +68,8 @@ export function registerIssueTools(server, client, fieldCache) {
         state: z
             .enum(["OPEN", "CLOSED"])
             .optional()
-            .default("OPEN")
-            .describe("Issue state filter (default: OPEN)"),
+            .describe("Issue state filter. When omitted, returns issues in any state " +
+            "(matches dashboard-family behavior). Pass 'OPEN' or 'CLOSED' to narrow."),
         reason: z
             .enum(["completed", "not_planned", "reopened"])
             .optional()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-hero-mcp-server",
-  "version": "2.5.130",
+  "version": "2.5.140",
   "description": "MCP server for GitHub Projects V2 - Ralph workflow automation",
   "type": "module",
   "main": "dist/index.js",
@@ -20,6 +20,12 @@
     "@modelcontextprotocol/sdk": "^1.26.0",
     "@octokit/graphql": "^9.0.3",
     "@octokit/plugin-paginate-graphql": "^6.0.0",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.57.0",
+    "@opentelemetry/resources": "^1.30.0",
+    "@opentelemetry/sdk-node": "^0.57.0",
+    "@opentelemetry/sdk-trace-base": "^1.30.0",
+    "@opentelemetry/semantic-conventions": "^1.28.0",
     "yaml": "^2.7.0",
     "zod": "^3.25.0"
   },