ralph-hero-mcp-server 2.5.75 → 2.5.80

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/lib/directions.js

@@ -34,6 +34,7 @@ export const DEFAULT_RANK_CONFIG = {
     lockStaleHours: 24,
     treeRecentDoneDays: 7,
     prStaleHours: 24,
+    audience: "human",
 };
 // ---------------------------------------------------------------------------
 // Internal scoring constants
@@ -60,6 +61,18 @@ const STALE_BOOST = -50;
 const LOCK_STALE_BOOST = -100;
 const TREE_CONTINUE_BOOST = -75;
 const PR_REVIEW_REQUIRED_BOOST = -200;
+/**
+ * Per-estimate penalty applied when audience === "agent". Larger items
+ * cost more (positive score), pushing them down the ranking so agent
+ * loops dispatch on XS/S items first.
+ */
+const ESTIMATE_PENALTY = {
+    XS: 0,
+    S: 0,
+    M: 20,
+    L: 40,
+    XL: 60,
+};
 const HOUR_MS = 60 * 60 * 1000;
 const DAY_MS = 24 * HOUR_MS;
 // ---------------------------------------------------------------------------
@@ -100,6 +113,20 @@ function hasOpenBlockers(item) {
 function isLockState(state) {
     return state !== null && LOCK_STATES.includes(state);
 }
+/**
+ * Returns a positive score adjustment when audience === "agent" so larger
+ * estimates get pushed down the ranking. Returns 0 for human audience
+ * (existing behavior). Items with unknown estimate get a mid-tier penalty
+ * (30) so unestimated work doesn't accidentally outrank XS/S items.
+ */
+function audiencePenalty(item, audience) {
+    if (audience !== "agent")
+        return 0;
+    const est = item.estimate;
+    if (est === null || est === undefined)
+        return 30; // unknown: mid penalty
+    return ESTIMATE_PENALTY[est] ?? 30;
+}
 // ---------------------------------------------------------------------------
 // Detection helpers
 // ---------------------------------------------------------------------------
@@ -176,6 +203,9 @@ export function detectTreeContinue(item, allItems, config) {
 export function scoreIssue(item, allItems, config) {
     const tags = [];
     let score = priorityScore(item.priority) + phaseScore(item.workflowState);
+    // Audience-aware estimate penalty (no-op for "human"; pushes XL items
+    // down for "agent" so autonomous loops favor XS/S work).
+    score += audiencePenalty(item, config.audience);
     const lockStale = detectLockStale(item, config);
     const treeContinue = detectTreeContinue(item, allItems, config);
     // Stale boost (non-lock states only)
@@ -295,7 +325,20 @@ export function buildReason(kind, issue, pr, tags, config, linkedIssueNumber = n
         const hours = Math.round(ageHours(issue.updatedAt, config.now));
         const days = Math.max(1, Math.floor(hours / 24));
         const dayLabel = days === 1 ? "day" : "days";
-        return `${phase} for ${days} ${dayLabel} — likely the most unblocking thing`;
+        const priority = issue.priority;
+        if (priority === "P0") {
+            return `P0 stalled in ${phase} for ${days} ${dayLabel} — top of the queue`;
+        }
+        if (priority === "P1") {
+            return `P1 stalled in ${phase} for ${days} ${dayLabel} — likely the most unblocking thing`;
+        }
+        if (priority === "P2") {
+            return `Sitting in ${phase} for ${days} ${dayLabel} — small unblock if you have a moment`;
+        }
+        if (priority === "P3") {
+            return `Low-priority item in ${phase} for ${days} ${dayLabel}`;
+        }
+        return `Unprioritized in ${phase} for ${days} ${dayLabel}`;
     }
     if (issue.priority === "P0") {
         return `P0 in ${phase} — top of the queue`;
@@ -423,6 +466,7 @@ export function rankDirections(items, openPRs, config) {
             const reason = buildReason(c.kind, c.item, null, c.tags, config, null);
             return {
                 rank,
+                recommended: false,
                 kind: c.kind,
                 issue: toDirectionIssue(c.item),
                 pr: null,
@@ -436,6 +480,7 @@ export function rankDirections(items, openPRs, config) {
         const reason = buildReason("pr", null, p.pr, p.tags, config, p.linkedIssueNumber);
         return {
             rank,
+            recommended: false,
             kind: "pr",
             issue: null,
             pr: toDirectionPR(p.pr),
@@ -444,6 +489,12 @@ export function rankDirections(items, openPRs, config) {
             score: p.score,
         };
     });
+    // Mark the top-ranked entry as recommended. Both modes use this
+    // flag for selection: interactive picker pre-selects it; headless
+    // orchestrators dispatch on it.
+    if (directions.length > 0) {
+        directions[0].recommended = true;
+    }
     return directions;
 }
 //# sourceMappingURL=directions.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

@@ -1,11 +1,14 @@
 /**
- * MCP tool wrapping the pure ranker at `lib/directions.ts`.
+ * MCP tools wrapping the pure ranker at `lib/directions.ts`.
  *
- * Exposes `ralph_hero__hello_directions`: a single-tool, fixed-shape,
- * deterministic surface that returns up to N ranked "directions" for the
- * `hello` skill's session briefing. The skill is responsible for fetching
- * open PRs (via `gh pr list`) and passing them in as a parameter — the
- * MCP server does not itself open an Octokit-style PR API surface.
+ * Exposes two tools that share a single implementation:
+ *   - `ralph_hero__next_actions` (current name; accepts `audience` param)
+ *   - `ralph_hero__hello_directions` (DEPRECATED alias; fixed at audience="human")
+ *
+ * Both return a fixed-shape JSON payload with up to N ranked "directions"
+ * for the `hello` skill's session briefing. The skill is responsible for
+ * fetching open PRs (via `gh pr list`) and passing them in as a parameter
+ * — the MCP server does not itself open an Octokit-style PR API surface.
  *
  * Behaviour:
  *   1. Resolve owner + project numbers from args or client config.
@@ -32,68 +35,27 @@ import { toolSuccess, toolError, resolveProjectOwner, resolveProjectNumbers, } f
 // ---------------------------------------------------------------------------
 const HOUR_MS = 60 * 60 * 1000;
 // ---------------------------------------------------------------------------
-// Register
+// Shared schema fragments
 // ---------------------------------------------------------------------------
-export function registerDirectionsTools(server, client, fieldCache) {
-    server.tool("ralph_hero__hello_directions", "Compute up to N deterministic 'directions' for the hello skill's session briefing. Single tool call returns a fixed-shape JSON payload with ranked issue/PR action items. Open PRs must be passed in as a parameter (the MCP server does not fetch them itself).", {
-        owner: z
-            .string()
-            .optional()
-            .describe("GitHub owner. Defaults to RALPH_GH_OWNER env var."),
-        projectNumbers: z
-            .array(z.coerce.number())
-            .optional()
-            .describe("Project numbers to include. Defaults to RALPH_GH_PROJECT_NUMBERS or single configured project."),
-        limit: z
-            .number()
-            .int()
-            .nonnegative()
-            .optional()
-            .default(3)
-            .describe("Max directions to return (default: 3)."),
-        stuckThresholdHours: z
-            .number()
-            .nonnegative()
-            .optional()
-            .default(48)
-            .describe("Hours before a non-lock issue is considered stale (default: 48)."),
-        lockStaleHours: z
-            .number()
-            .nonnegative()
-            .optional()
-            .default(24)
-            .describe("Hours before a lock-state issue is considered stalled (default: 24)."),
-        treeRecentDoneDays: z
-            .number()
-            .nonnegative()
-            .optional()
-            .default(7)
-            .describe("Days within which a sibling Done event still pulls a tree forward (default: 7)."),
-        prStaleHours: z
-            .number()
-            .nonnegative()
-            .optional()
-            .default(24)
-            .describe("Hours before an open PR is considered stale (default: 24)."),
-        openPRs: z
-            .array(z.object({
-            number: z.number(),
-            title: z.string(),
-            url: z.string(),
-            isDraft: z.boolean(),
-            reviewDecision: z
-                .string()
-                .nullable()
-                .describe("REVIEW_REQUIRED | APPROVED | CHANGES_REQUESTED | null"),
-            headRefName: z.string(),
-            createdAt: z
-                .string()
-                .describe("ISO timestamp from gh pr list"),
-        }))
-            .optional()
-            .default([])
-            .describe("Open PRs gathered by the caller (e.g. via `gh pr list`). Drafts and APPROVED PRs are filtered internally."),
-    }, async (args) => {
+const openPRSchema = z.object({
+    number: z.number(),
+    title: z.string(),
+    url: z.string(),
+    isDraft: z.boolean(),
+    reviewDecision: z
+        .string()
+        .nullable()
+        .describe("REVIEW_REQUIRED | APPROVED | CHANGES_REQUESTED | null"),
+    headRefName: z.string(),
+    createdAt: z.string().describe("ISO timestamp from gh pr list"),
+});
+// ---------------------------------------------------------------------------
+// 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.
+// ---------------------------------------------------------------------------
+function makeRunDirections(client, fieldCache) {
+    return async function runDirections(args) {
         try {
             const owner = args.owner || resolveProjectOwner(client.config);
             if (!owner) {
@@ -124,6 +86,7 @@ export function registerDirectionsTools(server, client, fieldCache) {
                 lockStaleHours: args.lockStaleHours ?? DEFAULT_RANK_CONFIG.lockStaleHours,
                 treeRecentDoneDays: args.treeRecentDoneDays ?? DEFAULT_RANK_CONFIG.treeRecentDoneDays,
                 prStaleHours: args.prStaleHours ?? DEFAULT_RANK_CONFIG.prStaleHours,
+                audience: args.audience,
                 now,
             };
             // Compute PR ageHours at the boundary so the lib never reads the wall clock.
@@ -154,6 +117,113 @@ export function registerDirectionsTools(server, client, fieldCache) {
             const message = error instanceof Error ? error.message : String(error);
             return toolError(`Failed to compute hello directions: ${message}`);
         }
+    };
+}
+// ---------------------------------------------------------------------------
+// Register
+// ---------------------------------------------------------------------------
+export function registerDirectionsTools(server, client, fieldCache) {
+    const runDirections = makeRunDirections(client, fieldCache);
+    server.tool("ralph_hero__hello_directions", "[DEPRECATED — use ralph_hero__next_actions instead. Removed in 2.7.0.] Compute up to N deterministic 'directions' for the hello skill's session briefing.", {
+        owner: z
+            .string()
+            .optional()
+            .describe("GitHub owner. Defaults to RALPH_GH_OWNER env var."),
+        projectNumbers: z
+            .array(z.coerce.number())
+            .optional()
+            .describe("Project numbers to include. Defaults to RALPH_GH_PROJECT_NUMBERS or single configured project."),
+        limit: z
+            .number()
+            .int()
+            .nonnegative()
+            .optional()
+            .default(3)
+            .describe("Max directions to return (default: 3)."),
+        stuckThresholdHours: z
+            .number()
+            .nonnegative()
+            .optional()
+            .default(48)
+            .describe("Hours before a non-lock issue is considered stale (default: 48)."),
+        lockStaleHours: z
+            .number()
+            .nonnegative()
+            .optional()
+            .default(24)
+            .describe("Hours before a lock-state issue is considered stalled (default: 24)."),
+        treeRecentDoneDays: z
+            .number()
+            .nonnegative()
+            .optional()
+            .default(7)
+            .describe("Days within which a sibling Done event still pulls a tree forward (default: 7)."),
+        prStaleHours: z
+            .number()
+            .nonnegative()
+            .optional()
+            .default(24)
+            .describe("Hours before an open PR is considered stale (default: 24)."),
+        openPRs: z
+            .array(openPRSchema)
+            .optional()
+            .default([])
+            .describe("Open PRs gathered by the caller (e.g. via `gh pr list`). Drafts and APPROVED PRs are filtered internally."),
+    }, async (args) => {
+        return await runDirections({ ...args, audience: "human" });
+    });
+    server.tool("ralph_hero__next_actions", "Compute up to N deterministic 'directions' (next actions) with one flagged `recommended: true`. Used by the /hello skill picker (interactive) and by headless orchestrators (auto-select recommended). Open PRs must be passed in as a parameter.", {
+        owner: z
+            .string()
+            .optional()
+            .describe("GitHub owner. Defaults to RALPH_GH_OWNER env var."),
+        projectNumbers: z
+            .array(z.coerce.number())
+            .optional()
+            .describe("Project numbers to include. Defaults to RALPH_GH_PROJECT_NUMBERS or single configured project."),
+        limit: z
+            .number()
+            .int()
+            .nonnegative()
+            .optional()
+            .default(3)
+            .describe("Max directions to return (default: 3)."),
+        audience: z
+            .enum(["human", "agent"])
+            .optional()
+            .default("human")
+            .describe("Tilts scoring per consumer; agent penalizes large estimates to honor autonomous-loop XS/S preference (default: human)."),
+        stuckThresholdHours: z
+            .number()
+            .nonnegative()
+            .optional()
+            .default(48)
+            .describe("Hours before a non-lock issue is considered stale (default: 48)."),
+        lockStaleHours: z
+            .number()
+            .nonnegative()
+            .optional()
+            .default(24)
+            .describe("Hours before a lock-state issue is considered stalled (default: 24)."),
+        treeRecentDoneDays: z
+            .number()
+            .nonnegative()
+            .optional()
+            .default(7)
+            .describe("Days within which a sibling Done event still pulls a tree forward (default: 7)."),
+        prStaleHours: z
+            .number()
+            .nonnegative()
+            .optional()
+            .default(24)
+            .describe("Hours before an open PR is considered stale (default: 24)."),
+        openPRs: z
+            .array(openPRSchema)
+            .optional()
+            .default([])
+            .describe("Open PRs gathered by the caller (e.g. via `gh pr list`). Drafts and APPROVED PRs are filtered internally."),
+    }, async (args) => {
+        return await runDirections({ ...args, audience: args.audience ?? "human" });
     });
 }
 //# sourceMappingURL=directions-tools.js.map

package/package.json

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