@adia-ai/a2ui-compose 0.0.1 → 0.1.0

package/engines/zettel/chunk-synthesizer.js

@@ -0,0 +1,235 @@
+/**
+ * Chunk-aware composition synthesizer.
+ *
+ * Mirrors the existing `synthesizer.js` (fragment-graph) but operates on the
+ * gen-UI training-chunk corpus instead of the fragment catalog. When pure
+ * retrieval can't surface a strong match for an intent, this asks the LLM to
+ * mix-and-match: pick a page-kind chunk, then bind block/panel chunks to its
+ * slots. Validator checks slot names + chunk-kind contracts before composing.
+ *
+ * Two-tier behavior:
+ *   1. Retrieval first — searchChunks returns a strong match (score > threshold)
+ *      → return that chunk directly. Fast path; no LLM call.
+ *   2. Synthesis fallback — retrieval is weak → invoke the LLM to compose
+ *      from the catalog. This is the creative mix-and-match path.
+ *
+ * Token-budget mitigation: pre-search filters the catalog to ~30 candidates
+ * before the LLM sees them. Mirrors the fragment-synthesizer technique.
+ *
+ * Plan: docs/plans/training-pipeline-chunk-harvest-2026-04-27.md (Phase C.2).
+ */
+
+import {
+  getChunk,
+  searchChunks,
+  searchChunksAsync,
+  listChunksByKind,
+  getAllChunks,
+} from '../../../corpus/scripts/chunk-library.js';
+import { composeFromPlan, validatePlan } from './chunk-composer.js';
+
+const STRONG_RETRIEVAL_SCORE = 8;     // search-score threshold for fast path
+const PRE_SEARCH_LIMIT = 30;           // chunks shown to the LLM in the prompt
+const DEFAULT_MAX_ATTEMPTS = 2;
+
+const SYSTEM_PROMPT = `You compose web-app pages by binding training chunks into named slots.
+
+You are given:
+  - A user intent (what they want to build).
+  - A catalog of available chunks. Each chunk is a discrete UI sample harvested
+    from a real page. Chunks have:
+      - name (stable ID)
+      - kind ("page", "panel", or "block")
+      - primary (the chunk's outermost element, e.g. "card-ui", "grid-ui")
+      - slots (only on page/panel chunks — named regions where blocks plug in)
+  - 1-3 example bindings as in-context anchors.
+
+Return ONLY a JSON object shaped exactly like:
+{
+  "page": "<name of a page-kind chunk to use as the layout shell>",
+  "slot_bindings": {
+    "<slot-name>": "<bound chunk name>"        // single chunk
+    OR
+    "<slot-name>": ["<chunk1>", "<chunk2>"]    // ordered list of chunks
+  }
+}
+
+Rules:
+- The "page" must be a chunk with kind="page" or kind="panel".
+- Every slot you bind must be declared by the page chunk (do not invent slots).
+- Bound chunks should be kind="block" or kind="panel" — pages can't nest inside
+  pages.
+- Return valid JSON. No prose, no comments, no markdown fences. Begin with "{".
+`;
+
+function buildCatalogSummary(chunks) {
+  return chunks.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),
+  }));
+}
+
+function buildExamples() {
+  // Hard-coded canonical example: "build me an admin dashboard". This anchors
+  // the LLM on the expected output shape.
+  return [
+    {
+      intent: 'admin dashboard with KPIs and a conversion funnel',
+      output: {
+        page: 'dashboard-admin-page',
+        slot_bindings: {
+          'page-header': 'dashboard-page-header',
+          'page-content': ['dashboard-overview-panel', 'dashboard-funnel'],
+        },
+      },
+    },
+  ];
+}
+
+function buildUserPrompt(intent, catalog, examples) {
+  const lines = [];
+  lines.push(`Intent: ${intent}`);
+  lines.push('');
+  lines.push('## Available chunks');
+  lines.push('');
+  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('## Example bindings');
+  lines.push('');
+  for (const ex of examples) {
+    lines.push(`Intent: ${ex.intent}`);
+    lines.push('Output:');
+    lines.push(JSON.stringify(ex.output, null, 2));
+    lines.push('');
+  }
+  lines.push('## Your turn');
+  lines.push('');
+  lines.push('Return JSON binding for the intent above. JSON only.');
+  return lines.join('\n');
+}
+
+function extractJSON(raw) {
+  if (!raw || typeof raw !== 'string') return null;
+  const trimmed = raw.trim();
+  // Strip markdown fences if present
+  const fenced = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/);
+  const candidate = fenced ? fenced[1].trim() : trimmed;
+  try {
+    return JSON.parse(candidate);
+  } catch {
+    // Find the first { ... } balanced object
+    const m = candidate.match(/\{[\s\S]*\}/);
+    if (!m) return null;
+    try { return JSON.parse(m[0]); } catch { return null; }
+  }
+}
+
+/**
+ * Try retrieval-first; fall back to synthesis if retrieval is weak or missing.
+ *
+ * @param {object} opts
+ * @param {string} opts.intent
+ * @param {object} opts.llmAdapter — { complete: async ({ messages, systemPrompt }) => { content|text } }
+ * @param {number} [opts.maxAttempts=2]
+ * @returns {Promise<{ html: string, plan: object|null, source: 'retrieval'|'synthesis', score?: number, warnings: string[], synthesis?: object }>}
+ */
+export async function composeFromIntent({ intent, llmAdapter, maxAttempts = DEFAULT_MAX_ATTEMPTS }) {
+  // Tier 1 — retrieval. Try semantic-blended hit first; fall back to keyword
+  // when embeddings are unavailable (no chunk-embeddings.json or no API key).
+  const hits = await searchChunksAsync(intent, { limit: 5 });
+  if (hits.length > 0 && hits[0].score >= STRONG_RETRIEVAL_SCORE) {
+    const top = getChunk(hits[0].name);
+    const html = top.html || top.instances?.[0]?.html || '';
+    return {
+      html,
+      plan: null,
+      source: 'retrieval',
+      score: hits[0].score,
+      cosineScore: hits[0].cosineScore,
+      warnings: [],
+    };
+  }
+
+  // Tier 2 — synthesis. Need an LLM adapter.
+  if (!llmAdapter?.complete) {
+    return {
+      html: null,
+      plan: null,
+      source: 'synthesis',
+      warnings: ['retrieval was weak and no llmAdapter provided — cannot synthesize'],
+    };
+  }
+
+  // Pre-search the catalog to keep the prompt token-budget bounded.
+  // Strategy: retrieve top N by semantic-blended search; ALWAYS include all
+  // page-kind chunks (small set, the LLM needs to see what shells are
+  // available). Block pre-search uses embeddings when available.
+  const pageChunks = listChunksByKind('page');
+  const panelChunks = listChunksByKind('panel');
+  const blockHits = await searchChunksAsync(intent, {
+    kind: 'block',
+    limit: PRE_SEARCH_LIMIT - pageChunks.length - panelChunks.length,
+  });
+  const blockChunks = blockHits.map((h) => getChunk(h.name)).filter(Boolean);
+
+  const filtered = [
+    ...pageChunks,
+    ...panelChunks,
+    ...blockChunks,
+  ];
+  const catalog = buildCatalogSummary(filtered);
+  const examples = buildExamples();
+
+  const userPrompt = buildUserPrompt(intent, catalog, examples);
+  let lastError = null;
+  const attempts = [];
+
+  for (let i = 0; i < maxAttempts; i++) {
+    const retryNudge = lastError
+      ? `\n\nPREVIOUS ATTEMPT FAILED: ${lastError}. Return ONLY a JSON object shaped as { "page": "...", "slot_bindings": { ... } }. No prose, no questions.`
+      : '';
+    const messages = [{ role: 'user', content: userPrompt + retryNudge }];
+    const response = await llmAdapter.complete({ messages, systemPrompt: SYSTEM_PROMPT });
+    const raw = response?.content || response?.text || (typeof response === 'string' ? response : '');
+    attempts.push({ attempt: i + 1, raw });
+
+    const plan = extractJSON(raw);
+    if (!plan || !plan.page || !plan.slot_bindings) {
+      lastError = 'Response was not valid JSON with { page, slot_bindings } fields.';
+      continue;
+    }
+
+    const validation = validatePlan(plan);
+    if (!validation.ok) {
+      lastError = validation.errors.slice(0, 3).join('; ');
+      continue;
+    }
+
+    const composed = composeFromPlan(plan);
+    if (!composed.html) {
+      lastError = composed.warnings.join('; ') || 'composer returned null html';
+      continue;
+    }
+
+    return {
+      html: composed.html,
+      plan,
+      source: 'synthesis',
+      warnings: composed.warnings,
+      synthesis: { attempts: i + 1, attemptsLog: attempts, validation },
+    };
+  }
+
+  return {
+    html: null,
+    plan: null,
+    source: 'synthesis',
+    warnings: [`synthesis failed after ${maxAttempts} attempts: ${lastError}`],
+    synthesis: { attempts: maxAttempts, attemptsLog: attempts },
+  };
+}

