chati-dev 3.3.1 → 4.0.0

package/src/terminal/run-agent.js

@@ -18,7 +18,10 @@ import { buildAgentPrompt } from './prompt-builder.js';
 import { spawnTerminal } from './spawner.js';
 import { parseAgentOutput } from './handoff-parser.js';
 import { createCostTracker } from './cost-tracker.js';
-import { track as telemetryTrack } from '../telemetry/collector.js';
+import { getRateLimiter } from './rate-limiter.js';
+import { initCollector, track as telemetryTrack, flush as telemetryFlush } from '../telemetry/collector.js';
+import { sendEvents } from '../telemetry/sender.js';
+import { getTelemetryConfig, isEnabled as isTelemetryEnabled } from '../telemetry/config.js';
 
 // ---------------------------------------------------------------------------
 // CLI argument parsing (no external deps)
@@ -62,6 +65,9 @@ async function main() {
   const projectDir = args['project-dir'] || process.cwd();
   const timeout = parseInt(args.timeout, 10) || 600_000; // default 10 minutes
 
+  // Initialize telemetry for this process
+  initCollector(isTelemetryEnabled(projectDir));
+
   // Load session state if available
   let sessionState = {};
   try {
@@ -94,6 +100,20 @@ async function main() {
     process.exit(1);
   }
 
+  // Wait for rate limit slot before spawning
+  const spawnProvider = promptResult.provider || args.provider || 'claude';
+  const limiter = getRateLimiter(spawnProvider);
+  if (!limiter.canSpawn()) {
+    const rateLimitStart = Date.now();
+    await limiter.waitForSlot();
+    const rateLimitWait = Date.now() - rateLimitStart;
+    telemetryTrack('rate_limit_wait', {
+      agent: args.agent,
+      provider: spawnProvider,
+      waitMs: rateLimitWait,
+    });
+  }
+
   // Spawn the agent terminal
   const startTime = Date.now();
   let handle;
@@ -117,6 +137,13 @@ async function main() {
   try {
     await waitForExit(handle, timeout);
   } catch (err) {
+    telemetryTrack('error_occurred', {
+      errorType: 'agent_failure',
+      agent: args.agent,
+      provider: promptResult.provider || args.provider || 'claude',
+      phase: sessionState?.phase || 'unknown',
+    });
+    await flushAndSend(projectDir);
     outputError(`Terminal execution failed: ${err.message}`);
     process.exit(2);
   }
@@ -156,6 +183,23 @@ async function main() {
     pipelineType: sessionState?.isQuickFlow ? 'quick-flow' : 'standard',
   });
 
+  // Track token usage if cost data is available
+  if (costRecord.inputTokens !== undefined) {
+    telemetryTrack('token_usage', {
+      sessionId: sessionState?.sessionId || 'unknown',
+      agent: args.agent,
+      provider: costRecord.provider,
+      model: costRecord.model || 'unknown',
+      inputTokens: costRecord.inputTokens || 0,
+      outputTokens: costRecord.outputTokens || 0,
+      totalTokens: (costRecord.inputTokens || 0) + (costRecord.outputTokens || 0),
+      estimatedCostUsd: costRecord.cost || 0,
+    });
+  }
+
+  // Flush telemetry before exit
+  await flushAndSend(projectDir);
+
   // Parse the handoff from stdout
   const parsed = parseAgentOutput(stdout);
 
@@ -193,6 +237,22 @@ async function main() {
 // Helpers
 // ---------------------------------------------------------------------------
 
+/**
+ * Flush buffered telemetry events and send to the backend.
+ * Fire-and-forget — never blocks process exit on failure.
+ */
+async function flushAndSend(projectDir) {
+  const events = telemetryFlush();
+  if (events.length === 0) return;
+
+  try {
+    const tConfig = getTelemetryConfig(projectDir);
+    await sendEvents(events, { ...tConfig, version: tConfig.chatiVersion || 'unknown' });
+  } catch {
+    // Silently fail — telemetry must never block agent execution
+  }
+}
+
 /**
  * Wait for a terminal handle's process to exit.
  */

package/src/terminal/run-parallel.js

@@ -16,11 +16,12 @@
 
 import { fileURLToPath } from 'url';
 import { buildAgentPrompt } from './prompt-builder.js';
-import { spawnParallelGroup } from './spawner.js';
+import { spawnParallelGroup, spawnTerminal } from './spawner.js';
 import { TerminalMonitor } from './monitor.js';
 import { collectResults, mergeHandoffs, buildConsolidatedHandoff } from './collector.js';
 import { parseAgentOutput } from './handoff-parser.js';
 import { estimateTokens, COST_PER_1K } from './cost-tracker.js';
+import { getRateLimiter } from './rate-limiter.js';
 
 // ---------------------------------------------------------------------------
 // CLI argument parsing
@@ -119,13 +120,29 @@ async function main() {
     }
   }
 
-  // Spawn all terminals in parallel
+  // Check rate limit capacity before spawning
+  const groupProvider = configs[0]?.provider || 'claude';
+  const limiter = getRateLimiter(groupProvider);
+  const rateStats = limiter.getStats();
+  const availableSlots = rateStats.limit - rateStats.used;
+  if (availableSlots < configs.length) {
+    console.error(`[chati] Rate limiter: ${availableSlots} slots available for ${configs.length} agents. Spawns may be throttled.`);
+  }
+
+  // Spawn all terminals in parallel (with sequential fallback)
   let group;
+  let fallbackUsed = false;
   try {
     group = spawnParallelGroup(configs);
   } catch (err) {
-    outputError(`Failed to spawn parallel group: ${err.message}`);
-    process.exit(1);
+    console.error(`[chati] Parallel spawn failed: ${err.message}. Falling back to sequential execution.`);
+    try {
+      group = await sequentialFallback(configs, timeout);
+      fallbackUsed = true;
+    } catch (fallbackErr) {
+      outputError(`Sequential fallback also failed: ${fallbackErr.message}`);
+      process.exit(1);
+    }
   }
 
   // Monitor until completion
@@ -218,6 +235,7 @@ async function main() {
       timeSaved: elapsed * (agents.length - 1),
     },
     costEstimate: costEstimates,
+    fallbackUsed,
   };
 
   process.stdout.write(JSON.stringify(output, null, 2) + '\n');
@@ -228,6 +246,60 @@ async function main() {
 // Helpers
 // ---------------------------------------------------------------------------
 
+/**
+ * Sequential fallback: spawn agents one at a time when parallel spawning fails.
+ * Produces the same group structure as spawnParallelGroup for transparent handling.
+ *
+ * @param {object[]} configs - Agent spawn configurations
+ * @param {number} timeout - Per-agent timeout in ms
+ * @returns {Promise<{ groupId: string, terminals: object[] }>}
+ */
+async function sequentialFallback(configs, timeout) {
+  const groupId = `seq-fallback-${Date.now()}`;
+  const terminals = [];
+
+  for (let i = 0; i < configs.length; i++) {
+    const cfg = configs[i];
+    const terminal = spawnTerminal({
+      agent: cfg.agent,
+      taskId: cfg.taskId,
+      model: cfg.model,
+      provider: cfg.provider,
+      prompt: cfg.prompt,
+      workingDir: cfg.workingDir,
+      timeout: cfg.timeout || timeout,
+    });
+
+    // Wait for this terminal to finish before spawning the next
+    await new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        terminal.kill?.();
+        resolve();
+      }, (cfg.timeout || timeout) + 5_000);
+
+      terminal.onExit?.(() => {
+        clearTimeout(timer);
+        resolve();
+      });
+
+      // If terminal doesn't have onExit, resolve after a short poll
+      if (!terminal.onExit) {
+        clearTimeout(timer);
+        resolve();
+      }
+    });
+
+    terminals.push(terminal);
+
+    // Small delay between spawns to avoid rate limit pressure
+    if (i < configs.length - 1) {
+      await new Promise(r => setTimeout(r, 500));
+    }
+  }
+
+  return { groupId, terminals };
+}
+
 /**
  * Determine the next sequential agent after a parallel group.
  * GROUP 1 (detail+architect+ux) → phases
@@ -256,4 +328,4 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
   });
 }
 
-export { parseArgs, determineNextAgent };
+export { parseArgs, determineNextAgent, sequentialFallback };

package/src/terminal/spawner.js

@@ -10,6 +10,7 @@
 import { spawn } from 'child_process';
 import { validateWriteScopes, buildIsolationEnv } from './isolation.js';
 import { getProvider } from './cli-registry.js';
+import { getRateLimiter } from './rate-limiter.js';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -234,6 +235,10 @@ export function spawnTerminal(config) {
     timeout,
   };
 
+  // Record spawn in rate limiter for throttling
+  const providerForRate = config.provider || 'claude';
+  getRateLimiter(providerForRate).recordSpawn();
+
   // Capture output (capped at ~10MB to prevent unbounded memory growth)
   const MAX_BUFFER_CHUNKS = 10_000;
   if (child.stdout) {
@@ -297,6 +302,14 @@ export function spawnParallelGroup(configs) {
     throw new Error(`Write scope conflicts detected: ${details}`);
   }
 
+  // Preemptive rate limit capacity check
+  const groupProvider = configs[0]?.provider || 'claude';
+  const limiter = getRateLimiter(groupProvider);
+  const stats = limiter.getStats();
+  if (stats.used + configs.length > stats.limit) {
+    console.error(`[chati] Rate limit warning: ${stats.used}/${stats.limit} slots used, requesting ${configs.length} more`);
+  }
+
   const groupId = `group-${Date.now()}`;
   const terminals = configs.map(cfg => spawnTerminal(cfg));
 

package/src/utils/feature-flags.js

@@ -0,0 +1,106 @@
+/**
+ * @fileoverview Feature flag reader for chati.dev framework.
+ *
+ * Reads the `features:` section from config.yaml and returns boolean
+ * values for each feature toggle. All features default to false when
+ * not explicitly set.
+ *
+ * Uses lightweight regex-based parsing consistent with config-parser.js.
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * All known feature flags with their default values.
+ * New features start as false (opt-in).
+ */
+const DEFAULTS = {
+  hybrid_budget: false,
+  anti_dash: false,
+  rate_limiter_integration: false,
+  l5_keywords: false,
+  prompt_size_guard: false,
+  ids_decision_engine: false,
+  surface_criteria: false,
+  parallel_fallback: false,
+  tool_mesh: false,
+  tech_presets: false,
+  doctor_autofix: false,
+  brandbook: false,
+};
+
+/**
+ * Check if a specific feature is enabled.
+ *
+ * @param {string} projectDir - Project root directory (contains chati.dev/)
+ * @param {string} featureName - Feature flag name (e.g., 'hybrid_budget')
+ * @returns {boolean} True if feature is enabled, false otherwise
+ */
+export function isFeatureEnabled(projectDir, featureName) {
+  const features = getEnabledFeatures(projectDir);
+  return features[featureName] ?? DEFAULTS[featureName] ?? false;
+}
+
+/**
+ * Get all feature flags with their current values.
+ *
+ * @param {string} projectDir - Project root directory (contains chati.dev/)
+ * @returns {Record<string, boolean>} Map of feature name to enabled status
+ */
+export function getEnabledFeatures(projectDir) {
+  const configPath = join(projectDir, 'chati.dev', 'config.yaml');
+  if (!existsSync(configPath)) {
+    return { ...DEFAULTS };
+  }
+
+  const raw = readFileSync(configPath, 'utf-8');
+  return parseFeaturesSection(raw);
+}
+
+/**
+ * Parse the features section from raw config.yaml content.
+ *
+ * @param {string} raw - Raw YAML content
+ * @returns {Record<string, boolean>} Parsed feature flags merged with defaults
+ */
+export function parseFeaturesSection(raw) {
+  const result = { ...DEFAULTS };
+
+  // Find the features: block
+  const featuresMatch = raw.match(/^features:\s*\n((?:\s+\w[\w]*:\s*.+\n?)*)/m);
+  if (!featuresMatch) return result;
+
+  const block = featuresMatch[1];
+
+  // Extract each key: value pair
+  const linePattern = /^\s+(\w[\w]*):\s*(true|false)\s*$/gm;
+  let match;
+  while ((match = linePattern.exec(block)) !== null) {
+    const key = match[1];
+    const value = match[2] === 'true';
+    if (key in result) {
+      result[key] = value;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Get the list of known feature flag names.
+ *
+ * @returns {string[]} Array of feature flag names
+ */
+export function getFeatureNames() {
+  return Object.keys(DEFAULTS);
+}
+
+/**
+ * Get default values for all feature flags.
+ *
+ * @returns {Record<string, boolean>} Default feature flag values
+ */
+export function getDefaults() {
+  return { ...DEFAULTS };
+}

package/src/wizard/i18n.js

@@ -66,9 +66,14 @@ const FALLBACK_EN = {
     quick_start_1: 'Open your IDE',
     quick_start_2: 'Type: /chati',
     quick_start_3: 'The orchestrator will guide you through the process',
-    telemetry_consent: 'Help improve Chati.dev by sharing anonymous usage data?',
-    telemetry_description: 'Anonymous metrics only (agents used, pipeline duration, gate scores). Zero code, files, or personal data. You can disable anytime with: npx chati-dev telemetry disable',
-    telemetry_privacy: 'Privacy: opt-in only, anonymous UUID, no PII collected.',
+    tos_title: 'Terms of Use',
+    tos_summary: 'By continuing, you accept the Chati.dev Terms of Use (see TERMS_OF_USE.md in the package).',
+    tos_telemetry_what: 'Chati.dev collects anonymous usage data: agents used, pipeline duration, gate scores. No code, files, or personal data is collected.',
+    tos_telemetry_optout: 'You can disable telemetry anytime with: npx chati-dev telemetry disable',
+    tos_accept: 'Do you accept the Terms of Use?',
+    tos_declined: 'Terms of Use declined. Installation cancelled.',
+    tos_telemetry_enabled: 'Telemetry: enabled (anonymous, opt-out — disable with: npx chati-dev telemetry disable)',
+    tos_telemetry_disabled: 'Telemetry: disabled',
   },
   agents: {
     starting: 'Starting agent: {agent}',

package/src/wizard/index.js

@@ -3,10 +3,13 @@ import { readFileSync } from 'fs';
 import { join, dirname, basename } from 'path';
 import { fileURLToPath } from 'url';
 import { logBanner } from '../utils/logger.js';
-import { stepLanguage, stepProjectType, stepIDESelection, stepProviderSelection, stepEditorSelection, stepPrimaryProvider, stepConfirmation, stepTelemetryConsent } from './questions.js';
+import { stepLanguage, stepProjectType, stepProviderSelection, stepEditorSelection, stepPrimaryProvider, stepConfirmation, stepTermsOfUse } from './questions.js';
 import { createSpinner, showStep, showValidation, showQuickStart } from './feedback.js';
 import { installFramework } from '../installer/core.js';
 import { validateInstallation } from '../installer/validator.js';
+import { initCollector, track as telemetryTrack, flush as telemetryFlush } from '../telemetry/collector.js';
+import { sendEvents } from '../telemetry/sender.js';
+import { getTelemetryConfig } from '../telemetry/config.js';
 import { t } from './i18n.js';
 import { DEFAULT_MCPS } from '../config/mcp-configs.js';
 import { IDE_CONFIGS, IDE_TO_PROVIDER } from '../config/ide-configs.js';
@@ -33,7 +36,12 @@ export async function runWizard(targetDir, options = {}) {
 
   const language = options.language || await stepLanguage();
 
-  // Step 2: Project Type
+  // Step 2: Terms of Use (must accept to continue)
+  if (options.telemetry === undefined) {
+    await stepTermsOfUse();
+  }
+
+  // Step 3: Project Type
   const projectType = options.projectType || await stepProjectType(targetDir);
 
   // Step 3a: Provider Selection (which AI providers to use)
@@ -73,14 +81,15 @@ export async function runWizard(targetDir, options = {}) {
 
   await stepConfirmation(config);
 
-  // Step 5: Telemetry Consent (opt-in)
-  const telemetryEnabled = options.telemetry !== undefined ? options.telemetry : await stepTelemetryConsent();
-  config.telemetryEnabled = telemetryEnabled;
+  // Telemetry: enabled by default (opt-out model via ToS)
+  config.telemetryEnabled = options.telemetry !== undefined ? options.telemetry : true;
 
-  // Step 5: Installation + Validation
+  // Installation + Validation
   const primaryIDE = selectedIDEs.find(ide => IDE_TO_PROVIDER[ide] === primaryProvider) || selectedIDEs[0];
   const primaryIDEName = IDE_CONFIGS[primaryIDE]?.name || primaryIDE;
 
+  const installStart = Date.now();
+
   console.log();
   const installSpinner = createSpinner(t('installer.installing'));
   installSpinner.start();
@@ -112,9 +121,10 @@ export async function runWizard(targetDir, options = {}) {
     showStep(t('installer.created_memories'));
     showStep(t('installer.installed_intelligence'));
     showStep(`${t('installer.configured_mcps')} ${selectedMCPs.join(', ')}`);
-    if (telemetryEnabled) {
-      showStep('Telemetry: enabled (anonymous, opt-in)');
-    }
+    showStep(config.telemetryEnabled
+      ? t('installer.tos_telemetry_enabled')
+      : t('installer.tos_telemetry_disabled')
+    );
 
     // Validation
     console.log();
@@ -161,6 +171,22 @@ export async function runWizard(targetDir, options = {}) {
 
     showQuickStart(t('installer.quick_start_title'), quickStartSteps);
 
+    // Track installation telemetry
+    initCollector(config.telemetryEnabled);
+    telemetryTrack('installation_completed', {
+      providers: cliProviders,
+      editors: selectedEditors,
+      projectType,
+      language,
+      primaryProvider,
+      installDuration: Date.now() - installStart,
+    });
+    const installEvents = telemetryFlush();
+    if (installEvents.length > 0) {
+      const tConfig = getTelemetryConfig(targetDir);
+      sendEvents(installEvents, { ...tConfig, version: VERSION });
+    }
+
     return { success: true, config, validation };
   } catch (err) {
     installSpinner.stop();

package/src/wizard/questions.js

@@ -295,23 +295,32 @@ export async function stepConfirmation(config) {
 }
 
 /**
- * Step 5: Telemetry Consent (opt-in)
+ * Step: Terms of Use Acceptance
  *
- * Asks the user if they want to share anonymous usage metrics.
- * Returns true (opt-in) or false (opt-out).
+ * Shows Terms of Use that include telemetry data collection notice.
+ * User must accept to proceed. Declining aborts installation.
+ * Telemetry is enabled by default (opt-out model).
  */
-export async function stepTelemetryConsent() {
+export async function stepTermsOfUse() {
   p.note(
-    `${dim(t('installer.telemetry_description'))}\n\n${dim(t('installer.telemetry_privacy'))}`,
-    dim('Telemetry')
+    `${dim(t('installer.tos_summary'))}\n\n` +
+    `${dim(t('installer.tos_telemetry_what'))}\n\n` +
+    `${dim(t('installer.tos_telemetry_optout'))}`,
+    t('installer.tos_title')
   );
 
-  const consent = await p.confirm({
-    message: t('installer.telemetry_consent'),
+  const accepted = await p.confirm({
+    message: t('installer.tos_accept'),
     initialValue: true,
   });
 
-  if (p.isCancel(consent)) return false;
+  if (p.isCancel(accepted) || !accepted) {
+    p.cancel(t('installer.tos_declined'));
+    process.exit(0);
+  }
 
-  return consent;
+  return true;
 }
+
+/** @deprecated Use stepTermsOfUse instead */
+export const stepTelemetryConsent = stepTermsOfUse;