@mindrian_os/install 1.13.0-beta.11

package/lib/chat/fabric-chat.cjs

@@ -0,0 +1,288 @@
+/**
+ * MindrianOS Plugin -- Fabric Chat (NL to SQL)
+ * Translates natural language questions into SQLite SQL queries
+ * against the Room's Fabric (LazyGraph), executes them, and formats results.
+ *
+ * Uses BYOAPI pattern: user's Claude API key for NL-to-SQL translation.
+ * Designed for both Node.js (CJS) and browser (IIFE) environments.
+ *
+ * Exports: nlToSQL, executeAndFormat, injectContext, GRAPH_SCHEMA
+ */
+
+'use strict';
+
+// -- Graph Schema (all 14 Thread types + node properties) --
+
+var GRAPH_SCHEMA = {
+  nodeTypes: [
+    {
+      name: 'Artifact',
+      properties: ['id TEXT PRIMARY KEY', 'title TEXT', 'section TEXT', 'methodology TEXT', 'created TEXT', 'content_hash TEXT'],
+      description: 'A markdown knowledge Entry filed in a Room Section'
+    },
+    {
+      name: 'Section',
+      properties: ['name TEXT PRIMARY KEY', 'label TEXT'],
+      description: 'A domain of knowledge (problem, market, solution, team, etc.)'
+    }
+  ],
+  edgeTypes: [
+    { name: 'INFORMS', from: 'Artifact', to: 'Artifact', properties: [], description: 'One Entry references another via wikilink' },
+    { name: 'CONTRADICTS', from: 'Artifact', to: 'Artifact', properties: ['confidence TEXT'], description: 'Two Entries make opposing claims (a Tension)' },
+    { name: 'CONVERGES', from: 'Artifact', to: 'Artifact', properties: ['term TEXT'], description: 'Same theme in 3+ Entries (a Pattern)' },
+    { name: 'ENABLES', from: 'Artifact', to: 'Artifact', properties: [], description: 'One Entry unblocks another' },
+    { name: 'INVALIDATES', from: 'Artifact', to: 'Artifact', properties: [], description: 'One Entry makes another stale' },
+    { name: 'BELONGS_TO', from: 'Artifact', to: 'Section', properties: [], description: 'Entry is filed in a Section' },
+    { name: 'REASONING_INFORMS', from: 'Section', to: 'Section', properties: ['provides TEXT'], description: 'Minto reasoning chain between Sections' },
+    { name: 'HSI_CONNECTION', from: 'Artifact', to: 'Artifact', properties: ['hsi_score REAL', 'lsa_sim REAL', 'semantic_sim REAL', 'surprise_type TEXT', 'breakthrough_potential REAL', 'tier TEXT'], description: 'Hidden Structural Insight -- a Surprise connection' },
+    { name: 'REVERSE_SALIENT', from: 'Section', to: 'Section', properties: ['differential_score REAL', 'innovation_type TEXT', 'source_artifact TEXT', 'target_artifact TEXT', 'innovation_thesis TEXT'], description: 'Bottleneck -- where understanding lags behind ambition (Hughes 1983)' },
+    { name: 'ANALOGOUS_TO', from: 'Artifact', to: 'Artifact', properties: ['analogy_distance TEXT', 'structural_fitness REAL', 'source_domain TEXT', 'transfer_map TEXT', 'discovery_method TEXT'], description: 'Design-by-Analogy cross-domain bridge' },
+    { name: 'STRUCTURALLY_ISOMORPHIC', from: 'Section', to: 'Section', properties: ['isomorphism_score REAL', 'mapped_elements TEXT', 'source TEXT'], description: 'Identical relational topology between Sections' },
+    { name: 'RESOLVES_VIA', from: 'Artifact', to: 'Artifact', properties: ['resolution_type TEXT', 'triz_principle TEXT', 'analogy_source TEXT', 'confidence REAL'], description: 'Contradiction resolved via analogy or TRIZ principle' },
+    { name: 'CAUSES', from: 'Artifact', to: 'Artifact', properties: ['mechanism TEXT', 'confidence REAL', 'framework TEXT', 'direction TEXT'], description: 'One Entry directly causes or triggers effects in another' },
+    { name: 'ROOT_CAUSE_OF', from: 'Artifact', to: 'Artifact', properties: ['chain_length INTEGER', 'intermediate_causes TEXT', 'confidence REAL', 'discovery_source TEXT'], description: 'Traces backward to the root cause of a problem chain' }
+  ],
+  sampleQueries: [
+    { question: 'What entries are in the problem-definition section?', sql: "SELECT n2.title, n2.id FROM edges e JOIN nodes n1 ON e.target = n1.id JOIN nodes n2 ON e.source = n2.id WHERE e.type = 'BELONGS_TO' AND n1.id = 'problem-definition'" },
+    { question: 'What contradictions exist in this room?', sql: "SELECT n1.title AS from_entry, n2.title AS to_entry, json_extract(e.properties, '$.confidence') AS confidence FROM edges e JOIN nodes n1 ON e.source = n1.id JOIN nodes n2 ON e.target = n2.id WHERE e.type = 'CONTRADICTS'" },
+    { question: 'Show all surprises with high breakthrough potential', sql: "SELECT n1.title, n2.title, json_extract(e.properties, '$.hsi_score') AS hsi_score, json_extract(e.properties, '$.surprise_type') AS surprise_type FROM edges e JOIN nodes n1 ON e.source = n1.id JOIN nodes n2 ON e.target = n2.id WHERE e.type = 'HSI_CONNECTION' AND CAST(json_extract(e.properties, '$.breakthrough_potential') AS REAL) > 0.7" },
+    { question: 'Which sections have bottlenecks?', sql: "SELECT n1.id AS lagging, n2.id AS leading, json_extract(e.properties, '$.differential_score') AS differential_score, json_extract(e.properties, '$.innovation_thesis') AS innovation_thesis FROM edges e JOIN nodes n1 ON e.source = n1.id JOIN nodes n2 ON e.target = n2.id WHERE e.type = 'REVERSE_SALIENT'" },
+    { question: 'How many entries per section?', sql: "SELECT n2.id AS section, n2.title AS label, COUNT(*) AS entry_count FROM edges e JOIN nodes n2 ON e.target = n2.id WHERE e.type = 'BELONGS_TO' GROUP BY n2.id ORDER BY entry_count DESC" },
+    { question: 'What cross-domain analogies exist?', sql: "SELECT n1.title, n2.title, json_extract(e.properties, '$.analogy_distance') AS analogy_distance, json_extract(e.properties, '$.source_domain') AS source_domain FROM edges e JOIN nodes n1 ON e.source = n1.id JOIN nodes n2 ON e.target = n2.id WHERE e.type = 'ANALOGOUS_TO'" },
+    { question: 'What causes what in this room?', sql: "SELECT n1.title AS cause, n2.title AS effect, json_extract(e.properties, '$.mechanism') AS mechanism FROM edges e JOIN nodes n1 ON e.source = n1.id JOIN nodes n2 ON e.target = n2.id WHERE e.type = 'CAUSES'" },
+    { question: 'What are the root causes of problems?', sql: "SELECT n1.title AS root_cause, n2.title AS symptom, json_extract(e.properties, '$.chain_length') AS chain_length FROM edges e JOIN nodes n1 ON e.source = n1.id JOIN nodes n2 ON e.target = n2.id WHERE e.type = 'ROOT_CAUSE_OF'" }
+  ]
+};
+
+/**
+ * Build the schema description string for the NL-to-SQL system prompt.
+ * @param {object} [schema] - Optional custom schema override
+ * @returns {string} Schema description for LLM context
+ */
+function buildSchemaDescription(schema) {
+  var s = schema || GRAPH_SCHEMA;
+  var lines = [];
+
+  lines.push('## SQLite Graph Schema');
+  lines.push('');
+  lines.push('Database: room/.mindrian/room.db');
+  lines.push('Tables: nodes (id, label, section, title, metadata JSON), edges (source, target, type, weight, properties JSON)');
+  lines.push('');
+  lines.push('### Node Types (stored in nodes.label)');
+  for (var i = 0; i < s.nodeTypes.length; i++) {
+    var nt = s.nodeTypes[i];
+    lines.push('- ' + nt.name + ': ' + nt.description);
+    lines.push('  Properties (in metadata JSON): ' + nt.properties.join(', '));
+  }
+
+  lines.push('');
+  lines.push('### Edge Types (stored in edges.type) -- 14 Thread Types');
+  for (var j = 0; j < s.edgeTypes.length; j++) {
+    var et = s.edgeTypes[j];
+    var propsStr = et.properties.length > 0 ? ' [' + et.properties.join(', ') + ']' : '';
+    lines.push('- ' + et.name + ' (' + et.from + ' -> ' + et.to + ')' + propsStr + ': ' + et.description);
+  }
+
+  lines.push('');
+  lines.push('### Sample Queries');
+  for (var k = 0; k < s.sampleQueries.length; k++) {
+    var sq = s.sampleQueries[k];
+    lines.push('Q: ' + sq.question);
+    lines.push('SQL: ' + sq.sql);
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Build the system prompt for NL-to-SQL translation.
+ * @param {object} [schema] - Optional custom schema override
+ * @returns {string} System prompt
+ */
+function buildNlToSQLPrompt(schema) {
+  var schemaDesc = buildSchemaDescription(schema);
+
+  return [
+    'You are a SQLite SQL query translator for MindrianOS.',
+    'Your job is to convert natural language questions about a Room\'s knowledge graph (the Fabric) into valid SQLite SQL queries.',
+    '',
+    'RULES:',
+    '1. Return ONLY the SQL query -- no explanation, no markdown fencing, no preamble.',
+    '2. The database has two main tables: nodes (id, label, section, title, metadata JSON) and edges (source, target, type, weight, properties JSON).',
+    '3. Use json_extract(properties, \'$.key\') to access edge properties and json_extract(metadata, \'$.key\') for node metadata.',
+    '4. String comparisons are case-sensitive. Use LOWER() for case-insensitive matching.',
+    '5. Always use meaningful column aliases (AS ...) for readability.',
+    '6. If the question is ambiguous, write a broad query that returns useful results.',
+    '7. For graph traversals, JOIN edges with nodes: edges e JOIN nodes n1 ON e.source = n1.id JOIN nodes n2 ON e.target = n2.id.',
+    '8. LIMIT results to 25 unless the user asks for all.',
+    '9. Use GROUP BY with aggregate functions (COUNT, AVG, etc.).',
+    '10. For path queries use recursive CTEs: WITH RECURSIVE path AS (...).',
+    '',
+    schemaDesc
+  ].join('\n');
+}
+
+// -- NL to SQL Translation (Browser-compatible, uses fetch) --
+
+/**
+ * Translate a natural language question to a SQLite SQL query.
+ * Uses the Anthropic Messages API (BYOAPI) via fetch.
+ *
+ * @param {string} question - Natural language question
+ * @param {string} apiKey - User's Anthropic API key
+ * @param {object} [options] - Optional overrides
+ * @param {object} [options.schema] - Custom graph schema
+ * @param {string} [options.model] - Model ID (default: claude-haiku-4-20250414)
+ * @returns {Promise<{sql: string, error?: string}>}
+ */
+async function nlToSQL(question, apiKey, options) {
+  options = options || {};
+  var model = options.model || 'claude-haiku-4-20250414';
+  var systemPrompt = buildNlToSQLPrompt(options.schema);
+
+  if (!apiKey) {
+    return { sql: '', error: 'No API key provided' };
+  }
+
+  if (!question || !question.trim()) {
+    return { sql: '', error: 'No question provided' };
+  }
+
+  try {
+    var response = await fetch('https://api.anthropic.com/v1/messages', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-api-key': apiKey,
+        'anthropic-version': '2023-06-01',
+        'anthropic-dangerous-direct-browser-access': 'true'
+      },
+      body: JSON.stringify({
+        model: model,
+        max_tokens: 512,
+        system: systemPrompt,
+        messages: [{ role: 'user', content: question }]
+      })
+    });
+
+    if (!response.ok) {
+      var errText = await response.text();
+      var errMsg = 'API error (' + response.status + ')';
+      try {
+        var errJson = JSON.parse(errText);
+        if (errJson.error && errJson.error.message) errMsg = errJson.error.message;
+      } catch (_) {}
+      return { sql: '', error: errMsg };
+    }
+
+    var data = await response.json();
+    var sql = '';
+    if (data.content && data.content.length > 0) {
+      sql = data.content[0].text.trim();
+      // Strip any markdown code fencing the model might add despite instructions
+      sql = sql.replace(/^```(?:sql)?\n?/i, '').replace(/\n?```$/i, '').trim();
+    }
+
+    return { sql: sql };
+  } catch (err) {
+    return { sql: '', error: 'Connection error: ' + (err.message || 'unknown') };
+  }
+}
+
+// Backward-compat alias
+var nlToCypher = nlToSQL;
+
+/**
+ * Execute a SQL query against SQLite room.db and format results as a chat-friendly response.
+ * For Node.js server-side use (requires lazygraph-ops.cjs connection).
+ *
+ * @param {string} sql - SQL query string
+ * @param {object} conn - node:sqlite DatabaseSync object (from lazygraph-ops openGraph)
+ * @returns {Promise<{rows: Array<object>, formatted: string, error?: string}>}
+ */
+async function executeAndFormat(sql, conn) {
+  if (!sql) {
+    return { rows: [], formatted: 'No query to execute.', error: 'Empty query' };
+  }
+
+  try {
+    var rows = conn.prepare(sql).all();
+
+    if (!rows || rows.length === 0) {
+      return { rows: [], formatted: 'No results found for this query.' };
+    }
+
+    // Format as markdown table
+    var keys = Object.keys(rows[0]);
+    var headerRow = '| ' + keys.join(' | ') + ' |';
+    var sepRow = '| ' + keys.map(function() { return '---'; }).join(' | ') + ' |';
+    var dataRows = rows.map(function(row) {
+      return '| ' + keys.map(function(k) {
+        var val = row[k];
+        if (val === null || val === undefined) return '--';
+        if (typeof val === 'object') return JSON.stringify(val);
+        return String(val);
+      }).join(' | ') + ' |';
+    });
+
+    var formatted = headerRow + '\n' + sepRow + '\n' + dataRows.join('\n');
+
+    // Add count summary
+    formatted += '\n\n*' + rows.length + ' result' + (rows.length === 1 ? '' : 's') + ' returned.*';
+
+    return { rows: rows, formatted: formatted };
+  } catch (err) {
+    return { rows: [], formatted: '', error: 'Query error: ' + (err.message || 'unknown') };
+  }
+}
+
+/**
+ * Build a context injection string from a clicked graph element.
+ * Used when Constellation node/edge clicks inject context into the chat.
+ *
+ * @param {string} nodeId - The ID of the clicked node (artifact id or section name)
+ * @param {string} nodeType - 'Artifact' or 'Section'
+ * @param {string} [label] - Display label of the node
+ * @returns {string} A natural language question to inject into chat
+ */
+function injectContext(nodeId, nodeType, label) {
+  var displayName = label || nodeId;
+
+  if (nodeType === 'Section') {
+    return 'Tell me about the ' + displayName + ' section. What entries does it contain and what are its key connections?';
+  }
+
+  if (nodeType === 'Artifact') {
+    return 'Tell me about the entry "' + displayName + '". What does it connect to and what threads involve it?';
+  }
+
+  // Generic fallback
+  return 'Tell me about "' + displayName + '".';
+}
+
+// -- Module exports --
+
+// Node.js CJS
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = {
+    GRAPH_SCHEMA: GRAPH_SCHEMA,
+    buildSchemaDescription: buildSchemaDescription,
+    nlToSQL: nlToSQL,
+    nlToCypher: nlToCypher, // backward-compat alias
+    executeAndFormat: executeAndFormat,
+    injectContext: injectContext
+  };
+}
+
+// Browser global
+if (typeof window !== 'undefined') {
+  window.FabricChat = {
+    GRAPH_SCHEMA: GRAPH_SCHEMA,
+    buildSchemaDescription: buildSchemaDescription,
+    nlToSQL: nlToSQL,
+    nlToCypher: nlToCypher, // backward-compat alias
+    executeAndFormat: executeAndFormat,
+    injectContext: injectContext
+  };
+}

