ralph-hero-mcp-server 2.5.79 → 2.5.81

package/dist/index.js

@@ -28,6 +28,7 @@ import { registerDebugTools } from "./tools/debug-tools.js";
 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";
 /**
  * Initialize the GitHub client from environment variables.
  */
@@ -401,6 +402,8 @@ async function main() {
     registerViewTools(server, client, fieldCache);
     // Plan graph sync tool (sync plan dependency edges to GitHub)
     registerPlanGraphTools(server, client);
+    // Activity log reader (recent_activity tool — pure filesystem, no GitHub client)
+    registerActivityTools(server);
     // Debug tools (only when RALPH_DEBUG=true)
     if (process.env.RALPH_DEBUG === 'true') {
         registerDebugTools(server, client);

package/dist/lib/activity.js

@@ -0,0 +1,90 @@
+/**
+ * Pure read library for the local ralph-hero activity log.
+ *
+ * The log lives at `~/.ralph-hero/activity/YYYY/MM/DD.jsonl` (or a
+ * configurable root). One JSON object per line, append-only. Hooks
+ * write the file via `record-activity.sh`; this library only reads.
+ *
+ * Determinism: pure functions. Time is injected via `ActivityReadConfig.now`
+ * for tests. Filesystem reads are the only side effect.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+export function readActivity(config) {
+    if (!fs.existsSync(config.rootDir)) {
+        return { events: [], cursor_advanced_to: null, skipped_lines: 0 };
+    }
+    const sinceTs = config.since ? new Date(config.since).getTime() : 0;
+    const untilTs = config.until ? new Date(config.until).getTime() : Number.MAX_SAFE_INTEGER;
+    if (config.since && Number.isNaN(sinceTs)) {
+        throw new Error(`Invalid 'since' format: ${config.since}`);
+    }
+    if (config.until && Number.isNaN(untilTs)) {
+        throw new Error(`Invalid 'until' format: ${config.until}`);
+    }
+    const events = [];
+    let skipped = 0;
+    // Walk YYYY/MM/DD structure
+    const years = safeReadDir(config.rootDir).filter((d) => /^\d{4}$/.test(d)).sort();
+    for (const y of years) {
+        const yDir = path.join(config.rootDir, y);
+        const months = safeReadDir(yDir).filter((d) => /^\d{2}$/.test(d)).sort();
+        for (const m of months) {
+            const mDir = path.join(yDir, m);
+            const days = safeReadDir(mDir).filter((d) => /^\d{2}\.jsonl$/.test(d)).sort();
+            for (const dFile of days) {
+                const filePath = path.join(mDir, dFile);
+                const content = safeReadFile(filePath);
+                if (content === null)
+                    continue;
+                for (const line of content.split("\n")) {
+                    if (line.trim() === "")
+                        continue;
+                    let parsed;
+                    try {
+                        parsed = JSON.parse(line);
+                    }
+                    catch {
+                        skipped++;
+                        continue;
+                    }
+                    const eventTs = new Date(parsed.ts).getTime();
+                    if (Number.isNaN(eventTs)) {
+                        skipped++;
+                        continue;
+                    }
+                    if (eventTs < sinceTs || eventTs > untilTs)
+                        continue;
+                    if (config.category !== "all" && parsed.category !== config.category)
+                        continue;
+                    if (config.kinds !== null && !config.kinds.includes(parsed.kind))
+                        continue;
+                    if (config.project !== null && parsed.project !== config.project)
+                        continue;
+                    events.push(parsed);
+                }
+            }
+        }
+    }
+    events.sort((a, b) => a.ts.localeCompare(b.ts));
+    const limited = events.slice(0, config.limit);
+    const cursor = limited.length > 0 ? limited[limited.length - 1].ts : null;
+    return { events: limited, cursor_advanced_to: cursor, skipped_lines: skipped };
+}
+function safeReadDir(dir) {
+    try {
+        return fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+}
+function safeReadFile(filePath) {
+    try {
+        return fs.readFileSync(filePath, "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=activity.js.map

package/dist/tools/activity-tools.js

@@ -0,0 +1,36 @@
+import { z } from "zod";
+import * as path from "node:path";
+import * as os from "node:os";
+import { readActivity } from "../lib/activity.js";
+import { toolSuccess, toolError } from "../types.js";
+function defaultActivityRoot() {
+    return process.env.RALPH_ACTIVITY_DIR ?? path.join(os.homedir(), ".ralph-hero", "activity");
+}
+export function registerActivityTools(server) {
+    server.tool("ralph_hero__recent_activity", "Read structured events from the local ralph-hero activity log since a cursor. Used by /catch-up to synthesize 'what changed since last time' narratives. Pure read; the log is written by harness hooks.", {
+        since: z.string().nullable().default(null).describe("ISO8601 timestamp lower bound; null = all of today"),
+        until: z.string().nullable().default(null).describe("Optional ISO8601 upper bound"),
+        kinds: z.array(z.string()).nullable().default(null).describe("Filter by event kind (e.g., ['pr_opened','issue_advanced'])"),
+        category: z.enum(["work", "meta", "all"]).default("work").describe("Filter by category; default 'work' excludes meta noise"),
+        project: z.string().nullable().default(null).describe("Filter by project name"),
+        limit: z.number().int().min(1).default(100).describe("Max events to return"),
+    }, async (params) => {
+        try {
+            const result = readActivity({
+                rootDir: defaultActivityRoot(),
+                since: params.since ?? null,
+                until: params.until ?? null,
+                kinds: params.kinds ?? null,
+                category: (params.category ?? "work"),
+                project: params.project ?? null,
+                limit: params.limit ?? 100,
+                now: new Date(),
+            });
+            return toolSuccess(result);
+        }
+        catch (err) {
+            return toolError(err instanceof Error ? err.message : String(err));
+        }
+    });
+}
+//# sourceMappingURL=activity-tools.js.map

package/dist/tools/directions-tools.js

@@ -51,10 +51,12 @@ const openPRSchema = z.object({
 });
 // ---------------------------------------------------------------------------
 // Shared implementation — extracted so both `hello_directions` (deprecated)
-// and `next_actions` (current) can route through the same code path. Keep
-// file-private (no export) — alias lives in this same file.
+// and `next_actions` (current) can route through the same code path. Also
+// exported so the deprecated `pick_actionable_issue` wrapper in
+// `issue-tools.ts` can delegate without duplicating the data-fetch +
+// scoring pipeline.
 // ---------------------------------------------------------------------------
-function makeRunDirections(client, fieldCache) {
+export function makeRunDirections(client, fieldCache) {
     return async function runDirections(args) {
         try {
             const owner = args.owner || resolveProjectOwner(client.config);

package/dist/tools/issue-tools.js

@@ -10,6 +10,7 @@ import { detectGroup } from "../lib/group-detection.js";
 import { detectPipelinePosition, OVERSIZED_ESTIMATES, } from "../lib/pipeline-detection.js";
 import { isValidState, isParentGateState, VALID_STATES, LOCK_STATES, TERMINAL_STATES, WORKFLOW_STATE_TO_STATUS, } from "../lib/workflow-states.js";
 import { buildBatchMutationQuery } from "./batch-tools.js";
+import { makeRunDirections } from "./directions-tools.js";
 import { resolveState } from "../lib/state-resolution.js";
 import { parseDateMath } from "../lib/date-math.js";
 import { expandProfile } from "../lib/filter-profiles.js";
@@ -1185,9 +1186,20 @@ export function registerIssueTools(server, client, fieldCache) {
         }
     });
     // -------------------------------------------------------------------------
-    // ralph_hero__pick_actionable_issue
+    // ralph_hero__pick_actionable_issue [DEPRECATED]
+    //
+    // Thin wrapper that delegates to the shared `runDirections` helper from
+    // `directions-tools.ts` (audience="agent"). Preserves the legacy
+    // `{ found, issue, group, alternatives }` shape so existing callers
+    // (justfile recipes, hero/team allowlists) keep working until removal in
+    // 2.7.0. Same backwards-compat pattern as `hello_directions` from Phase 2.
+    //
+    // Migration: callers should switch to
+    //   ralph_hero__next_actions(limit=1, audience="agent")
+    // and consume the rank-1 (recommended) entry directly.
     // -------------------------------------------------------------------------
-    server.tool("ralph_hero__pick_actionable_issue", "Find the highest-priority issue matching a workflow state that is not blocked or locked. Returns: found, issue (with number, title, workflowState, estimate, priority, group context), alternatives count. Used by dispatch loop to find work for idle teammates. Recovery: if no issues found, try a different workflowState or increase maxEstimate.", {
+    const runDirections = makeRunDirections(client, fieldCache);
+    server.tool("ralph_hero__pick_actionable_issue", "[DEPRECATED — use ralph_hero__next_actions(limit=1, audience='agent') instead. Removed in 2.7.0.] Find the highest-priority issue matching a workflow state that is not blocked or locked. Returns: found, issue (with number, title, workflowState, estimate, priority, group context), alternatives count. Used by dispatch loop to find work for idle teammates.", {
         owner: z
             .string()
             .optional()
@@ -1200,7 +1212,8 @@ export function registerIssueTools(server, client, fieldCache) {
             .describe("Project number override (defaults to configured project)"),
         workflowState: z
             .string()
-            .describe("Target workflow state (e.g., 'Research Needed', 'Ready for Plan')"),
+            .optional()
+            .describe("Target workflow state (e.g., 'Research Needed', 'Ready for Plan'). Optional — when omitted, the rank-1 (recommended) direction across all actionable phases is returned (same as next_actions(limit=1, audience='agent'))."),
         maxEstimate: z
             .string()
             .optional()
@@ -1208,8 +1221,9 @@ export function registerIssueTools(server, client, fieldCache) {
             .describe("Maximum estimate to include (XS, S, M, L, XL). Default: S"),
     }, async (args) => {
         try {
-            // Validate workflow state
-            if (!isValidState(args.workflowState)) {
+            // Validate workflow state (only when provided — wrapper allows
+            // omission so it can mirror next_actions(limit=1, audience='agent')).
+            if (args.workflowState !== undefined && !isValidState(args.workflowState)) {
                 return toolError(`Unknown workflow state '${args.workflowState}'. ` +
                     `Valid states: ${VALID_STATES.join(", ")}. ` +
                     `Recovery: retry with a valid state name. ` +
@@ -1224,111 +1238,59 @@ export function registerIssueTools(server, client, fieldCache) {
                     `Valid estimates: ${validEstimates.join(", ")}. ` +
                     `Recovery: retry with a valid estimate or omit for default (S).`);
             }
-            const { owner, repo, projectNumber, projectOwner } = resolveFullConfig(client, args);
-            // Ensure field cache is populated
-            await ensureFieldCache(client, fieldCache, projectOwner, projectNumber);
-            const projectId = fieldCache.getProjectId(projectNumber);
-            if (!projectId) {
-                return toolError("Could not resolve project ID");
+            const { owner, repo } = resolveFullConfig(client, args);
+            // Delegate to the shared ranker with audience="agent". Use a
+            // generous limit so we have enough entries to filter by
+            // workflowState + maxEstimate while still finding the highest
+            // priority candidate. The ranker uses priority + audience-aware
+            // estimate penalty as the dominant ordering signal, which matches
+            // the legacy P0 -> P3 sort.
+            const directionsResult = await runDirections({
+                owner,
+                projectNumbers: args.projectNumber !== undefined ? [args.projectNumber] : undefined,
+                limit: 50,
+                openPRs: [],
+                audience: "agent",
+            });
+            if (directionsResult.isError) {
+                // Surface the underlying error verbatim so callers see the same
+                // recovery hints they would from next_actions.
+                return directionsResult;
             }
-            // Fetch all project items
-            const itemsResult = await paginateConnection((q, v) => client.projectQuery(q, v), `query($projectId: ID!, $cursor: String, $first: Int!) {
-            node(id: $projectId) {
-              ... on ProjectV2 {
-                items(first: $first, after: $cursor) {
-                  totalCount
-                  pageInfo { hasNextPage endCursor }
-                  nodes {
-                    id
-                    type
-                    content {
-                      ... on Issue {
-                        number
-                        title
-                        body
-                        state
-                        url
-                        labels(first: 10) { nodes { name } }
-                        trackedIssues(first: 10) {
-                          nodes { number state }
-                        }
-                      }
-                    }
-                    fieldValues(first: 20) {
-                      nodes {
-                        ... on ProjectV2ItemFieldSingleSelectValue {
-                          __typename
-                          name
-                          optionId
-                          field { ... on ProjectV2FieldCommon { name } }
-                        }
-                      }
-                    }
-                  }
-                }
-              }
+            const payload = JSON.parse(directionsResult.content[0].text);
+            // Restrict to plain "issue" directions — exclude PRs (kind="pr"),
+            // lock-stale items (kind="lock-stale"), and tree-continue picks
+            // (kind="tree-continue") since legacy semantics returned a single
+            // ready-to-claim issue.
+            let issueDirections = payload.directions.filter((d) => d.kind === "issue" && d.issue !== null);
+            // Apply legacy filters: workflowState (if provided) and maxEstimate.
+            if (args.workflowState !== undefined) {
+                issueDirections = issueDirections.filter((d) => d.issue.workflowState === args.workflowState);
             }
-          }`, { projectId, first: 100 }, "node.items", { maxItems: 500 });
-            // Filter to matching items
-            let candidates = itemsResult.nodes.filter((item) => {
-                if (item.type !== "ISSUE" || !item.content)
-                    return false;
-                const content = item.content;
-                if (content.state !== "OPEN")
-                    return false;
-                // Check workflow state
-                const ws = getFieldValue(item, "Workflow State");
-                if (ws !== args.workflowState)
-                    return false;
-                // Check estimate
-                const est = getFieldValue(item, "Estimate");
-                if (est) {
-                    const estIdx = validEstimates.indexOf(est);
-                    const maxIdx = validEstimates.indexOf(maxEstimate);
-                    if (estIdx > maxIdx)
-                        return false;
-                }
-                return true;
-            });
-            // Filter out locked issues (in a lock state - shouldn't happen if matching target state, but safety check)
-            candidates = candidates.filter((item) => {
-                const ws = getFieldValue(item, "Workflow State");
-                return !ws || !LOCK_STATES.includes(ws);
-            });
-            // Filter out issues with unresolved blockers
-            candidates = candidates.filter((item) => {
-                const content = item.content;
-                const blockedBy = content.trackedIssues;
-                if (!blockedBy?.nodes || blockedBy.nodes.length === 0)
+            const maxIdx = validEstimates.indexOf(maxEstimate);
+            issueDirections = issueDirections.filter((d) => {
+                const est = d.issue.estimate;
+                if (!est)
                     return true;
-                // Issue is blocked if any blocker is still OPEN
-                return !blockedBy.nodes.some((dep) => dep.state === "OPEN");
-            });
-            // Sort by priority (P0 > P1 > P2 > P3 > none)
-            const priorityOrder = {
-                P0: 0,
-                P1: 1,
-                P2: 2,
-                P3: 3,
-            };
-            candidates.sort((a, b) => {
-                const pA = getFieldValue(a, "Priority");
-                const pB = getFieldValue(b, "Priority");
-                const orderA = pA ? (priorityOrder[pA] ?? 99) : 99;
-                const orderB = pB ? (priorityOrder[pB] ?? 99) : 99;
-                return orderA - orderB;
+                const estIdx = validEstimates.indexOf(est);
+                if (estIdx < 0)
+                    return true;
+                return estIdx <= maxIdx;
             });
-            if (candidates.length === 0) {
+            // Drop blocked items (legacy behavior). The ranker already strips
+            // these unless that would empty the candidate set; the "blocked"
+            // tag still rides along when it kept them as a fallback.
+            issueDirections = issueDirections.filter((d) => !d.tags.includes("blocked"));
+            if (issueDirections.length === 0) {
                 return toolSuccess({
                     found: false,
                     issue: null,
                     alternatives: 0,
                 });
             }
-            const best = candidates[0];
-            const content = best.content;
-            const issueNumber = content.number;
-            // Detect group context for the picked issue (best-effort)
+            const best = issueDirections[0].issue;
+            const issueNumber = best.number;
+            // Detect group context for the picked issue (best-effort).
             let group = null;
             try {
                 const groupResult = await detectGroup(client, owner, repo, issueNumber);
@@ -1355,16 +1317,19 @@ export function registerIssueTools(server, client, fieldCache) {
                 found: true,
                 issue: {
                     number: issueNumber,
-                    title: content.title,
-                    description: content.body || "",
-                    workflowState: getFieldValue(best, "Workflow State"),
-                    estimate: getFieldValue(best, "Estimate") || null,
-                    priority: getFieldValue(best, "Priority") || null,
+                    title: best.title,
+                    // Body is not fetched by the ranker's data pipeline — kept
+                    // empty for backward compat. Callers needing the body should
+                    // chain a `get_issue` call (or migrate to `next_actions`).
+                    description: "",
+                    workflowState: best.workflowState,
+                    estimate: best.estimate || null,
+                    priority: best.priority || null,
                     isLocked: false,
                     blockedBy: [],
                 },
                 group,
-                alternatives: candidates.length - 1,
+                alternatives: issueDirections.length - 1,
             });
         }
         catch (error) {

package/package.json

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