chati-dev 3.2.5 → 3.3.0

package/src/terminal/prompt-builder.js

@@ -13,6 +13,9 @@ import { join } from 'path';
 import { runPrism } from '../context/engine.js';
 import { loadHandoff, formatHandoff } from '../tasks/handoff.js';
 import { getWriteScope } from './isolation.js';
+import { resolveOverlayPath } from '../installer/provider-overlay.js';
+import { resolveProviderForAgent } from './cli-registry.js';
+import { buildCompactGotchasSummary } from '../memory/gotchas-injector.js';
 
 // Import AGENT_MODELS from model-governance (safe — named export,
 // does not trigger main() which is guarded by fileURLToPath check).
@@ -46,6 +49,7 @@ export const AGENT_FILE_MAP = {
  * @property {object} [sessionState]  - Parsed session.yaml fields
  * @property {string[]} [writeScope]  - Override write scope
  * @property {string} [additionalContext] - Extra context (e.g. user answer to needs_input)
+ * @property {string} [provider] - Active CLI provider (for overlay resolution)
  */
 
 /**
@@ -70,8 +74,8 @@ export function buildAgentPrompt(config) {
     sections.push(prismResult.xml);
   }
 
-  // 2. Agent definition (.md file)
-  const agentDef = loadAgentDefinition(config.agent, config.projectDir);
+  // 2. Agent definition (.md file — resolved via overlay for secondary providers)
+  const agentDef = loadAgentDefinition(config.agent, config.projectDir, config.provider);
   if (agentDef) {
     sections.push('<!-- AGENT DEFINITION -->\n' + agentDef);
   }
@@ -82,7 +86,20 @@ export function buildAgentPrompt(config) {
     sections.push(handoffSection);
   }
 
-  // 4. Additional context (user input relay for needs_input)
+  // 4. Gotchas (relevant past errors)
+  try {
+    const gotchasSection = buildCompactGotchasSummary(config.projectDir, {
+      agent: config.agent,
+      task: config.taskId,
+    });
+    if (gotchasSection) {
+      sections.push('<!-- GOTCHAS -->\n' + gotchasSection);
+    }
+  } catch {
+    // Gotchas are advisory — never block prompt building
+  }
+
+  // 5. Additional context (user input relay for needs_input)
   if (config.additionalContext) {
     sections.push(
       '<!-- ADDITIONAL CONTEXT -->\n' +
@@ -91,23 +108,29 @@ export function buildAgentPrompt(config) {
     );
   }
 
-  // 5. Write scope instructions
+  // 6. Write scope instructions
   sections.push(buildWriteScopeSection(config));
 
-  // 6. Session context
-  sections.push(buildSessionSection(config));
+  // 7. Resolve provider/model (needed by session context AND output instructions)
+  const staticAssignment = AGENT_MODELS[config.agent] || { provider: 'claude', model: 'sonnet', tier: 'sonnet' };
+  const resolved = (config.projectDir && AGENT_MODELS[config.agent])
+    ? resolveProviderForAgent(config.agent, config.projectDir, AGENT_MODELS)
+    : { provider: staticAssignment.provider, model: staticAssignment.model };
+  const resolvedProvider = config.provider || resolved.provider || 'claude';
+  const model = config.model || resolved.model || staticAssignment.model || 'sonnet';
+
+  // 8. Session context (uses resolved model/provider)
+  sections.push(buildSessionSection(config, { model, provider: resolvedProvider }));
 
-  // 7. Output format instructions (handoff template)
-  sections.push(buildOutputInstructions());
+  // 9. Output format instructions (handoff template — includes provider/model for audit)
+  sections.push(buildOutputInstructions({ provider: resolvedProvider, model }));
 
   const prompt = sections.join('\n\n---\n\n');
-  const assignment = AGENT_MODELS[config.agent] || { provider: 'claude', model: 'sonnet', tier: 'sonnet' };
-  const model = assignment.model || assignment;
 
   return {
     prompt,
     model,
-    provider: assignment.provider || 'claude',
+    provider: resolvedProvider,
     metadata: {
       agent: config.agent,
       layers: prismResult.layerCount || 0,
@@ -163,14 +186,23 @@ function buildPrismSection(config) {
 
 /**
  * Load the agent's full .md definition file.
+ * For non-primary providers, resolves via overlay directory.
  */
-function loadAgentDefinition(agent, projectDir) {
+function loadAgentDefinition(agent, projectDir, provider = null) {
   const relativePath = AGENT_FILE_MAP[agent];
   if (!relativePath) return null;
 
-  const fullPath = join(projectDir, relativePath);
-  if (!existsSync(fullPath)) return null;
+  // Strip 'chati.dev/' prefix for overlay resolution
+  const relToFramework = relativePath.replace(/^chati\.dev\//, '');
+
+  let fullPath;
+  if (provider && provider !== 'claude') {
+    fullPath = resolveOverlayPath(projectDir, relToFramework, provider);
+  } else {
+    fullPath = join(projectDir, relativePath);
+  }
 
+  if (!existsSync(fullPath)) return null;
   return readFileSync(fullPath, 'utf-8');
 }
 
@@ -238,7 +270,7 @@ function buildWriteScopeSection(config) {
 /**
  * Build session context section.
  */
-function buildSessionSection(config) {
+function buildSessionSection(config, resolvedModelInfo = {}) {
   const state = config.sessionState || {};
   const project = state.project || {};
 
@@ -253,8 +285,8 @@ function buildSessionSection(config) {
     `- **User Level**: ${state.user_level || 'auto'}`,
     `- **Execution Mode**: ${state.execution_mode || 'autonomous'}`,
     `- **Your Agent**: ${config.agent}`,
-    `- **Your Model**: ${(AGENT_MODELS[config.agent]?.model) || 'sonnet'}`,
-    `- **Your Provider**: ${(AGENT_MODELS[config.agent]?.provider) || 'claude'}`,
+    `- **Your Model**: ${resolvedModelInfo.model || 'sonnet'}`,
+    `- **Your Provider**: ${resolvedModelInfo.provider || 'claude'}`,
   ];
 
   return lines.join('\n');
@@ -263,7 +295,10 @@ function buildSessionSection(config) {
 /**
  * Build output format instructions so the agent produces a parseable handoff.
  */
-function buildOutputInstructions() {
+function buildOutputInstructions(config) {
+  const providerValue = config?.provider || 'claude';
+  const modelValue = config?.model || 'unknown';
+
   return `<!-- OUTPUT INSTRUCTIONS -->
 ## Output Instructions (MANDATORY)
 
@@ -274,6 +309,8 @@ This block is how the orchestrator reads your results. Without it, your work can
 <chati-handoff>
 status: complete
 score: 95
+provider: ${providerValue}
+model: ${modelValue}
 summary: One to three sentence summary of what was accomplished.
 outputs:
   - path/to/artifact1.md
@@ -297,5 +334,6 @@ needs_input_question: null
 - The \`<chati-handoff>\` block MUST appear in your response
 - Score must be 0-100 (95+ to pass quality gate)
 - List ALL artifacts you created/modified in outputs
+- The \`provider\` and \`model\` fields MUST match: provider: ${providerValue}, model: ${modelValue}
 - If you need user input, set status to "needs_input" and write your question in needs_input_question`;
 }

package/src/terminal/rate-limiter.js

@@ -0,0 +1,172 @@
+/**
+ * @fileoverview Rate limiting for terminal spawner.
+ *
+ * Prevents exceeding API rate limits when spawning multiple agent
+ * processes. Uses a sliding window counter per provider.
+ *
+ * Constitution Article XIX — Multi-CLI Governance.
+ */
+
+// ---------------------------------------------------------------------------
+// Default Limits
+// ---------------------------------------------------------------------------
+
+/**
+ * Default rate limits per provider (requests per minute).
+ * Conservative defaults — can be overridden at creation time.
+ */
+export const DEFAULT_LIMITS = {
+  claude: 20,
+  gemini: 15,
+  codex: 10,
+  copilot: 10,
+};
+
+/** Sliding window size in milliseconds (1 minute). */
+const WINDOW_MS = 60_000;
+
+// ---------------------------------------------------------------------------
+// RateLimiter Class
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {object} RateLimiterStats
+ * @property {number} used - Requests used in current window
+ * @property {number} limit - Maximum requests per window
+ * @property {number} windowStart - Window start timestamp (ms)
+ * @property {number|null} nextAvailable - Timestamp when next slot opens (null if available now)
+ * @property {string} provider - Provider name
+ */
+
+/**
+ * Create a rate limiter instance for a specific provider.
+ *
+ * @param {string} provider - Provider name (claude, gemini, codex, copilot)
+ * @param {{ limit?: number }} [customLimits={}]
+ * @returns {{ canSpawn: () => boolean, recordSpawn: () => void, waitForSlot: () => Promise<void>, getStats: () => RateLimiterStats, reset: () => void }}
+ */
+export function createRateLimiter(provider, customLimits = {}) {
+  const limit = customLimits.limit || DEFAULT_LIMITS[provider] || 10;
+
+  /** @type {number[]} Timestamps of recorded spawns */
+  let timestamps = [];
+
+  /**
+   * Prune timestamps outside the sliding window.
+   */
+  function prune() {
+    const cutoff = Date.now() - WINDOW_MS;
+    timestamps = timestamps.filter(t => t > cutoff);
+  }
+
+  /**
+   * Check if a spawn is allowed under current rate limits.
+   * @returns {boolean}
+   */
+  function canSpawn() {
+    prune();
+    return timestamps.length < limit;
+  }
+
+  /**
+   * Record a spawn event.
+   */
+  function recordSpawn() {
+    timestamps.push(Date.now());
+  }
+
+  /**
+   * Wait until a rate limit slot becomes available.
+   * Resolves immediately if a slot is available.
+   *
+   * @returns {Promise<void>}
+   */
+  function waitForSlot() {
+    if (canSpawn()) {
+      return Promise.resolve();
+    }
+
+    // Calculate when the oldest timestamp exits the window
+    prune();
+    if (timestamps.length === 0) {
+      return Promise.resolve();
+    }
+
+    const oldestInWindow = timestamps[0];
+    const waitTime = Math.max(0, (oldestInWindow + WINDOW_MS) - Date.now() + 10);
+
+    return new Promise(resolve => {
+      setTimeout(() => {
+        prune();
+        resolve();
+      }, waitTime);
+    });
+  }
+
+  /**
+   * Get current rate limiter statistics.
+   * @returns {RateLimiterStats}
+   */
+  function getStats() {
+    prune();
+
+    const now = Date.now();
+    const windowStart = now - WINDOW_MS;
+
+    let nextAvailable = null;
+    if (timestamps.length >= limit && timestamps.length > 0) {
+      nextAvailable = timestamps[0] + WINDOW_MS;
+    }
+
+    return {
+      used: timestamps.length,
+      limit,
+      windowStart,
+      nextAvailable,
+      provider,
+    };
+  }
+
+  /**
+   * Reset the rate limiter (clear all recorded timestamps).
+   */
+  function reset() {
+    timestamps = [];
+  }
+
+  return { canSpawn, recordSpawn, waitForSlot, getStats, reset };
+}
+
+// ---------------------------------------------------------------------------
+// Global Registry
+// ---------------------------------------------------------------------------
+
+/** @type {Map<string, ReturnType<typeof createRateLimiter>>} */
+const _registry = new Map();
+
+/**
+ * Get or create a rate limiter for a provider.
+ * Ensures one limiter per provider across the application.
+ *
+ * @param {string} provider - Provider name
+ * @param {{ limit?: number }} [customLimits={}]
+ * @returns {ReturnType<typeof createRateLimiter>}
+ */
+export function getRateLimiter(provider, customLimits = {}) {
+  if (!_registry.has(provider)) {
+    _registry.set(provider, createRateLimiter(provider, customLimits));
+  }
+  return _registry.get(provider);
+}
+
+/**
+ * Clear all registered rate limiters (useful in tests).
+ */
+export function clearAllLimiters() {
+  _registry.clear();
+}
+
+/**
+ * Exported for testing.
+ */
+export { WINDOW_MS };

package/src/terminal/run-agent.js

@@ -17,6 +17,8 @@ import { fileURLToPath } from 'url';
 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';
 
 // ---------------------------------------------------------------------------
 // CLI argument parsing (no external deps)
@@ -85,6 +87,7 @@ async function main() {
       workflow: args.workflow || null,
       sessionState,
       additionalContext: args['additional-context'] || null,
+      provider: args.provider || null,
     });
   } catch (err) {
     outputError(`Failed to build prompt: ${err.message}`);
@@ -100,6 +103,7 @@ async function main() {
       agent: args.agent,
       taskId: args['task-id'],
       model: promptResult.model,
+      provider: promptResult.provider,
       prompt: promptResult.prompt,
       workingDir: projectDir,
       timeout,
@@ -121,6 +125,37 @@ async function main() {
   const stdout = handle.stdout.join('');
   const stderr = handle.stderr.join('');
 
+  // Track cost metrics
+  const tracker = createCostTracker();
+  const costRecord = tracker.recordExecution({
+    agent: args.agent,
+    model: promptResult.model,
+    provider: promptResult.provider || args.provider || 'claude',
+    taskId: args['task-id'],
+    inputText: promptResult.prompt || '',
+    outputText: stdout,
+    duration: elapsed,
+  });
+
+  const costEstimate = {
+    inputTokens: costRecord.inputTokens,
+    outputTokens: costRecord.outputTokens,
+    totalCost: costRecord.cost,
+    model: costRecord.model,
+    provider: costRecord.provider,
+  };
+
+  // Track telemetry (fire-and-forget, non-blocking)
+  telemetryTrack('agent_completed', {
+    agent: args.agent,
+    provider: costRecord.provider,
+    model: costRecord.model,
+    duration: elapsed,
+    score: null, // Score is determined by the gate, not the agent
+    retryCount: 0,
+    pipelineType: sessionState?.isQuickFlow ? 'quick-flow' : 'standard',
+  });
+
   // Parse the handoff from stdout
   const parsed = parseAgentOutput(stdout);
 
@@ -129,9 +164,11 @@ async function main() {
       status: parsed.handoff.status,
       agent: args.agent,
       model: promptResult.model,
+      provider: promptResult.provider || args.provider || 'claude',
       exitCode: handle.exitCode,
       handoff: parsed.handoff,
       elapsed,
+      costEstimate,
     });
   } else {
     // No handoff block found — return raw output
@@ -139,11 +176,13 @@ async function main() {
       status: handle.exitCode === 0 ? 'partial' : 'error',
       agent: args.agent,
       model: promptResult.model,
+      provider: promptResult.provider || args.provider || 'claude',
       exitCode: handle.exitCode,
       handoff: null,
       rawOutput: stdout.slice(0, 5000), // Truncate to avoid huge JSON
       stderr: stderr.slice(0, 2000),
       elapsed,
+      costEstimate,
     });
   }
 

package/src/terminal/run-parallel.js

@@ -20,6 +20,7 @@ import { spawnParallelGroup } 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';
 
 // ---------------------------------------------------------------------------
 // CLI argument parsing
@@ -100,12 +101,14 @@ async function main() {
         projectDir,
         previousAgent,
         sessionState,
+        provider: args.provider || null,
       });
 
       configs.push({
         agent: agents[i],
         taskId: taskIds[i],
         model: promptResult.model,
+        provider: promptResult.provider,
         prompt: promptResult.prompt,
         workingDir: projectDir,
         timeout,
@@ -150,6 +153,23 @@ async function main() {
 
   const elapsed = Date.now() - startTime;
 
+  // Cost estimation per agent
+  const costEstimates = configs.map((cfg, i) => {
+    const terminal = group.terminals[i];
+    const inputTokens = estimateTokens(cfg.prompt || '');
+    const outputTokens = estimateTokens((terminal?.stdout || []).join(''));
+    const modelKey = cfg.model || 'sonnet';
+    const rate = COST_PER_1K[modelKey] || COST_PER_1K.sonnet || 0.015;
+    return {
+      agent: cfg.agent,
+      model: modelKey,
+      provider: cfg.provider || 'claude',
+      inputTokens,
+      outputTokens,
+      estimatedCost: ((inputTokens + outputTokens) / 1000) * rate,
+    };
+  });
+
   // Collect and merge results
   const rawResults = collectResults(group.groupId, group.terminals);
 
@@ -197,6 +217,7 @@ async function main() {
       parallelActual: elapsed,
       timeSaved: elapsed * (agents.length - 1),
     },
+    costEstimate: costEstimates,
   };
 
   process.stdout.write(JSON.stringify(output, null, 2) + '\n');
@@ -213,7 +234,7 @@ async function main() {
  * GROUP 2 (dev tasks) → qa-implementation
  */
 function determineNextAgent(agents) {
-  const groupKey = agents.sort().join(',');
+  const groupKey = [...agents].sort().join(',');
   if (groupKey.includes('architect') && groupKey.includes('detail') && groupKey.includes('ux')) {
     return 'phases';
   }