@adia-ai/a2ui-mcp 0.6.0 → 0.6.2

package/CHANGELOG.md

@@ -10,6 +10,25 @@ zettel strategies.
 
 _No pending changes._
 
+## [0.6.2] - 2026-05-18
+
+### v0.6.2 §357 — TypeScript-first Phase 4: `@adia-ai/a2ui-mcp` sources → `.ts`
+
+`tools/synthesis.ts` + `server.ts`. mcp:smoke OK, generate.mjs end-to-end OK.
+**No BREAKING changes.**
+
+
+
+## [0.6.1] - 2026-05-18
+
+### v0.6.1 — Lockstep ride-along
+
+`@adia-ai/llm` TS Phase 2 (§353) + `<link-ui>` token rename (§354) +
+`@adia-ai/a2ui-compose` TS Phase 3 (§355). No source changes in this package.
+Internal dep ranges stay at `^0.6.0`.
+
+
+
 ## [0.6.0] - 2026-05-18
 
 _Lockstep ride-along (no source change in this package; companion to web-components v0.6.0 — see root CHANGELOG)._

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/a2ui-mcp",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "AdiaUI A2UI MCP server. Exposes the compose engine over MCP with an engine selector for monolithic + zettel strategies.",
   "type": "module",
   "bin": {

package/tools/synthesis.ts

@@ -0,0 +1,449 @@
+/**
+ * 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).
+ */
+
+// Node's `process` global is not in scope under `"types": []` — declare
+// minimally for the env-var access below.
+declare const process: { env: Record<string, string | undefined> } | undefined;
+
+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 '../../../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';
+
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+const stateCache = getStateCache();
+
+const ENGINE_VERSION_INFO = {
+  mcp: '0.2.0',
+  corpus: '0.2.0',
+  engine: 'zettel',
+  llm_adapter: 'anthropic',
+  model: (typeof process !== 'undefined' && process.env['ANTHROPIC_MODEL']) || 'claude-opus-4-7',
+};
+
+export { stateCache, ENGINE_VERSION_INFO, autoReport, reportIssueImpl };
+
+export function registerSynthesisTools(server: McpServer): void {
+  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) {
+        const err = e instanceof Error ? e : new Error(String(e));
+        return {
+          isError: true,
+          content: [{ type: 'text', text: JSON.stringify({ error: err.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: unknown[];
+        let delta_summary = '';
+        let synthesis: unknown = null;
+        let warnings: unknown[] = [];
+
+        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 as { version?: number })['version'] ?? 1) + 1);
+            const synthInfo = synthesis as { attempts?: unknown; targeted?: unknown } | null;
+            return {
+              content: [{ type: 'text', text: JSON.stringify({
+                state_id: childId,
+                ops_applied: [],
+                ops_failed: [],
+                delta_summary: '',
+                warnings,
+                synthesis: synthInfo ? { attempts: synthInfo['attempts'], targeted: synthInfo['targeted'] } : null,
+                html: (priorState as { html?: unknown })['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 as { version?: number })['version']) ?? 1;
+        const newVersion = parentVersion + 1;
+        const newStateId = mintNextStateId(state_id, newVersion);
+
+        stateCache.set(newStateId, {
+          state_id: newStateId,
+          intent: intent ?? `(ops) ${(priorState as { intent?: string })['intent'] ?? ''}`,
+          plan: (applied.newState as { plan?: unknown })['plan'],
+          html: (applied.newState as { html?: unknown })['html'],
+          source: 'refinement',
+          version: newVersion,
+          ops_history: [...((priorState as { ops_history?: unknown[] })['ops_history'] ?? []), ...a2uiMessages],
+          parent_state_id: state_id,
+          warnings: (applied.newState as { warnings?: unknown })['warnings'],
+          delta_summary,
+          synthesis,
+          created_at: new Date().toISOString(),
+          duration_ms: Date.now() - startedAt,
+        });
+
+        await issueAccumulator.flush(issueCtx);
+
+        const synthInfo = synthesis as { attempts?: unknown; targeted?: unknown; locatedTargets?: unknown } | null;
+        const newStateWarnings = (applied.newState as { warnings?: unknown[] })['warnings'] ?? [];
+        return {
+          content: [{ type: 'text', text: JSON.stringify({
+            state_id: newStateId,
+            ops_applied: a2uiMessages,
+            ops_failed: applied.ops_failed,
+            delta_summary,
+            warnings: [...warnings, ...newStateWarnings],
+            synthesis: synthInfo ? { attempts: synthInfo['attempts'], targeted: synthInfo['targeted'], locatedTargets: synthInfo['locatedTargets'] } : null,
+            html: (applied.newState as { html?: unknown })['html'],
+          }, null, 2) }],
+        };
+      } catch (e) {
+        await issueAccumulator.flush(issueCtx);
+        const err = e instanceof Error ? e : new Error(String(e));
+        return {
+          isError: true,
+          content: [{ type: 'text', text: JSON.stringify({ error: err.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) }],
+        };
+      }
+      const e = entry as Record<string, unknown>;
+      return {
+        content: [{ type: 'text', text: JSON.stringify({
+          state_id: e['state_id'],
+          intent: e['intent'],
+          plan: e['plan'],
+          html: e['html'],
+          source: e['source'],
+          version: e['version'] ?? 1,
+          parent_state_id: e['parent_state_id'] ?? null,
+          ops_history: e['ops_history'] ?? [],
+          warnings: e['warnings'] ?? [],
+          created_at: e['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 ui-audit-coherence 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) {
+        const err = e instanceof Error ? e : new Error(String(e));
+        return {
+          isError: true,
+          content: [{ type: 'text', text: JSON.stringify({ error: err.message }, null, 2) }],
+        };
+      }
+    },
+  );
+}