smart-context-mcp 1.6.2 → 1.7.1

package/README.md

@@ -52,9 +52,9 @@ Restart your AI client. Done.
 
 ---
 
-## `1.6.0` Task Runner
+## Task Runner
 
-`1.6.0` adds `smart-context-task`, a workflow-oriented CLI on top of the raw MCP tools.
+`smart-context-task` is a workflow-oriented CLI on top of the raw MCP tools.
 
 Use it when you want a more repeatable path than “agent reads rules and hopefully picks the right flow”.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smart-context-mcp",
-  "version": "1.6.2",
+  "version": "1.7.1",
   "description": "MCP server that reduces agent token usage by 90% with intelligent context compression, task checkpoint persistence, and workflow-aware agent guidance.",
   "author": "Francisco Caballero Portero <fcp1978@hotmail.com>",
   "type": "module",

package/scripts/headless-wrapper.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { runHeadlessWrapper } from '../src/orchestration/headless-wrapper.js';
+import { detectClient } from '../src/utils/client-detection.js';
 
 const requireValue = (argv, index, flag) => {
   const value = argv[index + 1];
@@ -11,7 +12,7 @@ const requireValue = (argv, index, flag) => {
 
 const parseArgs = (argv) => {
   const options = {
-    client: 'generic',
+    client: null,
     prompt: '',
     sessionId: undefined,
     event: undefined,

package/scripts/report-metrics.js

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { smartMetrics } from '../src/tools/smart-metrics.js';
 import { formatAdoptionReport } from '../src/analytics/adoption.js';
-import { formatProductQualityReport } from '../src/analytics/product-quality.js';
+import { formatProductQualityReport, hasProductQualitySignals } from '../src/analytics/product-quality.js';
 
 const requireValue = (argv, index, flag) => {
   const value = argv[index + 1];
@@ -101,7 +101,7 @@ const printHuman = (report) => {
     console.log(formatAdoptionReport(report.adoption));
   }
 
-  if (report.productQuality?.turnsMeasured > 0) {
+  if (hasProductQualitySignals(report.productQuality)) {
     console.log(formatProductQualityReport(report.productQuality));
   }
 };

package/scripts/task-runner.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { runTaskRunner } from '../src/task-runner.js';
 import { checkNodeVersion } from '../src/utils/runtime-check.js';
+import { detectClient } from '../src/utils/client-detection.js';
 
 const runtimeCheck = checkNodeVersion();
 if (!runtimeCheck.ok) {
@@ -28,7 +29,7 @@ const parseArgs = (argv) => {
   const rest = argv[0] && !argv[0].startsWith('--') ? argv.slice(1) : argv;
   const options = {
     commandName: subcommand,
-    client: 'generic',
+    client: null,
     prompt: '',
     sessionId: undefined,
     event: undefined,

package/src/analytics/product-quality.js

@@ -12,6 +12,139 @@ const isTaskRunnerQualityEntry = (entry) =>
   entry?.tool === 'task_runner'
   && entry?.metadata?.analyticsKind === TASK_RUNNER_QUALITY_ANALYTICS_KIND;
 
+const roundAverage = (total, count) =>
+  count > 0 ? Number((total / count).toFixed(1)) : 0;
+
+const getMetricsClient = (entry) =>
+  entry?.metadata?.adapterClient
+  ?? entry?.metadata?.client
+  ?? null;
+
+const hasMeasuredClientAdapters = (stats) =>
+  Number(stats?.clientAdapters?.clientsMeasured ?? 0) > 0;
+
+const appendClientAdapterSignals = (lines, stats) => {
+  if (!hasMeasuredClientAdapters(stats)) {
+    return;
+  }
+
+  const clients = stats.clientAdapters.byClient;
+  const lowestOverheadClient = clients.reduce((best, current) => {
+    if (!best) {
+      return current;
+    }
+
+    if (current.averageContextOverheadTokens < best.averageContextOverheadTokens) {
+      return current;
+    }
+
+    if (current.averageContextOverheadTokens === best.averageContextOverheadTokens
+      && current.client.localeCompare(best.client) < 0) {
+      return current;
+    }
+
+    return best;
+  }, null);
+  const highestAutoStartClient = clients.reduce((best, current) => {
+    if (!best) {
+      return current;
+    }
+
+    if (current.autoStartCoveragePct > best.autoStartCoveragePct) {
+      return current;
+    }
+
+    if (current.autoStartCoveragePct === best.autoStartCoveragePct
+      && current.client.localeCompare(best.client) < 0) {
+      return current;
+    }
+
+    return best;
+  }, null);
+
+  lines.push('Client Adapter Signals:');
+  lines.push(`Clients measured:      ${stats.clientAdapters.clientsMeasured}`);
+  lines.push(`Adapter events:        ${clients.reduce((total, client) => total + client.adapterEvents, 0)}`);
+  lines.push(`Overhead total:        ${stats.clientAdapters.totalContextOverheadTokens} tokens`);
+  if (lowestOverheadClient) {
+    lines.push(`Lowest avg overhead:   ${lowestOverheadClient.client} (${lowestOverheadClient.averageContextOverheadTokens} tokens)`);
+  }
+  if (highestAutoStartClient) {
+    lines.push(`Best auto-start rate:  ${highestAutoStartClient.client} (${highestAutoStartClient.autoStartCoveragePct}%)`);
+  }
+  lines.push('');
+
+  for (const client of clients) {
+    lines.push(`${client.client}:`);
+    lines.push(`  Entries measured:    ${client.entriesMeasured}`);
+    lines.push(`  Adapter coverage:    ${client.adapterEvents}/${client.entriesMeasured} (${client.adapterCoveragePct}%)`);
+    lines.push(`  Base orchestrated:   ${client.baseOrchestratedEvents}/${client.entriesMeasured} (${client.baseOrchestratorCoveragePct}%)`);
+    lines.push(`  Auto-started:        ${client.autoStartedEvents}/${client.entriesMeasured} (${client.autoStartCoveragePct}%)`);
+    lines.push(`  Auto-preflighted:    ${client.autoPreflightedEvents}/${client.entriesMeasured} (${client.autoPreflightCoveragePct}%)`);
+    lines.push(`  Auto-checkpointed:   ${client.autoCheckpointedEvents}/${client.entriesMeasured} (${client.autoCheckpointCoveragePct}%)`);
+    lines.push(`  Context overhead:    ${client.contextOverheadTokens} tokens total (${client.averageContextOverheadTokens} avg)`);
+    if (client.blockedEvents > 0) {
+      lines.push(`  Blocked events:      ${client.blockedEvents}`);
+    }
+    lines.push('');
+  }
+};
+
+const analyzeClientAdapterQuality = (entries = []) => {
+  const clientEntries = entries.filter((entry) => Boolean(getMetricsClient(entry)));
+
+  const byClient = [...clientEntries.reduce((acc, entry) => {
+    const client = getMetricsClient(entry);
+    const current = acc.get(client) ?? {
+      client,
+      entriesMeasured: 0,
+      adapterEvents: 0,
+      wrapperEvents: 0,
+      taskRunnerEvents: 0,
+      baseOrchestratedEvents: 0,
+      autoStartedEvents: 0,
+      autoPreflightedEvents: 0,
+      autoCheckpointedEvents: 0,
+      blockedEvents: 0,
+      contextOverheadEntries: 0,
+      contextOverheadTokens: 0,
+    };
+
+    const overheadTokens = Math.max(0, Number(entry.metadata?.overheadTokens ?? 0));
+    current.entriesMeasured += 1;
+    current.adapterEvents += entry.metadata?.managedByClientAdapter ? 1 : 0;
+    current.wrapperEvents += entry.tool === 'agent_wrapper' ? 1 : 0;
+    current.taskRunnerEvents += entry.tool === 'task_runner' ? 1 : 0;
+    current.baseOrchestratedEvents += entry.metadata?.managedByBaseOrchestrator ? 1 : 0;
+    current.autoStartedEvents += (entry.metadata?.autoStartTriggered || entry.metadata?.autoStarted) ? 1 : 0;
+    current.autoPreflightedEvents += entry.metadata?.autoPreflightTriggered ? 1 : 0;
+    current.autoCheckpointedEvents += (entry.metadata?.autoCheckpointTriggered || entry.metadata?.autoAppended) ? 1 : 0;
+    current.blockedEvents += entry.metadata?.blocked ? 1 : 0;
+    current.contextOverheadEntries += overheadTokens > 0 ? 1 : 0;
+    current.contextOverheadTokens += overheadTokens;
+
+    acc.set(client, current);
+    return acc;
+  }, new Map()).values()]
+    .map((entry) => ({
+      ...entry,
+      averageContextOverheadTokens: roundAverage(entry.contextOverheadTokens, entry.contextOverheadEntries),
+      adapterCoveragePct: roundPct(entry.adapterEvents, entry.entriesMeasured),
+      baseOrchestratorCoveragePct: roundPct(entry.baseOrchestratedEvents, entry.entriesMeasured),
+      autoStartCoveragePct: roundPct(entry.autoStartedEvents, entry.entriesMeasured),
+      autoPreflightCoveragePct: roundPct(entry.autoPreflightedEvents, entry.entriesMeasured),
+      autoCheckpointCoveragePct: roundPct(entry.autoCheckpointedEvents, entry.entriesMeasured),
+    }))
+    .sort((a, b) => a.client.localeCompare(b.client));
+
+  return {
+    clientsMeasured: byClient.length,
+    entriesMeasured: clientEntries.length,
+    totalContextOverheadTokens: byClient.reduce((total, entry) => total + entry.contextOverheadTokens, 0),
+    byClient,
+  };
+};
+
 const analyzeTaskRunnerQuality = (entries = []) => {
   const runnerEntries = entries.filter(isTaskRunnerQualityEntry);
   const workflowEntries = runnerEntries.filter((entry) => entry.metadata?.isWorkflowCommand);
@@ -25,6 +158,16 @@ const analyzeTaskRunnerQuality = (entries = []) => {
   const blockedWithDoctor = blockedEntries.filter((entry) => entry.metadata?.doctorIssued);
   const checkpointEntries = runnerEntries.filter((entry) => entry.action === 'checkpoint');
   const persistedCheckpointEntries = checkpointEntries.filter((entry) => entry.metadata?.checkpointPersisted);
+  const baseOrchestratedEntries = workflowEntries.filter((entry) => entry.metadata?.managedByBaseOrchestrator);
+  const autoStartedEntries = workflowEntries.filter((entry) => entry.metadata?.autoStartTriggered);
+  const autoPreflightEntries = workflowEntries.filter((entry) => entry.metadata?.autoPreflightTriggered);
+  const autoCheckpointEntries = runnerEntries.filter((entry) => entry.metadata?.autoCheckpointTriggered);
+  const isolatedWorkflowEntries = workflowEntries.filter((entry) => entry.metadata?.isolatedSession);
+  const contextOverheadEntries = runnerEntries.filter((entry) => Number(entry.metadata?.contextOverheadTokens ?? 0) > 0);
+  const contextOverheadTokens = runnerEntries.reduce(
+    (total, entry) => total + Number(entry.metadata?.contextOverheadTokens ?? 0),
+    0,
+  );
 
   const commandBreakdown = [...runnerEntries.reduce((acc, entry) => {
     const key = entry.action ?? 'unknown';
@@ -71,6 +214,20 @@ const analyzeTaskRunnerQuality = (entries = []) => {
       persistedCommands: persistedCheckpointEntries.length,
       persistenceRatePct: roundPct(persistedCheckpointEntries.length, checkpointEntries.length),
     },
+    automaticity: {
+      baseOrchestratedCommands: baseOrchestratedEntries.length,
+      autoStartedCommands: autoStartedEntries.length,
+      autoPreflightedCommands: autoPreflightEntries.length,
+      autoCheckpointedCommands: autoCheckpointEntries.length,
+      isolatedWorkflowCommands: isolatedWorkflowEntries.length,
+      contextOverheadTokens,
+      averageContextOverheadTokens: contextOverheadEntries.length > 0
+        ? Number((contextOverheadTokens / contextOverheadEntries.length).toFixed(1))
+        : 0,
+      baseOrchestratorCoveragePct: roundPct(baseOrchestratedEntries.length, workflowEntries.length),
+      autoStartCoveragePct: roundPct(autoStartedEntries.length, workflowEntries.length),
+      autoPreflightCoveragePct: roundPct(autoPreflightEntries.length, workflowEntries.length),
+    },
   };
 };
 
@@ -132,15 +289,24 @@ export const analyzeProductQuality = (entries = []) => {
       blockedEnds,
       persistenceRatePct: roundPct(persistedEnds, endEntries.length),
     },
+    clientAdapters: analyzeClientAdapterQuality(entries),
     taskRunner: analyzeTaskRunnerQuality(entries),
   };
 };
 
+export const hasProductQualitySignals = (stats) =>
+  Boolean(stats)
+  && (
+    Number(stats.turnsMeasured ?? 0) > 0
+    || Number(stats?.taskRunner?.commandsMeasured ?? 0) > 0
+    || hasMeasuredClientAdapters(stats)
+  );
+
 export const formatProductQualityReport = (stats) => {
   const hasSmartTurn = Number(stats?.turnsMeasured ?? 0) > 0;
   const hasTaskRunner = Number(stats?.taskRunner?.commandsMeasured ?? 0) > 0;
 
-  if (!stats || (!hasSmartTurn && !hasTaskRunner)) {
+  if (!hasProductQualitySignals(stats)) {
     return '';
   }
 
@@ -193,11 +359,20 @@ export const formatProductQualityReport = (stats) => {
     lines.push('Blocked-State Routing:');
     lines.push(`Blocked with doctor:   ${stats.taskRunner.blockedState.blockedWithDoctor}/${stats.taskRunner.blockedState.blockedCommands} (${stats.taskRunner.blockedState.doctorCoveragePct}%)`);
     lines.push('');
+    lines.push('Automaticity:');
+    lines.push(`Base orchestrated:     ${stats.taskRunner.automaticity.baseOrchestratedCommands}/${stats.taskRunner.workflowCommands} (${stats.taskRunner.automaticity.baseOrchestratorCoveragePct}%)`);
+    lines.push(`Auto-started:          ${stats.taskRunner.automaticity.autoStartedCommands}/${stats.taskRunner.workflowCommands} (${stats.taskRunner.automaticity.autoStartCoveragePct}%)`);
+    lines.push(`Auto-preflighted:      ${stats.taskRunner.automaticity.autoPreflightedCommands}/${stats.taskRunner.workflowCommands} (${stats.taskRunner.automaticity.autoPreflightCoveragePct}%)`);
+    lines.push(`Auto-checkpointed:     ${stats.taskRunner.automaticity.autoCheckpointedCommands}`);
+    lines.push(`Context overhead:      ${stats.taskRunner.automaticity.contextOverheadTokens} tokens total (${stats.taskRunner.automaticity.averageContextOverheadTokens} avg)`);
+    lines.push('');
     lines.push('Checkpoint Commands:');
     lines.push(`Persisted checkpoints: ${stats.taskRunner.checkpointing.persistedCommands}/${stats.taskRunner.checkpointing.commandsMeasured} (${stats.taskRunner.checkpointing.persistenceRatePct}%)`);
     lines.push('');
   }
 
+  appendClientAdapterSignals(lines, stats);
+
   lines.push('Notes:');
   lines.push('- These are measured orchestration signals, not direct answer-quality scores.');
   lines.push('- Context refresh usefulness is proxied by whether refreshed turns surfaced top-file signals.');