@adia-ai/gen-ui 0.8.37

package/compose/strategies/zettel/chunk-refiner.js

@@ -0,0 +1,582 @@
+/**
+ * chunk-refiner — multi-turn refinement engine for chunk-composed UIs.
+ *
+ * Sibling to chunk-synthesizer.js. Where the synthesizer produces fresh
+ * compositions from intent, the refiner takes a prior composition + intent
+ * and emits ops that mutate it.
+ *
+ * Phase A scope (per .claude/docs/specs/genui-multiturn-architecture.md §4):
+ *   - Two-pass synthesis (locator → modifier).
+ *   - Validator-driven retry loop, default maxAttempts=2.
+ *   - Op format: chunk-plan-level ops internally; A2UI-message-shaped on output.
+ *   - Auto-fires on engine failure paths through the IssueAccumulator passed
+ *     in via opts (issueAccumulator).
+ *
+ * Phase A simplification: refinements operate on the chunk binding plan
+ * (rebindSlot / appendToSlot / removeFromSlot / replacePage). The
+ * `opsToA2UI()` translator wraps each plan-mutation in a standard
+ * `updateComponents` A2UI message so the wire-format contract holds.
+ * Phase B may introduce richer component-tree refinements; this Phase A
+ * approach honors the wire format while keeping engine code focused on the
+ * chunk corpus.
+ */
+
+import {
+  getChunk,
+  listChunksByKind,
+  searchChunksAsync,
+} from '../../../corpus/scripts/chunk-library.js';
+import { composeFromPlan } from './chunk-composer.js';
+
+const DEFAULT_MAX_ATTEMPTS = 2;
+const PRE_SEARCH_LIMIT = 30;
+const SURFACE_ID = 'main';
+
+const VALID_OP_TYPES = new Set(['rebindSlot', 'appendToSlot', 'removeFromSlot', 'replacePage']);
+
+const LOCATOR_SYSTEM_PROMPT = `You identify which slots in an existing UI need modification.
+
+You are given:
+  - An "intent" describing what the user wants changed.
+  - A "component map" listing the slots in the prior UI, each with its name
+    and the chunks currently bound to it.
+
+If the component map is EMPTY, the prior UI is a single chunk with no bindable
+slots. There is nothing to target: return { "targeted": false, "target_slots": [] }.
+
+Decide if the intent is:
+  - "targeted" — the user named a specific slot/element to change, OR the
+    intent's verb implies a localized change (e.g. "change the title",
+    "remove the funnel", "add a country list to page-content").
+  - "untargeted" — broad changes touching many slots (e.g. "make everything
+    more compact", "use teal not blue").
+
+If targeted, return target_slots: list of slot names to modify.
+If untargeted, return targeted: false and target_slots: [].
+
+Return ONLY a JSON object: { "targeted": bool, "target_slots": string[] }.
+No prose. Begin with {.`;
+
+const MODIFIER_SYSTEM_PROMPT = `You emit refinement ops on an existing chunk-composed UI.
+
+Op types:
+  - rebindSlot:    replace a slot's binding entirely.
+                   { "type": "rebindSlot", "slot": "<name>", "chunks": ["<chunk-name>"...] }
+  - appendToSlot:  append chunk(s) to the END of a slot's bound list.
+                   { "type": "appendToSlot", "slot": "<name>", "chunks": ["<chunk-name>"...] }
+  - removeFromSlot: remove chunks from a slot's bound list by index.
+                   { "type": "removeFromSlot", "slot": "<name>", "indices": [0, 2] }
+  - replacePage:   swap the page chunk entirely.
+                   { "type": "replacePage", "page": "<page-chunk-name>", "slot_bindings": { ... } }
+
+Rules:
+  - Mutate only the slots you've been told to target (when target_slots provided).
+  - Every chunk name must exist in the catalog.
+  - Multi-clause intents → emit multiple ops.
+
+SINGLE-CHUNK PRIOR (the prior plan lists NO slot bindings):
+  The prior UI is one chunk with no slots, so slot ops have nothing to
+  address — they will fail validation. Emit exactly ONE "replacePage" op that
+  re-roots the UI in a shell:
+    - "page" MUST be a catalog chunk with kind=page or kind=panel.
+    - "slot_bindings" MUST bind the PRIOR chunk (named in the prompt) into one
+      of that shell's slots, so the existing UI is preserved, PLUS the chunk(s)
+      the intent asks to add. Never drop the prior chunk unless the intent
+      explicitly asks to remove it.
+
+Return ONLY a JSON object: { "ops": [...], "delta_summary": "<one-line>" }.
+No prose. Begin with {.`;
+
+function buildComponentMap(priorState) {
+  const plan = priorState?.plan;
+  if (!plan?.slot_bindings) return [];
+  return Object.entries(plan.slot_bindings).map(([slot, bound]) => ({
+    slot,
+    chunks: Array.isArray(bound) ? bound : [bound],
+  }));
+}
+
+/**
+ * A plan with no slot bindings is a single-chunk composition — what the
+ * retrieval tier produces (gh#832). It has no addressable slots, so the only
+ * refinement the op vocabulary can express is `replacePage`.
+ */
+function isSingleChunkPlan(plan) {
+  return !!plan && Object.keys(plan.slot_bindings || {}).length === 0;
+}
+
+/** Every chunk name a plan references — its root plus everything bound. */
+function priorPlanChunkNames(plan) {
+  const names = new Set();
+  if (!plan) return names;
+  if (plan.page) names.add(plan.page);
+  for (const bound of Object.values(plan.slot_bindings || {})) {
+    for (const n of (Array.isArray(bound) ? bound : [bound])) if (n) names.add(n);
+  }
+  return names;
+}
+
+function buildLocatorPrompt(intent, componentMap, plan) {
+  const lines = [];
+  lines.push(`Intent: ${intent}`);
+  lines.push('');
+  lines.push('## Component map');
+  if (componentMap.length === 0) {
+    lines.push(`(empty — the prior UI is the single chunk "${plan?.page}", no bindable slots)`);
+  }
+  for (const { slot, chunks } of componentMap) {
+    lines.push(`- ${slot}: [${chunks.join(', ')}]`);
+  }
+  lines.push('');
+  lines.push('Return JSON: { "targeted": bool, "target_slots": string[] }.');
+  return lines.join('\n');
+}
+
+function buildModifierPrompt(intent, priorPlan, targetedSlots, catalog) {
+  const lines = [];
+  lines.push(`Intent: ${intent}`);
+  lines.push('');
+  lines.push('## Prior plan');
+  lines.push(`Page: ${priorPlan?.page || '(unknown)'}`);
+  if (isSingleChunkPlan(priorPlan)) {
+    lines.push('Slot bindings: (none — SINGLE-CHUNK PRIOR)');
+    lines.push('');
+    lines.push(
+      `The prior UI is the single chunk "${priorPlan?.page}". Emit ONE replacePage ` +
+      `op: pick a kind=page or kind=panel shell from the catalog below and bind ` +
+      `"${priorPlan?.page}" into one of its slots ALONGSIDE the chunk(s) the intent asks for, ` +
+      `so the existing UI survives the refinement.`,
+    );
+  } else {
+    lines.push('Slot bindings:');
+    for (const [slot, bound] of Object.entries(priorPlan?.slot_bindings || {})) {
+      const arr = Array.isArray(bound) ? bound : [bound];
+      const focus = targetedSlots.includes(slot) ? ' ← TARGETED' : '';
+      lines.push(`  ${slot}: [${arr.join(', ')}]${focus}`);
+    }
+  }
+  lines.push('');
+  lines.push('## Available chunks (filtered)');
+  for (const c of catalog) {
+    const slots = c.slots?.length ? ` slots=[${c.slots.join(', ')}]` : '';
+    lines.push(`- ${c.name} (kind=${c.kind}, primary=${c.primary})${slots}`);
+  }
+  lines.push('');
+  lines.push('Return JSON: { "ops": [...], "delta_summary": "..." }');
+  return lines.join('\n');
+}
+
+function extractJSON(raw) {
+  if (!raw || typeof raw !== 'string') return null;
+  const trimmed = raw.trim();
+  const fenced = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/);
+  const candidate = fenced ? fenced[1].trim() : trimmed;
+  try { return JSON.parse(candidate); } catch {}
+  const m = candidate.match(/\{[\s\S]*\}/);
+  if (!m) return null;
+  try { return JSON.parse(m[0]); } catch { return null; }
+}
+
+/**
+ * Validate ops against the prior state.
+ *
+ * Checks:
+ *  - Op shape (type field is one of four known types; required fields present).
+ *  - Slot references exist in the prior plan.
+ *  - Chunk references exist in the corpus.
+ *  - Page references (replacePage) are kind=page or kind=panel.
+ *
+ * @param {object[]} ops
+ * @param {object} priorState — must have .plan.{page, slot_bindings}
+ * @returns {{ ok: boolean, errors: string[] }}
+ */
+export function validateOps(ops, priorState) {
+  const errors = [];
+  if (!Array.isArray(ops)) {
+    return { ok: false, errors: ['ops must be an array'] };
+  }
+  if (!priorState?.plan) {
+    return { ok: false, errors: ['priorState must have a plan with page+slot_bindings'] };
+  }
+
+  const declaredSlots = new Set(Object.keys(priorState.plan.slot_bindings || {}));
+
+  ops.forEach((op, i) => {
+    if (!op || typeof op !== 'object') {
+      errors.push(`ops[${i}]: not an object`);
+      return;
+    }
+    const T = op.type;
+    if (!VALID_OP_TYPES.has(T)) {
+      errors.push(`ops[${i}]: unknown op type "${T}"`);
+      return;
+    }
+
+    if (T === 'replacePage') {
+      if (!op.page || typeof op.page !== 'string') {
+        errors.push(`ops[${i}]: replacePage requires a "page" string`);
+      } else {
+        const rec = getChunk(op.page);
+        if (!rec) {
+          errors.push(`ops[${i}]: page chunk "${op.page}" not found`);
+        } else if (rec.kind !== 'page' && rec.kind !== 'panel') {
+          errors.push(`ops[${i}]: replacePage chunk "${op.page}" must be kind page|panel; got ${rec.kind}`);
+        }
+      }
+      const bindings = op.slot_bindings || {};
+      for (const [slot, bound] of Object.entries(bindings)) {
+        const names = Array.isArray(bound) ? bound : [bound];
+        for (const name of names) {
+          if (!getChunk(name)) {
+            errors.push(`ops[${i}]: bound chunk "${name}" (slot "${slot}") not found`);
+          }
+        }
+      }
+      return;
+    }
+
+    if (!op.slot || typeof op.slot !== 'string') {
+      errors.push(`ops[${i}]: ${T} requires a "slot" string`);
+      return;
+    }
+    if (!declaredSlots.has(op.slot)) {
+      errors.push(`ops[${i}]: slot "${op.slot}" not in prior plan (declared: ${[...declaredSlots].join(',')})`);
+    }
+    if (T === 'rebindSlot' || T === 'appendToSlot') {
+      if (!Array.isArray(op.chunks) || op.chunks.length === 0) {
+        errors.push(`ops[${i}]: ${T} requires a non-empty "chunks" array`);
+        return;
+      }
+      for (const c of op.chunks) {
+        if (!getChunk(c)) errors.push(`ops[${i}]: chunk "${c}" not found`);
+      }
+    } else if (T === 'removeFromSlot') {
+      if (!Array.isArray(op.indices) || op.indices.length === 0) {
+        errors.push(`ops[${i}]: removeFromSlot requires a non-empty "indices" array`);
+        return;
+      }
+      const slotBound = priorState.plan.slot_bindings[op.slot];
+      const slotArr = Array.isArray(slotBound) ? slotBound : (slotBound ? [slotBound] : []);
+      for (const idx of op.indices) {
+        if (!Number.isInteger(idx) || idx < 0 || idx >= slotArr.length) {
+          errors.push(`ops[${i}]: index ${idx} out of range for slot "${op.slot}" (length ${slotArr.length})`);
+        }
+      }
+    }
+  });
+
+  return { ok: errors.length === 0, errors };
+}
+
+/**
+ * Apply ops to the prior state.
+ *
+ * Op-level failures are non-fatal — the apply phase continues with subsequent
+ * ops. Returns { newState, ops_applied, ops_failed }. The `newState` includes
+ * the mutated plan + freshly materialized HTML.
+ *
+ * @param {object} input
+ * @param {object} input.priorState — { plan, html, ... }
+ * @param {object[]} input.ops
+ * @returns {Promise<{
+ *   newState: { plan, html, warnings },
+ *   ops_applied: object[],
+ *   ops_failed: { op, reason }[],
+ * }>}
+ */
+export async function applyOps({ priorState, ops }) {
+  if (!priorState?.plan) {
+    return {
+      newState: priorState,
+      ops_applied: [],
+      ops_failed: (ops || []).map((op) => ({ op, reason: 'priorState has no plan' })),
+    };
+  }
+
+  // Deep-clone the plan so we mutate a copy
+  const plan = {
+    page: priorState.plan.page,
+    slot_bindings: {},
+  };
+  for (const [slot, bound] of Object.entries(priorState.plan.slot_bindings || {})) {
+    plan.slot_bindings[slot] = Array.isArray(bound) ? [...bound] : (bound ? [bound] : []);
+  }
+
+  const ops_applied = [];
+  const ops_failed = [];
+
+  for (const op of (ops || [])) {
+    try {
+      if (!op || typeof op !== 'object') {
+        ops_failed.push({ op, reason: 'op is not an object' });
+        continue;
+      }
+      if (op.type === 'rebindSlot') {
+        if (!Array.isArray(op.chunks)) {
+          ops_failed.push({ op, reason: 'rebindSlot.chunks must be an array' });
+          continue;
+        }
+        plan.slot_bindings[op.slot] = [...op.chunks];
+        ops_applied.push(op);
+      } else if (op.type === 'appendToSlot') {
+        if (!Array.isArray(op.chunks)) {
+          ops_failed.push({ op, reason: 'appendToSlot.chunks must be an array' });
+          continue;
+        }
+        const cur = plan.slot_bindings[op.slot];
+        const arr = Array.isArray(cur) ? [...cur] : (cur ? [cur] : []);
+        arr.push(...op.chunks);
+        plan.slot_bindings[op.slot] = arr;
+        ops_applied.push(op);
+      } else if (op.type === 'removeFromSlot') {
+        if (!Array.isArray(op.indices)) {
+          ops_failed.push({ op, reason: 'removeFromSlot.indices must be an array' });
+          continue;
+        }
+        const cur = plan.slot_bindings[op.slot];
+        const arr = Array.isArray(cur) ? [...cur] : (cur ? [cur] : []);
+        const dropSet = new Set(op.indices);
+        plan.slot_bindings[op.slot] = arr.filter((_, i) => !dropSet.has(i));
+        ops_applied.push(op);
+      } else if (op.type === 'replacePage') {
+        plan.page = op.page;
+        plan.slot_bindings = {};
+        for (const [slot, bound] of Object.entries(op.slot_bindings || {})) {
+          plan.slot_bindings[slot] = Array.isArray(bound) ? [...bound] : (bound ? [bound] : []);
+        }
+        ops_applied.push(op);
+      } else {
+        ops_failed.push({ op, reason: `unknown op type "${op.type}"` });
+      }
+    } catch (e) {
+      ops_failed.push({ op, reason: e.message });
+    }
+  }
+
+  // Re-materialize the HTML
+  const composed = composeFromPlan(plan);
+
+  return {
+    newState: {
+      plan,
+      html: composed.html,
+      warnings: composed.warnings || [],
+    },
+    ops_applied,
+    ops_failed,
+  };
+}
+
+/**
+ * Translate chunk-plan-level ops to A2UI message arrays for wire-format
+ * compatibility (spec §2.3 + §3.4).
+ *
+ * Phase A approach: each chunk-plan op produces one `updateComponents`
+ * message targeting the affected slot. Components carry a `chunk_op` echo
+ * + a materialized `html` string. Phase B may upgrade `html` to a proper
+ * component-tree shape.
+ *
+ * @param {object[]} ops — chunk-plan ops (post-validation)
+ * @param {object} newState — { html, plan, warnings } from applyOps
+ * @returns {object[]} A2UI messages
+ */
+export function opsToA2UI(ops, newState) {
+  const messages = [];
+  for (const op of (ops || [])) {
+    if (op.type === 'replacePage') {
+      messages.push({
+        type: 'updateComponents',
+        surfaceId: SURFACE_ID,
+        components: [
+          {
+            id: SURFACE_ID,
+            chunk_op: op,
+            html: newState?.html ?? null,
+          },
+        ],
+      });
+    } else {
+      messages.push({
+        type: 'updateComponents',
+        surfaceId: SURFACE_ID,
+        components: [
+          {
+            id: `slot-${op.slot}`,
+            chunk_op: op,
+            html: newState?.html ?? null,
+          },
+        ],
+      });
+    }
+  }
+  return messages;
+}
+
+/**
+ * Refine a prior composition based on a natural-language intent.
+ *
+ * Two-pass synthesis:
+ *   Pass 1 (locator) — LLM identifies which slots to modify.
+ *   Pass 2 (modifier) — LLM emits chunk-plan ops on the targeted slots.
+ *
+ * Validator-driven retry: if modifier ops fail validation, the engine
+ * re-prompts with errors, up to maxAttempts.
+ *
+ * Auto-fires on these failure paths (when issueAccumulator is provided):
+ *   - locator-empty-targets: targeted=true but target_slots is empty.
+ *   - validator-exhausted: maxAttempts reached without valid ops.
+ *
+ * @param {object} opts
+ * @param {object} opts.priorState — { state_id, plan, html, ... }
+ * @param {string} opts.intent
+ * @param {object} opts.llmAdapter — { complete: async ({messages, systemPrompt}) }
+ * @param {number} [opts.maxAttempts=2]
+ * @param {object} [opts.issueAccumulator] — IssueAccumulator from issue-reporter.js
+ * @returns {Promise<{
+ *   ops: object[],
+ *   delta_summary?: string,
+ *   warnings: string[],
+ *   synthesis: { attempts, attemptsLog?, locatedTargets, targeted },
+ * }>}
+ */
+export async function refineFromIntent({
+  priorState,
+  intent,
+  llmAdapter,
+  maxAttempts = DEFAULT_MAX_ATTEMPTS,
+  issueAccumulator = null,
+  catalog = null,
+}) {
+  if (!priorState?.plan) {
+    return {
+      ops: [],
+      warnings: ['priorState has no plan; cannot refine'],
+      synthesis: { attempts: 0, locatedTargets: null, targeted: false },
+    };
+  }
+  if (!llmAdapter?.complete) {
+    return {
+      ops: [],
+      warnings: ['no llmAdapter provided'],
+      synthesis: { attempts: 0, locatedTargets: null, targeted: false },
+    };
+  }
+
+  // Pass 1 — locate
+  const componentMap = buildComponentMap(priorState);
+  const locatorPrompt = buildLocatorPrompt(intent, componentMap, priorState.plan);
+  const locatorResp = await llmAdapter.complete({
+    messages: [{ role: 'user', content: locatorPrompt }],
+    systemPrompt: LOCATOR_SYSTEM_PROMPT,
+  });
+  const locatorRaw = locatorResp?.content || locatorResp?.text || '';
+  const locatorParsed = extractJSON(locatorRaw);
+
+  let targeted = false;
+  let target_slots = [];
+  if (locatorParsed && typeof locatorParsed === 'object') {
+    targeted = !!locatorParsed.targeted;
+    target_slots = Array.isArray(locatorParsed.target_slots) ? locatorParsed.target_slots : [];
+  }
+
+  if (targeted && target_slots.length === 0) {
+    issueAccumulator?.add('locator-empty-targets', {
+      intent,
+      state_id: priorState.state_id,
+    });
+  }
+
+  // Pass 2 — modify. Pre-search the catalog if not provided.
+  let resolvedCatalog = catalog;
+  if (!resolvedCatalog) {
+    const blockHits = await searchChunksAsync(intent, { kind: 'block', limit: PRE_SEARCH_LIMIT });
+    const blockChunks = blockHits.map((h) => getChunk(h.name)).filter(Boolean);
+    const pageChunks = listChunksByKind('page');
+    const panelChunks = listChunksByKind('panel');
+    const filtered = [...pageChunks, ...panelChunks, ...blockChunks];
+    resolvedCatalog = filtered.map((c) => ({
+      name: c.name,
+      kind: c.kind,
+      primary: c.primary || c.instances?.[0]?.primary,
+      slots: (c.slots || c.instances?.[0]?.slots || []).map((s) => s.name),
+    }));
+  }
+
+  // The prior plan's own chunks must be in the catalog the modifier sees:
+  // a single-chunk refinement has to re-bind the prior root by name, and the
+  // intent-driven pre-search (which searches for the CHANGE, not the existing
+  // UI) has no reason to surface it (gh#832).
+  const catalogNames = new Set(resolvedCatalog.map((c) => c.name));
+  for (const name of priorPlanChunkNames(priorState.plan)) {
+    if (catalogNames.has(name)) continue;
+    const rec = getChunk(name);
+    if (!rec) continue;
+    catalogNames.add(name);
+    resolvedCatalog = [
+      ...resolvedCatalog,
+      {
+        name: rec.name,
+        kind: rec.kind,
+        primary: rec.primary || rec.instances?.[0]?.primary,
+        slots: (rec.slots || rec.instances?.[0]?.slots || []).map((s) => s.name),
+      },
+    ];
+  }
+
+  const modifierUserPrompt = buildModifierPrompt(intent, priorState.plan, target_slots, resolvedCatalog);
+  const attemptsLog = [];
+  let lastError = null;
+
+  for (let i = 0; i < maxAttempts; i++) {
+    const retryNudge = lastError
+      ? `\n\nPREVIOUS ATTEMPT FAILED VALIDATION: ${lastError}. Re-emit ops without invalid references.`
+      : '';
+    const modifierResp = await llmAdapter.complete({
+      messages: [{ role: 'user', content: modifierUserPrompt + retryNudge }],
+      systemPrompt: MODIFIER_SYSTEM_PROMPT,
+    });
+    const modifierRaw = modifierResp?.content || modifierResp?.text || '';
+    attemptsLog.push({ attempt: i + 1, raw: modifierRaw });
+
+    const parsed = extractJSON(modifierRaw);
+    if (!parsed || !Array.isArray(parsed.ops)) {
+      lastError = 'response was not valid JSON with { ops: [...] } shape';
+      continue;
+    }
+
+    const validation = validateOps(parsed.ops, priorState);
+    if (!validation.ok) {
+      lastError = validation.errors.slice(0, 3).join('; ');
+      continue;
+    }
+
+    return {
+      ops: parsed.ops,
+      delta_summary: parsed.delta_summary || '',
+      warnings: [],
+      synthesis: {
+        attempts: i + 1,
+        attemptsLog,
+        locatedTargets: target_slots,
+        targeted,
+      },
+    };
+  }
+
+  issueAccumulator?.add('validator-exhausted', {
+    state_id: priorState.state_id,
+    tool: 'refine_composition',
+    intent,
+  });
+
+  return {
+    ops: [],
+    warnings: [`refinement failed after ${maxAttempts} attempts: ${lastError}`],
+    synthesis: {
+      attempts: maxAttempts,
+      attemptsLog,
+      locatedTargets: target_slots,
+      targeted,
+    },
+  };
+}