@plexor-dev/claude-code-plugin-staging 0.1.0-beta.26 → 0.1.0-beta.28

package/hooks/track-response.js

@@ -17,7 +17,7 @@
 const path = require('path');
 
 // Use lib modules
-let ConfigManager, SessionManager, LocalCache, Logger, ServerSync;
+let ConfigManager, SessionManager, LocalCache, Logger, ServerSync, SupervisorEmitter;
 try {
   ConfigManager = require('../lib/config');
   SessionManager = require('../lib/session');
@@ -26,6 +26,8 @@ try {
   // Issue #701: Phase 2 - Server sync for persistent session state
   const serverSyncModule = require('../lib/server-sync');
   ServerSync = serverSyncModule.getServerSync;
+  // Phase 1 supervisor UX
+  SupervisorEmitter = require('../lib/supervisor').SupervisorEmitter;
 } catch {
   // Fallback inline implementations if lib not found
   const fs = require('fs');
@@ -171,12 +173,18 @@ try {
     scheduleSync: () => {},
     needsSync: () => false
   });
+
+  // Fallback SupervisorEmitter (no-op)
+  SupervisorEmitter = class {
+    emit() {}
+  };
 }
 
 const logger = new Logger('track-response');
 const config = new ConfigManager();
 const cache = new LocalCache();
 const session = new SessionManager();
+const supervisor = new SupervisorEmitter();
 
 // Issue #701: Phase 2 - Initialize server sync (lazy, initialized on first use)
 let serverSync = null;