package/lib/chat/generative-tools.js

@@ -0,0 +1,219 @@
+/**
+ * MindrianOS Plugin -- Generative Tools for Larry Chat
+ * Defines AI tool definitions (Anthropic API format), execution handlers,
+ * and a declarative UI renderer (json-render pattern) for inline components.
+ *
+ * Tools:
+ *   - highlightCluster: highlight graph nodes by section or edge type
+ *   - filterEdgeType: filter graph to show specific edge type
+ *   - showInsight: render structured insight card inline in chat
+ *
+ * Zero dependencies. Embeddable via script tag or CJS require.
+ * Follows var/IIFE pattern matching canvas-graph.js and chat-panel.js.
+ *
+ * Usage:
+ *   GenerativeTools.TOOL_DEFINITIONS  // array for Anthropic API tools param
+ *   GenerativeTools.executeToolCall(name, input, context)
+ *   GenerativeTools.renderComponent(component)  // returns HTML string
+ */
+
+'use strict';
+
+var GenerativeTools = (function() {
+
+  // -- Tool definitions (Anthropic API format) --
+
+  var TOOL_DEFINITIONS = [
+    {
+      name: 'highlightCluster',
+      description: 'Highlight a group of nodes on the knowledge graph. Use for section names (e.g., "market-analysis", "problem-definition") or edge types (CONTRADICTS, CONVERGES, ENABLES, INFORMS). Always call this when the user asks to "show" or "highlight" something on the graph.',
+      input_schema: {
+        type: 'object',
+        properties: {
+          group: { type: 'string', description: 'Section name or edge type to highlight (e.g., "market-analysis", "CONTRADICTS")' }
+        },
+        required: ['group']
+      }
+    },
+    {
+      name: 'filterEdgeType',
+      description: 'Filter the graph to show only edges of a specific type. Use when user asks about relationships, connections of a specific kind, or wants to focus on contradictions/convergences/etc.',
+      input_schema: {
+        type: 'object',
+        properties: {
+          edgeType: { type: 'string', enum: ['CONTRADICTS', 'CONVERGES', 'ENABLES', 'INFORMS', 'HSI_CONNECTION', 'REVERSE_SALIENT'], description: 'Edge type to filter' }
+        },
+        required: ['edgeType']
+      }
+    },
+    {
+      name: 'showInsight',
+      description: 'Render a visual insight card in the chat with structured data. Use when presenting analysis results, summaries, or comparisons. The card renders inline in the chat.',
+      input_schema: {
+        type: 'object',
+        properties: {
+          title: { type: 'string', description: 'Card title' },
+          items: {
+            type: 'array',
+            items: {
+              type: 'object',
+              properties: {
+                label: { type: 'string' },
+                value: { type: 'string' },
+                color: { type: 'string', description: 'Optional hex color for accent' }
+              },
+              required: ['label', 'value']
+            },
+            description: 'Key-value items to display'
+          },
+          footer: { type: 'string', description: 'Optional footer text' }
+        },
+        required: ['title', 'items']
+      }
+    }
+  ];
+
+  // -- Tool execution --
+
+  function executeToolCall(toolName, toolInput, context) {
+    context = context || {};
+    var graph = context.graph || null;
+
+    if (toolName === 'highlightCluster') {
+      if (!graph || typeof graph.highlightCluster !== 'function') {
+        return { success: false, message: 'Graph not available on this view' };
+      }
+      graph.highlightCluster(toolInput.group);
+      return { success: true, message: 'Highlighted ' + toolInput.group };
+    }
+
+    if (toolName === 'filterEdgeType') {
+      if (!graph || typeof graph.highlightCluster !== 'function') {
+        return { success: false, message: 'Graph not available on this view' };
+      }
+      // highlightCluster already handles edge types
+      graph.highlightCluster(toolInput.edgeType);
+      return { success: true, message: 'Filtered to ' + toolInput.edgeType + ' edges' };
+    }
+
+    if (toolName === 'showInsight') {
+      return {
+        success: true,
+        rendered: true,
+        component: {
+          type: 'insight-card',
+          title: toolInput.title,
+          items: toolInput.items,
+          footer: toolInput.footer || ''
+        }
+      };
+    }
+
+    return { success: false, message: 'Unknown tool: ' + toolName };
+  }
+
+  // -- Declarative UI renderer (json-render pattern, GENUI-01) --
+
+  function escapeHtml(str) {
+    if (!str) return '';
+    return String(str).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+  }
+
+  function renderComponent(component) {
+    if (!component || !component.type) return '';
+
+    if (component.type === 'insight-card') {
+      return renderInsightCard(component);
+    }
+
+    if (component.type === 'list') {
+      return renderList(component);
+    }
+
+    if (component.type === 'table') {
+      return renderTable(component);
+    }
+
+    return '<div style="color:var(--text-muted,#666);font-size:11px;">Unknown component: ' + escapeHtml(component.type) + '</div>';
+  }
+
+  function renderInsightCard(comp) {
+    var html = '<div style="border-left:3px solid var(--mondrian-yellow,#E8B931);background:rgba(232,185,49,0.06);border-radius:6px;padding:12px 14px;margin:4px 0;font-size:13px;">';
+    html += '<div style="font-weight:600;margin-bottom:8px;color:var(--text-primary,#EEF0F4);">' + escapeHtml(comp.title) + '</div>';
+
+    if (comp.items && comp.items.length) {
+      for (var i = 0; i < comp.items.length; i++) {
+        var item = comp.items[i];
+        var colorDot = item.color
+          ? '<span style="display:inline-block;width:8px;height:8px;border-radius:50%;background:' + escapeHtml(item.color) + ';margin-right:6px;vertical-align:middle;"></span>'
+          : '';
+        html += '<div style="display:flex;align-items:baseline;gap:6px;margin-bottom:4px;line-height:1.4;">';
+        html += colorDot;
+        html += '<span style="color:var(--text-secondary,#999);min-width:80px;">' + escapeHtml(item.label) + '</span>';
+        html += '<span style="color:var(--text-primary,#EEF0F4);">' + escapeHtml(item.value) + '</span>';
+        html += '</div>';
+      }
+    }
+
+    if (comp.footer) {
+      html += '<div style="margin-top:8px;font-size:11px;color:var(--text-muted,#666);border-top:1px solid var(--border-color,#2A2A2A);padding-top:6px;">' + escapeHtml(comp.footer) + '</div>';
+    }
+
+    html += '</div>';
+    return html;
+  }
+
+  function renderList(comp) {
+    var html = '<div style="border-left:3px solid var(--mondrian-blue,#1B3B6F);background:rgba(27,59,111,0.06);border-radius:6px;padding:12px 14px;margin:4px 0;font-size:13px;">';
+    if (comp.title) {
+      html += '<div style="font-weight:600;margin-bottom:8px;color:var(--text-primary,#EEF0F4);">' + escapeHtml(comp.title) + '</div>';
+    }
+    if (comp.items && comp.items.length) {
+      html += '<ul style="margin:0;padding-left:18px;color:var(--text-primary,#EEF0F4);">';
+      for (var i = 0; i < comp.items.length; i++) {
+        var item = typeof comp.items[i] === 'string' ? comp.items[i] : (comp.items[i].label || comp.items[i].value || '');
+        html += '<li style="margin-bottom:3px;line-height:1.4;">' + escapeHtml(item) + '</li>';
+      }
+      html += '</ul>';
+    }
+    html += '</div>';
+    return html;
+  }
+
+  function renderTable(comp) {
+    var html = '<div style="border-left:3px solid var(--mondrian-red,#C23B22);background:rgba(194,59,34,0.06);border-radius:6px;padding:12px 14px;margin:4px 0;font-size:12px;overflow-x:auto;">';
+    if (comp.title) {
+      html += '<div style="font-weight:600;margin-bottom:8px;font-size:13px;color:var(--text-primary,#EEF0F4);">' + escapeHtml(comp.title) + '</div>';
+    }
+    if (comp.headers && comp.rows) {
+      html += '<table style="width:100%;border-collapse:collapse;">';
+      html += '<thead><tr>';
+      for (var h = 0; h < comp.headers.length; h++) {
+        html += '<th style="text-align:left;padding:4px 8px;border-bottom:1px solid var(--border-color,#2A2A2A);color:var(--text-secondary,#999);font-weight:500;">' + escapeHtml(comp.headers[h]) + '</th>';
+      }
+      html += '</tr></thead><tbody>';
+      for (var r = 0; r < comp.rows.length; r++) {
+        html += '<tr>';
+        var row = comp.rows[r];
+        for (var c = 0; c < row.length; c++) {
+          html += '<td style="padding:4px 8px;border-bottom:1px solid rgba(42,42,42,0.5);color:var(--text-primary,#EEF0F4);">' + escapeHtml(row[c]) + '</td>';
+        }
+        html += '</tr>';
+      }
+      html += '</tbody></table>';
+    }
+    html += '</div>';
+    return html;
+  }
+
+  return {
+    TOOL_DEFINITIONS: TOOL_DEFINITIONS,
+    executeToolCall: executeToolCall,
+    renderComponent: renderComponent
+  };
+
+})();
+
+// Module exports
+if (typeof window !== 'undefined') window.GenerativeTools = GenerativeTools;
+if (typeof module !== 'undefined') module.exports = GenerativeTools;

