typeclaw 0.28.0 → 0.28.2

package/src/channels/adapters/github/review-state.ts

@@ -0,0 +1,206 @@
+import type { ReviewStateResolver, ReviewStateResult } from '@/channels/types'
+
+import type { GithubAuthContext } from './auth'
+import { GITHUB_API_BASE, githubJsonHeaders } from './auth-pat'
+
+// Answers the re-review stranding guard's question: is the bot's latest
+// EFFECTIVE formal review on this PR a sticky CHANGES_REQUESTED? GitHub clears a
+// same-reviewer CHANGES_REQUESTED only with a later APPROVED or DISMISSED from
+// the same reviewer — a later COMMENTED review does NOT clear it (the PR #644
+// trap). So we walk the bot's own reviews in chronological order, ignore
+// COMMENTED/PENDING, and read the last decisive one.
+export function createGithubReviewStateResolver(deps: {
+  token: (context?: GithubAuthContext) => Promise<string>
+  selfLogin: () => string | null
+  approve: () => boolean
+  fetchImpl?: typeof fetch
+}): ReviewStateResolver {
+  const fetchImpl = deps.fetchImpl ?? fetch
+  return async (req): Promise<ReviewStateResult> => {
+    const approve = deps.approve()
+    if (req.adapter !== 'github') {
+      return { ok: false, error: `unknown adapter: ${req.adapter}`, code: 'unsupported' }
+    }
+    const target = parseTarget(req.workspace, req.chat)
+    if (target === null) {
+      return { ok: false, error: `unparseable github PR target (chat=${req.chat})`, code: 'transient' }
+    }
+    const selfLogin = deps.selfLogin()
+    if (selfLogin === null) {
+      return { ok: false, error: 'github self-identity not resolved; cannot read review state', code: 'transient' }
+    }
+
+    const token = await deps.token({ repoSlug: `${target.owner}/${target.repo}` })
+    const [reviews, reviewDecision] = await Promise.all([
+      fetchSelfReviews(fetchImpl, token, target, selfLogin),
+      fetchReviewDecision(fetchImpl, token, target),
+    ])
+    if (!reviews.ok) return { ok: false, error: reviews.error, code: reviews.code }
+    if (!reviewDecision.ok) return { ok: false, error: reviewDecision.error, code: reviewDecision.code }
+
+    const lastDecisive = reviews.states.filter(isDecisive).at(-1) ?? null
+    return {
+      ok: true,
+      selfBlocking: lastDecisive === 'CHANGES_REQUESTED',
+      approve,
+      ...(reviewDecision.reviewDecision !== null ? { reviewDecision: reviewDecision.reviewDecision } : {}),
+    }
+  }
+}
+
+type Target = { owner: string; repo: string; prNumber: number }
+
+function parseTarget(workspace: string, chat: string): Target | null {
+  const [owner, repo, ...rest] = workspace.split('/')
+  if (owner === undefined || owner === '' || repo === undefined || repo === '' || rest.length > 0) return null
+  const m = /^pr:(\d+)$/.exec(chat)
+  if (m === null) return null
+  const prNumber = Number(m[1])
+  if (!Number.isSafeInteger(prNumber) || prNumber <= 0) return null
+  return { owner, repo, prNumber }
+}
+
+type SelfReviewsResult =
+  | { ok: true; states: string[] }
+  | { ok: false; error: string; code: 'not-found' | 'permission-denied' | 'transient' }
+
+type ReviewDecision = 'APPROVED' | 'CHANGES_REQUESTED' | 'REVIEW_REQUIRED'
+
+type ReviewDecisionResult =
+  | { ok: true; reviewDecision: ReviewDecision | null }
+  | { ok: false; error: string; code: 'not-found' | 'permission-denied' | 'transient' }
+
+async function fetchSelfReviews(
+  fetchImpl: typeof fetch,
+  token: string,
+  target: Target,
+  selfLogin: string,
+): Promise<SelfReviewsResult> {
+  const states: string[] = []
+  let url: string | null =
+    `${GITHUB_API_BASE}/repos/${target.owner}/${target.repo}/pulls/${target.prNumber}/reviews?per_page=100`
+  while (url !== null) {
+    let response: Response
+    try {
+      response = await fetchImpl(url, { headers: githubJsonHeaders(token) })
+    } catch (err) {
+      return { ok: false, error: err instanceof Error ? err.message : String(err), code: 'transient' }
+    }
+    if (!response.ok) {
+      const text = await response.text().catch(() => '')
+      return {
+        ok: false,
+        error: `GitHub reviews ${response.status}${text !== '' ? `: ${text}` : ''}`,
+        code: classifyStatus(response.status),
+      }
+    }
+    const page = (await response.json().catch(() => null)) as ReviewRow[] | null
+    if (page === null) return { ok: false, error: 'GitHub reviews returned non-JSON', code: 'transient' }
+    for (const row of page) {
+      if (typeof row.state !== 'string') continue
+      const login = row.user?.login ?? null
+      if (login === null) continue
+      const isBot = row.user?.type === 'Bot'
+      if (!isSelfReviewer(login, isBot, selfLogin)) continue
+      states.push(row.state)
+    }
+    url = nextLink(response.headers.get('link'))
+  }
+  return { ok: true, states }
+}
+
+async function fetchReviewDecision(
+  fetchImpl: typeof fetch,
+  token: string,
+  target: Target,
+): Promise<ReviewDecisionResult> {
+  let response: Response
+  try {
+    response = await fetchImpl(`${GITHUB_API_BASE}/graphql`, {
+      method: 'POST',
+      headers: githubJsonHeaders(token),
+      body: JSON.stringify({
+        query:
+          'query($owner:String!,$repo:String!,$number:Int!){repository(owner:$owner,name:$repo){pullRequest(number:$number){reviewDecision}}}',
+        variables: { owner: target.owner, repo: target.repo, number: target.prNumber },
+      }),
+    })
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err), code: 'transient' }
+  }
+  if (!response.ok) {
+    const text = await response.text().catch(() => '')
+    return {
+      ok: false,
+      error: `GitHub reviewDecision ${response.status}${text !== '' ? `: ${text}` : ''}`,
+      code: classifyStatus(response.status),
+    }
+  }
+  const raw = (await response.json().catch(() => null)) as ReviewDecisionResponse | null
+  if (raw === null) return { ok: false, error: 'GitHub reviewDecision returned non-JSON', code: 'transient' }
+  if (Array.isArray(raw.errors) && raw.errors.length > 0) {
+    return {
+      ok: false,
+      error: `GitHub reviewDecision errors: ${raw.errors.map(describeGraphqlError).join('; ')}`,
+      code: 'transient',
+    }
+  }
+  const value = raw.data?.repository?.pullRequest?.reviewDecision ?? null
+  if (value === null || isReviewDecision(value)) return { ok: true, reviewDecision: value }
+  return { ok: false, error: `GitHub reviewDecision returned unknown value: ${String(value)}`, code: 'transient' }
+}
+
+// A formal CHANGES_REQUESTED is sticky until a later APPROVED/DISMISSED; only
+// these three states decide the block. COMMENTED and PENDING are non-deciding
+// noise that must NOT shadow an earlier CHANGES_REQUESTED.
+const DECISIVE = new Set(['CHANGES_REQUESTED', 'APPROVED', 'DISMISSED'])
+
+function isDecisive(state: string): boolean {
+  return DECISIVE.has(state)
+}
+
+// A GitHub App's own login differs across REST (`slug[bot]`) and GraphQL (bare
+// `slug`). The REST reviews endpoint returns `slug[bot]` for the App, but the
+// suffix-strip must be gated on the reviewer actually being a Bot: a human User
+// can own the bare slug as a login, and stripping `[bot]` off the App's
+// selfLogin to match a human would wrongly attribute their review to the bot.
+const BOT_LOGIN_SUFFIX = '[bot]'
+
+function isSelfReviewer(login: string, isBot: boolean, selfLogin: string): boolean {
+  if (isBot) return normalizeBotLogin(login) === normalizeBotLogin(selfLogin)
+  return login === selfLogin
+}
+
+function normalizeBotLogin(login: string): string {
+  return login.endsWith(BOT_LOGIN_SUFFIX) ? login.slice(0, -BOT_LOGIN_SUFFIX.length) : login
+}
+
+function nextLink(linkHeader: string | null): string | null {
+  if (linkHeader === null) return null
+  for (const part of linkHeader.split(',')) {
+    const m = /<([^>]+)>;\s*rel="next"/.exec(part)
+    if (m !== null) return m[1] ?? null
+  }
+  return null
+}
+
+function classifyStatus(status: number): 'not-found' | 'permission-denied' | 'transient' {
+  if (status === 401 || status === 403) return 'permission-denied'
+  if (status === 404) return 'not-found'
+  return 'transient'
+}
+
+type ReviewRow = { id?: number; state?: unknown; user?: { login?: string; type?: string } }
+
+type ReviewDecisionResponse = {
+  data?: { repository?: { pullRequest?: { reviewDecision?: unknown } | null } | null }
+  errors?: Array<{ message?: unknown }>
+}
+
+function isReviewDecision(value: unknown): value is ReviewDecision {
+  return value === 'APPROVED' || value === 'CHANGES_REQUESTED' || value === 'REVIEW_REQUIRED'
+}
+
+function describeGraphqlError(error: { message?: unknown }): string {
+  return typeof error.message === 'string' ? error.message : JSON.stringify(error)
+}

