@adia-ai/a2ui-mcp 0.1.3 → 0.2.1

package/tools/synthesis.js

@@ -0,0 +1,436 @@
+/**
+ * Synthesis tools — chunk-based composition + multi-turn refinement.
+ *
+ * Extracts the 4 tools that share the LLM bridge + state-cache +
+ * issue-reporter + chunk-refiner stack: `compose_from_chunks`,
+ * `refine_composition`, `get_state`, `report_issue`.
+ *
+ * Spec: docs/specs/genui-multiturn-architecture.md (Phase A).
+ */
+
+import { z } from 'zod';
+
+import { composeFromIntent as composeFromChunksImpl } from '../../compose/strategies/zettel/chunk-synthesizer.js';
+import { composeFromPlan, validatePlan } from '../../compose/strategies/zettel/chunk-composer.js';
+import { createAdapter as createLLMAdapter } from '../../compose/llm/llm-bridge.js';
+import {
+  getStateCache,
+  mintStateId,
+  mintNextStateId,
+} from '../../compose/strategies/zettel/state-cache.js';
+import {
+  reportIssue as reportIssueImpl,
+  autoReport,
+  createIssueAccumulator,
+} from '../../compose/strategies/zettel/issue-reporter.js';
+import {
+  refineFromIntent,
+  applyOps,
+  opsToA2UI,
+  validateOps,
+} from '../../compose/strategies/zettel/chunk-refiner.js';
+
+const stateCache = getStateCache();
+
+const ENGINE_VERSION_INFO = {
+  mcp: '0.2.0',
+  corpus: '0.2.0',
+  engine: 'zettel',
+  llm_adapter: 'anthropic',
+  model: process.env.ANTHROPIC_MODEL || 'claude-opus-4-7',
+};
+
+export { stateCache, ENGINE_VERSION_INFO, autoReport, reportIssueImpl };
+
+export function registerSynthesisTools(server) {
+  server.tool(
+    'compose_from_chunks',
+    `Compose a UI page from training chunks — retrieval-first, synthesis-fallback.
+
+Mix-and-match composition for intents that don't have a 1:1 chunk match. Workflow:
+  1. Pure-retrieval tier: if \`search_chunks\` returns a strong direct match, return
+     that chunk's HTML immediately (no LLM call).
+  2. Synthesis tier: when retrieval is weak, the LLM picks a page-kind chunk and
+     binds block/panel chunks to its named slots. Output validated against the
+     chunk catalog (slot names exist, bound chunks exist, kinds match).
+
+Returns the composed HTML string + a binding plan describing which chunks plug
+where. Useful when the prompt is novel ("dashboard with KPI grid + funnel +
+country list") and no exact chunk has all those parts together — the LLM mixes
+and matches from the corpus.
+
+Two-call mode also available via \`plan\` parameter — pass a pre-baked binding
+plan to skip the LLM call and just materialize HTML.`,
+    {
+      intent: z.string().optional().describe('Natural-language description of what to build (uses LLM synthesis)'),
+      plan: z.object({
+        page: z.string(),
+        slot_bindings: z.record(z.union([z.string(), z.array(z.string())])),
+      }).optional().describe('Pre-baked binding plan (skips LLM, materializes directly)'),
+      max_attempts: z.number().int().min(1).max(5).default(2).describe('LLM retry budget for synthesis'),
+    },
+    async ({ intent, plan, max_attempts }) => {
+      if (plan) {
+        const validation = validatePlan(plan);
+        if (!validation.ok) {
+          return {
+            isError: true,
+            content: [{ type: 'text', text: JSON.stringify({ error: 'invalid plan', errors: validation.errors }, null, 2) }],
+          };
+        }
+        const result = composeFromPlan(plan);
+        const state_id = mintStateId(intent || plan.page || 'plan', 1);
+        stateCache.set(state_id, {
+          state_id,
+          intent: intent || `(plan) ${plan.page}`,
+          plan: result.plan,
+          html: result.html,
+          source: 'plan',
+          ops_history: [],
+          parent_state_id: null,
+          created_at: new Date().toISOString(),
+        });
+        return {
+          content: [{ type: 'text', text: JSON.stringify({
+            state_id,
+            html: result.html,
+            plan: result.plan,
+            warnings: result.warnings,
+            source: 'plan',
+          }, null, 2) }],
+        };
+      }
+
+      if (!intent) {
+        return {
+          isError: true,
+          content: [{ type: 'text', text: JSON.stringify({ error: 'must provide either intent or plan' }, null, 2) }],
+        };
+      }
+
+      try {
+        const llmAdapter = await createLLMAdapter();
+        const result = await composeFromChunksImpl({
+          intent,
+          llmAdapter,
+          maxAttempts: max_attempts,
+        });
+        const state_id = mintStateId(intent, 1);
+        stateCache.set(state_id, {
+          state_id,
+          intent,
+          plan: result.plan,
+          html: result.html,
+          source: result.source,
+          score: result.score,
+          ops_history: [],
+          parent_state_id: null,
+          warnings: result.warnings,
+          synthesis: result.synthesis,
+          scopeDrift: result.scopeDrift,
+          created_at: new Date().toISOString(),
+        });
+
+        // Scope-drift auto-fire: composed HTML envelope exceeded the bound-
+        // chunk envelope by > SCOPE_DRIFT_RATIO. Fires a `scope-drift` issue
+        // (writes both .json and high-res .md) so post-mortem review can
+        // catch the canvas-drift regression class without manual reporting.
+        if (result.scopeDrift?.drift) {
+          await autoReport(
+            'scope-drift',
+            {
+              intent,
+              state_id,
+              scopeDrift: result.scopeDrift,
+              tags: ['canvas-drift'],
+              trace: 'full',
+            },
+            { cache: stateCache, versionInfo: ENGINE_VERSION_INFO }
+          );
+        }
+
+        return {
+          content: [{ type: 'text', text: JSON.stringify({
+            state_id,
+            html: result.html,
+            plan: result.plan,
+            source: result.source,
+            score: result.score,
+            warnings: result.warnings,
+            scopeDrift: result.scopeDrift,
+            synthesis: result.synthesis ? { attempts: result.synthesis.attempts } : undefined,
+          }, null, 2) }],
+        };
+      } catch (e) {
+        return {
+          isError: true,
+          content: [{ type: 'text', text: JSON.stringify({ error: e.message }, null, 2) }],
+        };
+      }
+    },
+  );
+
+  // ── Multi-turn refinement (Phase A) ─────────────────────────────────
+  // Spec: docs/specs/genui-multiturn-architecture.md §3.
+
+  server.tool(
+    'refine_composition',
+    `Refine an existing chunk-composed UI based on a natural-language intent or an explicit op-list.
+
+Use when the user wants to modify an *existing* UI. Triggers on "change", "update", "modify", "add to", "remove from", "this", "it", "the X". Requires \`state_id\` from a prior \`compose_from_chunks\` call.
+
+Two modes:
+  - **Intent-driven** — pass \`intent\`. Engine runs two-pass synthesis (locator pass identifies which slots to modify; modifier pass emits chunk-plan ops). Validator-driven retry on op-validation failure.
+  - **Explicit ops** — pass \`ops\` directly. Skips the LLM entirely; engine applies + materializes.
+
+Returns a new \`state_id\` (versioned chain from the parent), the A2UI op-list applied, the post-op HTML, and a delta summary. Failed ops are reported in \`ops_failed\` with reasons.
+
+For *fresh creation* use \`compose_from_chunks\`, not this tool.`,
+    {
+      state_id: z.string().describe('State id from a prior compose_from_chunks or refine_composition call'),
+      intent: z.string().optional().describe('Natural-language description of what to change (e.g. "add a country list to page-content")'),
+      ops: z.array(z.any()).optional().describe('Pre-computed chunk-plan ops to apply directly (skips the LLM)'),
+      max_attempts: z.number().int().min(1).max(5).default(2).describe('Validator retry budget for synthesis'),
+    },
+    async ({ state_id, intent, ops, max_attempts }) => {
+      const priorState = stateCache.get(state_id);
+      if (!priorState) {
+        await autoReport(
+          'cache-miss-on-known-state',
+          { state_id, tool: 'refine_composition' },
+          { cache: stateCache, versionInfo: ENGINE_VERSION_INFO }
+        );
+        return {
+          isError: true,
+          content: [{ type: 'text', text: JSON.stringify({
+            error: 'state_id not found in cache',
+            hint: 'state cache is in-memory and bounded; re-run compose_from_chunks to mint a fresh state_id',
+            state_id,
+          }, null, 2) }],
+        };
+      }
+
+      if (!intent && !ops) {
+        return {
+          isError: true,
+          content: [{ type: 'text', text: JSON.stringify({ error: 'must provide either intent or ops' }, null, 2) }],
+        };
+      }
+
+      const issueAccumulator = createIssueAccumulator();
+      const issueCtx = { cache: stateCache, versionInfo: ENGINE_VERSION_INFO };
+      const startedAt = Date.now();
+
+      try {
+        let resolvedOps;
+        let delta_summary = '';
+        let synthesis = null;
+        let warnings = [];
+
+        if (ops && Array.isArray(ops)) {
+          // Explicit ops path — validate then apply
+          const validation = validateOps(ops, priorState);
+          if (!validation.ok) {
+            await issueAccumulator.flush(issueCtx);
+            return {
+              isError: true,
+              content: [{ type: 'text', text: JSON.stringify({
+                error: 'ops failed validation',
+                errors: validation.errors,
+              }, null, 2) }],
+            };
+          }
+          resolvedOps = ops;
+          delta_summary = `applied ${ops.length} explicit op(s)`;
+        } else {
+          // Intent path — two-pass synthesis with stub-friendly LLM bridge
+          const llmAdapter = await createLLMAdapter();
+          const refined = await refineFromIntent({
+            priorState,
+            intent,
+            llmAdapter,
+            maxAttempts: max_attempts,
+            issueAccumulator,
+          });
+          resolvedOps = refined.ops;
+          delta_summary = refined.delta_summary || '';
+          synthesis = refined.synthesis;
+          warnings = refined.warnings;
+
+          if (resolvedOps.length === 0) {
+            // Synthesizer gave up. Auto-fires already accumulated.
+            await issueAccumulator.flush(issueCtx);
+            const childId = mintNextStateId(state_id, (priorState.version || 1) + 1);
+            return {
+              content: [{ type: 'text', text: JSON.stringify({
+                state_id: childId,
+                ops_applied: [],
+                ops_failed: [],
+                delta_summary: '',
+                warnings,
+                synthesis: synthesis ? { attempts: synthesis.attempts, targeted: synthesis.targeted } : null,
+                html: priorState.html,
+              }, null, 2) }],
+            };
+          }
+        }
+
+        const applied = await applyOps({ priorState, ops: resolvedOps });
+
+        if (applied.ops_failed.length > 0) {
+          issueAccumulator.add('ops-failed-after-apply', {
+            state_id,
+            tool: 'refine_composition',
+            intent,
+          });
+        }
+
+        const a2uiMessages = opsToA2UI(applied.ops_applied, applied.newState);
+
+        const parentVersion = priorState.version || 1;
+        const newVersion = parentVersion + 1;
+        const newStateId = mintNextStateId(state_id, newVersion);
+
+        stateCache.set(newStateId, {
+          state_id: newStateId,
+          intent: intent || `(ops) ${priorState.intent}`,
+          plan: applied.newState.plan,
+          html: applied.newState.html,
+          source: 'refinement',
+          version: newVersion,
+          ops_history: [...(priorState.ops_history || []), ...a2uiMessages],
+          parent_state_id: state_id,
+          warnings: applied.newState.warnings,
+          delta_summary,
+          synthesis,
+          created_at: new Date().toISOString(),
+          duration_ms: Date.now() - startedAt,
+        });
+
+        await issueAccumulator.flush(issueCtx);
+
+        return {
+          content: [{ type: 'text', text: JSON.stringify({
+            state_id: newStateId,
+            ops_applied: a2uiMessages,
+            ops_failed: applied.ops_failed,
+            delta_summary,
+            warnings: [...warnings, ...(applied.newState.warnings || [])],
+            synthesis: synthesis ? { attempts: synthesis.attempts, targeted: synthesis.targeted, locatedTargets: synthesis.locatedTargets } : null,
+            html: applied.newState.html,
+          }, null, 2) }],
+        };
+      } catch (e) {
+        await issueAccumulator.flush(issueCtx);
+        return {
+          isError: true,
+          content: [{ type: 'text', text: JSON.stringify({ error: e.message }, null, 2) }],
+        };
+      }
+    },
+  );
+
+  server.tool(
+    'get_state',
+    `Inspect a cached composition state by state_id.
+
+Returns the full cache entry including the materialized HTML, the chunk binding plan, the chronological ops history (every refinement applied to this state's lineage), and the parent state_id (chain-back to the originating compose_from_chunks call).
+
+Useful for debugging refinement sequences, replaying a state's history, or verifying that a state_id is still cached before issuing a refine_composition call.
+
+Auto-fires a low-severity \`cache-miss-on-known-state\` issue when the state_id is not in the cache (the cache is bounded LRU; long-paused conversations may evict their state).`,
+    {
+      state_id: z.string().describe('State id from a prior compose_from_chunks or refine_composition call'),
+    },
+    async ({ state_id }) => {
+      const entry = stateCache.peek(state_id);
+      if (!entry) {
+        await autoReport(
+          'cache-miss-on-known-state',
+          { state_id, tool: 'get_state' },
+          { cache: stateCache, versionInfo: ENGINE_VERSION_INFO }
+        );
+        return {
+          isError: true,
+          content: [{ type: 'text', text: JSON.stringify({
+            error: 'state_id not found in cache',
+            state_id,
+          }, null, 2) }],
+        };
+      }
+      return {
+        content: [{ type: 'text', text: JSON.stringify({
+          state_id: entry.state_id,
+          intent: entry.intent,
+          plan: entry.plan,
+          html: entry.html,
+          source: entry.source,
+          version: entry.version || 1,
+          parent_state_id: entry.parent_state_id || null,
+          ops_history: entry.ops_history || [],
+          warnings: entry.warnings || [],
+          created_at: entry.created_at,
+        }, null, 2) }],
+      };
+    },
+  );
+
+  server.tool(
+    'report_issue',
+    `File a structured issue ticket — writes BOTH a machine-readable JSON file AND a human-readable Markdown report containing the full session trace (intent, retrieval log, LLM prompts, every attempt's raw response, composer plan, generated HTML preview, component count, warnings, environment).
+
+When to call (any of these is a trigger):
+  (a) USER PHRASES — call immediately when the user says any of:
+      "file a ticket", "log a ticket", "save a ticket",
+      "report this as a bug", "report this issue", "log this issue",
+      "save the trace", "capture the session", "save the session for review",
+      "create a session ticket", "this is broken — debug it",
+      "download the trace", "export this for review",
+      "track this regression", "open a ticket for this".
+  (b) USER COMPLAINS the output is broken / wrong / missing.
+  (c) YOU CANNOT satisfy the user's intent after retrying.
+  (d) YOU DETECT a mismatch between requested and produced output you can't fix.
+
+ALWAYS pass \`state_id\` from the most-recent compose_from_chunks or refine_composition call when one exists. The default \`trace: "full"\` then writes the high-resolution Markdown ticket. (Pass \`trace: "summary"\` for compact tickets, or \`trace: "none"\` to suppress the trace entirely.)
+
+Do NOT call this for ordinary clarification or for output the user has not yet seen.
+
+The tool returns BOTH paths in its response: \`path\` (.json) and \`markdown_path\` (.md). Surface BOTH to the user so they can navigate / download either:
+
+  📋 Logged ticket \`{issue_id}\` (\`{severity}\` · owner: {suggested_owner})
+  • Trace report: \`{markdown_path}\` ← human-readable, scan this first
+  • Raw JSON:     \`{path}\`           ← machine-readable
+
+Issue files land under \`.brain/audit-history/issues/\` (immutable; resolution lands in a sidecar file). Severity taxonomy matches the project's coherence-audit vocabulary: blocker = contract violation; drift = quality erosion; nit = cosmetic.`,
+    {
+      type: z.enum(['bug', 'training-gap', 'protocol-gap', 'ux-feedback']).describe('Issue category'),
+      severity: z.enum(['blocker', 'drift', 'nit']).describe('Severity tier'),
+      title: z.string().max(80).describe('One-line title (≤ 80 chars)'),
+      body: z.string().describe('Markdown body — observed vs expected, repro steps'),
+      state_id: z.string().optional().describe('State id from a prior tool call; auto-attaches the trace'),
+      trace: z.enum(['full', 'summary', 'none']).optional().describe('Trace depth — DEFAULT: "full" when state_id is provided (writes both .json + .md ticket with retrieval log, LLM prompts/attempts, plan, HTML preview). Use "summary" for compact tickets; "none" to suppress trace entirely.'),
+      suggested_owner: z.enum(['synthesis', 'retrieval', 'validator', 'chunk-corpus', 'mcp-protocol', 'unknown']).optional().describe('Best-guess owner for triage'),
+      tags: z.array(z.string()).optional().describe('Free-form tags for filtering'),
+    },
+    async ({ type, severity, title, body, state_id, trace, suggested_owner, tags }) => {
+      try {
+        const result = await reportIssueImpl(
+          { type, severity, title, body, state_id, trace, suggested_owner, tags },
+          {
+            cache: stateCache,
+            versionInfo: ENGINE_VERSION_INFO,
+            reporter: 'llm',
+          }
+        );
+        return {
+          content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        };
+      } catch (e) {
+        return {
+          isError: true,
+          content: [{ type: 'text', text: JSON.stringify({ error: e.message }, null, 2) }],
+        };
+      }
+    },
+  );
+}

