chati-dev 3.2.4 → 3.3.0

package/src/telemetry/collector.js

@@ -0,0 +1,83 @@
+/**
+ * @fileoverview Telemetry event collector.
+ *
+ * Buffers events in memory during pipeline execution.
+ * Events are flushed (sent) at pipeline completion or on demand.
+ */
+
+import { validateEvent } from './schema.js';
+
+// ---------------------------------------------------------------------------
+// Collector
+// ---------------------------------------------------------------------------
+
+/** @type {Array<{ type: string, properties: object, timestamp: string }>} */
+let buffer = [];
+
+/** @type {boolean} */
+let enabled = false;
+
+/**
+ * Initialize the collector with enabled state.
+ *
+ * @param {boolean} isEnabled
+ */
+export function initCollector(isEnabled) {
+  enabled = isEnabled;
+  buffer = [];
+}
+
+/**
+ * Track a telemetry event.
+ * Events are buffered until flush() is called.
+ * Invalid events are silently dropped.
+ *
+ * @param {string} type - Event type (from TELEMETRY_EVENTS)
+ * @param {object} [properties={}] - Event properties
+ */
+export function track(type, properties = {}) {
+  if (!enabled) return;
+
+  const event = { type, properties };
+  const validation = validateEvent(event);
+
+  if (!validation.valid) return; // Silently drop invalid events
+
+  buffer.push({
+    type,
+    properties,
+    timestamp: new Date().toISOString(),
+  });
+}
+
+/**
+ * Flush all buffered events and clear the buffer.
+ * Returns empty array if telemetry is disabled.
+ *
+ * @returns {Array<{ type: string, properties: object, timestamp: string }>}
+ */
+export function flush() {
+  if (!enabled) return [];
+
+  const events = [...buffer];
+  buffer = [];
+  return events;
+}
+
+/**
+ * Get current buffer size (for diagnostics).
+ *
+ * @returns {number}
+ */
+export function getBufferSize() {
+  return buffer.length;
+}
+
+/**
+ * Get status of the collector.
+ *
+ * @returns {{ enabled: boolean, buffered: number }}
+ */
+export function getStatus() {
+  return { enabled, buffered: buffer.length };
+}

package/src/telemetry/config.js

@@ -0,0 +1,119 @@
+/**
+ * @fileoverview Telemetry configuration reader/writer.
+ *
+ * Reads and writes telemetry preferences from chati.dev/config.yaml.
+ * Manages the anonymous UUID for tracking.
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { randomUUID } from 'crypto';
+import yaml from 'js-yaml';
+
+// ---------------------------------------------------------------------------
+// Config Management
+// ---------------------------------------------------------------------------
+
+/**
+ * Read telemetry config from project's config.yaml.
+ *
+ * @param {string} targetDir - Project root directory
+ * @returns {{ enabled: boolean, anonymousId: string | null, endpoint: string }}
+ */
+export function getTelemetryConfig(targetDir) {
+  const configPath = join(targetDir, 'chati.dev', 'config.yaml');
+
+  const defaults = {
+    enabled: false,
+    anonymousId: null,
+    endpoint: 'https://chati-telemetry.vercel.app/api/events',
+    apiKey: '10b0b54ba4f392fa46379ba778062ab0af5ca61e79609a7dce4aadd660104b56',
+  };
+
+  if (!existsSync(configPath)) return defaults;
+
+  try {
+    const content = readFileSync(configPath, 'utf-8');
+    const config = yaml.load(content);
+    const telemetry = config?.telemetry || {};
+
+    return {
+      enabled: telemetry.enabled === true,
+      anonymousId: telemetry.anonymous_id || null,
+      endpoint: telemetry.endpoint || defaults.endpoint,
+      apiKey: telemetry.api_key || defaults.apiKey,
+    };
+  } catch {
+    return defaults;
+  }
+}
+
+/**
+ * Check if telemetry is enabled.
+ *
+ * @param {string} targetDir
+ * @returns {boolean}
+ */
+export function isEnabled(targetDir) {
+  return getTelemetryConfig(targetDir).enabled;
+}
+
+/**
+ * Set telemetry enabled/disabled in config.yaml.
+ * Generates anonymous UUID on first enable.
+ *
+ * @param {string} targetDir
+ * @param {boolean} enabled
+ */
+export function setEnabled(targetDir, enabled) {
+  const configPath = join(targetDir, 'chati.dev', 'config.yaml');
+
+  if (!existsSync(configPath)) return;
+
+  try {
+    const content = readFileSync(configPath, 'utf-8');
+    const config = yaml.load(content) || {};
+
+    if (!config.telemetry) config.telemetry = {};
+    config.telemetry.enabled = enabled;
+
+    // Generate UUID on first enable
+    if (enabled && !config.telemetry.anonymous_id) {
+      config.telemetry.anonymous_id = randomUUID();
+    }
+
+    writeFileSync(configPath, yaml.dump(config, { lineWidth: -1 }), 'utf-8');
+  } catch {
+    // Silently fail — telemetry config is non-critical
+  }
+}
+
+/**
+ * Get or generate the anonymous tracking ID.
+ *
+ * @param {string} targetDir
+ * @returns {string}
+ */
+export function getAnonymousId(targetDir) {
+  const config = getTelemetryConfig(targetDir);
+
+  if (config.anonymousId) return config.anonymousId;
+
+  // Generate and persist
+  const id = randomUUID();
+  const configPath = join(targetDir, 'chati.dev', 'config.yaml');
+
+  if (existsSync(configPath)) {
+    try {
+      const content = readFileSync(configPath, 'utf-8');
+      const parsed = yaml.load(content) || {};
+      if (!parsed.telemetry) parsed.telemetry = {};
+      parsed.telemetry.anonymous_id = id;
+      writeFileSync(configPath, yaml.dump(parsed, { lineWidth: -1 }), 'utf-8');
+    } catch {
+      // Return generated ID even if persistence fails
+    }
+  }
+
+  return id;
+}