package/src/channels/github-rereview-guard.ts

@@ -0,0 +1,100 @@
+import { classifyReviewClaim, isPositiveWarnCloseout } from './github-review-claim'
+import type { ReviewStateResult } from './types'
+
+// The re-review stranding guard. A bot that resolves a review thread (or posts a
+// close-out ack) while it still holds its own sticky CHANGES_REQUESTED leaves the
+// PR blocked forever — the resolve/ack carries no review state, so GitHub's
+// reviewDecision never clears (PR #644). This guard blocks that close-out and
+// tells the model to land a formal APPROVE / dismissal first.
+//
+// It is the same enforcement seam as the false-receipt guard and the
+// resolve-thread author check: BLOCK and instruct, never act on the model's
+// behalf — the runtime cannot prove a semantic approval from "one thread closed".
+
+export type RereviewGuardInput = {
+  adapter: string
+  chat: string
+  thread: string | null
+  text: string | undefined
+  wantsResolve: boolean
+  // A mid-turn status reply (continue:true) is not the turn's receipt, so it
+  // suppresses the warn-tier escalation below — but never the explicit resolve,
+  // which is a real mutation. Mirrors the false-receipt guard's continue rule.
+  isContinue: boolean
+  getReviewState: (req: { adapter: 'github'; workspace: string; chat: string }) => Promise<ReviewStateResult>
+  workspace: string
+}
+
+export type RereviewGuardDecision = { block: false } | { block: true; reason: string }
+
+const ALLOW: RereviewGuardDecision = { block: false }
+
+export async function evaluateRereviewGuard(input: RereviewGuardInput): Promise<RereviewGuardDecision> {
+  if (input.adapter !== 'github') return ALLOW
+  if (!/^pr:\d+$/.test(input.chat)) return ALLOW
+  // No `thread === null` exemption: a top-level PR comment carries no thread but
+  // a close-out ack in it ("Verified — that closes it") strands the block just
+  // as a thread reply would. Only the resolve ACTION needs a thread; the
+  // text-claim path fires regardless (caught by isCloseoutAttempt below).
+  if (!isCloseoutAttempt(input)) return ALLOW
+
+  const state = await input.getReviewState({ adapter: 'github', workspace: input.workspace, chat: input.chat })
+
+  // Fail closed: an unverifiable review state is treated as a live block, so the
+  // bot never strands a re-review on a transient API failure.
+  if (!state.ok) return { block: true, reason: unverifiableReason(state.error) }
+  if (!state.selfBlocking) {
+    if (state.reviewDecision === 'REVIEW_REQUIRED' && isPositiveWarnCloseout(input.text ?? '')) {
+      return { block: true, reason: INITIAL_REVIEW_REQUIRED }
+    }
+    return ALLOW
+  }
+
+  return { block: true, reason: state.approve ? STICKY_BLOCK_APPROVE_ENABLED : STICKY_BLOCK_APPROVE_DISABLED }
+}
+
+// Trigger when the model asks to resolve a thread (only meaningful with a
+// thread), OR when its reply reads as a close-out/verdict claim — the latter
+// strands the block whether or not it sits in a thread, so it fires for any PR
+// chat. Unlike the pure false-receipt classifier, this guard has the objective
+// review state available, so an approval-shaped warn reply ("looks good"/"lgtm")
+// is escalated to a closeout too: it only blocks when the bot actually holds a
+// live CHANGES_REQUESTED, so casual approval-shaped chatter on an unblocked PR
+// still posts. Only POSITIVE warn phrases escalate — negative ones ("needs
+// changes", "still needs work") re-assert a block rather than strand it, so they
+// stay non-firing. `continue:true` exempts the warn escalation (mid-turn
+// planning, not the receipt), but never the explicit resolve action. Plain
+// `ignore` text never fires.
+function isCloseoutAttempt(input: RereviewGuardInput): boolean {
+  if (input.wantsResolve && input.thread !== null) return true
+  const claim = classifyReviewClaim(input.text ?? '')
+  if (claim === 'block-resolve' || claim === 'block-approve') return true
+  return !input.isContinue && isPositiveWarnCloseout(input.text ?? '')
+}
+
+function unverifiableReason(error: string): string {
+  return (
+    'Could not verify whether your prior CHANGES_REQUESTED on this PR is still live ' +
+    `(${error}). Refusing to close out the thread while the block state is unknown — ` +
+    'retry once the GitHub API is reachable, or land a formal review verdict first.'
+  )
+}
+
+const STICKY_BLOCK_APPROVE_ENABLED =
+  'You still hold a CHANGES_REQUESTED on this PR. Resolving the thread (or posting a close-out ack) ' +
+  'does NOT clear it — only a fresh formal review does. Submit `APPROVE` via ' +
+  '`gh api -X POST /repos/<owner>/<repo>/pulls/<N>/reviews` (event: APPROVE) if the blockers are fixed, ' +
+  'or `REQUEST_CHANGES` if not, THEN resolve the thread / reply.'
+
+const STICKY_BLOCK_APPROVE_DISABLED =
+  'You still hold a CHANGES_REQUESTED on this PR and resolving the thread does NOT clear it. ' +
+  'Approval is disabled for this agent (channels.github.review.approve: false), so you cannot APPROVE — ' +
+  'dismiss your prior review via ' +
+  '`gh api -X PUT /repos/<owner>/<repo>/pulls/<N>/reviews/<review_id>/dismissals -f message="..." -f event=DISMISS` ' +
+  'if the blockers are fixed (or submit REQUEST_CHANGES if not), THEN resolve the thread / reply.'
+
+const INITIAL_REVIEW_REQUIRED =
+  'This PR still requires a formal GitHub review. A flat `LGTM` / `looks good` PR comment does not create ' +
+  'review state, so it leaves the PR awaiting review. Submit the reviewer verdict via ' +
+  '`gh api -X POST /repos/<owner>/<repo>/pulls/<N>/reviews` with event `APPROVE` when approval is enabled, ' +
+  'or event `COMMENT` when approval is disabled, then narrate only if needed.'

