From 8bb6e2096048272c82f8b9bbef07e7a261b4d43b Mon Sep 17 00:00:00 2001
From: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Date: Sat, 27 Jun 2026 14:22:01 +0800
Subject: [PATCH] =?UTF-8?q?feat(console):=20Build=20Doctor=20drawer=20?=
 =?UTF-8?q?=E2=80=94=20self-serve=20"what=20actually=20landed=3F"=20for=20?=
 =?UTF-8?q?AI=20builds?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds a Build Doctor button (build-agent conversations only) to the AI
build page header. It opens a right-side drawer that calls the admin
build-debug endpoint (objectstack-ai/cloud) and renders the
reconciliation: what the agent CLAIMED vs what is LIVE in sys_metadata.

The chat renders the agent's self-report ("已搭好"), never what actually
landed — so a build that silently dropped a change (a confirm card no
turn applied) reads as success. The drawer surfaces exactly that:
  - PROPOSED-BUT-ORPHANED: a changes_proposed card that evaporated.
  - CLAIMED-BUT-MISSING: said applied, isn't live.
plus de-noised verify_build (platform sys_*/cloud_*/ai_* hidden), pending
actions, and a collapsed timeline. Read-only; same-origin cookie auth, no
DB credentials — the diagnosis a founder used to do by hand-querying two
databases now happens in the browser.

Distinct from useReconcileOnError (ADR-0013 D2 stream-failure recovery):
this reconciles the BUILD against live metadata, not a transport drop.

- buildDebugApi.ts: typed client for GET /conversations/:id/debug.
- BuildDebugDrawer.tsx: the Sheet drawer + rendering.
- AiChatPage: Build Doctor button (showDebug=isBuildAgent) + drawer wiring.

type-check clean; app-shell suite green (929) incl. 2 new drawer tests
(orphaned render + endpoint call). Needs the cloud service-ai debug
endpoint deployed; absent it the drawer shows an empty state.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../app-shell/src/console/ai/AiChatPage.tsx   |  34 ++-
 .../src/console/ai/BuildDebugDrawer.tsx       | 264 ++++++++++++++++++
 .../ai/__tests__/BuildDebugDrawer.test.tsx    |  57 ++++
 .../app-shell/src/console/ai/buildDebugApi.ts |  86 ++++++
 4 files changed, 440 insertions(+), 1 deletion(-)
 create mode 100644 packages/app-shell/src/console/ai/BuildDebugDrawer.tsx
 create mode 100644 packages/app-shell/src/console/ai/__tests__/BuildDebugDrawer.test.tsx
 create mode 100644 packages/app-shell/src/console/ai/buildDebugApi.ts

diff --git a/packages/app-shell/src/console/ai/AiChatPage.tsx b/packages/app-shell/src/console/ai/AiChatPage.tsx
index 2f6a02288..ef7d0ecca 100644
--- a/packages/app-shell/src/console/ai/AiChatPage.tsx
+++ b/packages/app-shell/src/console/ai/AiChatPage.tsx
@@ -36,7 +36,7 @@ import {
   EmptyDescription,
   cn,
 } from '@object-ui/components';
