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

package/lib/supervisor.js

@@ -0,0 +1,282 @@
+/**
+ * Plexor Supervisor Emitter — Phases 1-4
+ *
+ * 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}]
+ *
+ * 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 RESET = '\x1b[0m';
+
+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;
+    }
+  }
+
+  /**
+   * 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 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`);
+    }
+  }
+
+  // ---- 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.27",
   "description": "STAGING - LLM cost optimization plugin for Claude Code (internal testing)",
   "main": "lib/constants.js",
   "bin": {