@quickchatai/quickreview 0.0.0-stage → 1.1.0

package/src/slack/policy.ts

@@ -0,0 +1,354 @@
+// Slack concierge caps + cooldowns.
+//
+// Every limit here is enforced in DAEMON CODE, never by prompt: a session (or
+// an operator) may ask the concierge to speak, this module decides whether it
+// may. Nothing in this file performs I/O or talks to Slack — it is pure
+// decision logic over the sqlite ledgers in src/state.ts plus [slack.policy].
+//
+// Windows:
+//   * turn + post caps are **policy-day** windows ([slack.policy] timezone,
+//     defaulting from [ops]), DST-correct, derived from
+//     the Intl helpers in src/eod.ts (the single date implementation in this
+//     codebase — never re-derived here), exactly as the improvement/issue rate
+//     caps count filed_items rows inside a day window.
+//   * the announcement limiter is a ROLLING hour, not a calendar one.
+//
+// Announcements are cheap (no model turn) and therefore BYPASS the turn caps —
+// but they still pass the per-hour limiter and the per-cause cooldown table,
+// whose fold/bypass semantics mirror src/tui/alerts.ts AlertPolicy: one fire
+// per cause per cooldown, repeats inside the window fold into a counter, and a
+// genuine escalation may break the cooldown exactly once per policy day.
+import type { Config, SlackCausePolicy } from "../config.js";
+import { zoneDateString, zoneDayBounds, zonedParts } from "../eod.js";
+import type { SlackPostKind, StateStore } from "../state.js";
+
+export interface DayWindow {
+  /** "YYYY-MM-DD" in the policy timezone — the cooldown table's day key. */
+  day: string;
+  /** Half-open [startIso, endIso) of that local day, as UTC ISO instants. */
+  startIso: string;
+  endIso: string;
+}
+
+/**
+ * The local calendar day containing `now`, as a half-open instant window.
+ * Built from eod.ts's zone helpers so the 23h/25h DST days are exact.
+ */
+export function dayWindow(now: Date, timeZone: string): DayWindow {
+  const p = zonedParts(now, timeZone);
+  const { start, end } = zoneDayBounds(p.year, p.month, p.day, timeZone);
+  return {
+    day: zoneDateString(now, timeZone),
+    startIso: start.toISOString(),
+    endIso: end.toISOString(),
+  };
+}
+
+/** The policy-timezone day window in force for this config. */
+export function policyWindow(cfg: Config, now: Date): DayWindow {
+  return dayWindow(now, cfg.slack.policy.timezone);
+}
+
+// ---- turn admission (pre-injection, at the router) ------------------------
+
+export type TurnCap = "daily_turns" | "per_user_daily_turns";
+
+export interface TurnDecision {
+  allow: boolean;
+  /** Which cap refused — set iff `allow` is false. Callers key the one-per-day
+   * `slack.cap_reached` announcement off this, so a denial is never mistaken
+   * for any other kind of drop. */
+  cap?: TurnCap;
+  reason?: string;
+  day: string;
+  used: number;
+  userUsed: number;
+}
+
+/**
+ * May this inbound Slack message become a model turn? Counts `injected`
+ * events in the policy day, channel-wide and (when the sender is known) for
+ * that one person. An unknown sender is only subject to the channel cap.
+ */
+export function decideTurn(
+  store: StateStore,
+  cfg: Config,
+  input: { slackUser?: string | null },
+  now: Date = new Date(),
+): TurnDecision {
+  const { daily_turns, per_user_daily_turns } = cfg.slack.policy;
+  const w = policyWindow(cfg, now);
+  const used = store.slackTurnsBetween(w.startIso, w.endIso);
+  const user = input.slackUser ?? null;
+  const userUsed = user ? store.slackTurnsBetween(w.startIso, w.endIso, user) : 0;
+  const base = { day: w.day, used, userUsed };
+  if (used >= daily_turns) {
+    return {
+      ...base,
+      allow: false,
+      cap: "daily_turns",
+      reason: `Slack daily turn cap reached (${used}/${daily_turns})`,
+    };
+  }
+  if (user && userUsed >= per_user_daily_turns) {
+    return {
+      ...base,
+      allow: false,
+      cap: "per_user_daily_turns",
+      reason: `Slack per-user daily turn cap reached for ${user} (${userUsed}/${per_user_daily_turns})`,
+    };
+  }
+  return { ...base, allow: true };
+}
+
+/**
+ * The budget a turn refusal announces in the channel, or null when it
+ * announces none. Only the channel-wide budget is channel news: a per-user
+ * cap leaves everyone else free to ask, so telling the channel "questions
+ * resume at midnight" — and spending the day's one cap announcement on it —
+ * would be false.
+ */
+export function announcedCap(cfg: Config, decision: TurnDecision): number | null {
+  return decision.cap === "daily_turns" ? cfg.slack.policy.daily_turns : null;
+}
+
+// ---- reply admission (at the slack_reply path) ---------------------------
+
+export type ReplyCap = "daily_posts" | "thread_replies_per_day" | "idempotent";
+
+// The post taxonomy, in one place: `kind = 'reply'` is the ONLY conversational
+// post (a model turn stands behind it) and the only one the reply budgets
+// count. `pickup` / `verdict` / `announce` are daemon-authored and cost
+// nothing; an unprompted `announce` is bounded by `announcements_per_hour`,
+// while the thread-lifecycle posts (pickup, verdict, re-round, superseded)
+// answer one PR's real event and are bounded only by their idem key.
+
+/**
+ * Successful `kind = 'reply'` posts into one thread inside the window — the
+ * per-thread conversational cap.
+ *
+ * StateStore.slackThreadPostsBetween cannot express the kind filter (and
+ * src/state.ts is owned elsewhere), so this reads the same table directly, the
+ * way slack/reply.ts's `threadIsKnown` already does. It stays a pure read.
+ */
+export function threadReplyCount(
+  store: StateStore,
+  threadTs: string,
+  sinceIso: string,
+  untilIso: string,
+): number {
+  return (
+    store.db
+      .prepare(
+        "SELECT COUNT(*) AS c FROM slack_posts WHERE ok = 1 AND kind = 'reply' AND thread_ts = ? AND posted_at >= ? AND posted_at < ?",
+      )
+      .get(threadTs, sinceIso, untilIso) as { c: number }
+  ).c;
+}
+
+export interface ReplyDecision {
+  allow: boolean;
+  cap?: ReplyCap;
+  reason?: string;
+  day: string;
+  /** Conversational replies already made today, channel-wide. */
+  used: number;
+  /** Conversational replies already made into this thread today. */
+  threadUsed: number;
+}
+
+/**
+ * May the daemon post this reply? Three guards, cheapest first: the shared
+ * post ledger (a spent `idem_key` means the message is already in the channel
+ * — a retry must never double-post), the channel-wide daily post ceiling
+ * (`daily_turns`, since every conversational post follows a turn), and the
+ * per-thread `thread_replies_per_day`.
+ *
+ * BOTH budgets count `kind = 'reply'` ONLY. Lifecycle posts are labelled
+ * `pickup` / `verdict` / `announce`; letting them in would mean a PR that runs
+ * `thread_replies_per_day` rounds silently loses the ability to answer a human
+ * in its own thread for the rest of the day. Unprompted daemon announcements
+ * are bounded by `announcements_per_hour` instead (see decideAnnouncement);
+ * the thread-lifecycle posts by their idem key alone.
+ */
+export function decideReply(
+  store: StateStore,
+  cfg: Config,
+  input: { threadTs?: string | null; idemKey?: string },
+  now: Date = new Date(),
+): ReplyDecision {
+  const { daily_turns, thread_replies_per_day } = cfg.slack.policy;
+  const w = policyWindow(cfg, now);
+  const used = store.slackPostsBetween(w.startIso, w.endIso, "reply");
+  const threadUsed = input.threadTs
+    ? threadReplyCount(store, input.threadTs, w.startIso, w.endIso)
+    : 0;
+  const base = { day: w.day, used, threadUsed };
+  if (input.idemKey && store.slackPost(input.idemKey)) {
+    return {
+      ...base,
+      allow: false,
+      cap: "idempotent",
+      reason: `already posted (idem_key ${input.idemKey})`,
+    };
+  }
+  if (used >= daily_turns) {
+    return {
+      ...base,
+      allow: false,
+      cap: "daily_posts",
+      reason: `Slack daily post cap reached (${used}/${daily_turns})`,
+    };
+  }
+  if (input.threadTs && threadUsed >= thread_replies_per_day) {
+    return {
+      ...base,
+      allow: false,
+      cap: "thread_replies_per_day",
+      reason: `thread reply cap reached (${threadUsed}/${thread_replies_per_day})`,
+    };
+  }
+  return { ...base, allow: true };
+}
+
+// ---- announcement admission (cause switch + cooldown + hourly limiter) ---
+
+/** Per-PR cause key: one stuck PR must never silence another. */
+export function announcementKey(cause: string, pr?: number | null): string {
+  return pr === null || pr === undefined ? cause : `${cause}:${pr}`;
+}
+
+/** The cause's own switch + cooldown; unlisted causes take the default. */
+export function causePolicy(cfg: Config, cause: string): SlackCausePolicy {
+  return (
+    cfg.slack.policy.causes[cause] ?? {
+      enabled: true,
+      cooldown_min: cfg.slack.policy.default_cooldown_min,
+    }
+  );
+}
+
+export type AnnouncementBlock = "disabled" | "per_hour" | "cooldown";
+
+export interface AnnouncementDecision {
+  allow: boolean;
+  /** The per-PR cooldown key this decision was taken against. */
+  key: string;
+  /** True when a genuine escalation spent today's one cooldown bypass. */
+  bypass: boolean;
+  block?: AnnouncementBlock;
+  reason?: string;
+  /** Repeats swallowed inside the current cooldown window (0 when firing). */
+  folds?: number;
+}
+
+/**
+ * The rolling-hour announcement ceiling, read from the claimed `slack_posts`
+ * rows. EVERY daemon-authored post COUNTS here — `pickup` and `verdict` are as
+ * visible in the channel as an `announce` — but only an unprompted
+ * announcement is REFUSED by it: the thread-lifecycle posts answer one PR's
+ * real event and are never held back (announce.ts header). Expressed as "all
+ * posts minus replies" so a kind added later is counted by default rather
+ * than silently exempt. Read at admission (decideAnnouncement)
+ * AND again when an admitted announcement claims its row (announce.ts
+ * postNow): admission does not reserve a slot, so two announcements admitted
+ * before either claims would otherwise both post at cap-1.
+ */
+export function hourlyCeiling(
+  store: StateStore,
+  cfg: Config,
+  now: Date,
+): { reached: boolean; reason: string } {
+  const perHour = cfg.slack.policy.announcements_per_hour;
+  const hourAgo = new Date(now.getTime() - 3_600_000).toISOString();
+  const recent = store.slackPostsSince(hourAgo) - store.slackPostsSince(hourAgo, "reply");
+  return {
+    reached: recent >= perHour,
+    reason: `announcement rate cap reached (${recent}/${perHour} in the last hour)`,
+  };
+}
+
+/**
+ * Decide *and record*: on a fire the cooldown row is stamped, on a suppressed
+ * repeat the fold counter grows — the same mutate-on-decide contract as
+ * AlertPolicy.decide, so a caller can never fire without paying the cooldown.
+ * A disabled cause and an hour-limiter refusal write nothing: neither is a
+ * "we already told you", so the cause stays free to speak later.
+ */
+export function decideAnnouncement(
+  store: StateStore,
+  cfg: Config,
+  input: { cause: string; pr?: number | null; escalated?: boolean },
+  now: Date = new Date(),
+): AnnouncementDecision {
+  const key = announcementKey(input.cause, input.pr);
+  const policy = causePolicy(cfg, input.cause);
+  if (!policy.enabled) {
+    return {
+      allow: false,
+      key,
+      bypass: false,
+      block: "disabled",
+      reason: `cause '${input.cause}' is disabled`,
+    };
+  }
+
+  const ceiling = hourlyCeiling(store, cfg, now);
+  if (ceiling.reached) {
+    return {
+      allow: false,
+      key,
+      bypass: false,
+      block: "per_hour",
+      reason: ceiling.reason,
+    };
+  }
+
+  const w = policyWindow(cfg, now);
+  const prev = store.slackCooldown(key);
+  // A row from an earlier policy day is not "already told you today": the day
+  // rollover resets the fold counter and the escalation bypass with it.
+  const sameDay = prev !== undefined && prev.day === w.day;
+  if (!sameDay) {
+    store.recordSlackCooldownFire(key, w.day);
+    return { allow: true, key, bypass: false, folds: 0 };
+  }
+  const elapsedMin = (now.getTime() - Date.parse(prev.last_fired_at)) / 60_000;
+  if (elapsedMin >= policy.cooldown_min) {
+    store.recordSlackCooldownFire(key, w.day);
+    return { allow: true, key, bypass: false, folds: 0 };
+  }
+  if (input.escalated && prev.bypassed === 0) {
+    store.recordSlackCooldownFire(key, w.day, true);
+    return { allow: true, key, bypass: true, folds: 0 };
+  }
+  const folds = store.foldSlackCooldown(key);
+  return {
+    allow: false,
+    key,
+    bypass: false,
+    block: "cooldown",
+    reason: `cooldown for '${key}' (${elapsedMin.toFixed(1)}/${policy.cooldown_min} min, folded ×${folds})`,
+    folds,
+  };
+}
+
+// ---- ledger helper --------------------------------------------------------
+
+/**
+ * Claim an idempotence key before posting. Returns false when the key was
+ * already spent — the caller must then NOT call Slack. The row is settled with
+ * the Slack-assigned ts (or the failure) via StateStore.settleSlackPost.
+ */
+export function claimPost(
+  store: StateStore,
+  claim: {
+    idem_key: string;
+    kind: SlackPostKind;
+    pr?: number | null;
+    thread_ts?: string | null;
+    chars?: number;
+  },
+): boolean {
+  return store.recordSlackPost(claim);
+}

