@adia-ai/a2ui-mcp 0.0.5 → 0.1.1

package/server.js

@@ -668,6 +668,37 @@ import { composeFromIntent as composeFromChunksImpl } from '../compose/engines/z
 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.
@@ -704,8 +735,20 @@ plan to skip the LLM call and just materialize HTML.`,
         };
       }
       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,
@@ -728,8 +771,23 @@ plan to skip the LLM call and just materialize HTML.`,
         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,
@@ -747,6 +805,257 @@ plan to skip the LLM call and just materialize HTML.`,
   },
 );
 
+// ── 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.
+
+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 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 ──
 
 async function main() {