package/lib/conversation/ROOM.md

@@ -0,0 +1,39 @@
+---
+type: directory-identity
+name: lib/conversation
+purpose: Conversation operator state machine + NL classifier (Phase 99)
+phase: 99
+canon_parts: [3, 4, 7]
+created: 2026-05-01
+---
+
+# lib/conversation/
+
+The conversation layer. Owns the explicit operator state machine that makes Larry's per-turn behavior deterministic.
+
+## Files
+
+- `operator.cjs` - state primitive: `getCurrent / transition / validate`. Per-room JSON at `<roomDir>/.mindrian/conversation-operator.json`. Cold-start default: JUST_TALK. Atomic writes (mktemp + rename). Every transition emits an `OPERATOR_TRANSITION` typed edge to the local graph (Canon Part 4).
+- `classifier.cjs` (Plan 99-02) - heuristic NL classifier. Detects operator transitions from user messages + tool invocations. No LLM round-trip (D-10). Confidence threshold 0.6 (D-12).
+- `entity-signals.cjs` (DEFERRED to Phase 102.A) - shared lexicon for entity-introduction signals. Phase 99 ships an inline regex matcher inside classifier.cjs.
+
+## The five operators
+
+| Operator | Render contract |
+|----------|-----------------|
+| JUST_TALK | Prose only. No 4-zone. No Zone 4. No Intelligence Strip. |
+| EXPLORE_CAPTURE | Prose during talk; Shape E only on crystallization with Shape F.4 confirmation gate. |
+| BUILD_ROOM | Every response ends with 4-zone anatomy + Zone 4 footer. |
+| METHODOLOGY | No shape mid-session. Shape E or F at gate points only. Banned: spontaneous Zone 4 footers. |
+| DECISION_GATE | Shape F.x active. Keyboard input only. No prose. |
+
+## Canon Part 8 boundary (LOCAL ONLY)
+
+This directory writes only to `<roomDir>/.mindrian/conversation-operator.json` and `<roomDir>/.room-graph/room.db`. Never to Brain. Never queries Brain. Operator transitions are LOCAL data per Canon Part 8.
+
+## Consumers
+
+- Phase 100 `lib/hmi/jtbd-classifier.cjs` reads operator as classifier input (stratum 2).
+- Phase 102 `lib/render/render-v2.cjs` consumes operator via `render(zones, mode, operator, tier)`.
+- Phase 95.1 drift class F detector reads operator to suppress false-positives during legitimate METHODOLOGY-mode silence.
+- Sprites Workspace v2.0 reads the state file directly to render the right UI mode.

