@adia-ai/a2ui-mcp 0.1.3 → 0.2.1

package/server.js

@@ -26,7 +26,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { z } from 'zod';
 
 // ── Import from a2ui ──
-import { generateUI } from '../compose/engine/generator.js';
+import { generateUI } from '../compose/core/generator.js';
 import { validateSchema } from '../validator/validator.js';
 import { validateMessages as validateCatalogMessages } from '../validator/catalog-validator.js';
 import {
@@ -52,11 +52,11 @@ import {
   getAllCompositions as getAllZettelCompositions,
   searchAll as searchZettelAll,
   getGraph as getZettelGraph,
-} from '../compose/engines/zettel/fragment-library.js';
+} from '../compose/strategies/zettel/fragment-library.js';
 import {
   resolveComposition as resolveZettelComposition,
   templateToMessages as zettelTemplateToMessages,
-} from '../compose/engines/zettel/composer.js';
+} from '../compose/strategies/zettel/composer.js';
 // Zettel bootstrap is still needed for get_fragment/resolve_composition tools;
 // the generate_ui tool now dispatches through the unified registry in gen-ui.
 
@@ -74,6 +74,16 @@ import {
   searchChunks as searchGenUIChunks,
 } from '../corpus/scripts/chunk-library.js';
 
+// ── Inline-tool deps (transpiler / wiring / patterns / feedback) ──
+import { transpileHTML } from '../compose/transpiler/transpiler.js';
+import { getWiringCatalog } from '../retrieval/wiring-catalog.js';
+import { registerPattern } from '../retrieval/pattern-library.js';
+import { FeedbackCollector } from '../retrieval/feedback/feedback.js';
+import { feedbackStore } from '../retrieval/feedback/feedback-store.js';
+
+// ── Tools extracted to tools/ for modularity ──
+import { registerSynthesisTools } from './tools/synthesis.js';
+
 const _chunkIndex = getChunkIndex();
 if (_chunkIndex) {
   console.error(
@@ -279,9 +289,6 @@ server.tool(
 
 // ── Transpiler & Wiring Tools ──
 
-import { transpileHTML } from '../compose/transpiler/transpiler.js';
-import { getWiringCatalog } from '../retrieval/wiring-catalog.js';
-
 server.tool(
   'convert_html',
   'Convert HTML markup to A2UI flat adjacency component messages. Maps HTML tags to AdiaUI components, infers layout from styles, enforces Card content model.',
@@ -311,9 +318,6 @@ server.tool(
 
 // ── Pattern & Feedback Tools ──
 
-import { registerPattern } from '../retrieval/pattern-library.js';
-import { FeedbackCollector } from '../retrieval/feedback.js';
-
 const feedbackCollector = new FeedbackCollector();
 
 server.tool(
@@ -378,8 +382,6 @@ server.tool(
 
 // ── Quality metrics tool ──
 
-import { feedbackStore } from '../retrieval/feedback-store.js';
-
 server.tool(
   'get_quality_metrics',
   'Get aggregated quality metrics from the feedback store: avg score, thumb-up rate, per-domain breakdown, training gaps.',
@@ -656,405 +658,16 @@ Pair with \`get_chunk\` to fetch full records for any of the returned names.`,
   },
 );
 
-// ── Chunk-aware composition synthesizer (Phase C.2) ──────────────────
-// Mix-and-match: when retrieval returns no strong match, the LLM picks a
-// page chunk + binds block/panel chunks to its slots. Validator checks
-// chunk names + kind contracts; composer materializes to HTML.
+// ── Chunk-aware composition + multi-turn refinement ──────────────────
+// `compose_from_chunks`, `refine_composition`, `get_state`, `report_issue`
+// share the LLM bridge + state-cache + issue-reporter + chunk-refiner
+// stack. Extracted to tools/synthesis.js.
 //
-// Spec: docs/specs/genui-chunk-marker.md (§ "Harvester contract", future:
-// composition reasoning). Plan: docs/plans/training-pipeline-chunk-harvest-2026-04-27.md.
-
-import { composeFromIntent as composeFromChunksImpl } from '../compose/engines/zettel/chunk-synthesizer.js';
-import { composeFromPlan, validatePlan } from '../compose/engines/zettel/chunk-composer.js';
-import { createAdapter as createLLMAdapter } from '../compose/llm/llm-bridge.js';
-
-// ── Multi-turn architecture (Phase A) ────────────────────────────────
-// Spec: docs/specs/genui-multiturn-architecture.md (Draft v0.1.0).
-// Plan: docs/plans/genui-multiturn-rollout-2026-04-28.md (Phase A scoped).
-
-import {
-  getStateCache,
-  mintStateId,
-  mintNextStateId,
-} from '../compose/engines/zettel/state-cache.js';
-import {
-  reportIssue as reportIssueImpl,
-  autoReport,
-  createIssueAccumulator,
-} from '../compose/engines/zettel/issue-reporter.js';
-import {
-  refineFromIntent,
-  applyOps,
-  opsToA2UI,
-  validateOps,
-} from '../compose/engines/zettel/chunk-refiner.js';
-
-const stateCache = getStateCache();
-
-const ENGINE_VERSION_INFO = {
-  mcp: '0.1.0',
-  corpus: '0.0.6',
-  engine: 'zettel',
-  llm_adapter: 'anthropic',
-  model: process.env.ANTHROPIC_MODEL || 'claude-opus-4-7',
-};
-
-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,
-        created_at: new Date().toISOString(),
-      });
-      return {
-        content: [{ type: 'text', text: JSON.stringify({
-          state_id,
-          html: result.html,
-          plan: result.plan,
-          source: result.source,
-          score: result.score,
-          warnings: result.warnings,
-          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 tools (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.
+// Spec: docs/specs/genui-multiturn-architecture.md (Phase A) +
+// docs/specs/genui-chunk-marker.md.
 
-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).
+registerSynthesisTools(server);
 
-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 when something is wrong with the gen-UI output, the tool surface, or the training data.
-
-Use when:
-  (a) the user explicitly says the output is broken / wrong / missing,
-  (b) you cannot satisfy the user's intent after retrying,
-  (c) you detect a mismatch between requested and produced output that you cannot fix.
-
-Include \`state_id\` for full trace attachment (input + output + LLM prompts/responses + validator results, when available in the cache).
-
-Do NOT call this for ordinary clarification or for output the user has not yet seen.
-
-Issue files land at \`.brain/audit-history/issues/<issue_id>.json\` (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: summary if state_id provided, else none)'),
-    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) }],
-      };
-    }
-  },
-);
 
 // ── Start ──