@adia-ai/a2ui-mcp 0.0.4 → 0.1.0

package/CHANGELOG.md

@@ -11,6 +11,137 @@ zettel strategies.
 
 ---
 
+## [0.1.0] - 2026-04-28
+
+**Multi-turn gen-UI tool surface (Phase A code-complete).** Adds three new
+MCP tools that turn the chunk-composition pipeline from single-shot into a
+multi-turn surface, plus extends `compose_from_chunks` to mint a `state_id`
+for refinement chains.
+
+Spec: [`docs/specs/genui-multiturn-architecture.md`](../../../docs/specs/genui-multiturn-architecture.md) (Active v0.1.0).
+Plan: [`docs/plans/genui-multiturn-rollout-2026-04-28.md`](../../../docs/plans/genui-multiturn-rollout-2026-04-28.md) (Phase A scoped).
+ADR: [`0008-multiturn-genui-architecture.md`](../../../.brain/adrs/0008-multiturn-genui-architecture.md).
+
+### Added (MCP tools)
+
+- **`refine_composition(state_id, intent | ops, max_attempts?)`** — takes a
+  `state_id` from a prior `compose_from_chunks` (or `refine_composition`)
+  call plus either a natural-language intent OR an explicit op-list, runs
+  the chunk-refiner's two-pass synthesis (locator → modifier; validator-
+  driven retry on op-validation failure), applies the resulting chunk-plan
+  ops, re-materializes HTML, mints a child `state_id` chained back to the
+  parent, and returns A2UI `updateComponents` messages (the wire format).
+  Failed ops surface in `ops_failed` with reasons; the new state is cached
+  for further refinement.
+- **`get_state(state_id)`** — read-only inspection of a cached composition
+  state. Returns the chunk binding plan, materialized HTML, ops history
+  (chronological list of every refinement applied to this state's lineage),
+  and `parent_state_id` (chain-back). Auto-fires `cache-miss-on-known-state`
+  (severity `nit`) when the id is absent.
+- **`report_issue(type, severity, title, body, state_id?, trace?, …)`** —
+  first-class telemetry / dev-process feedback tool. Writes a structured
+  JSON ticket to `.brain/audit-history/issues/<issue_id>.json`. Three
+  reporter kinds: LLM self-fire (this tool with `reporter: 'llm'`),
+  consumer-fire (passed through directly), engine auto-fire (internal,
+  per `AUTO_FIRE_POLICY` in the issue-reporter module). Severity vocabulary
+  `blocker | drift | nit` matches the existing `coherence-audit`
+  discipline. Trace levels: `'full' | 'summary' | 'none'`; oversized
+  traces (> 200 KB) spill to a sidecar `.trace.json` file. Tool count
+  goes from 25 → 28.
+
+### Changed
+
+- **`compose_from_chunks`** now mints a `state_id` and caches the result
+  before returning. The response shape gains a `state_id` field; existing
+  fields (`html`, `plan`, `source`, `score`, `warnings`, `synthesis`)
+  are unchanged. Backward-compatible — consumers ignoring `state_id` see
+  no behavior change.
+- **MCP server boot** instantiates a `getStateCache()` singleton and an
+  `ENGINE_VERSION_INFO` block (mcp 0.1.0, corpus 0.0.6, engine zettel,
+  llm_adapter anthropic) that's threaded through every issue-reporter
+  call so written tickets carry environment metadata.
+
+### Auto-fire policy (engine-driven)
+
+`refine_composition` and `get_state` auto-fire `report_issue` on these
+failure paths via the per-tool-call `IssueAccumulator`:
+
+| Path | Type | Severity |
+|---|---|---|
+| Synthesizer exhausts retries | bug | drift |
+| Validator exhausts retries on refinement | bug | blocker |
+| Locator pass returns empty for targeted intent | bug | drift |
+| Retrieval 0 + synthesis fallback fails | training-gap | drift |
+| `get_state` called with absent `state_id` | bug | nit |
+| `refine_composition` ops_failed list non-empty | bug | drift |
+
+Multiple auto-fires within one tool call coalesce into a single issue
+(highest severity wins; reasons listed in body + tags).
+
+### Smoke + eval
+
+- `smoke:state-cache` — 34/34.
+- `smoke:issues` — 62/62.
+- `smoke:refine` — 51/51 (stub LLM).
+- `test:a2ui` — 25/25 + 1 skipped (was 19/19 + 1; +6 multi-turn assertions).
+- `mcp:smoke` — server boots clean with 28 tools registered.
+- **`eval:refine-synthesis`** — 15/15 PASS. Ops 100%, validate 100%,
+  0 auto-fires, 67 s.
+- **No regression:** `eval:chunk-synthesis` 10/10, `eval:diff zettel`
+  coverage 83 / score 89 / MRR 0.986.
+
+### Dependencies
+
+- Bumps `@adia-ai/a2ui-compose` requirement from `^0.0.1` to `^0.1.0`.
+
+### Migration
+
+Additive surface; no breaking changes. The existing 25 tools are
+unchanged behaviorally; `compose_from_chunks` adds a `state_id` field to
+its response that ignoring consumers can safely drop.
+
+### Phase A simplification (documented)
+
+Refinement ops internally use a chunk-plan vocabulary
+(`rebindSlot | appendToSlot | removeFromSlot | replacePage`), wrapped
+on output as standard `updateComponents` A2UI messages with
+`components[].html` carrying the materialized payload. Strict
+component-tree shape upgrade is queued for Phase B.
+
+---
+
+## [0.0.5] - 2026-04-28
+
+**Retires the legacy exemplar auto-ingest.** Server boot no longer pulls
+70 patterns from the prose exemplars on every start. The chunk corpus
++ chunk-aware synthesizer is the training surface now (`compose_from_chunks`
++ `search_chunks` + `get_chunk` + `lookup_chunk` from 0.0.2).
+
+### Changed
+
+- **`server.js` boot path** — removed the `auto-ingest` block that called
+  `ingestAll()` at startup. The runtime pattern library reverts from 225
+  (155 hand-authored + 70 ingested) to **155 hand-authored only**. Eval
+  metrics confirm no regression: `eval:diff zettel` still reports
+  coverage 83 / score 89; `smoke:chunks` still 33/33; `eval:chunk-synthesis`
+  still PASS at 100% / 9 retrieval / 1 synthesis on the hold-out set.
+- **`test:a2ui` test 6 updated** — was asserting "post-ingest count ≥ 200
+  patterns"; now asserts the two training-corpus surfaces independently:
+  pattern library ≥ 100 hand-authored entries (155 today), chunk corpus
+  ≥ 500 unique chunks (701 today).
+
+### Dependencies
+
+- Bumps `@adia-ai/a2ui-corpus` requirement from `^0.0.5` to `^0.0.6`.
+
+### Migration (none required)
+
+- Pure runtime simplification. Existing MCP consumers experience the
+  same tool surface; the only observable change is faster boot (no
+  ingest round trip) and a smaller in-memory pattern library.
+
+---
+
 ## [0.0.4] - 2026-04-28
 
 Dependency-only bump to pull `@adia-ai/a2ui-corpus@^0.0.5` (one fewer

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/a2ui-mcp",
-  "version": "0.0.4",
+  "version": "0.1.0",
   "description": "AdiaUI A2UI MCP server. Exposes the compose engine over MCP with an engine selector for monolithic + zettel strategies.",
   "type": "module",
   "bin": {
@@ -26,10 +26,10 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@adia-ai/a2ui-compose": "^0.0.1",
+    "@adia-ai/a2ui-compose": "^0.1.0",
     "@adia-ai/a2ui-retrieval": "^0.0.1",
     "@adia-ai/a2ui-validator": "^0.0.1",
-    "@adia-ai/a2ui-corpus": "^0.0.5",
+    "@adia-ai/a2ui-corpus": "^0.0.6",
     "zod": "^3.24.0"
   }
 }

package/scripts/eval-refine-synthesis.mjs

@@ -0,0 +1,270 @@
+#!/usr/bin/env node
+/**
+ * Real-LLM eval set for the chunk-refiner — multi-turn refinement engine.
+ *
+ * Walks 5 seed compositions × 3 refinement intents = 15 total. Seeds are
+ * deterministic chunk-binding plans (no LLM cost on the create side); the
+ * refiner exercises the full two-pass synthesis (locator → modifier),
+ * validator-driven retry, and op-application path.
+ *
+ * Pass criteria (per spec §6.2 + plan §1.7):
+ *   - ≥ 80% of refinements produce ops (no all-fail outcome).
+ *   - ≥ 90% of returned ops apply cleanly (validator + applyOps).
+ *   - ≤  5 auto-fired issues across the full run (plan §1.8 #3).
+ *
+ * Spec: docs/specs/genui-multiturn-architecture.md (Active v0.1.0).
+ * Plan: docs/plans/genui-multiturn-rollout-2026-04-28.md (Phase A).
+ *
+ * Usage:
+ *   ANTHROPIC_API_KEY=… node packages/a2ui/mcp/scripts/eval-refine-synthesis.mjs
+ */
+
+import '../../../../scripts/load-env.mjs';
+import {
+  refineFromIntent,
+  applyOps,
+} from '../../compose/engines/zettel/chunk-refiner.js';
+import { mintStateId } from '../../compose/engines/zettel/state-cache.js';
+import { createIssueAccumulator } from '../../compose/engines/zettel/issue-reporter.js';
+import { composeFromPlan } from '../../compose/engines/zettel/chunk-composer.js';
+import { listChunksByKind, getChunk } from '../../corpus/scripts/chunk-library.js';
+import { createAdapter } from '../../compose/llm/llm-bridge.js';
+
+// ── Discover corpus shape ────────────────────────────────────────────
+// Pick a page with ≥ 2 slots so refinements have room to target.
+
+const pages = listChunksByKind('page');
+const panels = listChunksByKind('panel');
+const blocks = listChunksByKind('block');
+
+const slotsOf = (c) => (c.slots || c.instances?.[0]?.slots || []).map((s) => s.name);
+
+const samplePage =
+  pages.find((p) => slotsOf(p).length >= 2)
+  || panels.find((p) => slotsOf(p).length >= 2)
+  || pages[0]
+  || panels[0];
+
+if (!samplePage || slotsOf(samplePage).length === 0) {
+  console.error('Corpus has no page/panel chunks with declared slots — aborting eval');
+  process.exit(2);
+}
+
+const pageSlots = slotsOf(samplePage);
+const slotA = pageSlots[0];                  // typically the header slot
+const slotB = pageSlots[1] || pageSlots[0];  // typically the content slot
+
+// Pick at least 4 distinct block chunks. Filter out anything missing HTML.
+const usableBlocks = blocks
+  .filter((b) => (b.html || b.instances?.[0]?.html))
+  .slice(0, 8)
+  .map((b) => b.name);
+
+if (usableBlocks.length < 4) {
+  console.error(`Corpus has only ${usableBlocks.length} usable block chunks (need ≥ 4) — aborting eval`);
+  process.exit(2);
+}
+
+const [B0, B1, B2, B3, B4 = B0, B5 = B1] = usableBlocks;
+
+console.log(`▶ refine-synthesis eval`);
+console.log(`  page: ${samplePage.name} (${pageSlots.join(', ')})`);
+console.log(`  blocks: ${usableBlocks.slice(0, 6).join(', ')}`);
+console.log('');
+
+// ── Seeds + refinements ──────────────────────────────────────────────
+// 5 seeds × 3 refinements = 15 hold-out intents.
+
+const SEEDS = [
+  {
+    label: 'two-block-content',
+    plan: {
+      page: samplePage.name,
+      slot_bindings: { [slotA]: [B0], [slotB]: [B1, B2] },
+    },
+    refinements: [
+      `add another block to ${slotB}`,
+      `remove one block from ${slotB}`,
+      `swap the ${slotA} for a different option`,
+    ],
+  },
+  {
+    label: 'single-block-content',
+    plan: {
+      page: samplePage.name,
+      slot_bindings: { [slotA]: [B0], [slotB]: [B1] },
+    },
+    refinements: [
+      `add a second block alongside the existing one in ${slotB}`,
+      `replace the ${slotA} with a more concise header`,
+      `preserve the existing block and append another to ${slotB}`,
+    ],
+  },
+  {
+    label: 'three-block-stack',
+    plan: {
+      page: samplePage.name,
+      slot_bindings: { [slotA]: [B0], [slotB]: [B1, B2, B3] },
+    },
+    refinements: [
+      `remove the middle block from ${slotB}`,
+      `drop the last block from ${slotB}`,
+      `make the layout more compact`,
+    ],
+  },
+  {
+    label: 'header-only',
+    plan: {
+      page: samplePage.name,
+      slot_bindings: { [slotA]: [B0], [slotB]: [B1] },
+    },
+    refinements: [
+      `add an additional block to ${slotB}`,
+      `change the ${slotA}`,
+      `preserve everything and add a new block to ${slotB}`,
+    ],
+  },
+  {
+    label: 'mixed-stack',
+    plan: {
+      page: samplePage.name,
+      slot_bindings: { [slotA]: [B0], [slotB]: [B2, B3] },
+    },
+    refinements: [
+      `swap the first block in ${slotB} for a different one`,
+      `add another block at the end of ${slotB}`,
+      `drop the last block from ${slotB}`,
+    ],
+  },
+];
+
+// ── Run ──────────────────────────────────────────────────────────────
+
+const llmAdapter = await createAdapter();
+const startedAt = Date.now();
+const results = [];
+const autoFires = { total: 0, byReason: {} };
+
+for (const seed of SEEDS) {
+  // Materialize the seed plan (no LLM call; pure compose-from-plan).
+  const composed = composeFromPlan(seed.plan);
+  if (!composed.html) {
+    console.log(`✗ seed [${seed.label}] failed to materialize — skipping refinements`);
+    for (const intent of seed.refinements) {
+      results.push({
+        seed: seed.label, intent, ms: 0, ops_count: 0, attempts: 0,
+        targeted: null, ops_applied: 0, ops_failed: 0,
+        auto_fires: [], error: 'seed-materialize-failed',
+      });
+    }
+    continue;
+  }
+
+  const priorState = {
+    state_id: mintStateId(seed.label, 1),
+    intent: `[seed] ${seed.label}`,
+    plan: seed.plan,
+    html: composed.html,
+    version: 1,
+  };
+
+  console.log(`── seed [${seed.label}] · ${seed.plan.slot_bindings[slotB].length} block(s) in ${slotB}`);
+
+  for (const intent of seed.refinements) {
+    const acc = createIssueAccumulator();
+    const t0 = Date.now();
+    const row = {
+      seed: seed.label, intent, ms: 0, ops_count: 0, attempts: 0,
+      targeted: null, ops_applied: 0, ops_failed: 0,
+      auto_fires: [], error: null,
+    };
+
+    try {
+      const refined = await refineFromIntent({
+        priorState,
+        intent,
+        llmAdapter,
+        maxAttempts: 2,
+        issueAccumulator: acc,
+      });
+      row.ms = Date.now() - t0;
+      row.ops_count = refined.ops.length;
+      row.attempts = refined.synthesis?.attempts ?? 0;
+      row.targeted = refined.synthesis?.targeted ?? null;
+
+      if (refined.ops.length > 0) {
+        const applied = await applyOps({ priorState, ops: refined.ops });
+        row.ops_applied = applied.ops_applied.length;
+        row.ops_failed = applied.ops_failed.length;
+      }
+    } catch (e) {
+      row.ms = Date.now() - t0;
+      row.error = e.message;
+    }
+
+    row.auto_fires = acc.reasons();
+    autoFires.total += row.auto_fires.length;
+    for (const r of row.auto_fires) {
+      autoFires.byReason[r] = (autoFires.byReason[r] || 0) + 1;
+    }
+
+    results.push(row);
+
+    const flag = row.ops_count > 0 && row.ops_failed === 0 ? '✓' : (row.ops_count > 0 ? '~' : '✗');
+    const tgtTag = row.targeted === true ? 'tgt' : row.targeted === false ? 'unt' : '???';
+    const padMs = row.ms.toString().padStart(5);
+    console.log(`  ${flag} [${tgtTag}] ${padMs}ms ops=${row.ops_count} att=${row.attempts} ${intent}`);
+    if (row.error) console.log(`        error: ${row.error}`);
+    if (row.ops_failed > 0) console.log(`        ops_failed: ${row.ops_failed}`);
+    if (row.auto_fires.length) console.log(`        auto-fires: ${row.auto_fires.join(', ')}`);
+  }
+}
+
+// ── Summary ──────────────────────────────────────────────────────────
+
+const total = results.length;
+const producedOps = results.filter((r) => r.ops_count > 0).length;
+const totalOpsReturned = results.reduce((s, r) => s + r.ops_count, 0);
+const totalOpsApplied = results.reduce((s, r) => s + r.ops_applied, 0);
+const totalOpsFailed = results.reduce((s, r) => s + r.ops_failed, 0);
+
+const opsRate = total ? producedOps / total : 0;
+const validateRate = totalOpsReturned ? totalOpsApplied / totalOpsReturned : 0;
+
+console.log(`\n── Summary ──`);
+console.log(`  Refinements: ${total}`);
+console.log(`  Produced ops: ${producedOps}/${total} (${(opsRate * 100).toFixed(0)}%)`);
+console.log(`  Ops returned: ${totalOpsReturned}; applied: ${totalOpsApplied}; failed: ${totalOpsFailed} (validate ${(validateRate * 100).toFixed(0)}%)`);
+console.log(`  Auto-fires: ${autoFires.total}`);
+if (autoFires.total > 0) {
+  for (const [reason, n] of Object.entries(autoFires.byReason)) {
+    console.log(`    ${reason}: ${n}`);
+  }
+}
+const targeted = results.filter((r) => r.targeted === true).length;
+const untargeted = results.filter((r) => r.targeted === false).length;
+console.log(`  Targeted vs untargeted: ${targeted} / ${untargeted}`);
+console.log(`  Total time: ${((Date.now() - startedAt) / 1000).toFixed(1)}s`);
+
+const opsThreshold = 0.8;
+const validateThreshold = 0.9;
+const autoFireCeiling = 5;
+
+const opsPass = opsRate >= opsThreshold;
+const validatePass = totalOpsReturned === 0 || validateRate >= validateThreshold;
+const autoFirePass = autoFires.total <= autoFireCeiling;
+
+const allPass = opsPass && validatePass && autoFirePass;
+
+console.log('');
+console.log(`  ops rate ≥ ${opsThreshold * 100}%:   ${opsPass ? '✓' : '✗'} (${(opsRate * 100).toFixed(0)}%)`);
+console.log(`  validate ≥ ${validateThreshold * 100}%:    ${validatePass ? '✓' : '✗'} (${(validateRate * 100).toFixed(0)}%)`);
+console.log(`  auto-fires ≤ ${autoFireCeiling}:    ${autoFirePass ? '✓' : '✗'} (${autoFires.total})`);
+
+if (allPass) {
+  console.log(`\n✓ PASS`);
+  process.exit(0);
+} else {
+  console.log(`\n✗ FAIL`);
+  process.exit(1);
+}