package/src/telemetry/index.js

@@ -0,0 +1,11 @@
+/**
+ * @fileoverview Telemetry public API.
+ *
+ * Provides track(), flush(), and configuration utilities.
+ * All telemetry is opt-in and anonymous.
+ */
+
+export { TELEMETRY_EVENTS, validateEvent } from './schema.js';
+export { getTelemetryConfig, isEnabled, setEnabled, getAnonymousId } from './config.js';
+export { initCollector, track, flush, getBufferSize, getStatus } from './collector.js';
+export { sendEvents, DEFAULT_ENDPOINT } from './sender.js';

package/src/telemetry/schema.js

@@ -0,0 +1,104 @@
+/**
+ * @fileoverview Telemetry event schema and validation.
+ *
+ * Defines the 6 event types collected by opt-in telemetry.
+ * Zero PII — only anonymous usage metrics.
+ */
+
+// ---------------------------------------------------------------------------
+// Event Types
+// ---------------------------------------------------------------------------
+
+export const TELEMETRY_EVENTS = [
+  'installation_completed',
+  'agent_completed',
+  'gate_evaluated',
+  'pipeline_completed',
+  'circuit_breaker_triggered',
+  'error_occurred',
+];
+
+// ---------------------------------------------------------------------------
+// Property Schemas (allowed fields per event type)
+// ---------------------------------------------------------------------------
+
+const EVENT_PROPERTIES = {
+  installation_completed: [
+    'providers', 'editors', 'projectType', 'language',
+    'primaryProvider', 'installDuration',
+  ],
+  agent_completed: [
+    'agent', 'provider', 'model', 'duration', 'score',
+    'retryCount', 'pipelineType',
+  ],
+  gate_evaluated: [
+    'gate', 'result', 'score', 'blockers',
+  ],
+  pipeline_completed: [
+    'pipelineType', 'totalDuration', 'agentsRun', 'finalStatus',
+    'abandonedAt', 'totalCost', 'deviationCount',
+  ],
+  circuit_breaker_triggered: [
+    'trigger', 'agent', 'provider',
+  ],
+  error_occurred: [
+    'errorType', 'agent', 'provider', 'phase',
+  ],
+};
+
+// ---------------------------------------------------------------------------
+// PII blocklist — fields that MUST NEVER appear in telemetry
+// ---------------------------------------------------------------------------
+
+const PII_BLOCKLIST = [
+  'path', 'filePath', 'fileName', 'directory', 'cwd',
+  'apiKey', 'token', 'secret', 'password', 'credential',
+  'email', 'username', 'name', 'ip', 'hostname',
+  'content', 'code', 'source', 'prompt', 'message',
+  'stackTrace', 'stack',
+];
+
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate a telemetry event.
+ *
+ * @param {{ type: string, properties?: object }} event
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateEvent(event) {
+  const errors = [];
+
+  if (!event || typeof event !== 'object') {
+    return { valid: false, errors: ['Event must be an object'] };
+  }
+
+  if (!event.type || !TELEMETRY_EVENTS.includes(event.type)) {
+    errors.push(`Unknown event type: "${event.type}". Valid: ${TELEMETRY_EVENTS.join(', ')}`);
+  }
+
+  const props = event.properties || {};
+
+  // Check for PII fields
+  for (const key of Object.keys(props)) {
+    if (PII_BLOCKLIST.includes(key)) {
+      errors.push(`PII field detected: "${key}" — must not be included in telemetry`);
+    }
+  }
+
+  // Check for PII in values (paths, emails)
+  for (const [key, value] of Object.entries(props)) {
+    if (typeof value === 'string') {
+      if (value.includes('/Users/') || value.includes('/home/') || value.includes('C:\\Users\\')) {
+        errors.push(`PII detected in "${key}": value contains filesystem path`);
+      }
+      if (value.includes('@') && value.includes('.')) {
+        errors.push(`PII detected in "${key}": value looks like an email`);
+      }
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}

package/src/telemetry/sender.js

@@ -0,0 +1,60 @@
+/**
+ * @fileoverview Telemetry event sender.
+ *
+ * Sends batched events to the telemetry endpoint via HTTP POST.
+ * Fire-and-forget: never blocks the user workflow, fails silently.
+ */
+
+// ---------------------------------------------------------------------------
+// Default Endpoint
+// ---------------------------------------------------------------------------
+
+export const DEFAULT_ENDPOINT = 'https://chati-telemetry.vercel.app/api/events';
+
+// ---------------------------------------------------------------------------
+// Sender
+// ---------------------------------------------------------------------------
+
+/**
+ * Send telemetry events to the remote endpoint.
+ *
+ * Fire-and-forget with 5s timeout. Never throws, never blocks.
+ *
+ * @param {Array<{ type: string, properties: object, timestamp: string }>} events
+ * @param {{ anonymousId: string, version: string, endpoint?: string }} config
+ * @returns {Promise<boolean>} true if sent successfully, false otherwise
+ */
+export async function sendEvents(events, config) {
+  if (!config || !config.anonymousId || events.length === 0) return false;
+
+  const endpoint = config.endpoint || DEFAULT_ENDPOINT;
+
+  const payload = {
+    anonymousId: config.anonymousId,
+    chatiVersion: config.version || 'unknown',
+    nodeVersion: process.version,
+    os: process.platform,
+    events,
+  };
+
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 5000);
+
+    await fetch(endpoint, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        ...(config.apiKey ? { 'X-Telemetry-Key': config.apiKey } : {}),
+      },
+      body: JSON.stringify(payload),
+      signal: controller.signal,
+    });
+
+    clearTimeout(timeout);
+    return true;
+  } catch {
+    // Silently fail — never block user workflow
+    return false;
+  }
+}

