@neriros/ralphy 2.18.0 → 2.19.0

package/README.md

@@ -169,6 +169,8 @@ A default `ralphy.config.json` is written on first run with every defaulted sett
     "assignee": "me",
     "postComments": true,
     "updateEveryIterations": 10,
+    "mentionTrigger": true,
+    "mentionHandle": "@ralphy",
     "indicators": {
       "getTodo": { "filter": [{ "type": "status", "value": "Todo" }] },
       "getInProgress": { "filter": [{ "type": "status", "value": "In Progress" }] },
@@ -213,6 +215,8 @@ Linear is the source of truth for which issues Ralph has touched. Each `linear.i
 
 **Review follow-ups.** When a Linear issue is in a "done" state and a reviewer adds the `getReview` marker (typically a label like `ralph:review` after leaving comments), Ralph picks it up, applies `setInProgress`, removes the `clearReview` label so the same trigger doesn't re-fire, fetches the comment thread, filters out Ralph's own comments, and prepends those reviewer comments as a new task at the top of `tasks.md`. The worker addresses them in the same change branch and `setDone` is re-applied on success.
 
+**`@ralphy` mention trigger.** Set `linear.mentionTrigger: true` (default `false`) to scan done-issue comments on both Linear and their linked GitHub PR for `@ralphy` mentions (configurable via `linear.mentionHandle`). New mentions enqueue the issue as a review run with the mention text used verbatim as the prepended task. Idempotency: a mention is considered processed when its `createdAt` is older than the most recent Ralph `🔁 picked up` comment on the Linear issue, so the same comment never re-fires across polls. Requires the `gh` CLI authenticated for the GitHub side.
+
 Marker types are `"label"` or `"status"`. Combine markers under `apply` when one event needs to set multiple — e.g. `setDone` flipping a status _and_ adding a "shipped" label.
 
 #### Per-task git worktrees

package/dist/cli/index.js

@@ -35029,8 +35029,8 @@ import { readFileSync as readFileSync2 } from "fs";
 import { resolve } from "path";
 function getVersion() {
   try {
-    if ("2.18.0")
-      return "2.18.0";
+    if ("2.19.0")
+      return "2.19.0";
   } catch {}
   const dirsToTry = [];
   try {
@@ -59621,6 +59621,12 @@ var MarkerSchema, GetIndicatorSchema, SetIndicatorSchema, IndicatorsSchema, Ralp
     // Post a progress update every N iterations. 0 disables. Requires postComments.
     "updateEveryIterations": 10,
 
+    // Watch done-issue Linear comments AND their linked GitHub PR comments
+    // for "@ralphy" mentions. New mentions enqueue the issue as a review run
+    // with the mention text as the prepended task.
+    "mentionTrigger": false,
+    // "mentionHandle": "@ralphy",
+
     // Indicators map Ralph lifecycle events to Linear labels/statuses.
     // WARNING: activating indicators will query AND mutate your Linear workspace.
     // Uncomment each entry after confirming the label/status names match your workspace.
@@ -59730,8 +59736,16 @@ var init_config = __esm(() => {
       assignee: exports_external.string().optional(),
       postComments: exports_external.boolean().default(true),
       updateEveryIterations: exports_external.number().int().nonnegative().default(10),
+      mentionTrigger: exports_external.boolean().default(false),
+      mentionHandle: exports_external.string().default("@ralphy"),
       indicators: IndicatorsSchema.default({})
-    }).strict().default({ postComments: true, updateEveryIterations: 10, indicators: {} })
+    }).strict().default({
+      postComments: true,
+      updateEveryIterations: 10,
+      mentionTrigger: false,
+      mentionHandle: "@ralphy",
+      indicators: {}
+    })
   }).default({
     concurrency: 1,
     pollIntervalSeconds: 60,
@@ -59740,7 +59754,13 @@ var init_config = __esm(() => {
     enableManualTest: false,
     engine: "claude",
     model: "opus",
-    linear: { postComments: true, updateEveryIterations: 10, indicators: {} }
+    linear: {
+      postComments: true,
+      updateEveryIterations: 10,
+      mentionTrigger: false,
+      mentionHandle: "@ralphy",
+      indicators: {}
+    }
   });
 });
 
@@ -60070,20 +60090,22 @@ class AgentCoordinator {
     let inProgress = [];
     let conflicted = [];
     let review = [];
+    let mentions = [];
     try {
-      [todo, inProgress, conflicted, review] = await Promise.all([
+      [todo, inProgress, conflicted, review, mentions] = await Promise.all([
         this.deps.fetchTodo(),
         this.deps.fetchInProgress(),
         this.deps.fetchConflicted(),
-        this.deps.fetchReview()
+        this.deps.fetchReview(),
+        this.deps.fetchMentions()
       ]);
     } catch (err) {
       this.deps.onLog(`! Linear poll failed: ${err.message}`, "red");
       capture("agent_linear_poll_failed", { error: err.message });
       return { found: 0, added: 0 };
     }
-    if (todo.length + inProgress.length + conflicted.length + review.length > 0) {
-      this.deps.onLog(`  poll: ${todo.length} todo, ${inProgress.length} in-progress, ${conflicted.length} conflicted, ${review.length} review`, "gray");
+    if (todo.length + inProgress.length + conflicted.length + review.length + mentions.length > 0) {
+      this.deps.onLog(`  poll: ${todo.length} todo, ${inProgress.length} in-progress, ${conflicted.length} conflicted, ${review.length} review, ${mentions.length} mention`, "gray");
     }
     const queuedIds = new Set(this.queue.map((q) => q.issue.id));
     const activeIds = new Set(this.workers.map((w) => w.issueId));
@@ -60128,6 +60150,16 @@ class AgentCoordinator {
       added += 1;
       this.deps.onLog(`  \u21B3 ${issue.identifier} queued (review)`, "gray");
     }
+    for (const { issue, trigger } of mentions) {
+      if (atTicketLimit())
+        break;
+      if (!eligible(issue.id))
+        continue;
+      this.queue.push({ issue, mode: "review", trigger });
+      queuedIds.add(issue.id);
+      added += 1;
+      this.deps.onLog(`  \u21B3 ${issue.identifier} queued (review via ${trigger.source} mention)`, "gray");
+    }
     for (const issue of todo) {
       if (atTicketLimit())
         break;
@@ -60158,7 +60190,7 @@ class AgentCoordinator {
     this.spawnNext();
     await this.scanDoneForConflicts();
     await this.reportProgress();
-    const found = todo.length + inProgress.length + conflicted.length + review.length;
+    const found = todo.length + inProgress.length + conflicted.length + review.length + mentions.length;
     return { found, added };
   }
   dependenciesResolved(issue) {
@@ -60267,13 +60299,13 @@ class AgentCoordinator {
     while (this.workers.length + this.pendingIds.size < this.opts.concurrency && this.queue.length > 0) {
       const next = this.queue.shift();
       this.pendingIds.add(next.issue.id);
-      this.launchWorker(next.issue, next.mode);
+      this.launchWorker(next.issue, next.mode, next.trigger);
     }
   }
-  async launchWorker(issue, mode) {
+  async launchWorker(issue, mode, trigger) {
     let prep;
     try {
-      prep = await this.deps.prepare(issue, mode);
+      prep = await this.deps.prepare(issue, mode, trigger);
     } catch (err) {
       this.pendingIds.delete(issue.id);
       this.deps.onLog(`! prepare(${mode}) failed for ${issue.identifier}: ${err.message}`, "red");
@@ -60316,8 +60348,9 @@ class AgentCoordinator {
       }
     }
     if (mode === "review" && this.opts.postComments !== false) {
+      const sourceTag = trigger ? trigger.source === "github" ? " (GitHub @mention)" : " (Linear @mention)" : "";
       try {
-        await this.deps.postComment(issue, `\uD83D\uDD01 Ralph picked up new review comments. Tracking change: \`${prep.changeName}\``);
+        await this.deps.postComment(issue, `\uD83D\uDD01 Ralph picked up new review comments${sourceTag}. Tracking change: \`${prep.changeName}\``);
       } catch (err) {
         this.deps.onLog(`! Linear review comment failed for ${issue.identifier}: ${err.message}`, "yellow");
       }
