@cat-factory/app 0.35.0 → 0.36.0

package/app/components/gates/GateResultView.vue

@@ -5,7 +5,7 @@
 // persists on `step.gate`: the precheck verdict, the helper attempt budget, the gated
 // commit, and — for CI — the failing checks behind the failure. One window serves both
 // gates; it branches on the step's `agentKind` for the copy and the failure detail.
-import { computed } from 'vue'
+import { computed, ref } from 'vue'
 import { agentKindMeta } from '~/utils/catalog'
 import type { GateStepState } from '~/types/execution'
 import StepRestartControl from '~/components/panels/StepRestartControl.vue'
@@ -30,10 +30,37 @@ const step = computed(() => {
 const gate = computed<GateStepState | null>(() => step.value?.gate ?? null)
 
 const isCi = computed(() => step.value?.agentKind === 'ci')
+const isHumanReview = computed(() => step.value?.agentKind === 'human-review')
 const meta = computed(() => agentKindMeta(step.value?.agentKind ?? 'ci'))
-const helperKind = computed(() => (isCi.value ? 'ci-fixer' : 'conflict-resolver'))
+const helperKind = computed(() =>
+  isHumanReview.value ? 'fixer' : isCi.value ? 'ci-fixer' : 'conflict-resolver',
+)
 const helperMeta = computed(() => agentKindMeta(helperKind.value))
 
+const subtitle = computed(() =>
+  isHumanReview.value
+    ? 'Waits for a human code review on the PR, looping the fixer on comments'
+    : isCi.value
+      ? 'Gates the PR on green CI, looping the CI fixer on failure'
+      : 'Gates the PR on a clean merge, looping the resolver on conflicts',
+)
+
+// Human-review: approval progress + the freeform "request a fix" control.
+const humanReview = useHumanReviewStore()
+const fixInstructions = ref('')
+const fixBusy = computed(() => (blockId.value ? humanReview.isBusy(blockId.value) : false))
+async function submitFix() {
+  const id = blockId.value
+  const text = fixInstructions.value.trim()
+  if (!id || !text) return
+  await humanReview.requestFix(id, text)
+  fixInstructions.value = ''
+}
+
+// The displayed "required approvals" is derived from the cached branch-protection count via
+// the gate's effective floor (`max(1, …)`, see review.logic.ts) rather than persisted twice.
+const requiredApprovals = computed(() => Math.max(1, gate.value?.requiredApprovingReviewCount ?? 1))
+
 const failingChecks = computed(() => gate.value?.failingChecks ?? [])
 const shortSha = computed(() => (gate.value?.headSha ? gate.value.headSha.slice(0, 7) : null))
 
@@ -130,13 +157,7 @@ const conflictVerdict = computed(() => {
             <h2 class="truncate text-sm font-semibold text-slate-100">
               {{ meta.label }}{{ block ? ` — ${block.title}` : '' }}
             </h2>
-            <p class="truncate text-[11px] text-slate-400">
-              {{
-                isCi
-                  ? 'Gates the PR on green CI, looping the CI fixer on failure'
-                  : 'Gates the PR on a clean merge, looping the resolver on conflicts'
-              }}
-            </p>
+            <p class="truncate text-[11px] text-slate-400">{{ subtitle }}</p>
           </div>
           <UBadge :color="STATUS_META[status].badge" variant="subtle" size="sm">
             {{ STATUS_META[status].label }}
@@ -186,6 +207,73 @@ const conflictVerdict = computed(() => {
                 </p>
               </div>
 
+              <!-- Human review: approval progress, the feedback being fixed, freeform fix box -->
+              <template v-else-if="isHumanReview">
+                <div
+                  class="flex items-center gap-2 rounded-md border border-slate-800 bg-slate-950/40 px-3 py-2"
+                >
+                  <UIcon name="i-lucide-users" class="h-4 w-4 shrink-0 text-violet-300" />
+                  <span class="text-[13px] text-slate-200">
+                    {{ gate.lastApprovals ?? 0 }} / {{ requiredApprovals }} approval{{
+                      requiredApprovals === 1 ? '' : 's'
+                    }}
+                    <template v-if="status === 'fixing'"> · fixer addressing comments…</template>
+                    <template v-else-if="status === 'failing'">
+                      · review comments to address</template
+                    >
+                    <template v-else> · awaiting review</template>
+                  </span>
+                </div>
+                <p
+                  v-if="gate.lastFailureSummary"
+                  class="mt-2 whitespace-pre-wrap rounded-md border border-slate-800 bg-slate-950/40 px-3 py-2 text-[12px] leading-relaxed text-slate-300"
+                >
+                  {{ gate.lastFailureSummary }}
+                </p>
+                <a
+                  v-if="prUrl"
+                  :href="prUrl"
+                  target="_blank"
+                  rel="noopener"
+                  class="mt-2 inline-flex items-center gap-1 text-[12px] text-sky-300 hover:text-sky-200 hover:underline"
+                >
+                  Review pull request on GitHub
+                  <UIcon name="i-lucide-external-link" class="h-3 w-3" />
+                </a>
+
+                <!-- Freeform fix request: dispatch the fixer now with these instructions. -->
+                <section v-if="status !== 'gave-up'" class="mt-4">
+                  <h3
+                    class="mb-1.5 text-[11px] font-semibold uppercase tracking-wide text-slate-500"
+                  >
+                    Request a fix
+                  </h3>
+                  <p class="mb-2 text-[11px] leading-relaxed text-slate-500">
+                    Describe a change for the fixer to make on the PR branch now (in addition to any
+                    review comments, which it addresses automatically).
+                  </p>
+                  <textarea
+                    v-model="fixInstructions"
+                    rows="3"
+                    :disabled="fixBusy"
+                    placeholder="e.g. rename the helper and add a unit test for the empty-input case"
+                    class="w-full resize-y rounded-md border border-slate-800 bg-slate-950/60 px-3 py-2 text-[13px] text-slate-200 placeholder:text-slate-600 focus:border-violet-500/60 focus:outline-none"
+                  />
+                  <div class="mt-2 flex justify-end">
+                    <UButton
+                      size="sm"
+                      color="primary"
+                      icon="i-lucide-wrench"
+                      :loading="fixBusy"
+                      :disabled="fixBusy || fixInstructions.trim().length === 0"
+                      @click="submitFix"
+                    >
+                      Request fix
+                    </UButton>
+                  </div>
+                </section>
+              </template>
+
               <!-- CI: failing checks -->
               <template v-else-if="isCi">
                 <h3 class="mb-2 text-[11px] font-semibold uppercase tracking-wide text-slate-500">
@@ -321,9 +409,16 @@ const conflictVerdict = computed(() => {
                 {{ helperMeta.label }}
               </h4>
               <p class="text-[12px] text-slate-300">
-                {{ gate.attempts }}/{{ gate.maxAttempts }} attempt{{
-                  gate.maxAttempts === 1 ? '' : 's'
-                }}
+                <!-- The human-review gate's budget is effectively unbounded (it waits for a human
+                     indefinitely), so render a plain round count rather than "0/9007199254740991". -->
+                <template v-if="isHumanReview">
+                  {{ gate.attempts }} fix round{{ gate.attempts === 1 ? '' : 's' }}
+                </template>
+                <template v-else>
+                  {{ gate.attempts }}/{{ gate.maxAttempts }} attempt{{
+                    gate.maxAttempts === 1 ? '' : 's'
+                  }}
+                </template>
                 <template v-if="gate.phase === 'working'"> · running…</template>
                 <template v-else-if="gate.attempts === 0"> · not needed yet</template>
               </p>

package/app/components/layout/NotificationsInbox.vue

@@ -36,6 +36,9 @@ const META: Record<Notification['type'], { icon: string; color: Accent; action:
   // Clicking the title opens the human-testing window for the task (see `reveal`); "act" just
   // marks it read (the gate is resolved in that window — confirm / request a fix — not here).
   human_test_ready: { icon: 'i-lucide-user-check', color: 'primary', action: 'Mark read' },
+  // Clicking the title opens the task's gate window (where the human can request a freeform
+  // fix); "act" just marks it read (approval happens on GitHub, not here).
+  human_review: { icon: 'i-lucide-users', color: 'primary', action: 'Mark read' },
   // Clicking the title opens the Follow-up companion window for the run (see `reveal`); "act"
   // just marks it read (items are decided in that window — file / send back / answer — not here).
   followup_pending: { icon: 'i-lucide-compass', color: 'warning', action: 'Mark read' },
@@ -84,10 +87,23 @@ function reveal(n: Notification) {
   else if (n.type === 'clarity_review') ui.openClarityReview(n.blockId)
   else if (n.type === 'decision_required') revealDecision(n)
   else if (n.type === 'human_test_ready') revealHumanTest(n)
+  else if (n.type === 'human_review') revealHumanReview(n)
   else if (n.type === 'followup_pending') revealFollowUps(n)
   else ui.select(n.blockId)
 }
 
+/**
+ * Open the gate window for a parked `human-review` gate: find the run's human-review step and
+ * open it through the universal step dispatch (its archetype declares the `gate` result view,
+ * where the human can request a freeform fix). Falls back to focusing the block.
+ */
+function revealHumanReview(n: Notification) {
+  const instance = n.executionId ? execution.getInstance(n.executionId) : undefined
+  const idx = instance?.steps.findIndex((s) => s.agentKind === 'human-review') ?? -1
+  if (instance && idx >= 0) ui.openStepDetail(instance.id, idx)
+  else if (n.blockId) ui.select(n.blockId)
+}
+
 /**
  * Open the Follow-up companion window for a run whose Coder parked on undecided items.
  * Falls back to focusing the block when the run isn't loaded.

package/app/components/slack/SlackPanel.vue

@@ -45,6 +45,7 @@ const routes = reactive<Record<NotificationType, SlackRoute>>({
   // In-app only (not in ROUTABLE), but the map is exhaustive over the type.
   decision_required: { enabled: false, channel: '' },
   human_test_ready: { enabled: false, channel: '' },
+  human_review: { enabled: false, channel: '' },
   followup_pending: { enabled: false, channel: '' },
 })
 const mentionsEnabled = ref(false)

package/app/composables/api/humanReview.ts

@@ -0,0 +1,18 @@
+import type { ExecutionInstance } from '~/types/domain'
+import type { ApiContext } from './context'
+
+/**
+ * The human-review gate's run-driving action. The gate self-drives off the PR's GitHub review
+ * state, but a human can request a freeform fix at any time — dispatched to the `fixer`
+ * immediately. Returns the updated execution instance (the gate state rides on its step + the
+ * execution stream).
+ */
+export function humanReviewApi({ http, ws }: ApiContext) {
+  return {
+    requestHumanReviewFix: (workspaceId: string, blockId: string, instructions: string) =>
+      http<ExecutionInstance>(
+        `${ws(workspaceId)}/blocks/${encodeURIComponent(blockId)}/human-review/request-fix`,
+        { method: 'POST', body: { instructions } },
+      ),
+  }
+}

package/app/composables/useApi.ts

@@ -9,6 +9,7 @@ import { executionApi } from './api/execution'
 import { followUpsApi } from './api/followUps'
 import { fragmentsApi } from './api/fragments'
 import { githubApi } from './api/github'
+import { humanReviewApi } from './api/humanReview'
 import { humanTestApi } from './api/humanTest'
 import { kaizenApi } from './api/kaizen'
 import { localSettingsApi } from './api/localSettings'
@@ -89,6 +90,7 @@ export function useApi() {
     ...reviewsApi(ctx),
     ...followUpsApi(ctx),
     ...humanTestApi(ctx),
+    ...humanReviewApi(ctx),
     ...kaizenApi(ctx),
     ...localSettingsApi(ctx),
     ...specApi(ctx),

package/app/stores/humanReview.ts

@@ -0,0 +1,41 @@
+import { defineStore } from 'pinia'
+import { ref } from 'vue'
+import { useExecutionStore } from '~/stores/execution'
+import { useWorkspaceStore } from '~/stores/workspace'
+
+/**
+ * Human-review gate actions. The gate's live state rides on its execution step (`step.gate`) and
+ * arrives via the execution stream, so this store holds NO gate state — it only drives the
+ * freeform "request a fix" action and patches the execution store from the response. A per-block
+ * `busy` flag lets the window disable its control while the request is in flight.
+ */
+export const useHumanReviewStore = defineStore('humanReview', () => {
+  const api = useApi()
+  const ws = useWorkspaceStore()
+  const execution = useExecutionStore()
+
+  const busy = ref<Set<string>>(new Set())
+
+  function isBusy(blockId: string): boolean {
+    return busy.value.has(blockId)
+  }
+
+  /** Dispatch the fixer against the PR from a human's freeform instructions (bypasses grace). */
+  async function requestFix(blockId: string, instructions: string): Promise<void> {
+    const next = new Set(busy.value)
+    next.add(blockId)
+    busy.value = next
+    try {
+      const instance = await api.requestHumanReviewFix(ws.requireId(), blockId, instructions)
+      if (instance && typeof instance === 'object' && 'steps' in instance) {
+        execution.upsert(instance as Parameters<typeof execution.upsert>[0])
+      }
+    } finally {
+      const after = new Set(busy.value)
+      after.delete(blockId)
+      busy.value = after
+    }
+  }
+
+  return { isBusy, requestFix }
+})

package/app/types/domain.ts

@@ -315,6 +315,10 @@ export type AgentKind =
   // validate the change in a live URL, dispatching the Tester's `fixer` (from findings) or
   // the `conflict-resolver` (on a conflicting pull-main) on demand. Opens its own window.
   | 'human-test'
+  // The human-review gate: watches the PR for a human code review on GitHub, looping the
+  // `fixer` to address review comments and advancing once approved with no unresolved threads.
+  // Opens the shared gate window (with a freeform "request a fix" box).
+  | 'human-review'
   // The Kaizen agent: post-run grader (NOT a pipeline step / palette archetype). Surfaced
   // only in Model Configuration (its model is pinnable like any agent) and run details.
   | 'kaizen'

package/app/types/execution.ts

@@ -464,6 +464,22 @@ export interface GateStepState {
   failingChecks?: GateFailingCheck[] | null
   /** history of the helper-agent attempts this gate dispatched, newest last */
   attemptLog?: GateAttempt[] | null
+  // ---- human-review gate only ----
+  /** approvals the PR had at the last probe (human-review gate) */
+  lastApprovals?: number | null
+  /**
+   * raw branch-protection required count, cached after the first probe (human-review gate).
+   * The displayed "required" count is `max(1, this)` — the gate's effective floor.
+   */
+  requiredApprovingReviewCount?: number | null
+  /** review threads handed to the fixer, pending resolve on its completion (human-review gate) */
+  pendingThreadIds?: string[] | null
+  /** the grace window (minutes) before the fixer addresses a comment batch (human-review gate) */
+  humanReviewGraceMinutes?: number | null
+  /** newest plain PR comment already handed to the fixer (human-review gate) */
+  lastAddressedCommentAt?: number | null
+  /** a human-initiated freeform fix parked on the gate, consumed on the next poll (human-review gate) */
+  pendingFix?: { instructions: string; at: number } | null
 }
 
 /** Live state of a `tester` step's Tester→Fixer loop (mirrors `testerStepStateSchema`). */

package/app/types/notifications.ts

@@ -15,6 +15,7 @@ export type NotificationType =
   | 'release_regression'
   | 'decision_required'
   | 'human_test_ready'
+  | 'human_review'
   | 'followup_pending'
 export type NotificationStatus = 'open' | 'acted' | 'dismissed'
 

package/app/utils/catalog.ts

@@ -352,6 +352,18 @@ export const SYSTEM_AGENT_META: Record<string, AgentArchetype> = {
     color: '#a3e635',
     description: 'Scores the PR and auto-merges within the task thresholds, or asks for review.',
   },
+  'human-review': {
+    kind: 'human-review',
+    label: 'Human Review Gate',
+    icon: 'i-lucide-users',
+    color: '#c084fc',
+    category: 'gates',
+    description:
+      'Waits for a human code review on the PR, looping the fixer to address comments; advances once approved with no unresolved threads.',
+    // Opens the dedicated gate window (approval progress, the feedback being fixed, and a
+    // freeform "request a fix" box) like the other gates.
+    resultView: 'gate',
+  },
   // The Kaizen agent grades agent steps AFTER a run completes (continuous improvement).
   // It is NOT a pipeline step (never in the palette — no `category`), but it runs an LLM,
   // so it needs display metadata here and a per-workspace model in Model Configuration.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/app",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "description": "Reusable Nuxt layer for the Agent Architecture Board SPA (components, stores, composables, pages). Consume it from a thin deployment app via `extends: ['@cat-factory/app']` and point it at your backend with NUXT_PUBLIC_API_BASE. See deploy/frontend for an example.",
   "repository": {
     "type": "git",