@open-everywhere/provider-github 0.0.0-stage → 0.1.1

package/agent/channels/github-reaction-scope.ts

@@ -0,0 +1,312 @@
+// THE GITHUB REACTION-POLL SCOPE (OPE-1540) — the two gates that decide whether one delivery is
+// allowed to spend REST calls looking for reactions, and the durable record the first gate reads.
+//
+// WHY A GATE EXISTS AT ALL. GitHub pushes no reaction webhook, so the feedback arm
+// (channels/github-reaction-feedback.ts) POLLS: every signature-verified `issue_comment`/`issues`
+// delivery made it read the issue and a comment page, and only then could it learn that the agent
+// has never commented in that conversation and there is nothing to look at. That is 2–3 installation
+// REST calls per delivery, on the SAME installation token the reply path mints. A repository taking
+// 400 deliveries an hour spent ~800–1200 GETs an hour learning nothing, and the 429 pressure landed
+// on the agent's own posts.
+//
+// ── GATE 1: THE CONVERSATION MUST BE ONE THE AGENT IS IN, AND IT READS TWO RECORDS
+//
+// A reaction the arm can record is a reaction on the AGENT's own comment, so a conversation the agent
+// has never commented in can hold none. Gate 1 answers "is the agent in this conversation" from two
+// durable records, and admits on EITHER. Both are keyed store reads; neither costs a REST call.
+//
+//  1. THE POST CLAIM, written by this bundle's own reply path (channels/github-post-arm.ts
+//     `liveGitHubPost`). That is the one place a GitHub comment leaves THIS BUNDLE — every `reply`
+//     tool call, every unified-window reply and every ambient-supervisor answer.
+//  2. THE ENGAGEMENT ROW, written by the §2.5 seam (channels/github-engagement.ts) when somebody
+//     @mentions the app in a container.
+//
+// 🔴 THE SECOND READ EXISTS BECAUSE THIS BUNDLE IS NOT THE ONLY POSTER. eve's default posts the
+// `input.requested` comment, which this bundle does not override, and it still posts a NATIVE
+// terminal completion on the paths that fall back to it — a review thread's inline reply, and a
+// state with no post anchor (`channels/github.ts`). (An ordinary native terminal completion claims
+// here now: it posts through `liveGitHubPost` since OPE-1681, so that example is no longer one.) Those comments carry the app's login and attract reactions exactly as a `reply`
+// does, and NOTHING in this bundle sees them go out — so a post-claim-only gate would refuse those
+// conversations forever, not merely until the next reply. The engagement row is what covers them: the
+// native leg wakes only on an @mention (which marks the row) or on a plain comment in a container
+// already marked, so every conversation eve can post in has one.
+//
+// 🔴 IT ADMITS A LITTLE MORE THAN "HAS POSTED", ON PURPOSE. A container somebody @mentioned the app
+// in where the app then said nothing is admitted and costs a poll. That is the safe direction — the
+// alternative is a reaction the deployment can never record — and gate 2 caps what it can cost.
+//
+// 🔴 THE POST CLAIM IS A `notice_claim`, AND THE LIFETIME IS THE POINT. "The agent has commented
+// here" never stops being true, so the record must never expire: a TTL would blind the poll to a
+// quiet conversation's reactions the moment the TTL lapsed, and re-writing the mark needs a post
+// nobody is going to make. `claimNotice`/`noticeClaimed` (operational/store.ts) is the tree's
+// at-most-once claim with no TTL and no prune, which is exactly this shape. Growth is one row per
+// conversation the agent has ever commented in — bounded by conversations, never by deliveries.
+//
+// 🔴 WHAT THE CUT-OVER COSTS, STATED. Both records start from what already exists: engagement rows
+// are already there for every container an @mention ever reached, and the post claim starts EMPTY. So
+// a conversation the agent only ever answered ambiently — no @mention, hence no engagement row — and
+// has not answered since this shipped is not polled until it answers there again. The reaction arm
+// landed one day before this gate (OPE-1502, PR #587), so the window of reactions that can fall into
+// that gap is one day wide. It is a real gap, not a theoretical one.
+//
+// FAIL-OPEN on a store error. An unreadable record answers "the agent is in this conversation", so a
+// store blip costs REST calls rather than silently stopping the feedback signal. It is the opposite
+// posture from the reaction DEDUPE next door (channels/github-reaction-feedback.ts), which fails
+// CLOSED — these two gates bound a COST, and that one bounds what the audit log claims happened.
+//
+// ── GATE 2: A PER-REPOSITORY HOURLY BUDGET
+//
+// Gate 1 bounds the poll to conversations the agent is in, which is the big cut. It does NOT bound
+// what one very busy conversation can spend: a hundred comments an hour in a pull request the agent
+// replied to is a hundred polls. So a second gate caps the polls one REPOSITORY may run in one clock
+// hour, and the trip is AUDITED — a silently capped feedback signal reads exactly like a feature that
+// stopped working.
+//
+// 🔴 THE COUNTER IS APPROXIMATE UNDER CONCURRENCY, AND THAT IS ACCEPTED. It is a read-then-write over
+// the opaque `task_result` KV, not an atomic increment, so two deliveries racing on the same repo can
+// both read N and write N+1 — the hour's true count can exceed the budget by roughly the number of
+// concurrent deliveries. A rate budget is a cost bound, not a security control: over-counting would
+// drop feedback that should have been recorded, under-counting costs a few extra GETs. The cheap,
+// non-atomic direction is the one whose failure mode is the harmless one.
+//
+// 🔴 THE TTL IS COUPLED, SO IT IS NOT A KNOB. `task_result`'s prune is ORG-WIDE and uses the CALLING
+// writer's own ttl (operational/store.ts, the task_result section), so every consumer must pass the
+// same six hours. {@link GITHUB_POLL_BUDGET_TTL_MS} exists to be that number and nothing else — a
+// shorter one here would start deleting `model/turn-state.ts`'s live rows on every delivery.
+
+import {
+  appendAudit,
+  deploymentOrg,
+  getOperationalStore,
+} from "@open-everywhere/core/agent/adapter-api.js";
+import { githubConversationKey } from "./github-identity.js";
+
+/** How many reaction polls one repository may run in one clock hour. Sized so an ordinarily busy
+ *  repository never reaches it — the gate is a ceiling on a runaway conversation, not a throttle on
+ *  normal traffic. One ADMITTED poll costs up to 13 GETs (the issue read, one or two comment pages,
+ *  and up to `GITHUB_REACTION_POLL_COMMENT_BUDGET` reaction reads), so this bounds a repository's
+ *  worst hour to ~780 GETs on the installation token the reply path shares. The everyday cost is far
+ *  below that: most polls read three. */
+export const GITHUB_REACTION_POLL_HOURLY_BUDGET = 60;
+
+/** The `task_result` retention every consumer of that table shares. See the header: it is coupled,
+ *  not tunable. Six hours, the same window `model/turn-state.ts` and the three other consumers use. */
+const GITHUB_POLL_BUDGET_TTL_MS = 6 * 60 * 60 * 1000;
+
+/** The audit action a tripped budget writes. Queryable over the control plane's audit route, the
+ *  same way `github.ambient_skipped` answers "why did the ambient leg stay quiet". */
+export const GITHUB_REACTION_POLL_BUDGET_ACTION = "github.reaction_poll_budget";
+
+/** The audit action an UNREADABLE CLAIM STORE writes, once per poll. The dedupe next door fails
+ *  CLOSED, so a store that cannot answer "is this recorded" stops every feedback row for as long as
+ *  it stays down — and a silent zero reads exactly like a quiet week. This row is the signal. It
+ *  carries the same audit ACTION shape as the budget trip above, so an operator reads both off the
+ *  control plane's audit route; the GRAIN differs, and {@link auditGitHubReactionClaimUnreadable}
+ *  says how. */
+export const GITHUB_REACTION_CLAIM_UNREADABLE_ACTION = "github.reaction_claim_unreadable";
+
+/** How long a reply may wait on the best-effort post claim below.
+ *
+ * 🔴 THE CEILING IS THE POINT, NOT THE NUMBER. `liveGitHubPost` marks the conversation AFTER the
+ * comment has already landed, so this write can only ever delay the reply tool's RETURN — and with
+ * no ceiling a slow store held that return for as long as it liked, on the turn path. Two seconds is
+ * far more than a keyed claim needs and far less than a turn can notice. */
+export const GITHUB_POSTED_MARK_TIMEOUT_MS = 2000;
+
+/** How long the trip row's once-per-hour guard holds. It is the bucket width, not a dedupe window:
+ *  the key already carries the hour, so this only has to outlive the hour it names. */
+const BUDGET_AUDIT_TTL_MS = 2 * 60 * 60 * 1000;
+
+/** The claim key for "the agent has commented in this conversation". `githubConversationKey` is the
+ *  SAME `owner/repo#N` anchor the engagement registry and the stop registry address, so the mark and
+ *  every other per-conversation record in this bundle name the container the same way. */
+function githubPostedClaimKey(owner: string | undefined, repo: string | undefined, number: number | undefined): string | undefined {
+  const anchor = githubConversationKey(owner, repo, number);
+  return anchor ? `github-posted:${anchor}` : undefined;
+}
+
+/** The hourly budget's key for one repository. The clock hour rides IN the key, so the counter needs
+ *  no reset and a stale bucket simply stops being read. */
+export function githubPollBudgetKey(owner: string, repo: string, atIso: string): string {
+  return `github-reaction-poll-budget:${owner}/${repo}:${atIso.slice(0, 13)}`;
+}
+
+/**
+ * Record that the agent has commented in this conversation. Best-effort and idempotent — a second
+ * post in the same conversation re-claims a key that is already claimed, which the store answers
+ * false to and this function ignores. NEVER THROWS: a lost mark costs a later poll, never a reply.
+ *
+ * 🔴 IT IS ALSO BOUNDED, WHICH IS THE OTHER HALF OF THAT CONTRACT. The one caller is
+ * `liveGitHubPost`, on the reply tool's own path, and it calls this AFTER the comment has landed. An
+ * unbounded await therefore could not lose a reply but could hold the tool's return for as long as
+ * the store took — a real hazard on a tree that already stalls in its post-turn closeout. So the
+ * write RACES {@link GITHUB_POSTED_MARK_TIMEOUT_MS}: a store slower than that is treated exactly
+ * like the store that throws, and costs a later poll rather than the turn.
+ *
+ * The abandoned write is not cancelled — nothing here can cancel a store call — so it carries its
+ * own settled handler and may still land after this returns. That is the harmless direction: the
+ * claim is idempotent and its only reader is the next poll.
+ */
+export async function markGitHubConversationPosted(owner: string | undefined, repo: string | undefined, number: number | undefined, atIso: string): Promise<void> {
+  const key = githubPostedClaimKey(owner, repo, number);
+  if (!key) return;
+  let write: Promise<void>;
+  try {
+    // The `.then(_, _)` is what keeps an abandoned rejection from surfacing as an unhandled one:
+    // after the race gives up, nothing else is holding this promise.
+    write = getOperationalStore()
+      .claimNotice(deploymentOrg(), key, atIso)
+      .then(
+        () => undefined,
+        () => undefined,
+      );
+  } catch {
+    // A store that cannot even be resolved. The reply already landed; there is nothing to wait on.
+    return;
+  }
+  // `unref` so the ceiling never keeps a host alive on its own, and `clearTimeout` so a write that
+  // beat it leaves no pending timer behind.
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const ceiling = new Promise<void>((resolve) => {
+    timer = setTimeout(resolve, GITHUB_POSTED_MARK_TIMEOUT_MS);
+    timer.unref?.();
+  });
+  try {
+    await Promise.race([write, ceiling]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Is the agent IN this conversation — has this bundle's reply path posted here, or did an @mention
+ * engage the container? Either answers yes; see the header for why both reads are needed.
+ *
+ * FAIL-OPEN on a store error, and on a delivery that names no container: an unanswerable question
+ * admits the poll, whose own parse then refuses a delivery that names nothing.
+ */
+export async function githubConversationInScope(surfaceKey: string, owner: string | undefined, repo: string | undefined, number: number | undefined): Promise<boolean> {
+  const key = githubPostedClaimKey(owner, repo, number);
+  const anchor = githubConversationKey(owner, repo, number);
+  if (!key || !anchor) return true;
+  const org = deploymentOrg();
+  try {
+    if (await getOperationalStore().noticeClaimed(org, key)) return true;
+    // 🔴 THE STORE, NOT `getThreadEngagement`. That helper swallows its own failure and answers
+    // null, so an unreadable registry would be indistinguishable from an un-engaged container and
+    // this gate would fail CLOSED on a store blip — the one direction the header forbids. Reading
+    // the store directly lets the catch below take the fail-open answer for BOTH records. The
+    // coordinates are the helper's own: `p.org` and `p.surfaceKey`, keyed by the container anchor.
+    return (await getOperationalStore().getEngagement(org, surfaceKey, anchor)) !== null;
+  } catch {
+    return true;
+  }
+}
+
+/** What one budget check decided, and what it counted. `polls` is the count INCLUDING this one when
+ *  the check admitted it, so a caller can log the pressure without a second read. */
+export interface GitHubPollBudgetVerdict {
+  readonly admitted: boolean;
+  readonly polls: number;
+}
+
+/**
+ * Spend one poll from this repository's hourly budget.
+ *
+ * Admits and counts while the hour has room; refuses once the budget is spent, and writes ONE
+ * {@link GITHUB_REACTION_POLL_BUDGET_ACTION} row for that hour rather than one per refused delivery —
+ * the refusals are the loud part of a busy hour, and an unthrottled row per delivery would be the
+ * same flood in the audit log that the budget exists to stop in GitHub's API.
+ *
+ * FAIL-OPEN on a store error: an unreadable counter admits the poll. A budget is a cost bound, so a
+ * store blip must never silence the feedback signal.
+ */
+export async function spendGitHubPollBudget(owner: string, repo: string, atIso: string, budget = GITHUB_REACTION_POLL_HOURLY_BUDGET): Promise<GitHubPollBudgetVerdict> {
+  const org = deploymentOrg();
+  const key = githubPollBudgetKey(owner, repo, atIso);
+  let used = 0;
+  try {
+    const raw = await getOperationalStore().getTaskResult(org, key);
+    const parsed = raw ? (JSON.parse(raw) as { readonly polls?: unknown }) : undefined;
+    used = typeof parsed?.polls === "number" && Number.isFinite(parsed.polls) ? parsed.polls : 0;
+  } catch {
+    return { admitted: true, polls: 0 };
+  }
+  if (used >= budget) {
+    await auditBudgetTrip(org, owner, repo, atIso, used, budget);
+    return { admitted: false, polls: used };
+  }
+  const polls = used + 1;
+  try {
+    await getOperationalStore().putTaskResult(org, key, JSON.stringify({ polls }), atIso, GITHUB_POLL_BUDGET_TTL_MS);
+  } catch {
+    // The count is lost for this delivery; the poll still runs. Under-counting costs GETs, never a row.
+  }
+  return { admitted: true, polls };
+}
+
+/**
+ * Write the one row that says this poll's claim store could not be read.
+ *
+ * 🔴 WHY IT EXISTS. The reaction dedupe (channels/github-reaction-feedback.ts) fails CLOSED on an
+ * unreadable claim — an unknown answer counts as ALREADY RECORDED — which is the right posture for
+ * what the audit log claims happened, and a silent one. A store that stays unreadable therefore
+ * records nothing at all, forever, and the operator sees a feature that looks healthy and reports
+ * zero. This row is the difference between "nobody reacted" and "the store is down".
+ *
+ * ONE ROW PER POLL, never one per reaction: a busy comment page holds dozens of reactions and one
+ * broken store would write a row for each. `skipped` carries the count instead, so the row is as
+ * loud as the flood would have been. That is a DIFFERENT GRAIN from the budget trip below, which
+ * `markEventSeen` throttles to one row per repository per hour — this one has no throttle, because a
+ * poll that could not read the store is a distinct event and the count is the thing being reported.
+ *
+ * 🔴 WHAT BOUNDS THE VOLUME, HONESTLY. The poll reaches here only past gate 2, so an ordinary hour
+ * holds at most {@link GITHUB_REACTION_POLL_HOURLY_BUDGET} of these per repository — but only WHILE
+ * THE BUDGET COUNTER IS WRITABLE. Gate 2 fails open on a store error, so a fault that breaks the
+ * `task_result` write while `audit_log` inserts still land gives one row per delivery instead. That
+ * is the same trade the gate already made, and both directions of it are a cost, never a lost row.
+ *
+ * 🔴 AND IT IS NOT A SIGNAL FOR EVERY OUTAGE. `appendAudit` writes through the SAME operational
+ * store whose claim read just threw, so a whole-store outage loses this row too — best-effort, one
+ * retry, then a drop-counter tick and a `[open-everywhere:audit] dropped a …` warn (core
+ * agent/audit/audit.ts). This row is what makes a PARTIAL fault legible — a missing `notice_claim`
+ * table, a table-level grant — and the audit drop counter is what makes the total one legible. The
+ * operator doc states the same split.
+ *
+ * Best-effort, like every other write in this module: nothing here may cost the ingress its ack.
+ */
+export async function auditGitHubReactionClaimUnreadable(owner: string, repo: string, atIso: string, skipped: number): Promise<void> {
+  try {
+    await appendAudit({
+      ts: atIso,
+      org: deploymentOrg(),
+      platform: "github",
+      workspace: owner,
+      surface: `github/${owner}/${repo}`,
+      action: GITHUB_REACTION_CLAIM_UNREADABLE_ACTION,
+      detail: { skipped, hour: atIso.slice(0, 13) },
+    });
+  } catch {
+    // Nothing here may cost the ingress its ack.
+  }
+}
+
+/** The trip row, at most once per repository per hour. Both the throttle and the write are
+ *  best-effort: a budget that cannot audit itself still refuses the poll. */
+async function auditBudgetTrip(org: string, owner: string, repo: string, atIso: string, used: number, budget: number): Promise<void> {
+  try {
+    const first = await getOperationalStore().markEventSeen(org, `${githubPollBudgetKey(owner, repo, atIso)}:tripped`, atIso, BUDGET_AUDIT_TTL_MS);
+    if (!first) return;
+    await appendAudit({
+      ts: atIso,
+      org,
+      platform: "github",
+      workspace: owner,
+      surface: `github/${owner}/${repo}`,
+      action: GITHUB_REACTION_POLL_BUDGET_ACTION,
+      detail: { budget, polls: used, hour: atIso.slice(0, 13) },
+    });
+  } catch {
+    // Nothing here may cost the ingress its ack.
+  }
+}