hilos-agent 0.7.0 → 0.9.0

package/src/thread-pr.mjs

@@ -0,0 +1,305 @@
+// The thread's pull request, daemon side (0704). 0701 resolves "which PR is this
+// thread about?" once on the server and serves the answer to every substrate; the
+// daemon reads it off `list_mentions` as `message.threadPr` and uses it for two
+// decisions:
+//
+//   1. ADOPT vs FRESH — a mention in a PR thread means "continue THIS pull
+//      request": fetch its head branch, push onto it, never `git checkout -b`.
+//   2. RELAY — "merge it" / "close it" is executed through the merge_pr /
+//      close_pr MCP tools rather than answered with "a human has to click".
+//
+// Pure + dependency-free apart from followup.mjs (the ONE truth table, shared
+// with the server), so every rule below unit-tests without git, gh, or a network.
+//
+// Both decisions are deliberately conservative. The daemon is not the authority
+// on either one: the server confirms the PR is really open before an iterate can
+// land (and here `gh` does too), and `executePrAction` owns the merge/close gate
+// — it re-classifies the cited instruction with a forced-tool model call, checks
+// the author's workspace role, and refuses fail-closed. A daemon false NEGATIVE
+// costs one extra mention; a daemon false POSITIVE is still caught server-side.
+
+import { resolveFollowupMode } from "./followup.mjs";
+
+/**
+ * @typedef {Object} ThreadPrAnchor
+ * @property {string} repoFullName
+ * @property {number} prNumber
+ * @property {string} prUrl
+ * @property {string|null} state   'open' | 'merged' | 'closed' | null (unknown)
+ * @property {string|null} branch  head branch when the evidence recorded one
+ * @property {string|null} source  'run' | 'report' | 'message' | 'link'
+ */
+
+/**
+ * Sanitize the `threadPr` block off a list_mentions payload. Everything here
+ * arrives over the wire, so nothing is trusted: a malformed anchor is simply no
+ * anchor, and the daemon behaves exactly as it did before 0704.
+ * @param {any} raw
+ * @returns {ThreadPrAnchor|null}
+ */
+export function normalizeThreadPr(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const repoFullName = typeof raw.repoFullName === "string" ? raw.repoFullName.trim() : "";
+  const prUrl = typeof raw.prUrl === "string" ? raw.prUrl.trim() : "";
+  const prNumber = Number(raw.prNumber);
+  if (!repoFullName || !prUrl) return null;
+  if (!Number.isInteger(prNumber) || prNumber <= 0) return null;
+  const state = typeof raw.state === "string" && raw.state.trim() ? raw.state.trim().toLowerCase() : null;
+  const branch = typeof raw.branch === "string" && raw.branch.trim() ? raw.branch.trim() : null;
+  const source = typeof raw.source === "string" && raw.source.trim() ? raw.source.trim() : null;
+  return { repoFullName, prNumber, prUrl, state, branch, source };
+}
+
+/** Case-insensitive `owner/repo` equality — GitHub is case-insensitive on both. */
+function sameRepo(a, b) {
+  return String(a || "").toLowerCase() === String(b || "").toLowerCase();
+}
+
+/**
+ * Should this mention adopt the thread's pull request instead of cutting a new
+ * branch? Mirrors the server's thread-anchor fallback in app/api/agent/route.ts
+ * signal for signal:
+ *
+ *   - Only THREAD-LOCAL evidence may direct code onto a PR. A 'link' anchor is
+ *     channel-wide — it would route an unrelated thread's work onto whatever PR
+ *     the room happens to have linked.
+ *   - The anchor must live in the repo this channel clones. A pasted cross-repo
+ *     PR is context for chat and review, never an iterate target: the daemon
+ *     would push a same-named branch into the wrong repository.
+ *   - A known-terminal anchor (merged/closed) never adopts. Unknown state is
+ *     only a hypothesis — `gh` proves it before anything is checked out
+ *     (see confirmAnchorOpen).
+ *   - The shared truth table decides intent: an explicit "in a separate PR"
+ *     forks even inside a PR thread.
+ *
+ * @param {{ threadPr: any, repoFullName: string, signal: string|null|undefined }} o
+ * @returns {{ adopt: boolean, reason: string, anchor: ThreadPrAnchor|null }}
+ */
+export function anchorIterateDecision({ threadPr, repoFullName, signal } = {}) {
+  const anchor = normalizeThreadPr(threadPr);
+  if (!anchor) return { adopt: false, reason: "no-anchor", anchor: null };
+  if (anchor.source === "link") return { adopt: false, reason: "link-anchor", anchor };
+  if (!sameRepo(anchor.repoFullName, repoFullName)) {
+    return { adopt: false, reason: "other-repo", anchor };
+  }
+  if (anchor.state === "merged" || anchor.state === "closed") {
+    return { adopt: false, reason: `anchor-${anchor.state}`, anchor };
+  }
+  // prOpen:true is the hypothesis this function is allowed to make (the terminal
+  // states are already out); hasActiveRun:true says "this thread owns work" —
+  // the anchor IS that work, whether or not a run row survived.
+  const mode = resolveFollowupMode({
+    hasActiveRun: true,
+    prOpen: true,
+    signal: signal || "ambiguous",
+  });
+  if (mode !== "iterate") return { adopt: false, reason: "new-scope", anchor };
+  return { adopt: true, reason: "adopt", anchor };
+}
+
+/**
+ * The staleness guard. `live` is what `gh pr view --json state,headRefName,…`
+ * reported for the anchor; this decides whether the daemon may check that branch
+ * out and push to it. Same shape as the server's confirmOpenPr: open, with a head
+ * branch, living in the base repo (a fork head is another repository's branch —
+ * pushing "to it" would touch an unrelated same-named branch here).
+ *
+ * No proof, no adoption: an unreachable `gh` returns null and the run starts a
+ * fresh branch rather than gambling on a possibly-merged PR.
+ *
+ * @param {{ live: any, anchor: ThreadPrAnchor }} o
+ * @returns {{ ok: boolean, branch: string|null, reason: string }}
+ */
+export function confirmAnchorOpen({ live, anchor } = {}) {
+  if (!anchor) return { ok: false, branch: null, reason: "no-anchor" };
+  if (!live || typeof live !== "object") return { ok: false, branch: null, reason: "unverified" };
+  const state = typeof live.state === "string" ? live.state.trim().toLowerCase() : "";
+  if (state === "merged" || state === "closed") return { ok: false, branch: null, reason: state };
+  if (state !== "open") return { ok: false, branch: null, reason: "unverified" };
+  const headRepo = typeof live.headRepoFullName === "string" ? live.headRepoFullName : null;
+  if (headRepo && !sameRepo(headRepo, anchor.repoFullName)) {
+    return { ok: false, branch: null, reason: "fork-head" };
+  }
+  const branch = typeof live.headRefName === "string" && live.headRefName.trim() ? live.headRefName.trim() : null;
+  if (!branch) return { ok: false, branch: null, reason: "unverified" };
+  return { ok: true, branch, reason: "open" };
+}
+
+/**
+ * One line for the run's status card when an intended adoption did NOT happen —
+ * the person asked inside a PR thread, so silence would read as "it's pushing to
+ * my PR" while a fresh branch is being cut. Returns "" when there is nothing to
+ * confess (the reasons that are simply "this isn't an iterate").
+ * @param {{ reason: string, anchor: ThreadPrAnchor|null }} o
+ */
+export function staleAnchorNote({ reason, anchor } = {}) {
+  if (!anchor) return "";
+  const pr = `PR #${anchor.prNumber}`;
+  if (reason === "merged" || reason === "anchor-merged") {
+    return `${pr} is already merged, so this goes on a new branch instead.`;
+  }
+  if (reason === "closed" || reason === "anchor-closed") {
+    return `${pr} is closed, so this goes on a new branch instead.`;
+  }
+  if (reason === "fork-head") {
+    return `${pr} is from a fork, so I can't push to its branch — this goes on a new branch instead.`;
+  }
+  if (reason === "unverified") {
+    return `I couldn't confirm ${pr} is still open, so this goes on a new branch instead.`;
+  }
+  if (reason === "checkout-failed") {
+    return `I couldn't check out ${pr}'s branch, so this goes on a new branch instead.`;
+  }
+  return "";
+}
+
+// ---------------------------------------------------------------------------
+// Merge / close cue classification
+// ---------------------------------------------------------------------------
+//
+// The server's own merge/close intent is an LLM call (decideAgentIntent with
+// allowPrActions). The daemon cannot reach it: the MCP `classify_agent_intent`
+// tool exposes ask/ship/deploy only — it never offers review/merge/close — so
+// there is no shared classifier to import here. Per 0704 this is therefore a
+// deliberately narrow phrase matcher over explicit instructions, and it is a
+// TRIGGER, not an authority: every match is handed to merge_pr / close_pr, where
+// the server re-classifies the cited human message with a forced-tool model call
+// before it spends the App's write token.
+//
+// Bias: miss rather than guess. A missed cue costs one clearer sentence.
+
+/** The pronouns/nouns an instruction can name the PR with. */
+const OBJECT = String.raw`(?:it|this|that|them|the\s+pr|this\s+pr|that\s+pr|the\s+pull\s+request|this\s+pull\s+request|that\s+pull\s+request|it\s+in|this\s+one|that\s+one|el\s+pr|la\s+pr)`;
+const PR_REF = String.raw`(?:#\d{1,6}|https?:\/\/\S*\/pull\/\d{1,6})`;
+
+const MERGE_PATTERNS = [
+  new RegExp(String.raw`\bmerge\s+${OBJECT}\b`, "i"),
+  new RegExp(String.raw`\bmerge\s+${PR_REF}`, "i"),
+  // "land it" is unambiguous for a pull request. "ship it" is NOT — it is also
+  // the daemon's own word for "go do the work", so it stays out of this list.
+  new RegExp(String.raw`\bland\s+${OBJECT}\b`, "i"),
+  /\bmerge\s+away\b/i,
+  // Spanish / Portuguese imperatives, matching the multi-language spirit of the
+  // follow-up cue lists.
+  /\b(?:mergea(?:lo|la)?|merg[eé]alo|haz\s+merge|fusiona(?:lo|la)?|fusi[oó]nal[oa])\b/i,
+];
+
+const CLOSE_PATTERNS = [
+  new RegExp(String.raw`\bclose\s+${OBJECT}\b`, "i"),
+  new RegExp(String.raw`\bclose\s+${PR_REF}`, "i"),
+  new RegExp(String.raw`\b(?:abandon|discard|scrap)\s+${OBJECT}\b`, "i"),
+  /\b(?:cierra(?:lo|la)?|ci[eé]rral[oa]|descarta(?:lo|la)?|desc[aá]rtal[oa])\b/i,
+];
+
+/** A sentence that says the opposite, defers, or hypothesizes is not an
+ *  instruction. Checked against the sentence the cue appeared in. */
+const DISQUALIFIERS = [
+  // Negation and deferral.
+  /\b(?:don'?t|do\s+not|dont|never|no\s+need|hold\s+off|not\s+yet|wait|hang\s+on|instead\s+of)\b/i,
+  /\bno\s+(?:lo|la|le)\b/i,
+  /\b(?:todav[ií]a|a[uú]n)\s+no\b/i,
+  // Conditional / sequenced — "once CI passes, merge it" is a plan, not a go.
+  /\b(?:if|once|when|after|before|unless|until|assuming|in\s+case|whenever)\b/i,
+  /\b(?:si|cuando|despu[eé]s|antes)\b/i,
+  // Someone else is doing it.
+  /\b(?:i|we)(?:'|’)?(?:ll|\s+will|\s+am\s+going\s+to|\s+can|\s+should)\s+(?:merge|close)\b/i,
+  /\b(?:i|we)\s+(?:just\s+)?(?:merged|closed)\b/i,
+  // Vocabulary that contains the verb but means something else entirely.
+  /\bmerge\s+(?:conflict|commit|base|queue|strategy)/i,
+  /\bclose\s+(?:call|enough|to)\b/i,
+  /\b(?:already|just)\s+(?:merged|closed)\b/i,
+];
+
+/** Politeness markers that keep a question-shaped sentence an instruction. */
+const POLITE_REQUEST = /\b(?:can\s+you|could\s+you|would\s+you|will\s+you|please|puedes|podr[ií]as|por\s+favor)\b/i;
+
+/** Strip `@handle` mentions so "@scout merge it" reads as "merge it". */
+function stripMentions(text) {
+  return String(text || "").replace(/(^|\s)@[a-z0-9][a-z0-9._-]*/gi, " ");
+}
+
+/** Sentences, roughly. Newlines end a sentence too — chat rarely punctuates. */
+function sentences(text) {
+  return text
+    .split(/(?<=[.!?…])\s+|\n+/)
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+function isInstruction(sentence) {
+  if (DISQUALIFIERS.some((re) => re.test(sentence))) return false;
+  // A question is a question ("should we merge it?") unless it's the polite
+  // shape of an order ("can you merge it?").
+  if (/\?\s*$/.test(sentence) && !POLITE_REQUEST.test(sentence)) return false;
+  return true;
+}
+
+/**
+ * Does this message explicitly instruct a merge or a close of the thread's PR?
+ * Returns 'merge', 'close', or null. A message that appears to ask for both gets
+ * null — an ambiguous instruction is not one.
+ * @param {string} text
+ * @returns {'merge'|'close'|null}
+ */
+export function classifyPrActionCue(text) {
+  const body = stripMentions(text);
+  if (!body.trim()) return null;
+  let merge = false;
+  let close = false;
+  for (const sentence of sentences(body)) {
+    if (!isInstruction(sentence)) continue;
+    if (MERGE_PATTERNS.some((re) => re.test(sentence))) merge = true;
+    if (CLOSE_PATTERNS.some((re) => re.test(sentence))) close = true;
+  }
+  if (merge && close) return null;
+  if (merge) return "merge";
+  if (close) return "close";
+  return null;
+}
+
+/**
+ * Should this mention be relayed to merge_pr / close_pr instead of routed as
+ * chat or code? Every "no" is a fall-through to today's behavior — the relay
+ * only ever ADDS a path.
+ *
+ * Requires an anchor: without one the daemon has no idea which PR "it" is, and
+ * guessing is exactly the failure 0701 exists to prevent. It deliberately does
+ * NOT check whether the anchor is in this channel's repo, whether the asker is
+ * allowed, or whether the message names a different PR — those are the server's
+ * calls, and its refusals are better written than anything decided here.
+ *
+ * @param {{ body: string, threadPr: any, mode: string|null, canRelay: boolean }} o
+ * @returns {{ relay: boolean, action: 'merge'|'close'|null, reason: string, anchor: ThreadPrAnchor|null }}
+ */
+export function prActionRelayDecision({ body, threadPr, mode, canRelay } = {}) {
+  const anchor = normalizeThreadPr(threadPr);
+  const action = classifyPrActionCue(body);
+  if (!action) return { relay: false, action: null, reason: "no-cue", anchor };
+  // Chat only is the human saying this agent does not act here (the server
+  // refuses PR actions the same way when mayExecute is false).
+  if (mode === "ask") return { relay: false, action, reason: "chat-only", anchor };
+  if (!canRelay) return { relay: false, action, reason: "no-tool", anchor };
+  if (!anchor) return { relay: false, action, reason: "no-anchor", anchor };
+  return { relay: true, action, reason: "relay", anchor };
+}
+
+/**
+ * What to say after a relay. The server posts the outcome of every executed
+ * action AND every refusal that reached executePrAction (its `message`), so
+ * repeating it would double-post in the thread. Only the tool-level refusals —
+ * which come back as `error` and are posted by nobody — need a message from the
+ * daemon, and they are surfaced verbatim: the server's wording is the authority.
+ * @param {any} result the parsed merge_pr / close_pr tool result
+ * @returns {{ post: string|null, ok: boolean, alreadyPosted: boolean }}
+ */
+export function prActionReply(result) {
+  if (!result || typeof result !== "object") {
+    return { post: null, ok: false, alreadyPosted: false };
+  }
+  if (result.ok === false && typeof result.error === "string" && result.error.trim()) {
+    return { post: result.error, ok: false, alreadyPosted: false };
+  }
+  // ok:true, or an executePrAction refusal — either way it already spoke in the
+  // thread with its own words.
+  return { post: null, ok: result.ok === true, alreadyPosted: true };
+}