package/evals/compose-from-chunks-holdout.jsonl

@@ -1,20 +0,0 @@
-{"id":"intent-001","kind":"compose","category":"data-display","intent":"kpi grid with 4 stat cards: users, revenue, sessions, churn","expected_components":["Card","Stat","Grid"],"expected_chunk":"kpi-grid-4-card"}
-{"id":"intent-002","kind":"compose","category":"forms","intent":"sign-in form with email + password + 'forgot password' link","expected_components":["Card","Input","Button","Field"],"expected_chunk":"auth-sign-in"}
-{"id":"intent-003","kind":"compose","category":"layout","intent":"settings page with three tabs (general, integrations, billing)","expected_components":["Tabs","Tab","Card","Section"],"expected_chunk":"settings-tabs-3"}
-{"id":"intent-004","kind":"compose","category":"data","intent":"data table of users with role badge + last-active timestamp","expected_components":["Table","Badge"],"expected_chunk":"users-table"}
-{"id":"intent-005","kind":"compose","category":"data-viz","intent":"conversion funnel chart over 6 stages, with drop-off labels","expected_components":["Chart","Card","ChartLegend"],"expected_chunk":"conversion-funnel"}
-{"id":"intent-006","kind":"compose","category":"agent","intent":"agent activity feed with reasoning steps + final artifact","expected_components":["AgentTrace","AgentReasoning","AgentArtifact"],"expected_chunk":"agent-activity-feed"}
-{"id":"intent-007","kind":"compose","category":"layout","intent":"split-pane editor: code on the left, preview on the right","expected_components":["EditorShell","Pane","Code"],"expected_chunk":"editor-split"}
-{"id":"intent-008","kind":"compose","category":"overlay","intent":"command palette modal with grouped results (recent, suggestions)","expected_components":["Command","Modal"],"expected_chunk":"command-grouped"}
-{"id":"intent-009","kind":"compose","category":"forms","intent":"registration step 2 of 5 — profile setup with 4 fields","expected_components":["Card","StepProgress","Field","Input"],"expected_chunk":"reg-step-shell"}
-{"id":"intent-010","kind":"compose","category":"layout","intent":"404 error page with breadcrumb + back-to-home link","expected_components":["Card","Breadcrumb","Button"],"expected_chunk":"error-404"}
-{"id":"intent-011","kind":"refine","category":"data-display","intent":"dashboard for project metrics","refine":"add a date-range filter at the top","expected_components":["Card","Stat","Select"],"expected_chunk":"project-dashboard"}
-{"id":"intent-012","kind":"refine","category":"display","intent":"user profile card","refine":"make the email editable inline","expected_components":["Card","Avatar","Input"],"expected_chunk":"user-profile-card"}
-{"id":"intent-013","kind":"refine","category":"data","intent":"kanban board with 3 columns","refine":"add a count badge to each column header","expected_components":["Card","Badge","Header"],"expected_chunk":"kanban-3col"}
-{"id":"intent-014","kind":"refine","category":"chat","intent":"chat surface with streaming reply","refine":"add a stop button while streaming","expected_components":["ChatShell","Button","ChatInput"],"expected_chunk":"chat-streaming"}
-{"id":"intent-015","kind":"refine","category":"forms","intent":"sign-up form with email + password","refine":"add password strength meter","expected_components":["Card","Input","Progress"],"expected_chunk":"auth-sign-up"}
-{"id":"intent-016","kind":"refine","category":"settings","intent":"settings tab for notifications","refine":"split email + push into separate sections","expected_components":["Card","Section","Switch"],"expected_chunk":"settings-notifications"}
-{"id":"intent-017","kind":"refine","category":"data","intent":"table of orders","refine":"add a bulk-action toolbar above the table","expected_components":["Table","TableToolbar","Button"],"expected_chunk":"orders-table"}
-{"id":"intent-018","kind":"refine","category":"agent","intent":"agent reasoning panel","refine":"collapse intermediate steps by default, expandable","expected_components":["AgentReasoning","Accordion"],"expected_chunk":"agent-reasoning-collapsed"}
-{"id":"intent-019","kind":"refine","category":"overlay","intent":"modal confirming destructive action","refine":"require typing the resource name to confirm","expected_components":["Modal","Input","Button"],"expected_chunk":"destructive-confirm"}
-{"id":"intent-020","kind":"refine","category":"display","intent":"marketing landing hero","refine":"add a secondary 'see demo' CTA","expected_components":["Card","Heading","Button"],"expected_chunk":"marketing-hero"}