@@ -61108,6 +61141,25 @@ ${c.body.trim()}`;
   ].join(`
 `);
 }
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function buildMentionTaskBody(trigger, issueUrl) {
+  const sourceLabel = trigger.source === "github" ? "GitHub PR" : "Linear issue";
+  const permalink = trigger.url ?? issueUrl;
+  const header = `${trigger.author ?? "unknown"} \u2014 ${trigger.createdAt} (${sourceLabel})`;
+  return [
+    `An @ralphy mention was left on ${sourceLabel} (${permalink}):`,
+    "",
+    `**${header}**`,
+    "",
+    trigger.body.trim(),
+    "",
+    "Treat this comment as the next concrete request. If it's ambiguous,",
+    "note your interpretation in proposal.md `## Steering` before acting."
+  ].join(`
+`);
+}
 function unionMarkers(...sets) {
   const out = [];
   const seen = new Set;
@@ -61318,7 +61370,7 @@ function buildAgentCoordinator(input) {
     }
     return { workerCwd, scaffoldTasksDir, scaffoldStatesDir, branch };
   }
-  async function prepare(issue, mode) {
+  async function prepare(issue, mode, trigger) {
     const { workerCwd, scaffoldTasksDir, scaffoldStatesDir, branch } = await setupWorktree(issue);
     let changeName;
     const isFresh = mode === "fresh";
@@ -61345,16 +61397,24 @@ function buildAgentCoordinator(input) {
     if (mode === "review") {
       const wtLayout = projectLayout(workerCwd);
       const tasksFile = join16(wtLayout.changeDir(changeName), "tasks.md");
-      let comments = [];
-      try {
-        comments = await fetchIssueComments(apiKey, issue.id);
-      } catch (err) {
-        onLog(`! Linear comment fetch failed for ${issue.identifier}: ${err.message}`, "yellow");
+      let body;
+      let heading;
+      if (trigger) {
+        heading = trigger.source === "github" ? "Address GitHub @ralphy mention" : "Address Linear @ralphy mention";
+        body = buildMentionTaskBody(trigger, issue.url);
+      } else {
+        heading = "Address reviewer comments";
+        let comments = [];
+        try {
+          comments = await fetchIssueComments(apiKey, issue.id);
+        } catch (err) {
+          onLog(`! Linear comment fetch failed for ${issue.identifier}: ${err.message}`, "yellow");
+        }
+        const reviewerComments = comments.filter((c) => !isRalphComment(c.body));
+        body = buildReviewTaskBody(reviewerComments, issue.url);
       }
-      const reviewerComments = comments.filter((c) => !isRalphComment(c.body));
-      const body = buildReviewTaskBody(reviewerComments, issue.url);
       try {
-        await prependFixTask(tasksFile, "Address reviewer comments", body);
+        await prependFixTask(tasksFile, heading, body);
       } catch (err) {
         onLog(`! could not prepend review task: ${err.message}`, "red");
       }
@@ -61630,11 +61690,145 @@ PR: ${prUrl}` : ""
       return [];
     return fetchOpenIssues(apiKey, { team, assignee, include, exclude });
   }
+  async function fetchMentions() {
+    if (!cfg.linear.mentionTrigger)
+      return [];
+    const handle = cfg.linear.mentionHandle;
+    let candidates = [];
+    try {
+      candidates = await fetchDoneCandidates();
+    } catch (err) {
+      onLog(`! mention scan: fetchDoneCandidates failed: ${err.message}`, "yellow");
+      return [];
+    }
+    const out = [];
+    for (const issue of candidates) {
+      let comments = [];
+      try {
+        comments = await fetchIssueComments(apiKey, issue.id);
+      } catch (err) {
+        onLog(`! mention scan: Linear comments failed for ${issue.identifier}: ${err.message}`, "yellow");
+        continue;
+      }
+      const lastRalphPickup = findLastRalphPickupISO(comments);
+      for (const c of comments) {
+        if (isRalphComment(c.body))
+          continue;
+        if (!containsHandle(c.body, handle))
+          continue;
+        if (lastRalphPickup && c.createdAt <= lastRalphPickup)
+          continue;
+        out.push({
+          issue,
+          trigger: {
+            source: "linear",
+            body: c.body,
+            createdAt: c.createdAt,
+            ...c.user?.name ? { author: c.user.name } : {},
+            url: issue.url
+          }
+        });
+        break;
+      }
+      if (out.length > 0 && out[out.length - 1].issue.id === issue.id)
+        continue;
+      const prUrl = await resolvePrUrlForIssue(issue);
+      if (!prUrl)
+        continue;
+      const ghComments = await fetchPrIssueComments(prUrl);
+      for (const c of ghComments) {
+        if (!containsHandle(c.body, handle))
+          continue;
+        if (lastRalphPickup && c.createdAt <= lastRalphPickup)
+          continue;
+        out.push({
+          issue,
+          trigger: {
+            source: "github",
+            body: c.body,
+            createdAt: c.createdAt,
+            ...c.author ? { author: c.author } : {},
+            url: c.url
+          }
+        });
+        break;
+      }
+    }
+    return out;
+  }
+  function findLastRalphPickupISO(comments) {
+    let latest = null;
+    for (const c of comments) {
+      if (!/^\uD83D\uDD01\s*Ralph picked up/.test(c.body.trimStart()))
+        continue;
+      if (latest === null || c.createdAt > latest)
+        latest = c.createdAt;
+    }
+    return latest;
+  }
+  function containsHandle(body, handle) {
+    const re = new RegExp(`(^|\\s|[^A-Za-z0-9_])${escapeRegex(handle)}\\b`, "i");
+    return re.test(body);
+  }
+  async function resolvePrUrlForIssue(issue) {
+    const changeName = changeNameForIssue(issue);
+    if (prUnavailable.has(changeName))
+      return null;
+    const cached = prByChange.get(changeName);
+    if (cached)
+      return cached;
+    const branch = branchForChange(changeName);
+    try {
+      const res = await cmdRunner.run([
+        "gh",
+        "pr",
+        "list",
+        "--head",
+        branch,
+        "--state",
+        "all",
+        "--json",
+        "url",
+        "--jq",
+        ".[0].url // empty"
+      ], projectRoot);
+      const found = res.stdout.trim();
+      if (!found) {
+        prUnavailable.add(changeName);
+        return null;
+      }
+      prByChange.set(changeName, found);
+      return found;
+    } catch {
+      return null;
+    }
+  }
+  async function fetchPrIssueComments(prUrl) {
+    const m = /^https:\/\/github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)/.exec(prUrl);
+    if (!m)
+      return [];
+    const [, owner, repo, num] = m;
+    try {
+      const res = await cmdRunner.run([
+        "gh",
+        "api",
+        `repos/${owner}/${repo}/issues/${num}/comments`,
+        "--jq",
+        "[.[] | {body: .body, createdAt: .created_at, author: .user.login, url: .html_url}]"
+      ], projectRoot);
+      const parsed = JSON.parse(res.stdout || "[]");
+      return parsed;
+    } catch (err) {
+      onLog(`! mention scan: gh comments failed for ${prUrl}: ${err.message}`, "yellow");
+      return [];
+    }
+  }
   const coord = new AgentCoordinator({
     fetchTodo: () => fetchByGet(indicators.getTodo, excludeFromTodo),
     fetchInProgress: () => fetchByGet(indicators.getInProgress, []),
     fetchConflicted: () => fetchByGet(indicators.getConflicted, []),
     fetchReview: () => fetchByGet(indicators.getReview, excludeFromReview),
+    fetchMentions,
     fetchDoneCandidates,
     prepare,
     spawnWorker,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neriros/ralphy",
-  "version": "2.18.0",
+  "version": "2.19.0",
   "description": "An iterative AI task execution framework. Orchestrates multi-phase autonomous work using Claude or Codex engines.",
   "keywords": [
     "agent",