package/src/channels/github-review-claim.ts

@@ -24,15 +24,16 @@ const BLOCK_REQUEST_CHANGES: readonly RegExp[] = [
   /\bthis is blocked\b/,
 ]
 
-// Only consulted by the caller when thread!=null (a review thread). Bare
-// "resolved" is intentionally NOT here — it collides with the warn-tier "looks
-// resolved?"; resolve claims must carry a definite marker (marked/that/this/
-// thanks) or a verify clause.
+// Bare "resolved" is intentionally NOT here — it collides with the warn-tier
+// "looks resolved?"; resolve claims must carry a definite marker (marked/that/
+// this/thanks) or a verify clause. "that/this closes it" is the canonical PR
+// #644 incident phrasing and must classify as a close-out claim.
 const BLOCK_RESOLVE: readonly RegExp[] = [
   /\bmarked resolved\b/,
   /\bthread resolved\b/,
   /\bthat resolves it\b/,
   /\bthis resolves it\b/,
+  /\b(that|this) closes it\b/,
   /\bclosing this out\b/,
   /\bconfirmed fixed\b/,
   // verify clause + a fix/resolve verb, allowing a short gap ("verified at <sha>, that fixes it").
@@ -40,19 +41,26 @@ const BLOCK_RESOLVE: readonly RegExp[] = [
   /\b(thanks,?|fixed,?) (looks )?resolved\b/,
 ]
 
-// Casual phrasing that might be chatter, not a formal close-out: allow + nudge.
-const WARN: readonly RegExp[] = [
+// Approval/resolve-shaped warn phrases: casual chatter that, on a PR the bot is
+// still blocking, READS as a close-out and so can strand the block. Split out so
+// the re-review guard can escalate only these — never the negative warn phrases
+// below, which re-assert a block rather than strand it.
+const WARN_POSITIVE_CLOSEOUT: readonly RegExp[] = [
   /\blgtm\b/,
   /\blooks good\b/,
   /\blooks fine\b/,
   /\bseems fine\b/,
   /\bshould be (fine|good)\b/,
-  /\bneeds changes\b/,
-  /\bstill needs work\b/,
   /\blooks resolved\b/,
   /\bseems resolved\b/,
 ]
 
+// Negative warn phrases re-assert a block ("not done yet") instead of closing it
+// out, so they are NOT close-out attempts — the re-review guard must ignore them.
+const WARN_NEGATIVE: readonly RegExp[] = [/\bneeds changes\b/, /\bstill needs work\b/]
+
+const WARN: readonly RegExp[] = [...WARN_POSITIVE_CLOSEOUT, ...WARN_NEGATIVE]
+
 // Negation / future-intent / past-reference markers DEMOTE a positive match to
 // ignore. Blocking "I haven't approved" / "I'll approve" / "approved it earlier"
 // (answering a question) is the worst false-positive class, so it is checked first.
@@ -60,15 +68,40 @@ const DEMOTE_TO_IGNORE: readonly RegExp[] = [
   /\b(haven'?t|have not|did ?n'?t|did not|not yet|never)\b[^.!?]*\b(approv|request|resolv|block)/,
   /\b(can'?t|cannot|won'?t|will not|wouldn'?t)\b[^.!?]*\b(approv|request|resolv|block)/,
   /\bnot (approved|resolved|blocked|requesting)\b/,
+  /\b(not|no longer|hardly|barely)\b[^.!?]*\b(lgtm|looks good|looks fine|seems fine|should be (fine|good)|looks resolved|seems resolved)\b/,
   /\b(i'?ll|i will|going to|gonna|about to|planning to)\b[^.!?]*\b(approv|review|request|resolv)/,
   /\b(approved|resolved|requested changes)\b[^.!?]*\b(earlier|already|yesterday|before|last (review|time)|previously)\b/,
+  /\b(pre|self|co|re|un|non|ai|admin|user|machine|auto) approved\b/,
 ]
 
+const QUESTION_CONTEXT =
+  /(?:^|\b)(who|what|when|where|why|how|was|were|is|are|did|do|does|has|have|can|could|would|should)\b[^.!?]*\?/
+
 export function classifyReviewClaim(rawText: string): ReviewClaim {
-  const text = normalize(rawText)
-  if (text === '') return 'ignore'
+  const segments = claimSegments(rawText)
+  if (segments.length === 0) return 'ignore'
+
+  const claims = segments.map(classifySegment)
+
+  if (claims.includes('block-approve')) return 'block-approve'
+  if (claims.includes('block-request-changes')) return 'block-request-changes'
+  if (claims.includes('block-resolve')) return 'block-resolve'
+  if (claims.includes('warn')) return 'warn'
+  return 'ignore'
+}
 
+// True only for warn-tier replies whose phrasing reads as an approval/resolve
+// close-out (e.g. "looks good", "lgtm"), excluding negative warn phrases like
+// "needs changes" that re-assert a block. The re-review guard uses this to
+// escalate just the stranding-shaped warns, not the whole warn bucket.
+export function isPositiveWarnCloseout(rawText: string): boolean {
+  if (classifyReviewClaim(rawText) !== 'warn') return false
+  return claimSegments(rawText).some((segment) => WARN_POSITIVE_CLOSEOUT.some((re) => re.test(segment)))
+}
+
+function classifySegment(text: string): ReviewClaim {
   if (DEMOTE_TO_IGNORE.some((re) => re.test(text))) return 'ignore'
+  if (QUESTION_CONTEXT.test(text)) return 'ignore'
 
   // Block-tier wins over warn-tier: an unambiguous "approved" in a casual message
   // is still a formal claim.
@@ -79,6 +112,21 @@ export function classifyReviewClaim(rawText: string): ReviewClaim {
   return 'ignore'
 }
 
+function claimSegments(text: string): string[] {
+  return redactQuotedAndCode(text)
+    .split(/(?<=[.!?])\s+|\n+/)
+    .map(normalize)
+    .filter((segment) => segment !== '')
+}
+
+function redactQuotedAndCode(text: string): string {
+  return text
+    .replace(/```[\s\S]*?```/g, ' ')
+    .replace(/`[^`\n]*`/g, ' ')
+    .replace(/"[^"\n]*"|“[^”\n]*”|‘[^’\n]*’/g, ' ')
+    .replace(/^\s*>.*$/gm, ' ')
+}
+
 // Strips markdown/emoji noise so "**Approved!**" and "approved" classify alike,
 // keeping apostrophes + sentence punctuation that the negation regexes rely on.
 function normalize(text: string): string {