ralph-hero-mcp-server 2.5.80 → 2.5.85

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.80",
+  "version": "2.5.85",
   "description": "MCP server for GitHub Projects V2 - Ralph workflow automation",
   "type": "module",
   "main": "dist/index.js",