typeclaw 0.27.0 → 0.28.1

package/src/channels/router.ts

@@ -32,6 +32,7 @@ import {
   StickyLedger,
   type EngagementDecision,
 } from './engagement'
+import { resetReviewTurn } from './github-review-turn-ledger'
 import {
   MEMBERSHIP_COLD_FETCH_TIMEOUT_MS,
   type MembershipCount,
@@ -74,6 +75,9 @@ import type {
   ReactionRequest,
   ReactionResult,
   ResolvedChannelNames,
+  ReviewStateRequest,
+  ReviewStateResolver,
+  ReviewStateResult,
   ReviewThreadResolveRequest,
   ReviewThreadResolveResult,
   ReviewThreadResolver,
@@ -177,6 +181,44 @@ export const MAX_POLICY_DENIED_CHANNEL_SENDS_PER_TURN = 3
 // including reasoning). Deliberately NOT lowered in `providers.ts`, where
 // `maxTokens` is the model's true capability that compaction math reads.
 export const CHANNEL_MAX_OUTPUT_TOKENS = 4096
+// Ceiling on automatic re-prompts for a turn that ended with NO user-facing
+// reply AND no attempted send — the pure "the model burned its budget thinking
+// and produced nothing" failure. The canonical trigger is Fireworks'
+// kimi-k2p6-turbo spiraling into a long reasoning loop on an ambiguous request
+// until it hits CHANNEL_MAX_OUTPUT_TOKENS (`stopReason: 'length'`); the same
+// path also catches a provider/router `aborted` leaf that left no recoverable
+// prose. Each retry injects EMPTY_TURN_RETRY_NUDGE as a reminder-only turn (no
+// new inbound) so `drain()` re-runs `session.prompt()` against the same branch.
+// Bounded because a genuinely stuck model would otherwise re-loop forever; on
+// exhaustion the user gets EMPTY_TURN_FALLBACK_TEXT instead of dead air. Reset
+// at turn start alongside `turnSeq`. Deliberately NOT applied to turns that
+// ATTEMPTED a send this turn (skip-locked or policy-denied) — those already
+// thrashed the send path, so a re-prompt would just re-thrash; they skip
+// straight to the fallback. See validateChannelTurn's candidate===null branch.
+export const MAX_EMPTY_TURN_RETRIES = 2
+// Reminder-only nudge injected before an empty-turn retry. Uses the repo's
+// SYSTEM MESSAGE framing (see composeTurnPrompt) so persona-rich models do not
+// reply to the notice itself. Neutral by design: it asks for a direct reply
+// without prescribing length or tone, matching the chosen "just retry" posture.
+export const EMPTY_TURN_RETRY_NUDGE = [
+  '---',
+  '**[SYSTEM MESSAGE — not from a human]**',
+  '',
+  'Your previous turn ended without sending any reply to the channel. This is',
+  'an automated signal from the channel router, not a message from anyone in',
+  'the chat. **Do not acknowledge or reply to this notice itself.**',
+  '',
+  'Respond to the last user message now with a direct answer via your channel',
+  'reply tool. If you genuinely have nothing to say, reply with `NO_REPLY`.',
+  '',
+  '---',
+].join('\n')
+// Posted to the channel (via the `source:'system'` one-shot bypass) when an
+// empty turn cannot be recovered AND retries are exhausted (or are skipped
+// because the turn thrashed the send path). Replaces the historical silent
+// drop so the human is never left staring at dead air after a degenerate turn.
+export const EMPTY_TURN_FALLBACK_TEXT =
+  "⚠️ I got stuck putting together a reply and couldn't finish. Could you rephrase or try again?"
 // Rolling window for outbound send-rate telemetry. 5s matches Discord's
 // rate-limit shape (5 msg / 5 s / channel) and comfortably covers Slack's
 // 1 msg/s sustained. The window is observational; exceeding the burst
@@ -480,6 +522,14 @@ type LiveSession = {
   // livelock the byte-identical loop-guard misses. Reset at turn start and
   // cleared per-target on a successful delivery to that target.
   policyDeniedToolSendsThisTurn: Map<string, number>
+  // Count of automatic empty-turn re-prompts already spent on the CURRENT
+  // logical turn, bounded by `MAX_EMPTY_TURN_RETRIES`. A "logical turn" spans
+  // the original user batch plus any router-injected retry nudges, so this is
+  // reset only when a real user/reminder batch starts a fresh turn — NOT on the
+  // reminder-only iterations the retry itself queues. `validateChannelTurn`
+  // increments it before injecting EMPTY_TURN_RETRY_NUDGE and reads it to decide
+  // retry-vs-fallback. See the candidate===null branch.
+  emptyTurnRetries: number
   // Stamped by `markTurnSkipped` (called from the `skip_response` tool)
   // with the current `turnSeq`. Read at the top of `validateChannelTurn`:
   // if it matches the just-completed turn, recovery is skipped entirely
@@ -634,6 +684,12 @@ export type ChannelRouter = {
   registerReviewThreadResolver: (adapter: ChannelKey['adapter'], resolver: ReviewThreadResolver) => void
   unregisterReviewThreadResolver: (adapter: ChannelKey['adapter'], resolver: ReviewThreadResolver) => void
   resolveReviewThread: (req: ReviewThreadResolveRequest) => Promise<ReviewThreadResolveResult>
+  // Re-review stranding guard support: answers whether the bot still holds a
+  // blocking CHANGES_REQUESTED on a PR. Opt-in per adapter like the thread
+  // resolver; `getReviewState` answers `unsupported` when none is registered.
+  registerReviewStateResolver: (adapter: ChannelKey['adapter'], resolver: ReviewStateResolver) => void
+  unregisterReviewStateResolver: (adapter: ChannelKey['adapter'], resolver: ReviewStateResolver) => void
+  getReviewState: (req: ReviewStateRequest) => Promise<ReviewStateResult>
   lookupInboundAttachment: (args: ChannelKey & { id: number }) => InboundAttachment | null
   listInboundAttachmentIds: (args: ChannelKey) => readonly number[]
   // Execute a command by name against an existing live session, bypassing
@@ -904,6 +960,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
   const historyCallbacks = new Map<ChannelKey['adapter'], Set<HistoryCallback>>()
   const fetchAttachmentCallbacks = new Map<ChannelKey['adapter'], Set<FetchAttachmentCallback>>()
   const reviewThreadResolvers = new Map<ChannelKey['adapter'], ReviewThreadResolver>()
+  const reviewStateResolvers = new Map<ChannelKey['adapter'], ReviewStateResolver>()
   const stickyLedger = new StickyLedger()
   // The /help handler reads the live registry to enumerate commands, so it
   // forward-references `commands`. Safe at runtime — the handler only runs on
@@ -1351,6 +1408,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         successfulSendsAtTurnStart: 0,
         inFlightToolSends: new Map(),
         policyDeniedToolSendsThisTurn: new Map(),
+        emptyTurnRetries: 0,
         skippedTurn: null,
         skipLockedSendTurn: null,
         pendingQuoteCandidate: null,
@@ -1366,6 +1424,30 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       }
       live.unsubProviderErrors = subscribeProviderErrors(created.session, (err) => {
         logger.error(`[channels] ${live.keyId}: LLM call failed: ${err.message}`)
+        // A provider soft-error (rate/usage limit, billing, malformed response)
+        // ends the turn with no assistant text, so the human otherwise sees
+        // silence. Surface the REDACTED `safeMessage` (never the raw provider
+        // text, which can carry response bodies / URLs / tokens) via a 'system'
+        // send — the same one-shot bypass path validateChannelTurn uses, so it
+        // lands regardless of per-turn send caps and skips the duplicate guard.
+        void send(
+          {
+            adapter: live.key.adapter,
+            workspace: live.key.workspace,
+            chat: live.key.chat,
+            thread: live.key.thread,
+            text: `⚠️ ${err.safeMessage}`,
+          },
+          { source: 'system' },
+        )
+          .then((result) => {
+            if (!result.ok) {
+              logger.warn(`[channels] ${live.keyId}: provider-error notice send failed: ${result.error}`)
+            }
+          })
+          .catch((sendErr) => {
+            logger.warn(`[channels] ${live.keyId}: provider-error notice send threw: ${describe(sendErr)}`)
+          })
       })
       live.unsubTodoOutcome = created.session.subscribe((event: unknown) => {
         const usage = extractTurnUsage(event)
@@ -1795,6 +1877,11 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
           live.consecutiveSends.clear()
           live.lastSentText.clear()
           live.pendingQuoteCandidate = captureQuoteCandidate(live.key.adapter, batch, observed)
+          // A real user batch starts a fresh logical turn → restore the full
+          // empty-turn retry budget. Reset here (batch.length > 0) and NOT in
+          // the per-prompt block below, so the reminder-only iterations the
+          // retry itself queues do not refill the budget and loop forever.
+          live.emptyTurnRetries = 0
         } else if (live.lastTurnAuthorId !== null) {
           live.currentTurnEngageReactions = []
           // Reminder-only turn (batch.length === 0, reminders.length > 0):
@@ -1844,6 +1931,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         live.successfulSendsAtTurnStart = successfulSendsBeforePrompt
         live.skipLockedSendTurn = null
         live.policyDeniedToolSendsThisTurn.clear()
+        resetReviewTurn(live.sessionId)
         const isRealUserTurn = batch.length > 0
         await fireSessionTurnStart(live, text)
         try {
@@ -2572,6 +2660,26 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     )
   }
 
+  const registerReviewStateResolver = (adapter: ChannelKey['adapter'], resolver: ReviewStateResolver): void => {
+    reviewStateResolvers.set(adapter, resolver)
+  }
+
+  const unregisterReviewStateResolver = (adapter: ChannelKey['adapter'], resolver: ReviewStateResolver): void => {
+    if (reviewStateResolvers.get(adapter) === resolver) {
+      reviewStateResolvers.delete(adapter)
+    }
+  }
+
+  const getReviewState = async (req: ReviewStateRequest): Promise<ReviewStateResult> => {
+    const resolver = reviewStateResolvers.get(req.adapter)
+    if (resolver === undefined) {
+      return { ok: false, error: `adapter "${req.adapter}" does not support review-state lookup`, code: 'unsupported' }
+    }
+    return await resolver(req).catch(
+      (err): ReviewStateResult => ({ ok: false, error: describe(err), code: 'transient' }),
+    )
+  }
+
   const lookupInboundAttachment = (args: ChannelKey & { id: number }): InboundAttachment | null => {
     const live = liveSessions.get(channelKeyId(args))
     if (live === undefined) return null
@@ -2842,15 +2950,64 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     }
     if (live.successfulChannelSends > successfulSendsBeforePrompt) return
 
+    const postEmptyTurnFallback = async (cause: string): Promise<void> => {
+      logger.warn(`[channels] ${live.keyId} empty_turn_fallback cause=${cause}`)
+      const result = await send(
+        {
+          adapter: live.key.adapter,
+          workspace: live.key.workspace,
+          chat: live.key.chat,
+          thread: live.key.thread,
+          text: EMPTY_TURN_FALLBACK_TEXT,
+        },
+        { source: 'system' },
+      )
+      if (!result.ok) {
+        logger.warn(`[channels] ${live.keyId}: empty-turn fallback send failed: ${result.error}`)
+      }
+    }
+
     const candidate = recoverableAssistantText(live.session)
     if (candidate === null) {
-      // Observability: previously a silent bail-out. The most common cause is a
-      // turn that ends mid-loop with NO assistant message at all (leaf is a
-      // session header / model_change / similar non-message entry, or a session
-      // that just started). Logged at debug-level info so operators can grep for
-      // unexpected silent turns; not warn-level because legitimate empty-state
-      // sessions hit this on every TUI-only check before the first user prompt.
-      logger.info(`[channels] ${live.keyId}: no recoverable assistant text in branch`)
+      // No recoverable assistant prose: the turn ended with no usable reply.
+      // Two distinct shapes, handled differently (Option B):
+      //
+      //   1. The model THRASHED the send path this turn — it tried to send but
+      //      every attempt was denied (skip-locked, or policy-denied/duplicate/
+      //      cap, tracked on skipLockedSendTurn / policyDeniedToolSendsThisTurn).
+      //      Re-prompting would just re-thrash, so skip retry and post the
+      //      user-facing fallback once.
+      //
+      //   2. The PURE reasoning-loop — no send was ever attempted; the model
+      //      burned its budget thinking and produced nothing (the canonical
+      //      kimi `stopReason: 'length'` / `aborted` degeneration). Re-prompt up
+      //      to MAX_EMPTY_TURN_RETRIES with a neutral nudge; on exhaustion, fall
+      //      back. The nudge is injected as a reminder-only turn so drain()'s
+      //      while-loop re-runs session.prompt() against the same branch.
+      //
+      // The legitimate empty-state case (a TUI-only check before any user
+      // prompt, no inbound this turn) is excluded: no batch means no real turn
+      // to retry or apologize for — keep the historical silent bail there.
+      const attemptedSendThisTurn =
+        live.skipLockedSendTurn === live.turnSeq || live.policyDeniedToolSendsThisTurn.size > 0
+
+      // Only a TRUNCATED assistant leaf (length/error/aborted) from a real
+      // conversational turn is a degeneration worth retrying. A cold/empty turn
+      // (no inbound author, or no assistant message at all) keeps the historical
+      // silent bail — re-prompting it would manufacture replies to nothing.
+      if (live.currentTurnAuthorId === null || !assistantLeafTruncated(live.session)) {
+        logger.info(`[channels] ${live.keyId}: no recoverable assistant text in branch`)
+        return
+      }
+      if (!attemptedSendThisTurn && live.emptyTurnRetries < MAX_EMPTY_TURN_RETRIES) {
+        live.emptyTurnRetries++
+        logger.warn(
+          `[channels] ${live.keyId} empty_turn_retry attempt=${live.emptyTurnRetries}/${MAX_EMPTY_TURN_RETRIES}`,
+        )
+        live.pendingSystemReminders.push(EMPTY_TURN_RETRY_NUDGE)
+        return
+      }
+      await postEmptyTurnFallback(attemptedSendThisTurn ? 'send_thrash' : 'retries_exhausted')
       return
     }
 
@@ -3396,6 +3553,9 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     registerReviewThreadResolver,
     unregisterReviewThreadResolver,
     resolveReviewThread,
+    registerReviewStateResolver,
+    unregisterReviewStateResolver,
+    getReviewState,
     lookupInboundAttachment,
     listInboundAttachmentIds,
     executeCommand,
@@ -4107,6 +4267,20 @@ function recoverableAssistantText(
   return null
 }
 
+// True only when the leaf is an assistant message that was CUT OFF mid-output:
+// `length` (hit the token cap — the canonical kimi reasoning-loop), `error`, or
+// `aborted`. This is the precise signature of "the model was producing but got
+// truncated", as distinct from a turn that produced no assistant message at all
+// (leaf undefined / a non-assistant entry), which is a benign empty/cold turn —
+// NOT something to re-prompt. The empty-turn retry guard keys off this so it
+// fires for real degenerations and stays silent for cold sessions.
+function assistantLeafTruncated(session: AgentSession): boolean {
+  const leaf = session.sessionManager.getLeafEntry()
+  if (!leaf || leaf.type !== 'message' || leaf.message.role !== 'assistant') return false
+  const stop = leaf.message.stopReason
+  return stop === 'length' || stop === 'error' || stop === 'aborted'
+}
+
 function visibleAssistantText(message: AssistantMessage): string {
   return message.content
     .filter((block) => block.type === 'text')

package/src/channels/schema.ts

@@ -107,11 +107,9 @@ const quotedReplySchema = z
   .default({ enabled: true, queueDelayMs: DEFAULT_QUOTED_REPLY_QUEUE_DELAY_MS })
 
 // Deliberately non-strict: a stale on-disk file may still carry the
-// legacy `allow` field (`migrateLegacyConfigShape` lifts it into
-// `roles.member.match[]` on load, but a between-reload window can
-// briefly contain both). Zod silently drops unknown keys here, which is
-// exactly what we want — a hard `.strict()` reject would brick recovery
-// for any user mid-migration.
+// legacy `allow` field. Zod silently drops unknown keys here, which is
+// exactly what we want — the field is ignored, not translated, and a hard
+// `.strict()` reject would brick recovery for any user with an old config.
 const adapterSchema = z.object({
   engagement: engagementSchema,
   history: historySchema,
@@ -128,6 +126,7 @@ export const DEFAULT_GITHUB_EVENT_ALLOWLIST = [
   'pull_request.ready_for_review',
   'pull_request.review_requested',
   'pull_request.review_request_removed',
+  'pull_request.synchronize',
   'discussion.created',
   'pull_request_review.submitted',
 ] as const
@@ -158,6 +157,21 @@ const GITHUB_EVENT_ALLOWLIST_V2 = [
   'discussion.created',
   'pull_request_review.submitted',
 ] as const
+//   - v3: added ready_for_review, shipped 0.12.0+ (the default just before
+//     synchronize was added). Snapshotted here so configs seeded with the
+//     pre-synchronize default unfreeze and re-track the new default.
+const GITHUB_EVENT_ALLOWLIST_V3 = [
+  'issue_comment.created',
+  'pull_request_review_comment.created',
+  'discussion_comment.created',
+  'issues.opened',
+  'pull_request.opened',
+  'pull_request.ready_for_review',
+  'pull_request.review_requested',
+  'pull_request.review_request_removed',
+  'discussion.created',
+  'pull_request_review.submitted',
+] as const
 
 // Every event-allowlist that `channel add` / `init` has ever seeded verbatim
 // into typeclaw.json, oldest first, current default last. The legacy-shape
@@ -169,6 +183,7 @@ const GITHUB_EVENT_ALLOWLIST_V2 = [
 export const SEEDED_GITHUB_EVENT_ALLOWLISTS: readonly (readonly string[])[] = [
   GITHUB_EVENT_ALLOWLIST_V1,
   GITHUB_EVENT_ALLOWLIST_V2,
+  GITHUB_EVENT_ALLOWLIST_V3,
   DEFAULT_GITHUB_EVENT_ALLOWLIST,
 ]
 

package/src/channels/types.ts

@@ -382,6 +382,37 @@ export type ReviewThreadResolveResult =
 // support review threads never register one; the router answers `unsupported`.
 export type ReviewThreadResolver = (req: ReviewThreadResolveRequest) => Promise<ReviewThreadResolveResult>
 
+// A query for "does the bot still owe this PR a verdict?" — i.e. is the bot's
+// latest formal review on the PR a sticky CHANGES_REQUESTED that no later
+// APPROVE/dismissal has cleared. Used by the re-review stranding guard to stop
+// the bot from resolving a thread / posting a close-out ack while it still
+// holds a blocking review (the PR #644 failure: thread resolved + chat ack, but
+// reviewDecision stuck at CHANGES_REQUESTED because neither carries review
+// state). `workspace` is the repo slug `owner/name`; `chat` is `pr:<N>`.
+export type ReviewStateRequest = {
+  adapter: AdapterId
+  workspace: string
+  chat: string
+}
+
+// `selfBlocking` is the answer the guard acts on: true means the bot's latest
+// effective formal review is its own CHANGES_REQUESTED (COMMENTED reviews are
+// ignored — they never clear the sticky block, GitHub's own rule). `approve`
+// mirrors `channels.github.review.approve` so the guard's denial text can tell
+// the model whether to land a fresh APPROVE or to DISMISS its prior review.
+//
+// On `ok: false` the caller MUST fail closed: an unverifiable review state is
+// treated like a live block, so the bot never claims close-out when the runtime
+// could not confirm the platform-side verdict.
+export type ReviewStateResult =
+  | { ok: true; selfBlocking: boolean; approve: boolean }
+  | { ok: false; error: string; code?: 'unsupported' | 'not-found' | 'permission-denied' | 'transient' }
+
+// Registered per-adapter on the ChannelRouter, last-write-wins like the
+// review-thread resolver. Adapters that never register one make `getReviewState`
+// answer `unsupported`.
+export type ReviewStateResolver = (req: ReviewStateRequest) => Promise<ReviewStateResult>
+
 export function channelKeyId(key: { adapter: string; workspace: string; chat: string; thread: string | null }): string {
   return `${key.adapter}:${key.workspace}:${key.chat}:${key.thread ?? ''}`
 }

package/src/cli/channel.ts

@@ -629,8 +629,9 @@ async function promptGithubCredentials(cwd: string): Promise<{
     message: 'GitHub authentication type',
     options: [
       { value: 'pat', label: 'Fine-grained personal access token' },
-      { value: 'app', label: 'GitHub App installation token' },
+      { value: 'app', label: 'GitHub App installation token (recommended)' },
     ],
+    initialValue: 'app',
   })
   if (isCancel(authType)) {
     cancel('Aborted.')

package/src/cli/init.ts

@@ -1182,8 +1182,9 @@ async function runGithubFlow(cwd: string): Promise<StepResult<CollectedInputs['c
     message: 'GitHub authentication type',
     options: [
       { value: 'pat', label: 'Fine-grained personal access token' },
-      { value: 'app', label: 'GitHub App installation token' },
+      { value: 'app', label: 'GitHub App installation token (recommended)' },
     ],
+    initialValue: 'app',
   })
   if (isCancel(authType)) return back()
   const auth = authType === 'pat' ? await promptGithubPatAuth() : await promptGithubAppAuth()