package/engines/zettel/issue-reporter.js

@@ -0,0 +1,380 @@
+/**
+ * Issue-reporter — first-class telemetry surface for the gen-UI engine.
+ *
+ * Three call paths converge here:
+ *   1. LLM self-fire — the `report_issue` MCP tool. ctx.reporter = 'llm'.
+ *   2. Consumer-fire — human user requests a bug ticket. ctx.reporter = 'user'.
+ *   3. Engine auto-fire — internal failure paths trigger `autoReport(reason)`.
+ *      ctx.reporter = 'auto'. Suppressed when ctx.evalMode is true.
+ *
+ * Every issue lands as immutable JSON under `.brain/audit-history/issues/`.
+ * Traces > 200KB spill to a sidecar `.trace.json` next to the issue.
+ *
+ * Spec: docs/specs/genui-multiturn-architecture.md §3.5 + §4.6 + §11.
+ *
+ * Distinct from the curated `.tickets/` system (corpus/scripts/ticket.mjs):
+ * those are human-authored work items. Issues here are runtime telemetry —
+ * promoted to tickets during weekly triage when patterns emerge (spec §11.5).
+ */
+
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, resolve, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(__dirname, '../../../../..');
+const DEFAULT_STORAGE_ROOT = resolve(REPO_ROOT, '.brain/audit-history/issues');
+const TRACE_INLINE_THRESHOLD_BYTES = 200 * 1024;
+
+const VALID_TYPES = new Set(['bug', 'training-gap', 'protocol-gap', 'ux-feedback']);
+const VALID_SEVERITIES = new Set(['blocker', 'drift', 'nit']);
+const VALID_OWNERS = new Set(['synthesis', 'retrieval', 'validator', 'chunk-corpus', 'mcp-protocol', 'unknown']);
+const VALID_TRACE_DEPTHS = new Set(['full', 'summary', 'none']);
+const VALID_REPORTER_KINDS = new Set(['auto', 'user', 'llm']);
+
+const SEVERITY_RANK = { nit: 0, drift: 1, blocker: 2 };
+
+/**
+ * Auto-fire policy: maps reason → defaults for type/severity/owner/title.
+ * Spec §11.3.
+ */
+export const AUTO_FIRE_POLICY = {
+  'synthesizer-exhausted': {
+    type: 'bug',
+    severity: 'drift',
+    suggested_owner: 'synthesis',
+    titleFor: (ctx) => `Synthesizer exhausted retries${ctx?.intent ? ` for "${truncate(ctx.intent, 50)}"` : ''}`,
+  },
+  'validator-exhausted': {
+    type: 'bug',
+    severity: 'blocker',
+    suggested_owner: 'validator',
+    titleFor: (ctx) => `Validator exhausted retries on ${ctx?.tool || 'refine_composition'}`,
+  },
+  'locator-empty-targets': {
+    type: 'bug',
+    severity: 'drift',
+    suggested_owner: 'synthesis',
+    titleFor: (ctx) => `Locator pass returned empty targets${ctx?.intent ? ` for "${truncate(ctx.intent, 50)}"` : ''}`,
+  },
+  'retrieval-zero-then-synthesis-fail': {
+    type: 'training-gap',
+    severity: 'drift',
+    suggested_owner: 'chunk-corpus',
+    titleFor: (ctx) => `Retrieval returned 0 candidates and synthesis failed${ctx?.intent ? ` for "${truncate(ctx.intent, 40)}"` : ''}`,
+  },
+  'cache-miss-on-known-state': {
+    type: 'bug',
+    severity: 'nit',
+    suggested_owner: 'mcp-protocol',
+    titleFor: (ctx) => `get_state called with unknown state_id "${truncate(ctx?.state_id || 'unknown', 40)}"`,
+  },
+  'ops-failed-after-apply': {
+    type: 'bug',
+    severity: 'drift',
+    suggested_owner: 'validator',
+    titleFor: () => `refine_composition ops_failed list non-empty after apply`,
+  },
+};
+
+function truncate(s, n = 60) {
+  if (!s || typeof s !== 'string') return '';
+  return s.length > n ? `${s.slice(0, n - 1)}…` : s;
+}
+
+function slugify(s, max = 40) {
+  return (s || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, max);
+}
+
+function mintIssueId(title) {
+  const date = new Date().toISOString().slice(0, 10);
+  const titleSlug = slugify(title) || 'issue';
+  const rand4 = Math.floor(Math.random() * 0xffff).toString(16).padStart(4, '0');
+  return `${date}-${titleSlug}-${rand4}`;
+}
+
+function getStorageRoot(ctx) {
+  return ctx?.storageRoot || DEFAULT_STORAGE_ROOT;
+}
+
+function validateInput(input) {
+  if (!input || typeof input !== 'object') {
+    throw new Error('reportIssue: input is required');
+  }
+  if (!input.title || typeof input.title !== 'string') {
+    throw new Error('reportIssue: title (string) is required');
+  }
+  if (input.title.length > 80) {
+    throw new Error('reportIssue: title must be ≤ 80 chars');
+  }
+  if (typeof input.body !== 'string') {
+    throw new Error('reportIssue: body (string) is required');
+  }
+  if (!VALID_TYPES.has(input.type)) {
+    throw new Error(`reportIssue: type must be one of ${[...VALID_TYPES].join('|')}`);
+  }
+  if (!VALID_SEVERITIES.has(input.severity)) {
+    throw new Error(`reportIssue: severity must be one of ${[...VALID_SEVERITIES].join('|')}`);
+  }
+  if (input.suggested_owner != null && !VALID_OWNERS.has(input.suggested_owner)) {
+    throw new Error(`reportIssue: suggested_owner must be one of ${[...VALID_OWNERS].join('|')}`);
+  }
+  if (input.trace != null && !VALID_TRACE_DEPTHS.has(input.trace)) {
+    throw new Error(`reportIssue: trace must be one of ${[...VALID_TRACE_DEPTHS].join('|')}`);
+  }
+  if (input.tags != null && !Array.isArray(input.tags)) {
+    throw new Error('reportIssue: tags must be an array');
+  }
+}
+
+/**
+ * Pull a trace from the cached state-entry.
+ *
+ * `summary` — final intent + last 5 ops + warnings (compact).
+ * `full` — every prompt, every LLM response, every validator result, every retry.
+ *
+ * Returns null when state_id is absent from the cache.
+ *
+ * @param {string} state_id
+ * @param {'full'|'summary'} depth
+ * @param {object} cache — StateCache instance (uses .peek() to avoid touching recency)
+ */
+export async function attachTrace(state_id, depth, cache) {
+  if (!cache || typeof cache.peek !== 'function') return null;
+  const entry = cache.peek(state_id);
+  if (!entry) return null;
+  if (depth === 'none') return null;
+
+  const baseTrace = {
+    state_id,
+    tool: entry.tool ?? null,
+    input: entry.input ?? null,
+  };
+
+  if (depth === 'summary') {
+    return {
+      ...baseTrace,
+      output: {
+        ops: (entry.ops_history || []).slice(-5),
+        delta_summary: entry.delta_summary ?? null,
+      },
+      warnings: entry.warnings || [],
+      duration_ms: entry.duration_ms ?? null,
+    };
+  }
+
+  // 'full'
+  return {
+    ...baseTrace,
+    internal: entry.internal ?? null,
+    output: entry.output ?? {
+      ops: entry.ops_history || [],
+      delta_summary: entry.delta_summary ?? null,
+    },
+    warnings: entry.warnings || [],
+    duration_ms: entry.duration_ms ?? null,
+  };
+}
+
+/**
+ * Write an issue to disk.
+ *
+ * @returns {Promise<{ issue_id, path, ack: 'logged' }>}
+ */
+export async function reportIssue(input, ctx = {}) {
+  validateInput(input);
+
+  const storageRoot = getStorageRoot(ctx);
+  await mkdir(storageRoot, { recursive: true });
+
+  const issue_id = mintIssueId(input.title);
+  const created_at = new Date().toISOString();
+
+  const reporterKind = ctx.reporter && VALID_REPORTER_KINDS.has(ctx.reporter)
+    ? ctx.reporter
+    : 'user';
+
+  const traceDepth = input.trace ?? (input.state_id ? 'summary' : 'none');
+  let trace = null;
+  if (input.state_id && traceDepth !== 'none') {
+    trace = await attachTrace(input.state_id, traceDepth, ctx.cache);
+  }
+
+  // Spill oversized traces to a sidecar file
+  let tracePayload = trace;
+  if (trace && JSON.stringify(trace).length > TRACE_INLINE_THRESHOLD_BYTES) {
+    const tracesDir = join(storageRoot, 'traces');
+    await mkdir(tracesDir, { recursive: true });
+    const tracePath = join(tracesDir, `${issue_id}.trace.json`);
+    await writeFile(tracePath, JSON.stringify(trace, null, 2));
+    tracePayload = { sidecar: `traces/${issue_id}.trace.json` };
+  }
+
+  const issue = {
+    issue_id,
+    created_at,
+    type: input.type,
+    severity: input.severity,
+    status: 'open',
+    title: input.title,
+    body: input.body,
+    reporter: {
+      kind: reporterKind,
+      context: ctx.reporterContext ?? null,
+    },
+    trace: tracePayload,
+    environment: ctx.versionInfo ?? null,
+    suggested_owner: input.suggested_owner ?? 'unknown',
+    tags: input.tags ?? [],
+    related_issue_ids: ctx.related_issue_ids ?? [],
+    linked_specs: ctx.linked_specs ?? ['docs/specs/genui-multiturn-architecture.md'],
+  };
+
+  const path = join(storageRoot, `${issue_id}.json`);
+  await writeFile(path, JSON.stringify(issue, null, 2));
+
+  return { issue_id, path, ack: 'logged' };
+}
+
+/**
+ * Auto-fire an issue based on a known reason.
+ *
+ * Looks up the policy table, derives type/severity/title/owner; the caller
+ * passes intent / state_id / extra context via `autoCtx`.
+ *
+ * Returns null when ctx.evalMode is true (eval runs don't pollute the ledger);
+ * manual reportIssue calls are unaffected by evalMode.
+ *
+ * @param {keyof typeof AUTO_FIRE_POLICY} reason
+ * @param {object} autoCtx — { intent?, state_id?, tool?, body?, trace?, tags? }
+ * @param {object} ctx — { cache, versionInfo, evalMode, storageRoot }
+ */
+export async function autoReport(reason, autoCtx = {}, ctx = {}) {
+  if (ctx.evalMode) return null;
+  const policy = AUTO_FIRE_POLICY[reason];
+  if (!policy) {
+    throw new Error(
+      `autoReport: unknown reason "${reason}". Valid: ${Object.keys(AUTO_FIRE_POLICY).join(', ')}`
+    );
+  }
+  const title = policy.titleFor(autoCtx);
+  const body = autoCtx.body || `Auto-fired by engine. Reason: \`${reason}\`.`;
+
+  return await reportIssue(
+    {
+      type: policy.type,
+      severity: policy.severity,
+      title,
+      body,
+      state_id: autoCtx.state_id,
+      trace: autoCtx.trace ?? (autoCtx.state_id ? 'summary' : 'none'),
+      suggested_owner: policy.suggested_owner,
+      tags: ['auto-fire', reason, ...(autoCtx.tags || [])],
+    },
+    {
+      ...ctx,
+      reporter: 'auto',
+      reporterContext: reason,
+    }
+  );
+}
+
+/**
+ * Per-tool-call accumulator for auto-fired issues.
+ *
+ * Multiple fires within one call coalesce into a single issue (spec §6.4).
+ * The highest-severity entry dictates type/severity/owner; the body lists
+ * every reason. Engine code creates one accumulator per tool invocation,
+ * pushes auto-fires into it, and flushes at the end.
+ */
+export function createIssueAccumulator() {
+  const entries = [];
+
+  return {
+    add(reason, autoCtx = {}) {
+      if (!AUTO_FIRE_POLICY[reason]) {
+        throw new Error(`accumulator.add: unknown reason "${reason}"`);
+      }
+      entries.push({ reason, autoCtx });
+    },
+
+    size() {
+      return entries.length;
+    },
+
+    reasons() {
+      return entries.map((e) => e.reason);
+    },
+
+    /**
+     * Write the accumulated issue(s).
+     *
+     * - 0 entries → returns null without writing.
+     * - 1 entry  → writes via autoReport (or no-op when evalMode).
+     * - N entries → coalesces into one issue. Highest-severity entry's policy
+     *   wins; body lists every reason; tags include all reasons + 'coalesced'.
+     */
+    async flush(ctx = {}) {
+      if (entries.length === 0) return null;
+
+      if (entries.length === 1) {
+        const { reason, autoCtx } = entries[0];
+        const result = await autoReport(reason, autoCtx, ctx);
+        entries.length = 0;
+        return result;
+      }
+
+      // Coalesce. Sort by severity desc, ties broken by insertion order.
+      const ranked = entries
+        .map((e, i) => ({ ...e, _idx: i }))
+        .sort((a, b) => {
+          const sa = SEVERITY_RANK[AUTO_FIRE_POLICY[a.reason].severity];
+          const sb = SEVERITY_RANK[AUTO_FIRE_POLICY[b.reason].severity];
+          return sb - sa || a._idx - b._idx;
+        });
+
+      const primary = ranked[0];
+      const policy = AUTO_FIRE_POLICY[primary.reason];
+      const reasons = entries.map((e) => e.reason);
+
+      if (ctx.evalMode) {
+        entries.length = 0;
+        return null;
+      }
+
+      const titles = entries.map((e) => AUTO_FIRE_POLICY[e.reason].titleFor(e.autoCtx));
+      const body = [
+        '## Coalesced auto-fires within one tool call',
+        '',
+        ...entries.map((e, i) => `${i + 1}. **\`${e.reason}\`** — ${titles[i]}`),
+        '',
+        `Primary (highest severity) dictates type/severity/owner: \`${primary.reason}\` (severity \`${policy.severity}\`).`,
+      ].join('\n');
+
+      const result = await reportIssue(
+        {
+          type: policy.type,
+          severity: policy.severity,
+          title: truncate(`Coalesced auto-fires: ${reasons.join(', ')}`, 80),
+          body,
+          state_id: primary.autoCtx?.state_id,
+          trace: primary.autoCtx?.trace ?? (primary.autoCtx?.state_id ? 'summary' : 'none'),
+          suggested_owner: policy.suggested_owner,
+          tags: ['auto-fire', 'coalesced', ...new Set(reasons)],
+        },
+        {
+          ...ctx,
+          reporter: 'auto',
+          reporterContext: 'coalesced',
+        }
+      );
+
+      entries.length = 0;
+      return result;
+    },
+  };
+}