-import { PanelLeft, PanelLeftClose, PanelLeftOpen, Share2 } from 'lucide-react';
+import { Bug, PanelLeft, PanelLeftClose, PanelLeftOpen, Share2 } from 'lucide-react';
 import {
   ChatbotEnhanced,
   useAgents,
@@ -76,6 +76,7 @@ import {
 import { useReconcileOnError } from '../../hooks/useReconcileOnError';
 import { ConversationsSidebar } from './ConversationsSidebar';
 import { LiveCanvas } from './LiveCanvas';
+import { BuildDebugDrawer } from './BuildDebugDrawer';
 
 const DEFAULT_AI_PATH = '/api/v1/ai';
 
@@ -633,6 +634,7 @@ export function AiChatPage({ apiBase: apiBaseProp, defaultAgent: defaultAgentPro
   const [refreshKey, setRefreshKey] = useState(0);
   const [titleHints, setTitleHints] = useState<Record<string, string>>({});
   const [shareOpen, setShareOpen] = useState(false);
+  const [debugOpen, setDebugOpen] = useState(false);
   const [mobileChatsOpen, setMobileChatsOpen] = useState(false);
   const {
     collapsed: chatsCollapsed,
@@ -833,6 +835,14 @@ export function AiChatPage({ apiBase: apiBaseProp, defaultAgent: defaultAgentPro
           publicBaseUrl={publicShareBase}
         />
       )}
+      {conversationId && isBuildAgent(activeAgent) && (
+        <BuildDebugDrawer
+          apiBase={apiBase}
+          conversationId={conversationId}
+          open={debugOpen}
+          onOpenChange={setDebugOpen}
+        />
+      )}
       <div className="flex min-h-0 flex-1 w-full bg-muted/20">
         {!chatsCollapsed && (
           <ConversationsSidebar
@@ -858,6 +868,8 @@ export function AiChatPage({ apiBase: apiBaseProp, defaultAgent: defaultAgentPro
             initialMessages={initialMessages}
             onSent={handleSent}
             onShare={() => setShareOpen(true)}
+            onDebug={() => setDebugOpen(true)}
+            showDebug={isBuildAgent(activeAgent)}
             onCanvasOpenChange={handleCanvasOpenChange}
           />
         </main>
@@ -932,6 +944,10 @@ interface ChatPaneProps {
   initialMessages: HydratedUIMessage[];
   onSent: (firstUserMessage?: string) => void;
   onShare: () => void;
+  /** Opens the Build Doctor drawer (build agent only). */
+  onDebug?: () => void;
+  /** Show the Build Doctor button — true only for build-agent conversations. */
+  showDebug?: boolean;
   /** Reports the Live Canvas preview opening/closing so the page can auto-tuck the chats list. */
   onCanvasOpenChange?: (open: boolean) => void;
 }
@@ -948,6 +964,8 @@ function ChatPane({
   initialMessages,
   onSent,
   onShare,
+  onDebug,
+  showDebug,
   onCanvasOpenChange,
 }: ChatPaneProps) {
   const { t } = useObjectTranslation();
@@ -1141,6 +1159,20 @@ function ChatPane({
         )}
       </div>
       <div className="flex shrink-0 items-center gap-1">
+        {showDebug && onDebug ? (
+          <Button
+            variant="ghost"
+            size="icon"
+            className="h-7 w-7 text-muted-foreground hover:text-foreground"
+            onClick={onDebug}
+            disabled={!conversationId}
+            aria-label="Build Doctor"
+            data-testid="ai-chat-debug-button"
+            title={conversationId ? 'Build Doctor — what actually landed?' : 'Send a message first'}
+          >
+            <Bug className="h-3.5 w-3.5" />
+          </Button>
+        ) : null}
         <Button
           variant="ghost"
           size="icon"
diff --git a/packages/app-shell/src/console/ai/BuildDebugDrawer.tsx b/packages/app-shell/src/console/ai/BuildDebugDrawer.tsx
new file mode 100644
index 000000000..332da832e
--- /dev/null
+++ b/packages/app-shell/src/console/ai/BuildDebugDrawer.tsx
@@ -0,0 +1,264 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * BuildDebugDrawer — self-serve "what actually landed?" panel for a build
+ * conversation. Opens a right-side sheet, calls the admin build-debug endpoint
+ * (see buildDebugApi.ts), and renders the reconciliation: agent-CLAIMED vs LIVE
+ * `sys_metadata`. The headline is the verdict + the two failure modes the chat
+ * can't show — PROPOSED-BUT-ORPHANED (a confirm card no turn applied) and
+ * CLAIMED-BUT-MISSING (said applied, isn't live). Read-only; no DB credentials.
+ *
+ * Distinct from `useReconcileOnError` (ADR-0013 D2 stream-failure recovery) —
+ * this reconciles the BUILD against live metadata, not a transport drop.
+ */
+
+import React, { useEffect, useState } from 'react';
+import {
+  Sheet,
+  SheetContent,
+  SheetHeader,
+  SheetTitle,
+  SheetDescription,
+} from '@object-ui/components';
+import { Bug, CheckCircle2, AlertTriangle, XCircle, Loader2, CircleSlash } from 'lucide-react';
+import { fetchBuildDebug, type BuildDebugReport, type MutationFinding } from './buildDebugApi';
+
+interface BuildDebugDrawerProps {
+  apiBase: string;
+  conversationId?: string;
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+}
+
+export function BuildDebugDrawer({ apiBase, conversationId, open, onOpenChange }: BuildDebugDrawerProps) {
+  const [report, setReport] = useState<BuildDebugReport | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (!open || !conversationId) return;
+    let cancelled = false;
+    setLoading(true);
+    setError(null);
+    setReport(null);
+    fetchBuildDebug(apiBase, conversationId)
+      .then((r) => {
+        if (cancelled) return;
+        if (!r) setError('Not available — the conversation was not found or you are not authorized.');
+        else setReport(r);
+      })
+      .catch((e: unknown) => {
+        if (!cancelled) setError(e instanceof Error ? e.message : String(e));
+      })
+      .finally(() => {
+        if (!cancelled) setLoading(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [open, conversationId, apiBase]);
+
+  const rec = report?.reconciliation;
+  const problems = rec ? rec.orphaned.length + rec.missing.length + rec.errors.length : 0;
+
+  return (
+    <Sheet open={open} onOpenChange={onOpenChange}>
+      <SheetContent side="right" className="w-full overflow-y-auto sm:max-w-xl">
+        <SheetHeader>
+          <SheetTitle className="flex items-center gap-2">
+            <Bug className="h-4 w-4" /> Build Doctor
+          </SheetTitle>
+          <SheetDescription>
+            What the agent claimed vs what is actually live. Read-only diagnostic.
+          </SheetDescription>
+        </SheetHeader>
+
+        <div className="mt-4 space-y-4 text-sm">
+          {loading && (
+            <div className="flex items-center gap-2 text-muted-foreground">
+              <Loader2 className="h-4 w-4 animate-spin" /> Reconciling…
+            </div>
+          )}
+          {error && !loading && (
+            <div className="rounded-md border border-destructive/30 bg-destructive/10 p-3 text-destructive">
+              {error}
+            </div>
+          )}
+
+          {report && !loading && (
+            <>
+              {/* Summary line */}
+              <div className="rounded-md border bg-muted/30 p-3 text-xs text-muted-foreground">
+                <div className="font-medium text-foreground">{report.title ?? '(untitled)'}</div>
+                <div className="mt-1">
+                  {report.summary.userTurns} turn(s) · {report.summary.messages} msgs ·{' '}
+                  {report.summary.totalTokens.toLocaleString()} tok ·{' '}
+                  {(report.summary.llmMs / 1000).toFixed(1)}s LLM
+                  {report.summary.models.length ? ` · ${report.summary.models.join(', ')}` : ''}
+                </div>
+              </div>
+
+              {/* Verdict */}
+              {rec && (
+                <div
+                  className={
+                    rec.ok
+                      ? 'flex items-center gap-2 rounded-md border border-emerald-500/30 bg-emerald-500/10 p-3 text-emerald-700 dark:text-emerald-400'
+                      : 'flex items-center gap-2 rounded-md border border-destructive/30 bg-destructive/10 p-3 text-destructive'
+                  }
+                >
+                  {rec.ok ? <CheckCircle2 className="h-4 w-4" /> : <AlertTriangle className="h-4 w-4" />}
+                  <span className="font-medium">
+                    {rec.ok
+                      ? `All ${rec.liveCount} attempted change(s) are live — nothing evaporated.`
+                      : `${problems} discrepancy(ies) — what the chat said doesn't match what's live.`}
+                  </span>
+                </div>
+              )}
+
+              {/* Orphaned — the headline failure */}
+              {rec && rec.orphaned.length > 0 && (
+                <FindingSection
+                  icon={<CircleSlash className="h-4 w-4 text-destructive" />}
+                  title="Proposed but never applied"
+                  hint="A confirm card the agent proposed but no later turn applied — the change silently evaporated."
+                  findings={rec.orphaned}
+                  tone="destructive"
+                />
+              )}
+              {rec && rec.missing.length > 0 && (
+                <FindingSection
+                  icon={<AlertTriangle className="h-4 w-4 text-amber-600" />}
+                  title="Claimed but missing"
+                  hint="A tool result said it was applied, but the artifact isn't live in sys_metadata."
+                  findings={rec.missing}
+                  tone="amber"
+                />
+              )}
+              {rec && rec.errors.length > 0 && (
+                <FindingSection
+                  icon={<XCircle className="h-4 w-4 text-destructive" />}
+                  title="Tool errors"
+                  hint="Tool calls that returned an error during the build."
+                  findings={rec.errors}
+                  tone="destructive"
+                />
+              )}
+
+              {/* verify_build, de-noised */}
+              {report.verify && (
+                <div className="rounded-md border p-3 text-xs">
+                  <div className="font-medium text-foreground">Build check (verify_build)</div>
+                  <div className="mt-1 text-muted-foreground">
+                    Your app:{' '}
+                    {report.verify.userIssues.length === 0 ? (
+                      <span className="text-emerald-600 dark:text-emerald-400">0 issues</span>
+                    ) : (
+                      <span className="text-destructive">{report.verify.userIssues.length} issue(s)</span>
+                    )}
+                    {report.verify.platformNoise > 0
+                      ? ` · ${report.verify.platformNoise} platform sys_* finding(s) hidden`
+                      : ''}
+                  </div>
+                  {report.verify.userIssues.map((is, i) => (
+                    <div key={i} className="mt-1 text-destructive">
+                      [{is.severity}] {is.code} {is.artifact ? `${is.artifact.type}:${is.artifact.name}` : ''}
+                    </div>
+                  ))}
+                </div>
+              )}
+
+              {/* Pending actions */}
+              {report.pendingActions.length > 0 && (
+                <div className="rounded-md border p-3 text-xs">
+                  <div className="font-medium text-foreground">Pending actions</div>
+                  {report.pendingActions.map((p, i) => (
+                    <div key={i} className="mt-1 text-muted-foreground">
+                      {p.tool ?? '?'} · {p.object ?? '-'} · <span className="font-mono">{p.status ?? '-'}</span>
+                    </div>
+                  ))}
+                </div>
+              )}
+
+              {/* Timeline (collapsed) */}
+              <details className="rounded-md border p-3 text-xs">
+                <summary className="cursor-pointer font-medium text-foreground">
+                  Timeline ({report.timeline.length})
+                </summary>
+                <div className="mt-2 space-y-1 font-mono text-[11px] leading-relaxed">
+                  {report.timeline.map((e, i) => (
+                    <TimelineRow key={i} entry={e} />
+                  ))}
+                </div>
+              </details>
+            </>
+          )}
+        </div>
+      </SheetContent>
+    </Sheet>
+  );
+}
+
+function FindingSection({
+  icon,
+  title,
+  hint,
+  findings,
+  tone,
+}: {
+  icon: React.ReactNode;
+  title: string;
+  hint: string;
+  findings: MutationFinding[];
+  tone: 'destructive' | 'amber';
+}) {
+  const border = tone === 'destructive' ? 'border-destructive/30' : 'border-amber-500/30';
+  return (
+    <div className={`rounded-md border ${border} p-3`}>
+      <div className="flex items-center gap-2 font-medium text-foreground">
+        {icon} {title} ({findings.length})
+      </div>
+      <div className="mt-1 text-xs text-muted-foreground">{hint}</div>
+      <div className="mt-2 space-y-1">
+        {findings.map((f, i) => (
+          <div key={i} className="font-mono text-xs">
+            {f.t ? `${f.t} · ` : ''}
+            {f.tool} → {f.artifact.type}:{f.artifact.name}
+            <span className="text-muted-foreground"> ({f.status})</span>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+function TimelineRow({ entry }: { entry: BuildDebugReport['timeline'][number] }) {
+  if (entry.kind === 'user') {
+    return (
+      <div>
+        <span className="text-muted-foreground">{entry.t}</span> 👤 {entry.text}
+      </div>
+    );
+  }
+  if (entry.kind === 'assistant-text') {
+    return (
+      <div>
+        <span className="text-muted-foreground">{entry.t}</span> 🤖 {entry.text}
+      </div>
+    );
+  }
+  if (entry.kind === 'assistant-calls') {
+    return (
+      <div>
+        <span className="text-muted-foreground">{entry.t}</span> 🤖 →{' '}
+        {entry.calls.map((c) => c.name).join(', ')}
+      </div>
+    );
+  }
+  return (
+    <div className={entry.isError ? 'text-destructive' : ''}>
+      <span className="text-muted-foreground">{entry.t}</span> ↳ {entry.name}
+      {entry.status ? ` (${entry.status})` : ''}
+    </div>
+  );
+}
diff --git a/packages/app-shell/src/console/ai/__tests__/BuildDebugDrawer.test.tsx b/packages/app-shell/src/console/ai/__tests__/BuildDebugDrawer.test.tsx
new file mode 100644
index 000000000..07af8a36b
--- /dev/null
+++ b/packages/app-shell/src/console/ai/__tests__/BuildDebugDrawer.test.tsx
@@ -0,0 +1,57 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import '@testing-library/jest-dom/vitest';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { BuildDebugDrawer } from '../BuildDebugDrawer';
+import type { BuildDebugReport } from '../buildDebugApi';
+
+const REPORT: BuildDebugReport = {
+  conversationId: 'conv_x',
+  title: '开发报销流程',
+  summary: { models: ['openai/gpt-5.4-mini'], userTurns: 3, messages: 36, totalTokens: 242495, llmMs: 82900 },
+  reconciliation: {
+    orphaned: [
+      { t: '04:29:43', tool: 'create_metadata', status: 'changes_proposed', artifact: { type: 'flow', name: 'reimbursement_approval_flow' } },
+    ],
+    missing: [],
+    errors: [],
+    liveCount: 9,
+    ok: false,
+  },
+  verify: { status: 'failed', errors: 2, warnings: 16, userIssues: [], platformNoise: 18 },
+  timeline: [{ t: '04:23:45', kind: 'user', text: '开发报销流程' }],
+  pendingActions: [],
+};
+
+describe('BuildDebugDrawer', () => {
+  beforeEach(() => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () => ({ ok: true, status: 200, json: async () => REPORT })),
+    );
+  });
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it('renders the orphaned proposal (审批流 evaporated) + de-noised verify when opened', async () => {
+    render(<BuildDebugDrawer apiBase="/api/v1/ai" conversationId="conv_x" open onOpenChange={() => {}} />);
+
+    // The headline failure: a proposed change that never landed.
+    expect(await screen.findByText(/Proposed but never applied/)).toBeInTheDocument();
+    expect(screen.getByText(/reimbursement_approval_flow/)).toBeInTheDocument();
+    // Verdict reflects a discrepancy.
+    expect(screen.getByText(/doesn't match what's live/)).toBeInTheDocument();
+    // verify_build de-noised: platform noise hidden, not failing the user's app.
+    expect(screen.getByText(/18 platform sys_\* finding/)).toBeInTheDocument();
+  });
+
+  it('hits the debug endpoint for the conversation', async () => {
+    const spy = vi.fn(async () => ({ ok: true, status: 200, json: async () => REPORT }));
+    vi.stubGlobal('fetch', spy);
+    render(<BuildDebugDrawer apiBase="/api/v1/ai" conversationId="conv_x" open onOpenChange={() => {}} />);
+    await screen.findByText(/Proposed but never applied/);
+    expect(spy).toHaveBeenCalledWith('/api/v1/ai/conversations/conv_x/debug', { credentials: 'include' });
+  });
+});
diff --git a/packages/app-shell/src/console/ai/buildDebugApi.ts b/packages/app-shell/src/console/ai/buildDebugApi.ts
new file mode 100644
index 000000000..93dcf8471
--- /dev/null
+++ b/packages/app-shell/src/console/ai/buildDebugApi.ts
@@ -0,0 +1,86 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Client for the admin build-debug endpoint
+ * (`GET /api/v1/ai/conversations/:id/debug`, service-ai).
+ *
+ * The chat renders the build agent's self-report, never what actually landed.
+ * This fetches the server-side reconciliation — agent-CLAIMED vs LIVE
+ * `sys_metadata` — so a signed-in admin can diagnose a build that "went wrong"
+ * from the browser, with no DB credentials. Mirrors `fetchConversation`'s
+ * same-origin cookie auth.
+ */
+
+export interface ArtifactRef {
+  type: string;
+  name: string;
+}
+
+export interface MutationFinding {
+  t?: string;
+  tool: string;
+  status: string;
+  artifact: ArtifactRef;
+}
+
+export interface VerifyIssue {
+  severity: string;
+  code: string;
+  artifact?: ArtifactRef;
+}
+
+export interface VerifySummary {
+  status: string;
+  errors: number;
+  warnings: number;
+  userIssues: VerifyIssue[];
+  platformNoise: number;
+}
+
+export type TimelineEntry =
+  | { t: string; kind: 'user'; text: string }
+  | { t: string; kind: 'assistant-text'; text: string; model?: string; tokens?: number; ms?: number }
+  | { t: string; kind: 'assistant-calls'; calls: Array<{ name: string; args: unknown }>; model?: string; tokens?: number; ms?: number }
+  | { t: string; kind: 'tool-result'; name: string; isError: boolean; status?: string; preview: string };
+
+export interface BuildDebugReport {
+  conversationId: string;
+  title: string | null;
+  summary: {
+    models: string[];
+    userTurns: number;
+    messages: number;
+    totalTokens: number;
+    llmMs: number;
+  };
+  reconciliation: {
+    orphaned: MutationFinding[];
+    missing: MutationFinding[];
+    errors: MutationFinding[];
+    liveCount: number;
+    ok: boolean;
+  };
+  verify: VerifySummary | null;
+  timeline: TimelineEntry[];
+  pendingActions: Array<{
+    tool: string | null;
+    object: string | null;
+    status: string | null;
+    error: string | null;
+    createdAt: string | null;
+  }>;
+}
+
+/**
+ * Fetch the reconciliation report for a build conversation. Returns null on
+ * 403/404 (not authorized / unknown conversation) so the caller can show an
+ * empty state instead of throwing.
+ */
+export async function fetchBuildDebug(apiBase: string, conversationId: string): Promise<BuildDebugReport | null> {
+  const res = await fetch(`${apiBase}/conversations/${encodeURIComponent(conversationId)}/debug`, {
+    credentials: 'include',
+  });
+  if (res.status === 404 || res.status === 403 || res.status === 401) return null;
+  if (!res.ok) throw new Error(`GET build debug failed: ${res.status}`);
+  return (await res.json()) as BuildDebugReport;
+}