package/src/slack/reply.ts

@@ -0,0 +1,201 @@
+// `slack_reply` — the overseer's only way to speak in Slack.
+//
+// The session never holds a Slack token and never names a channel: it writes a
+// command file with a thread ts and some text, and this executor decides
+// whether that becomes a message. Five guards, all in daemon code:
+//
+//   channel binding  the channel is always cfg.slack.channel; the command has
+//                    no channel field, so a wrong channel is unrepresentable.
+//   thread known     the thread must be one we opened or one we were spoken to
+//                    in — the bot cannot cold-start a conversation.
+//   caps             slack/policy.decideReply: the channel's daily posts and
+//                    the thread's daily replies, same ledger as every other post.
+//   length           truncated at cfg.slack.max_reply_chars.
+//   idempotence      one post per command file, claimed before the API call.
+//
+// Escaping is not cosmetic: model output goes into a channel with humans in it,
+// so `&<>` are escaped and a `<@U…>` mention is only ever emitted for an id the
+// daemon itself resolved — never one pasted through from the model.
+import type { Config } from "../config.js";
+import type { FileOutcome } from "../improvements.js";
+import type { StateStore } from "../state.js";
+// src/slack/messages.ts is the declared wording owner and owns the ONE
+// escaping implementation (`&` first, or the other two double-escape).
+import { escapeMrkdwn } from "./messages.js";
+import { claimPost, decideReply } from "./policy.js";
+import type { SlackWebApi } from "./types.js";
+
+/** Slack message ts, always "1712345678.123456". */
+export const SLACK_TS_RE = /^\d{10}\.\d{6}$/;
+
+export const TRUNCATION_SUFFIX = "…(truncated)";
+
+/**
+ * Escape + truncate RAW model text into a Slack-safe string of at most `max`
+ * characters.
+ *
+ * ORDER IS LOAD-BEARING: escaping first and slicing after can cut a `&amp;` in
+ * half and leave a literal `&am` in the channel, so the raw text is sliced
+ * first and escaped after — an entity is therefore always whole.
+ *
+ * PRECEDENCE, when escaping inflates the text back over the limit (a text of
+ * all `&` grows 5×): `max` WINS. `cfg.slack.max_reply_chars` is a hard channel
+ * budget, so the slice point is chosen against the ESCAPED length — the longest
+ * raw prefix whose escaped form plus the marker still fits. That costs
+ * characters of content, never correctness of the limit.
+ */
+export function truncateReply(text: string, max: number): string {
+  if (max <= 0) return "";
+  const whole = escapeMrkdwn(text);
+  if (whole.length <= max) return whole;
+  // A limit too small for the marker keeps the marker off entirely rather than
+  // spending the whole budget saying "truncated".
+  const budget = max <= TRUNCATION_SUFFIX.length ? max : max - TRUNCATION_SUFFIX.length;
+  const suffix = max <= TRUNCATION_SUFFIX.length ? "" : TRUNCATION_SUFFIX;
+  // Longest raw prefix that fits AFTER escaping. Escaping is monotonic in the
+  // prefix length, so a binary search is exact.
+  let lo = 0;
+  let hi = text.length;
+  while (lo < hi) {
+    const mid = Math.ceil((lo + hi) / 2);
+    if (escapeMrkdwn(text.slice(0, mid)).length <= budget) lo = mid;
+    else hi = mid - 1;
+  }
+  // Never cut a surrogate pair in half either — half an emoji is a mojibake
+  // box, for the same reason half an entity is a stray `&am`.
+  const cut =
+    lo > 0 &&
+    lo < text.length &&
+    text.charCodeAt(lo - 1) >= 0xd800 &&
+    text.charCodeAt(lo - 1) <= 0xdbff
+      ? lo - 1
+      : lo;
+  return escapeMrkdwn(text.slice(0, cut)) + suffix;
+}
+
+/**
+ * Has the daemon ever seen this thread? Either it opened the thread for a PR,
+ * or a PERSON spoke to it there (the message's own ts, or the parent it
+ * replied under). A bot's message or a user-less one (`dropped_echo`) is no
+ * person speaking, so it never makes a thread known. `slack_events` has no
+ * by-ts accessor on StateStore — this is a read-only probe over the table the
+ * router owns.
+ */
+export function threadIsKnown(store: StateStore, channel: string, threadTs: string): boolean {
+  if (store.slackThreadByRoot(channel, threadTs)) return true;
+  const row = store.db
+    .prepare(
+      "SELECT 1 AS hit FROM slack_events WHERE channel = ? AND (ts = ? OR thread_ts = ?) " +
+        "AND disposition != 'dropped_echo' LIMIT 1",
+    )
+    .get(channel, threadTs, threadTs) as { hit: number } | undefined;
+  return row !== undefined;
+}
+
+export interface SlackReplyDeps {
+  cfg: Config;
+  store: StateStore;
+  api: Pick<SlackWebApi, "postMessage">;
+  now?: () => Date;
+  log?: (line: string) => void;
+}
+
+export interface SlackReplyInput {
+  thread: string;
+  text: string;
+  /** Idempotence scope — the command's context `file` (its name without
+   * `.json`, prefixed by the serving watcher's scope; "" for direct calls). */
+  file?: string;
+}
+
+/** FNV-1a, so a direct (file-less) call still gets a stable idem key. */
+function shortHash(s: string): string {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 0x01000193) >>> 0;
+  }
+  return h.toString(16).padStart(8, "0");
+}
+
+/** `reply:<context file>` — one post per command delivery, forever. */
+export function replyIdemKey(input: SlackReplyInput): string {
+  const scope =
+    input.file && input.file.length > 0 ? input.file : `${input.thread}:${shortHash(input.text)}`;
+  return `reply:${scope}`;
+}
+
+/**
+ * Build the `CommandDeps.slackReply` handler. Returns a FileOutcome so every
+ * refusal lands in the command's result file, which is the overseer's only
+ * feedback channel.
+ */
+export function makeSlackReply(
+  deps: SlackReplyDeps,
+): (input: SlackReplyInput) => Promise<FileOutcome> {
+  const now = deps.now ?? (() => new Date());
+  const log = deps.log ?? (() => {});
+  return async (input: SlackReplyInput): Promise<FileOutcome> => {
+    const cfg = deps.cfg;
+    const store = deps.store;
+    if (!cfg.slack.enabled || !cfg.slack.channel) {
+      return { ok: false, reason: "slack is disabled — no channel to reply in" };
+    }
+    const channel = cfg.slack.channel; // never from the command: unrepresentable
+    const thread = input.thread;
+    if (!SLACK_TS_RE.test(thread))
+      return { ok: false, reason: `'thread' ${JSON.stringify(thread)} is not a Slack ts` };
+    if (!threadIsKnown(store, channel, thread)) {
+      return {
+        ok: false,
+        reason: `unknown thread ${thread} — the daemon only replies where it was spoken to`,
+      };
+    }
+
+    const idemKey = replyIdemKey(input);
+    const decision = decideReply(store, cfg, { threadTs: thread, idemKey }, now());
+    if (!decision.allow) {
+      return {
+        ok: false,
+        reason: decision.reason ?? "slack reply refused",
+        cap: decision.cap ?? null,
+      };
+    }
+
+    const text = truncateReply(input.text, cfg.slack.max_reply_chars);
+    if (
+      !claimPost(store, { idem_key: idemKey, kind: "reply", thread_ts: thread, chars: text.length })
+    ) {
+      return { ok: false, reason: `already replied for this command (idem_key ${idemKey})` };
+    }
+
+    let result;
+    try {
+      result = await deps.api.postMessage({ channel, text, thread_ts: thread });
+    } catch (err) {
+      result = { ok: false, error: (err as Error).message };
+    }
+    store.settleSlackPost(idemKey, {
+      ts: result.ts ?? null,
+      ok: result.ok,
+      error: result.error ?? null,
+    });
+    if (!result.ok) {
+      // A failed post is recorded and never blocks anything else.
+      log(`[slack] reply to ${thread} failed: ${result.error ?? "unknown"}`);
+      return { ok: false, reason: `slack post failed: ${result.error ?? "unknown"}` };
+    }
+    const pr = store.slackThreadByRoot(channel, thread)?.pr;
+    if (pr !== undefined) store.touchSlackThread(pr);
+    store.logEvent("slack_reply_posted", pr ?? null, { thread, ts: result.ts, chars: text.length });
+    return {
+      ok: true,
+      thread,
+      ts: result.ts,
+      chars: text.length,
+      // Whether content was cut, never whether the text ends like the marker
+      // (a reply may end so naturally; a tiny limit cuts with no marker).
+      truncated: text !== escapeMrkdwn(input.text),
+    };
+  };
+}