@@ -189,7 +197,7 @@ async function getServerSync() {
     if (settings.apiKey && settings.enabled) {
       serverSync = ServerSync({
         apiKey: settings.apiKey,
-        baseUrl: settings.apiUrl || 'https://api.plexor.dev',
+        baseUrl: settings.apiUrl || 'http://127.0.0.1:8000',
         enabled: settings.serverSyncEnabled !== false
       });
     } else {
@@ -221,6 +229,12 @@ async function main() {
     const plexorMeta = response._plexor;
     emitPlexorOutcomeSummary(response, plexorMeta, outputTokens);
 
+    // Phase 1 supervisor UX: concise single-line routing summary
+    supervisor.emit(response, plexorMeta);
+
+    // Proactive compact warning: check prompt token count against provider limits
+    emitCompactWarning(response, plexorMeta);
+
     // Issue #701: Track ALL responses, not just when enabled
     // This ensures session stats are always accurate
     if (plexorMeta) {
@@ -674,3 +688,29 @@ function emitPlexorOutcomeSummary(response, plexorMeta, outputTokens) {
     logger.ux(msg);
   }
 }
+
+/**
+ * Proactive compact warning: emit context-size alerts at 70K and 80K prompt tokens.
+ * Uses the per-request prompt token count (usage.input_tokens / usage.prompt_tokens)
+ * which represents the current context window size for that call.
+ */
+function emitCompactWarning(response, plexorMeta) {
+  if (!logger || typeof logger.ux !== 'function') return;
+
+  const promptTokens =
+    toNumber(response?.plexor_prompt_tokens) ??
+    toNumber(response?.usage?.input_tokens) ??
+    toNumber(response?.usage?.prompt_tokens) ??
+    toNumber(plexorMeta?.optimized_tokens) ??
+    null;
+
+  if (promptTokens === null || promptTokens < 70000) return;
+
+  const tokensK = Math.round(promptTokens / 1000);
+
+  if (promptTokens >= 80000) {
+    logger.ux(`\u26a0 Context at ${tokensK}K tokens \u2014 recommend /compact to prevent errors`);
+  } else {
+    logger.ux(`Context at ${tokensK}K tokens \u2014 approaching provider limits`);
+  }
+}

package/lib/supervisor.js

@@ -0,0 +1,423 @@
+/**
+ * Plexor Supervisor Emitter — Phases 1-5
+ *
+ * Phase 1: Basic routing summary
+ *   [PLEXOR: Routed to {provider}/{model}, {latency}ms, {routing_source}]
+ *
+ * Phase 2: Enhanced routing with cohort from response body fields
+ *   [PLEXOR: {provider}/{model}, {latency}ms, {source} | {cohort}]
+ *
+ * Phase 3: Zero-tool escalation detection (agent_halt / escalation signals)
+ *   [PLEXOR: Zero-tool escalation: {provider1} → {provider2}]
+ *
+ * Phase 4: Scaffolding gate blocked detection
+ *   [PLEXOR: Scaffolding gate: {model} blocked, using {alternative}]
+ *
+ * Phase 5: Session narration — cumulative tokens, cost, provider reliability,
+ *   context warnings, auto-compact suggestions
+ *   [PLEXOR: Session: 12 turns, $0.42 cost, 45K tokens]
+ *   [PLEXOR: Provider reliability (last 5): DeepSeek 4/5 tool_calls, Gemini 1/5]
+ *   [PLEXOR: Context at 72K tokens — approaching provider limits]
+ *   [PLEXOR: Context at 82K — recommend /compact to prevent errors]
+ *
+ * This module is consumed by track-response.js to surface routing
+ * decisions to the developer without requiring them to parse verbose logs.
+ */
+
+const CYAN = '\x1b[36m';
+const YELLOW = '\x1b[33m';
+const RED = '\x1b[31m';
+const MAGENTA = '\x1b[35m';
+const RESET = '\x1b[0m';
+
+const CONTEXT_WARNING_THRESHOLD = 70000;
+const CONTEXT_COMPACT_THRESHOLD = 80000;
+
+class SupervisorEmitter {
+  /**
+   * @param {object} [opts]
+   * @param {boolean} [opts.enabled] — honour PLEXOR_SUPERVISOR env var (default true)
+   */
+  constructor(opts = {}) {
+    const envFlag = process.env.PLEXOR_SUPERVISOR;
+    if (envFlag !== undefined) {
+      this.enabled = !/^(0|false|no|off)$/i.test(String(envFlag));
+    } else {
+      this.enabled = opts.enabled !== false;
+    }
+
+    // Phase 5: Session-level state
+    this._turnCount = 0;
+    this._cumulativeTokens = 0;
+    this._cumulativeCost = 0;
+    this._providerHistory = []; // last N entries: { provider, hadToolCalls }
+  }
+
+  /**
+   * Build the Phase 2 enhanced supervisor summary from a gateway response.
+   * Reads plexor_provider_used, plexor_selected_model, plexor_latency_ms,
+   * plexor_routing_source from the response body (not just headers).
+   *
+   * Format: [PLEXOR: provider/model, latencyms, source | cohort]
+   *
+   * @param {object} response  — the full LLM response object
+   * @param {object} [plexorMeta] — the _plexor metadata block (may be absent)
+   * @returns {string|null}
+   */
+  buildSummary(response, plexorMeta) {
+    if (!response || typeof response !== 'object') {
+      return null;
+    }
+
+    const provider = this._resolveProvider(response, plexorMeta);
+    const model = this._resolveModel(response, plexorMeta);
+    const latencyMs = this._resolveLatency(response, plexorMeta);
+    const routingSource = this._resolveRoutingSource(response, plexorMeta);
+    const cohort = this._resolveCohort(response, plexorMeta);
+
+    // Need at least provider or model to emit anything useful
+    if (!provider && !model) {
+      return null;
+    }
+
+    const target = [provider, model].filter(Boolean).join('/');
+    const parts = [target];
+
+    if (latencyMs !== null) {
+      parts.push(`${latencyMs}ms`);
+    }
+
+    if (routingSource) {
+      parts.push(routingSource);
+    }
+
+    let line = parts.join(', ');
+
+    if (cohort) {
+      line += ` | ${cohort}`;
+    }
+
+    return `[PLEXOR: ${line}]`;
+  }
+
+  /**
+   * Phase 3: Detect zero-tool escalation signals in the response.
+   * Fires when agent_halt is set or escalation_chain / fallback provider data
+   * indicates a provider switch due to tool incapability.
+   *
+   * @param {object} response
+   * @param {object} [plexorMeta]
+   * @returns {string|null} — escalation message or null
+   */
+  buildEscalationNotice(response, plexorMeta) {
+    if (!response || typeof response !== 'object') {
+      return null;
+    }
+
+    const agentHalt = this._toBool(
+      response?.plexor_agent_halt ??
+      response?.plexor?.agent_halt ??
+      plexorMeta?.agent_halt
+    );
+
+    const escalationChain =
+      response?.plexor_escalation_chain ||
+      response?.plexor?.escalation_chain ||
+      plexorMeta?.escalation_chain ||
+      null;
+
+    const fallbackUsed = this._toBool(
+      response?.plexor_fallback_used ??
+      response?.fallback_used ??
+      response?.plexor?.fallback_used
+    );
+
+    const originalProvider =
+      response?.plexor_original_provider ||
+      response?.plexor?.original_provider ||
+      plexorMeta?.original_provider ||
+      null;
+
+    const currentProvider = this._resolveProvider(response, plexorMeta);
+
+    // Case 1: Explicit escalation chain present (e.g., ["openai-mini", "openai"])
+    if (Array.isArray(escalationChain) && escalationChain.length >= 2) {
+      const from = escalationChain[0];
+      const to = escalationChain[escalationChain.length - 1];
+      return `[PLEXOR: Zero-tool escalation: ${from} \u2192 ${to}]`;
+    }
+
+    // Case 2: agent_halt with fallback — provider switched
+    if (agentHalt && fallbackUsed && originalProvider && currentProvider && originalProvider !== currentProvider) {
+      return `[PLEXOR: Zero-tool escalation: ${originalProvider} \u2192 ${currentProvider}]`;
+    }
+
+    // Case 3: agent_halt alone (escalation happened but we may not know the full chain)
+    if (agentHalt && fallbackUsed) {
+      const from = originalProvider || 'original';
+      const to = currentProvider || 'fallback';
+      return `[PLEXOR: Zero-tool escalation: ${from} \u2192 ${to}]`;
+    }
+
+    return null;
+  }
+
+  /**
+   * Phase 4: Detect scaffolding gate blocks.
+   * Fires when scaffolding_gate_blocked is present in the response,
+   * indicating a model was blocked by the scaffolding gate and an
+   * alternative was used.
+   *
+   * @param {object} response
+   * @param {object} [plexorMeta]
+   * @returns {string|null}
+   */
+  buildScaffoldingGateNotice(response, plexorMeta) {
+    if (!response || typeof response !== 'object') {
+      return null;
+    }
+
+    const gateBlocked = this._toBool(
+      response?.plexor_scaffolding_gate_blocked ??
+      response?.scaffolding_gate_blocked ??
+      response?.plexor?.scaffolding_gate_blocked ??
+      plexorMeta?.scaffolding_gate_blocked
+    );
+
+    if (!gateBlocked) {
+      return null;
+    }
+
+    const blockedModel =
+      response?.plexor_scaffolding_blocked_model ||
+      response?.plexor?.scaffolding_blocked_model ||
+      plexorMeta?.scaffolding_blocked_model ||
+      response?.plexor_original_model ||
+      response?.plexor?.original_model ||
+      plexorMeta?.original_model ||
+      'model';
+
+    const alternative =
+      response?.plexor_selected_model ||
+      response?.plexor?.selected_model ||
+      plexorMeta?.recommended_model ||
+      response?.model ||
+      'alternative';
+
+    return `[PLEXOR: Scaffolding gate: ${blockedModel} blocked, using ${alternative}]`;
+  }
+
+  /**
+   * Emit all applicable supervisor lines to stderr if enabled.
+   *
+   * @param {object} response
+   * @param {object} [plexorMeta]
+   */
+  emit(response, plexorMeta) {
+    if (!this.enabled) {
+      return;
+    }
+
+    // Phase 5: Accumulate session state before emitting
+    this._accumulateSessionState(response, plexorMeta);
+
+    // Phase 4: Scaffolding gate (highest priority — emit first if present)
+    const scaffoldingNotice = this.buildScaffoldingGateNotice(response, plexorMeta);
+    if (scaffoldingNotice) {
+      process.stderr.write(`${RED}${scaffoldingNotice}${RESET}\n`);
+    }
+
+    // Phase 3: Escalation notice
+    const escalationNotice = this.buildEscalationNotice(response, plexorMeta);
+    if (escalationNotice) {
+      process.stderr.write(`${YELLOW}${escalationNotice}${RESET}\n`);
+    }
+
+    // Phase 2: Enhanced routing summary (always emitted when data available)
+    const summary = this.buildSummary(response, plexorMeta);
+    if (summary) {
+      process.stderr.write(`${CYAN}${summary}${RESET}\n`);
+    }
+
+    // Phase 5: Session narration (after per-turn messages)
+    this._emitSessionNarration();
+  }
+
+  // ---- Phase 5: session narration ----
+
+  /**
+   * Accumulate per-turn data into session state.
+   * Called at the start of emit() so all session fields are current
+   * before any Phase 5 messages are built.
+   */
+  _accumulateSessionState(response, plexorMeta) {
+    this._turnCount++;
+
+    // Cumulative token counter — read prompt_tokens from usage block
+    const usage = response?.usage || response?.plexor?.usage || {};
+    const promptTokens = Number(usage.prompt_tokens) || 0;
+    const completionTokens = Number(usage.completion_tokens) || 0;
+    this._cumulativeTokens += promptTokens + completionTokens;
+
+    // Cumulative cost
+    const costUsd = Number(
+      response?.plexor_cost_usd ??
+      response?.plexor?.cost_usd ??
+      plexorMeta?.cost_usd ??
+      0
+    );
+    if (Number.isFinite(costUsd)) {
+      this._cumulativeCost += costUsd;
+    }
+
+    // Provider reliability tracking
+    const provider = this._resolveProvider(response, plexorMeta);
+    if (provider) {
+      const stopReason =
+        response?.stop_reason ||
+        response?.choices?.[0]?.finish_reason ||
+        response?.plexor?.stop_reason ||
+        null;
+      this._providerHistory.push({
+        provider,
+        hadToolCalls: stopReason === 'tool_use' || stopReason === 'tool_calls',
+      });
+    }
+  }
+
+  /**
+   * Emit session-level narration lines based on accumulated state.
+   */
+  _emitSessionNarration() {
+    // Session summary line — every turn
+    const tokenStr = this._formatTokenCount(this._cumulativeTokens);
+    const costStr = this._cumulativeCost < 0.01
+      ? `$${this._cumulativeCost.toFixed(4)}`
+      : `$${this._cumulativeCost.toFixed(2)}`;
+    process.stderr.write(
+      `${MAGENTA}[PLEXOR: Session: ${this._turnCount} turns, ${costStr} cost, ${tokenStr} tokens]${RESET}\n`
+    );
+
+    // Provider reliability digest — every 5th turn
+    if (this._turnCount % 5 === 0 && this._providerHistory.length > 0) {
+      const digest = this._buildProviderReliabilityDigest();
+      if (digest) {
+        process.stderr.write(`${MAGENTA}${digest}${RESET}\n`);
+      }
+    }
+
+    // Context warning at 70K tokens
+    if (this._cumulativeTokens >= CONTEXT_COMPACT_THRESHOLD) {
+      const kTokens = Math.round(this._cumulativeTokens / 1000);
+      process.stderr.write(
+        `${YELLOW}[PLEXOR: Context at ${kTokens}K \u2014 recommend /compact to prevent errors]${RESET}\n`
+      );
+    } else if (this._cumulativeTokens >= CONTEXT_WARNING_THRESHOLD) {
+      const kTokens = Math.round(this._cumulativeTokens / 1000);
+      process.stderr.write(
+        `${YELLOW}[PLEXOR: Context at ${kTokens}K tokens \u2014 approaching provider limits]${RESET}\n`
+      );
+    }
+  }
+
+  /**
+   * Build provider reliability digest from the last 5 entries in history.
+   * Format: [PLEXOR: Provider reliability (last 5): DeepSeek 4/5 tool_calls, Gemini 1/5]
+   */
+  _buildProviderReliabilityDigest() {
+    const recent = this._providerHistory.slice(-5);
+    const totals = {};
+    const toolHits = {};
+
+    for (const entry of recent) {
+      const p = entry.provider;
+      totals[p] = (totals[p] || 0) + 1;
+      if (entry.hadToolCalls) {
+        toolHits[p] = (toolHits[p] || 0) + 1;
+      }
+    }
+
+    const parts = Object.keys(totals).map(p => {
+      const hits = toolHits[p] || 0;
+      return `${p}: ${hits}/${totals[p]} tool_calls`;
+    });
+
+    if (parts.length === 0) return null;
+    return `[PLEXOR: Provider reliability (last 5): ${parts.join(', ')}]`;
+  }
+
+  /**
+   * Format token count: 1234 -> "1.2K", 123456 -> "123K"
+   */
+  _formatTokenCount(tokens) {
+    if (tokens < 1000) return String(tokens);
+    if (tokens < 10000) return `${(tokens / 1000).toFixed(1)}K`;
+    return `${Math.round(tokens / 1000)}K`;
+  }
+
+  // ---- Phase 5 accessors (for testing) ----
+
+  get turnCount() { return this._turnCount; }
+  get cumulativeTokens() { return this._cumulativeTokens; }
+  get cumulativeCost() { return this._cumulativeCost; }
+
+  // ---- private helpers ----
+
+  _resolveProvider(response, meta) {
+    return (
+      response?.plexor_provider_used ||
+      response?.plexor?.provider_used ||
+      meta?.recommended_provider ||
+      null
+    );
+  }
+
+  _resolveModel(response, meta) {
+    return (
+      response?.plexor_selected_model ||
+      response?.plexor?.selected_model ||
+      meta?.recommended_model ||
+      response?.model ||
+      null
+    );
+  }
+
+  _resolveLatency(response, meta) {
+    const raw =
+      response?.plexor_latency_ms ??
+      response?.plexor?.latency_ms ??
+      meta?.latency_ms ??
+      null;
+    if (raw === null || raw === undefined) {
+      return null;
+    }
+    const n = Number(raw);
+    return Number.isFinite(n) ? Math.round(n) : null;
+  }
+
+  _resolveRoutingSource(response, meta) {
+    return (
+      response?.plexor_routing_source ||
+      response?.plexor?.routing_source ||
+      meta?.source ||
+      null
+    );
+  }
+
+  _resolveCohort(response, meta) {
+    return (
+      response?.plexor_cohort ||
+      response?.plexor?.cohort ||
+      meta?.cohort ||
+      null
+    );
+  }
+
+  _toBool(value) {
+    if (value === true || value === 'true' || value === '1' || value === 1) return true;
+    if (value === false || value === 'false' || value === '0' || value === 0) return false;
+    return null;
+  }
+}
+
+module.exports = { SupervisorEmitter };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plexor-dev/claude-code-plugin-staging",
-  "version": "0.1.0-beta.26",
+  "version": "0.1.0-beta.28",
   "description": "STAGING - LLM cost optimization plugin for Claude Code (internal testing)",
   "main": "lib/constants.js",
   "bin": {