package/src/terminal/cli-registry.js

@@ -113,7 +113,13 @@ export function getAllProviders() {
  */
 export function loadEnabledProviders(projectDir) {
   const { primary, enabled } = parseProviderConfig(projectDir);
-  return { primary, enabled };
+  const validNames = Object.keys(PROVIDERS);
+
+  // Filter out invalid provider names (typos in config.yaml)
+  const validEnabled = enabled.filter(name => validNames.includes(name));
+  const validPrimary = validNames.includes(primary) ? primary : 'claude';
+
+  return { primary: validPrimary, enabled: validEnabled };
 }
 
 /**

package/src/terminal/cost-tracker.js

@@ -0,0 +1,197 @@
+/**
+ * @fileoverview Token cost tracking for terminal spawner.
+ *
+ * Estimates token usage and cost per agent execution,
+ * providing session-level and per-agent cost visibility.
+ *
+ * Constitution Article XVI — Model Governance.
+ */
+
+// ---------------------------------------------------------------------------
+// Cost Tables
+// ---------------------------------------------------------------------------
+
+/**
+ * Estimated cost per 1K tokens (input + output average) in USD.
+ * These are approximations for cost awareness — not billing.
+ */
+export const COST_PER_1K = {
+  // Claude models
+  opus: 0.075,
+  sonnet: 0.015,
+  haiku: 0.005,
+  // Gemini models
+  pro: 0.007,
+  flash: 0.001,
+  // Codex/Copilot
+  codex: 0.010,
+  copilot: 0.010,
+  mini: 0.003,
+  // Fallback
+  unknown: 0.015,
+};
+
+// ---------------------------------------------------------------------------
+// Token Estimation
+// ---------------------------------------------------------------------------
+
+/**
+ * Estimate token count from text using a simple heuristic.
+ * Approximation: ~4 characters per token for English text.
+ *
+ * @param {string} text
+ * @returns {number} Estimated token count
+ */
+export function estimateTokens(text) {
+  if (!text || typeof text !== 'string') return 0;
+  return Math.ceil(text.length / 4);
+}
+
+// ---------------------------------------------------------------------------
+// Cost Tracker
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {object} ExecutionRecord
+ * @property {string} agent - Agent name
+ * @property {string} model - Model tier used
+ * @property {string} taskId - Task identifier
+ * @property {number} inputTokens - Estimated input tokens
+ * @property {number} outputTokens - Estimated output tokens
+ * @property {number} cost - Estimated cost in USD
+ * @property {number} duration - Execution time in ms
+ * @property {string} timestamp - ISO timestamp
+ */
+
+/**
+ * @typedef {object} CostReport
+ * @property {number} totalCost - Total estimated cost
+ * @property {number} totalTokens - Total estimated tokens
+ * @property {number} executionCount - Number of executions
+ * @property {Record<string, { cost: number, tokens: number, count: number }>} byAgent - Per-agent breakdown
+ * @property {Record<string, { cost: number, tokens: number, count: number }>} byModel - Per-model breakdown
+ * @property {string} generatedAt - ISO timestamp
+ */
+
+/**
+ * Create a cost tracker instance.
+ *
+ * @returns {{ recordExecution: Function, getSessionCost: Function, getAgentCost: Function, exportReport: Function, reset: Function }}
+ */
+export function createCostTracker() {
+  /** @type {ExecutionRecord[]} */
+  let records = [];
+
+  /**
+   * Record a completed execution.
+   *
+   * @param {{ agent: string, model?: string, taskId: string, inputText?: string, outputText?: string, duration?: number }} execution
+   * @returns {ExecutionRecord}
+   */
+  function recordExecution(execution) {
+    const model = execution.model || 'unknown';
+    const inputTokens = estimateTokens(execution.inputText);
+    const outputTokens = estimateTokens(execution.outputText);
+    const totalTokens = inputTokens + outputTokens;
+    const costRate = COST_PER_1K[model] || COST_PER_1K.unknown;
+    const cost = (totalTokens / 1000) * costRate;
+
+    const record = {
+      agent: execution.agent,
+      model,
+      provider: execution.provider || 'unknown',
+      taskId: execution.taskId,
+      inputTokens,
+      outputTokens,
+      cost: Math.round(cost * 1_000_000) / 1_000_000, // 6 decimal places
+      duration: execution.duration || 0,
+      timestamp: new Date().toISOString(),
+    };
+
+    records.push(record);
+    return record;
+  }
+
+  /**
+   * Get total session cost.
+   *
+   * @returns {number} Total cost in USD
+   */
+  function getSessionCost() {
+    return records.reduce((sum, r) => sum + r.cost, 0);
+  }
+
+  /**
+   * Get cost for a specific agent.
+   *
+   * @param {string} agent
+   * @returns {{ cost: number, tokens: number, count: number }}
+   */
+  function getAgentCost(agent) {
+    const agentRecords = records.filter(r => r.agent === agent);
+    return {
+      cost: agentRecords.reduce((sum, r) => sum + r.cost, 0),
+      tokens: agentRecords.reduce((sum, r) => sum + r.inputTokens + r.outputTokens, 0),
+      count: agentRecords.length,
+    };
+  }
+
+  /**
+   * Export a full cost report.
+   *
+   * @returns {CostReport}
+   */
+  function exportReport() {
+    const byAgent = {};
+    const byModel = {};
+    const byProvider = {};
+
+    for (const record of records) {
+      const totalTokens = record.inputTokens + record.outputTokens;
+
+      // Aggregate by agent
+      if (!byAgent[record.agent]) {
+        byAgent[record.agent] = { cost: 0, tokens: 0, count: 0 };
+      }
+      byAgent[record.agent].cost += record.cost;
+      byAgent[record.agent].tokens += totalTokens;
+      byAgent[record.agent].count += 1;
+
+      // Aggregate by model
+      if (!byModel[record.model]) {
+        byModel[record.model] = { cost: 0, tokens: 0, count: 0 };
+      }
+      byModel[record.model].cost += record.cost;
+      byModel[record.model].tokens += totalTokens;
+      byModel[record.model].count += 1;
+
+      // Aggregate by provider
+      const prov = record.provider || 'unknown';
+      if (!byProvider[prov]) {
+        byProvider[prov] = { cost: 0, tokens: 0, count: 0 };
+      }
+      byProvider[prov].cost += record.cost;
+      byProvider[prov].tokens += totalTokens;
+      byProvider[prov].count += 1;
+    }
+
+    return {
+      totalCost: getSessionCost(),
+      totalTokens: records.reduce((sum, r) => sum + r.inputTokens + r.outputTokens, 0),
+      executionCount: records.length,
+      byAgent,
+      byModel,
+      byProvider,
+      generatedAt: new Date().toISOString(),
+    };
+  }
+
+  /**
+   * Reset all tracked records.
+   */
+  function reset() {
+    records = [];
+  }
+
+  return { recordExecution, getSessionCost, getAgentCost, exportReport, reset };
+}

package/src/terminal/handoff-parser.js

@@ -4,28 +4,79 @@
  * Agents running in separate `claude -p` terminals include a
  * <chati-handoff> block in their output. This module extracts
  * and parses that block so the orchestrator can read the results.
+ *
+ * Includes integrity validation via schema checking (Item 13).
+ */
+
+import { validateSchema, HANDOFF_SCHEMA } from '../utils/schema-validator.js';
+
+/**
+ * Valid status values for handoff blocks.
+ * @type {string[]}
  */
+const VALID_STATUSES = ['APPROVED', 'NEEDS_REVISION', 'BLOCKED', 'unknown'];
 
 /**
  * Parse the <chati-handoff> block from agent stdout.
  *
+ * Returns validation info alongside parsed data for integrity checking.
+ *
  * @param {string} output - Full stdout from the agent process
- * @returns {{ found: boolean, handoff: object|null, rawOutput: string }}
+ * @returns {{ found: boolean, handoff: object|null, rawOutput: string, valid: boolean, warnings: string[] }}
  */
 export function parseAgentOutput(output) {
   if (!output || typeof output !== 'string') {
-    return { found: false, handoff: null, rawOutput: '' };
+    return { found: false, handoff: null, rawOutput: '', valid: false, warnings: ['No output provided'] };
   }
 
   const match = output.match(/<chati-handoff>([\s\S]*?)<\/chati-handoff>/);
   if (!match) {
-    return { found: false, handoff: null, rawOutput: output };
+    return { found: false, handoff: null, rawOutput: output, valid: false, warnings: ['No handoff block found'] };
   }
 
   const content = match[1].trim();
   const handoff = parseHandoffFields(content);
 
-  return { found: true, handoff, rawOutput: output };
+  // Validate the parsed handoff
+  const { valid, warnings } = validateHandoff(handoff);
+
+  return { found: true, handoff, rawOutput: output, valid, warnings };
+}
+
+/**
+ * Validate a parsed handoff against the schema and business rules.
+ *
+ * @param {object} handoff
+ * @returns {{ valid: boolean, warnings: string[] }}
+ */
+export function validateHandoff(handoff) {
+  const warnings = [];
+
+  if (!handoff) {
+    return { valid: false, warnings: ['Handoff is null'] };
+  }
+
+  // Schema validation
+  const schemaResult = validateSchema(handoff, HANDOFF_SCHEMA);
+  warnings.push(...schemaResult.errors, ...schemaResult.warnings);
+
+  // Business rule: status must be a valid value
+  if (handoff.status && !VALID_STATUSES.includes(handoff.status)) {
+    warnings.push(`Invalid status "${handoff.status}" — expected one of: ${VALID_STATUSES.join(', ')}`);
+  }
+
+  // Business rule: score must be 0-100
+  if (handoff.score !== null && handoff.score !== undefined) {
+    if (typeof handoff.score !== 'number' || handoff.score < 0 || handoff.score > 100) {
+      warnings.push(`Score ${handoff.score} is out of range 0-100`);
+    }
+  }
+
+  // A handoff is valid if there are no errors (warnings are OK)
+  const hasErrors = schemaResult.errors.length > 0 ||
+    (handoff.status && !VALID_STATUSES.includes(handoff.status));
+
+  return { valid: !hasErrors, warnings };
 }
 
 /**
@@ -52,6 +103,8 @@ function parseHandoffFields(content) {
     decisions: {},
     blockers: [],
     needs_input_question: null,
+    provider: null,
+    model: null,
   };
 
   const lines = content.split('\n');
@@ -119,6 +172,10 @@ function parseHandoffFields(content) {
         result.summary = value || '';
       } else if (key === 'needs_input_question') {
         result.needs_input_question = value === 'null' || value === '' ? null : value;
+      } else if (key === 'provider') {
+        result.provider = value || null;
+      } else if (key === 'model') {
+        result.model = value || null;
       }
     }
   }