package/lib/conversation/classifier-rules.json

@@ -0,0 +1,38 @@
+{
+  "schema_version": "1.0.0",
+  "comment": "Phase 99-02 heuristic classifier rules. Tunable without code edits. Schema documented in 99-02-PLAN.md task 1.",
+  "tool_markers": [
+    { "pattern_type": "regex", "pattern": "^/mos:room\\b", "target_op": "BUILD_ROOM", "weight": 0.95, "trigger": "mos_command" },
+    { "pattern_type": "regex", "pattern": "^/mos:operator\\b", "target_op": null, "weight": 0.0, "trigger": null, "comment": "no transition; just shows state" },
+    { "pattern_type": "regex", "pattern": "^/mos:status\\b", "target_op": null, "weight": 0.0, "trigger": null, "comment": "diagnostic; does not change operator" },
+    { "pattern_type": "regex", "pattern": "^/mos:[a-z-]+", "target_op": "METHODOLOGY", "weight": 0.95, "trigger": "mos_command" },
+    { "pattern_type": "literal", "pattern": "/exit", "target_op": "BUILD_ROOM", "weight": 0.95, "trigger": "mos_command", "from_required": "METHODOLOGY" }
+  ],
+  "intent_patterns": [
+    { "pattern_type": "literal_ci", "pattern": "just talking", "target_op": "JUST_TALK", "weight": 0.7 },
+    { "pattern_type": "literal_ci", "pattern": "set this aside", "target_op": "JUST_TALK", "weight": 0.7 },
+    { "pattern_type": "literal_ci", "pattern": "off topic", "target_op": "JUST_TALK", "weight": 0.6 },
+    { "pattern_type": "literal_ci", "pattern": "by the way", "target_op": "JUST_TALK", "weight": 0.3 },
+    { "pattern_type": "literal_ci", "pattern": "let's file this", "target_op": "BUILD_ROOM", "weight": 0.7 },
+    { "pattern_type": "literal_ci", "pattern": "lets file this", "target_op": "BUILD_ROOM", "weight": 0.7 },
+    { "pattern_type": "literal_ci", "pattern": "add to the room", "target_op": "BUILD_ROOM", "weight": 0.7 },
+    { "pattern_type": "literal_ci", "pattern": "file this", "target_op": "BUILD_ROOM", "weight": 0.6 },
+    { "pattern_type": "literal_ci", "pattern": "save this", "target_op": "BUILD_ROOM", "weight": 0.6 },
+    { "pattern_type": "literal_ci", "pattern": "capture this", "target_op": "BUILD_ROOM", "weight": 0.6 },
+    { "pattern_type": "literal_ci", "pattern": "interesting", "target_op": "EXPLORE_CAPTURE", "weight": 0.4 },
+    { "pattern_type": "literal_ci", "pattern": "worth noting", "target_op": "EXPLORE_CAPTURE", "weight": 0.5 },
+    { "pattern_type": "literal_ci", "pattern": "did you know", "target_op": "EXPLORE_CAPTURE", "weight": 0.4 },
+    { "pattern_type": "literal_ci", "pattern": "i noticed", "target_op": "EXPLORE_CAPTURE", "weight": 0.5 },
+    { "pattern_type": "literal_ci", "pattern": "i wonder", "target_op": "EXPLORE_CAPTURE", "weight": 0.4 }
+  ],
+  "entity_signals": [
+    { "pattern_type": "regex", "pattern": "\\b[A-Z][a-z]+\\s+[A-Z][a-z]+\\b", "name": "person_full_name", "boost_op": "EXPLORE_CAPTURE", "weight": 0.3 },
+    { "pattern_type": "regex_ci", "pattern": "\\b(by|before|deadline|due|eod|eow)\\b", "name": "deadline_word", "boost_op": "EXPLORE_CAPTURE", "weight": 0.3 },
+    { "pattern_type": "regex", "pattern": "\\bQ[1-4]\\b", "name": "fiscal_quarter", "boost_op": "EXPLORE_CAPTURE", "weight": 0.3 },
+    { "pattern_type": "regex_ci", "pattern": "\\b(venture|startup|company|project)\\s+[\"']?[A-Z]", "name": "venture_name", "boost_op": "EXPLORE_CAPTURE", "weight": 0.3 }
+  ],
+  "thresholds": {
+    "transition_min_confidence": 0.6,
+    "tool_marker_override_floor": 0.95
+  }
+}