mcp-efficiency-engine 0.1.4 → 0.1.6

package/.github/workflows/release-npm.yml

@@ -26,7 +26,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
           registry-url: https://registry.npmjs.org
 
       - name: Resolve publish version
@@ -94,14 +94,23 @@ jobs:
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 
-      - name: Sync package.json version to repository
+      - name: Record package.json sync requirement
         if: steps.version.outputs.changed == 'true'
         run: |
-          git config user.name "github-actions[bot]"
-          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-          git add package.json
-          git commit -m "chore(release): sync npm version to ${{ steps.version.outputs.tag }} [skip ci]"
-          git push
+          echo "package.json was bumped in CI to publish an available npm version (${{ steps.version.outputs.tag }})."
+          echo "Repository sync is skipped because main is protected and requires PR-based updates."
+          echo "Open a follow-up PR to align package.json with npm published version."
+
+      - name: Release summary
+        run: |
+          echo "## NPM Release" >> "$GITHUB_STEP_SUMMARY"
+          echo "- mode: ${{ steps.version.outputs.mode }}" >> "$GITHUB_STEP_SUMMARY"
+          echo "- published: ${{ steps.version.outputs.tag }}" >> "$GITHUB_STEP_SUMMARY"
+          if [ "${{ steps.version.outputs.changed }}" = "true" ]; then
+            echo "- package.json sync: skipped (protected branch, requires PR)" >> "$GITHUB_STEP_SUMMARY"
+          else
+            echo "- package.json sync: not required" >> "$GITHUB_STEP_SUMMARY"
+          fi
 
       - name: Create GitHub release
         uses: softprops/action-gh-release@v2

package/.vscode/mcp.json

@@ -7,16 +7,23 @@
       "command": "codebase-memory-mcp"
     },
     "codegraph": {
-      "command": "codegraph",
+      "command": "pwsh",
       "args": [
-        "serve",
-        "--mcp"
+        "-NoProfile",
+        "-ExecutionPolicy",
+        "Bypass",
+        "-File",
+        "scripts/ops/start-codegraph-mcp.ps1"
       ]
     },
     "gitnexus": {
-      "command": "gitnexus",
+      "command": "pwsh",
       "args": [
-        "mcp"
+        "-NoProfile",
+        "-ExecutionPolicy",
+        "Bypass",
+        "-File",
+        "scripts/ops/start-gitnexus-mcp.ps1"
       ],
       "env": {
         "GITNEXUS_SEMANTIC_EXACT_SCAN_LIMIT": "50000",

package/README.md

@@ -233,6 +233,17 @@ py -3 .\scripts\intake\run-routing-evals.py
 .\scripts\ops\bye.ps1
 ```
 
+Telemetría de terminal (PowerShell, opcional):
+
+```powershell
+mcpee observe-on
+# ... comandos interactivos ...
+mcpee observe-off
+```
+
+- `mcpee observe-on` instala un hook global de perfil PowerShell para emitir un evento de telemetría por comando usando `scripts/ops/emit-terminal-command-telemetry.py`.
+- `mcpee observe-off` elimina el hook global y restaura el perfil sin instrumentación.
+
 Validación extendida recomendada:
 
 ```powershell
@@ -253,6 +264,11 @@ Comportamiento del hook:
   - `scripts/learning/iteration-value-report.py`
   - `scripts/ops/publish-langsmith-kpis.py` (best effort)
 
+Notas operativas recientes:
+
+- `mcpee` envuelve scripts PowerShell con `scripts/ops/trace-command.py` para emitir trazas por comando (`mcpee.*`) en el collector.
+- `scripts/ops/publish-langsmith-kpis.py` agrega snapshots locales de flujos, coste y tokens antes de publicar KPI runs en LangSmith.
+
 Artefactos/resultados:
 
 - AutoDocs actualizado en `autodocs/generated` y `autodocs/site`

package/bin/mcpee.js

@@ -12,8 +12,77 @@ const commandMap = {
   hi: "scripts/ops/hi.ps1",
   bye: "scripts/ops/bye.ps1",
   intake: "scripts/intake/run-repo-intake.ps1",
+  "observe-on": "scripts/ops/install-terminal-telemetry-hook.ps1",
+  "observe-off": "scripts/ops/uninstall-terminal-telemetry-hook.ps1",
 };
 
+function resolveSessionId() {
+  const explicitSessionId = (process.env.MCP_SESSION_ID || "").trim();
+  if (explicitSessionId) {
+    return explicitSessionId;
+  }
+
+  const sessionLogHint = (process.env.VSCODE_TARGET_SESSION_LOG || "").trim();
+  if (sessionLogHint) {
+    const match = sessionLogHint.match(/[0-9a-fA-F-]{36}/);
+    if (match && match[0]) {
+      return match[0];
+    }
+  }
+
+  return "mcpee-cli";
+}
+
+function resolvePythonCandidates() {
+  if (process.platform === "win32") {
+    return [
+      ["py", ["-3"]],
+      ["python", []],
+      ["python3", []],
+    ];
+  }
+
+  return [
+    ["python3", []],
+    ["python", []],
+  ];
+}
+
+function runCopilotUsageIngest(repoRootPath) {
+  const sessionLogHint = (process.env.VSCODE_TARGET_SESSION_LOG || "").trim();
+  if (!sessionLogHint) {
+    return;
+  }
+
+  const ingestScriptPath = path.join(repoRootPath, "scripts", "learning", "ingest-copilot-session-usage.py");
+  if (!fs.existsSync(ingestScriptPath)) {
+    return;
+  }
+
+  for (const [pythonCommand, pythonPrefixArgs] of resolvePythonCandidates()) {
+    const ingestResult = spawnSync(
+      pythonCommand,
+      [
+        ...pythonPrefixArgs,
+        ingestScriptPath,
+        "--session-log",
+        sessionLogHint,
+      ],
+      {
+        cwd: repoRootPath,
+        stdio: "ignore",
+      },
+    );
+
+    if (ingestResult.error && ingestResult.error.code === "ENOENT") {
+      continue;
+    }
+
+    // La ingesta es best-effort: si falla no bloquea el comando principal.
+    return;
+  }
+}
+
 function resolveExecutionRoot(scriptRelativePath) {
   const configuredTarget = process.env.MCPEE_TARGET_DIR ? path.resolve(process.env.MCPEE_TARGET_DIR) : "";
   const cwdRoot = process.cwd();
@@ -41,6 +110,8 @@ function printHelp() {
       "  hi         Ejecuta el preflight diario.",
       "  bye        Ejecuta el cierre diario.",
       "  intake     Ejecuta el repo intake.",
+      "  observe-on Activa telemetria global del terminal (hook PowerShell).",
+      "  observe-off Desactiva telemetria global del terminal.",
       "",
       "Ejemplos:",
       "  npx mcp-efficiency-engine bootstrap",
@@ -60,6 +131,11 @@ function resolveInvocationCandidates() {
 function runPowerShellScript(scriptRelativePath, forwardedArgs) {
   const executionRoot = resolveExecutionRoot(scriptRelativePath);
   const scriptPath = path.join(executionRoot, scriptRelativePath);
+  const tracerScriptPath = path.join(repoRoot, "scripts", "ops", "trace-command.py");
+  const sessionId = resolveSessionId();
+
+  runCopilotUsageIngest(repoRoot);
+
   if (!fs.existsSync(scriptPath)) {
     process.stderr.write(`Script no encontrado: ${scriptRelativePath}\n`);
     return 1;
@@ -67,6 +143,48 @@ function runPowerShellScript(scriptRelativePath, forwardedArgs) {
 
   const shellCandidates = resolveInvocationCandidates();
   for (const shellCommand of shellCandidates) {
+    if (fs.existsSync(tracerScriptPath)) {
+      const operation = `mcpee.${path.basename(scriptRelativePath, path.extname(scriptRelativePath))}`;
+      for (const [pythonCommand, pythonPrefixArgs] of resolvePythonCandidates()) {
+        const tracedResult = spawnSync(
+          pythonCommand,
+          [
+            ...pythonPrefixArgs,
+            tracerScriptPath,
+            "--operation",
+            operation,
+            "--session-id",
+            sessionId,
+            "--cwd",
+            executionRoot,
+            "--",
+            shellCommand,
+            "-NoProfile",
+            "-ExecutionPolicy",
+            "Bypass",
+            "-File",
+            scriptPath,
+            ...forwardedArgs,
+          ],
+          {
+            cwd: repoRoot,
+            stdio: "inherit",
+          },
+        );
+
+        if (tracedResult.error && tracedResult.error.code === "ENOENT") {
+          continue;
+        }
+
+        if (tracedResult.error) {
+          process.stderr.write(`${tracedResult.error.message}\n`);
+          return 1;
+        }
+
+        return tracedResult.status ?? 0;
+      }
+    }
+
     const result = spawnSync(
       shellCommand,
       ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", scriptPath, ...forwardedArgs],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-efficiency-engine",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Motor de orquestacion para agentes MCP con routing por dominio y bootstrap portable.",
   "license": "MIT",
   "type": "commonjs",
@@ -51,7 +51,7 @@
     "hi": "node ./bin/mcpee.js hi",
     "bye": "node ./bin/mcpee.js bye",
     "intake": "node ./bin/mcpee.js intake",
-    "langsmith:kpis": "py -3 ./scripts/ops/publish-langsmith-kpis.py",
+    "langsmith:kpis": "py -3 ./scripts/ops/trace-command.py --operation mcpee.langsmith-kpis --session-id mcpee-cli --cwd . -- py -3 ./scripts/ops/publish-langsmith-kpis.py",
     "pack:check": "npm pack --dry-run"
   },
   "engines": {

package/scripts/ops/emit-terminal-command-telemetry.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import argparse
+import hashlib
+import sys
+from pathlib import Path
+
+
+def _bootstrap_repo_root() -> Path:
+    repo_root = Path(__file__).resolve().parents[2]
+    if str(repo_root) not in sys.path:
+        sys.path.insert(0, str(repo_root))
+    return repo_root
+
+
+def _hash_command(command: str) -> str:
+    return hashlib.sha256(command.encode("utf-8")).hexdigest()[:16]
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Emit telemetry for an already executed terminal command.")
+    parser.add_argument("--session-id", default="terminal-session", help="Session identifier")
+    parser.add_argument("--cwd", default=".", help="Current working directory")
+    parser.add_argument("--command", default="", help="Executed command text")
+    parser.add_argument("--success", default="true", help="Whether command succeeded (true/false)")
+    parser.add_argument("--exit-code", type=int, default=0, help="Exit code for native commands")
+    args = parser.parse_args()
+
+    command_text = (args.command or "").strip()
+    if not command_text:
+        return 0
+
+    repo_root = _bootstrap_repo_root()
+    from telemetry import build_telemetry_collector
+
+    collector = build_telemetry_collector(repo_root)
+
+    success = str(args.success).strip().lower() in {"1", "true", "yes", "ok"}
+    normalized_cwd = str(Path(args.cwd).resolve())
+
+    with collector.start_execution(
+        operation="terminal.command",
+        session_id=str(args.session_id).strip() or "terminal-session",
+        model="powershell",
+        provider="local-shell",
+    ):
+        with collector.start_span(
+            name="terminal.executed_command",
+            kind="TOOL",
+            attributes={
+                "cwd": normalized_cwd,
+                "command_hash": _hash_command(command_text),
+                "success": success,
+                "exit_code": int(args.exit_code),
+            },
+        ):
+            collector.record_event(
+                "RoutingResolved",
+                {
+                    "source": "terminal-hook",
+                    "cwd": normalized_cwd,
+                    "success": success,
+                    "exit_code": int(args.exit_code),
+                },
+                level="INFO",
+            )
+            collector.record_metric("terminal_command_count", 1.0, unit="count")
+            collector.record_metric("terminal_last_exit_code", float(int(args.exit_code)), unit="code")
+            if not success:
+                collector.record_event(
+                    "ExceptionThrown",
+                    {
+                        "source": "terminal-hook",
+                        "message": "command_reported_failure",
+                        "exit_code": int(args.exit_code),
+                    },
+                    level="ERROR",
+                )
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/ops/install-terminal-telemetry-hook.ps1

@@ -0,0 +1,152 @@
+param(
+    [switch]$AllHosts,
+    [switch]$CurrentProcess,
+    [string]$SessionId = ''
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+$repoRoot = (Resolve-Path (Join-Path $PSScriptRoot '..\..')).Path
+$sessionIdResolved = if ([string]::IsNullOrWhiteSpace($SessionId)) {
+    if (-not [string]::IsNullOrWhiteSpace($env:MCP_SESSION_ID)) { $env:MCP_SESSION_ID }
+    elseif (-not [string]::IsNullOrWhiteSpace($env:VSCODE_TARGET_SESSION_LOG) -and $env:VSCODE_TARGET_SESSION_LOG -match '([0-9a-fA-F-]{36})') { $Matches[1] }
+    else { 'terminal-session' }
+}
+else {
+    $SessionId
+}
+
+$hookBlock = @"
+# >>> MCPEE_TERMINAL_TELEMETRY_START >>>
+`$global:MCPEE_TELEMETRY_REPO_ROOT = '$repoRoot'
+`$global:MCPEE_TELEMETRY_SESSION_ID = '$sessionIdResolved'
+`$global:MCPEE_TELEMETRY_LAST_HISTORY_ID = -1
+`$global:MCPEE_TELEMETRY_LAST_STAMP = ''
+
+function global:Get-McpeeTelemetryPythonCommand {
+    if (Get-Command py -ErrorAction SilentlyContinue) {
+        return @('py', '-3')
+    }
+    if (Get-Command python -ErrorAction SilentlyContinue) {
+        return @('python')
+    }
+    if (Get-Command python3 -ErrorAction SilentlyContinue) {
+        return @('python3')
+    }
+    return @()
+}
+
+function global:Invoke-McpeeTerminalTelemetry {
+    try {
+        `$last = Get-History -Count 1 -ErrorAction SilentlyContinue
+        if (`$null -eq `$last) { return }
+
+        `$historyId = [int]`$last.Id
+        if (`$historyId -le [int]`$global:MCPEE_TELEMETRY_LAST_HISTORY_ID) { return }
+
+        `$commandText = [string]`$last.CommandLine
+        if ([string]::IsNullOrWhiteSpace(`$commandText)) { return }
+
+        `$commandTrim = `$commandText.Trim()
+        if (`$commandTrim -match 'Invoke-McpeeTerminalTelemetry|emit-terminal-command-telemetry\.py') { 
+            `$global:MCPEE_TELEMETRY_LAST_HISTORY_ID = `$historyId
+            return 
+        }
+
+        `$stamp = ('{0}:{1}' -f `$historyId, `$commandTrim)
+        if (`$stamp -eq `$global:MCPEE_TELEMETRY_LAST_STAMP) {
+            `$global:MCPEE_TELEMETRY_LAST_HISTORY_ID = `$historyId
+            return
+        }
+
+        `$py = Get-McpeeTelemetryPythonCommand
+        if (`$py.Count -eq 0) {
+            `$global:MCPEE_TELEMETRY_LAST_HISTORY_ID = `$historyId
+            `$global:MCPEE_TELEMETRY_LAST_STAMP = `$stamp
+            return
+        }
+
+        `$scriptPath = Join-Path `$global:MCPEE_TELEMETRY_REPO_ROOT 'scripts/ops/emit-terminal-command-telemetry.py'
+        if (-not (Test-Path `$scriptPath)) {
+            `$global:MCPEE_TELEMETRY_LAST_HISTORY_ID = `$historyId
+            `$global:MCPEE_TELEMETRY_LAST_STAMP = `$stamp
+            return
+        }
+
+        `$success = if (`$?) { 'true' } else { 'false' }
+        `$nativeExit = if (`$null -eq `$LASTEXITCODE) { 0 } else { [int]`$LASTEXITCODE }
+
+        `$pyArgs = @()
+        if (`$py.Count -gt 1) {
+            `$pyArgs = `$py[1..(`$py.Count-1)]
+        }
+
+        & `$py[0] @(`$pyArgs) `$scriptPath --session-id `$global:MCPEE_TELEMETRY_SESSION_ID --cwd `$PWD.Path --command `$commandTrim --success `$success --exit-code `$nativeExit *> `$null
+
+        `$global:MCPEE_TELEMETRY_LAST_HISTORY_ID = `$historyId
+        `$global:MCPEE_TELEMETRY_LAST_STAMP = `$stamp
+    }
+    catch {
+        # Hook de telemetria best-effort: nunca romper la consola.
+    }
+}
+
+if (-not (Test-Path Function:\global:MCPEE_ORIGINAL_PROMPT)) {
+    `$originalPromptBody = if (Test-Path Function:\global:prompt) { (Get-Command prompt -CommandType Function).ScriptBlock.ToString() } else { '"PS " + `$executionContext.SessionState.Path.CurrentLocation + "> "' }
+    Set-Item -Path Function:\global:MCPEE_ORIGINAL_PROMPT -Value ([ScriptBlock]::Create(`$originalPromptBody)) -Force
+}
+
+function global:prompt {
+    Invoke-McpeeTerminalTelemetry
+    & global:MCPEE_ORIGINAL_PROMPT
+}
+# <<< MCPEE_TERMINAL_TELEMETRY_END <<<
+"@
+
+function Install-InProfile {
+    param([string]$ProfilePath)
+
+    $dir = Split-Path $ProfilePath -Parent
+    if (-not (Test-Path $dir)) {
+        New-Item -ItemType Directory -Path $dir -Force | Out-Null
+    }
+
+    if (-not (Test-Path $ProfilePath)) {
+        New-Item -ItemType File -Path $ProfilePath -Force | Out-Null
+    }
+
+    $content = Get-Content -Path $ProfilePath -Raw -ErrorAction SilentlyContinue
+    if ($null -eq $content) { $content = '' }
+
+    if ($content -match 'MCPEE_TERMINAL_TELEMETRY_START') {
+        $updated = [regex]::Replace(
+            $content,
+            '(?s)# >>> MCPEE_TERMINAL_TELEMETRY_START >>>.*?# <<< MCPEE_TERMINAL_TELEMETRY_END <<<',
+            $hookBlock
+        )
+        Set-Content -Path $ProfilePath -Value $updated -Encoding UTF8
+    }
+    else {
+        if (-not [string]::IsNullOrWhiteSpace($content) -and -not $content.EndsWith("`n")) {
+            $content += "`r`n"
+        }
+        $content += "`r`n$hookBlock`r`n"
+        Set-Content -Path $ProfilePath -Value $content -Encoding UTF8
+    }
+
+    Write-Host "[ok] Hook instalado/actualizado en: $ProfilePath"
+}
+
+if ($CurrentProcess) {
+    Invoke-Expression $hookBlock
+    Write-Host '[ok] Hook cargado en la sesion actual.'
+}
+
+Install-InProfile -ProfilePath $PROFILE.CurrentUserCurrentHost
+if ($AllHosts) {
+    Install-InProfile -ProfilePath $PROFILE.CurrentUserAllHosts
+}
+
+Write-Host '[ok] Telemetria global de terminal activada (best-effort).'
+Write-Host '[hint] Para desinstalar usa: mcpee observe-off'

package/scripts/ops/migrate-localdb-to-azure-sql.ps1

@@ -0,0 +1,98 @@
+param(
+    [string]$SourceConnectionString = 'Server=(localdb)\MSSQLLocalDB;Database=TechRidersDev;Trusted_Connection=True;MultipleActiveResultSets=True;TrustServerCertificate=True',
+    [string]$TargetServer = 'sql-techriders-dev-ohbnpr4l4fihc.database.windows.net',
+    [string]$TargetDatabase = 'sqldb-techriders-dev',
+    [string]$TargetUser = 'sqladminuser'
+)
+
+$ErrorActionPreference = 'Stop'
+Add-Type -AssemblyName System.Data
+
+if ([string]::IsNullOrWhiteSpace($env:SQL_ADMIN_PASSWORD)) {
+    throw 'Missing SQL_ADMIN_PASSWORD environment variable.'
+}
+
+$targetConnectionString = "Server=tcp:$TargetServer,1433;Initial Catalog=$TargetDatabase;Persist Security Info=False;User ID=$TargetUser;Password=$($env:SQL_ADMIN_PASSWORD);MultipleActiveResultSets=True;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"
+
+$sourceConn = New-Object System.Data.SqlClient.SqlConnection $SourceConnectionString
+$targetConn = New-Object System.Data.SqlClient.SqlConnection $targetConnectionString
+
+try {
+    $sourceConn.Open()
+    $targetConn.Open()
+
+    $tableCmd = $sourceConn.CreateCommand()
+    $tableCmd.CommandText = @"
+SELECT s.name AS SchemaName, t.name AS TableName
+FROM sys.tables t
+JOIN sys.schemas s ON s.schema_id = t.schema_id
+WHERE t.is_ms_shipped = 0
+ORDER BY s.name, t.name;
+"@
+
+    $reader = $tableCmd.ExecuteReader()
+    $tables = New-Object System.Collections.Generic.List[object]
+    while ($reader.Read()) {
+        $schema = $reader.GetString(0)
+        $table = $reader.GetString(1)
+        if ($table -ne '__EFMigrationsHistory') {
+            $tables.Add([PSCustomObject]@{ Schema = $schema; Table = $table })
+        }
+    }
+    $reader.Close()
+
+    if ($tables.Count -eq 0) {
+        throw 'No source user tables found.'
+    }
+
+    foreach ($t in $tables) {
+        $fullName = "[$($t.Schema)].[$($t.Table)]"
+        $disableCmd = $targetConn.CreateCommand()
+        $disableCmd.CommandText = "ALTER TABLE $fullName NOCHECK CONSTRAINT ALL;"
+        [void]$disableCmd.ExecuteNonQuery()
+    }
+
+    $summary = New-Object System.Collections.Generic.List[object]
+
+    foreach ($t in $tables) {
+        $fullName = "[$($t.Schema)].[$($t.Table)]"
+
+        $deleteCmd = $targetConn.CreateCommand()
+        $deleteCmd.CommandText = "DELETE FROM $fullName;"
+        [void]$deleteCmd.ExecuteNonQuery()
+
+        $selectCmd = $sourceConn.CreateCommand()
+        $selectCmd.CommandText = "SELECT * FROM $fullName;"
+
+        $adapter = New-Object System.Data.SqlClient.SqlDataAdapter $selectCmd
+        $dataTable = New-Object System.Data.DataTable
+        [void]$adapter.Fill($dataTable)
+
+        if ($dataTable.Rows.Count -gt 0) {
+            $bulkCopy = New-Object System.Data.SqlClient.SqlBulkCopy($targetConn, [System.Data.SqlClient.SqlBulkCopyOptions]::KeepIdentity, $null)
+            $bulkCopy.DestinationTableName = $fullName
+            $bulkCopy.BulkCopyTimeout = 0
+            foreach ($col in $dataTable.Columns) {
+                [void]$bulkCopy.ColumnMappings.Add($col.ColumnName, $col.ColumnName)
+            }
+            $bulkCopy.WriteToServer($dataTable)
+            $bulkCopy.Close()
+        }
+
+        $summary.Add([PSCustomObject]@{ Table = $fullName; Rows = $dataTable.Rows.Count })
+    }
+
+    foreach ($t in $tables) {
+        $fullName = "[$($t.Schema)].[$($t.Table)]"
+        $enableCmd = $targetConn.CreateCommand()
+        $enableCmd.CommandText = "ALTER TABLE $fullName WITH CHECK CHECK CONSTRAINT ALL;"
+        [void]$enableCmd.ExecuteNonQuery()
+    }
+
+    $summary | Sort-Object Table | Format-Table -AutoSize | Out-String | Write-Output
+    Write-Output 'MIGRATION_COMPLETED'
+}
+finally {
+    if ($sourceConn.State -eq 'Open') { $sourceConn.Close() }
+    if ($targetConn.State -eq 'Open') { $targetConn.Close() }
+}

package/scripts/ops/publish-langsmith-kpis.py

@@ -4,6 +4,7 @@ import json
 import os
 import sys
 import uuid
+from collections import Counter
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
@@ -25,6 +26,28 @@ def _read_json(path: Path) -> dict[str, Any]:
     return payload if isinstance(payload, dict) else {}
 
 
+def _read_jsonl(path: Path) -> list[dict[str, Any]]:
+    if not path.exists():
+        return []
+    rows: list[dict[str, Any]] = []
+    for line in path.read_text(encoding="utf-8").splitlines():
+        raw = line.strip()
+        if not raw:
+            continue
+        try:
+            obj = json.loads(raw)
+        except Exception:
+            continue
+        if isinstance(obj, dict):
+            rows.append(obj)
+    return rows
+
+
+def _write_json(path: Path, payload: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
+
+
 def _iso_now() -> datetime:
     return datetime.now(timezone.utc)
 
@@ -48,6 +71,161 @@ def _flatten_kpis(payload: dict[str, Any]) -> dict[str, Any]:
     return flat
 
 
+def _build_telemetry_snapshot(repo_root: Path) -> dict[str, Any]:
+    traces_path = repo_root / ".telemetry" / "traces.jsonl"
+    metrics_path = repo_root / ".telemetry" / "metrics.jsonl"
+    traces = _read_jsonl(traces_path)
+    metrics = _read_jsonl(metrics_path)
+
+    execution_ids: set[str] = set()
+    operations = Counter()
+    sessions = Counter()
+    engines = Counter()
+    agents = Counter()
+    warnings = 0
+    errors = 0
+    fallback_count = 0
+    grounded_count = 0
+    routing_count = 0
+    durations: list[float] = []
+    exporter_failures = Counter()
+
+    for row in traces:
+        context = row.get("context", {}) if isinstance(row.get("context"), dict) else {}
+        payload = row.get("payload", {}) if isinstance(row.get("payload"), dict) else {}
+        event_name = str(row.get("event_name", ""))
+        level = str(row.get("level", "INFO")).upper()
+
+        execution_id = str(context.get("execution_id", "")).strip()
+        if execution_id:
+            execution_ids.add(execution_id)
+
+        session_id = str(context.get("session_id", "")).strip()
+        if session_id:
+            sessions[session_id] += 1
+
+        if level == "WARNING":
+            warnings += 1
+        if level == "ERROR":
+            errors += 1
+
+        if event_name == "ExecutionStarted":
+            op = str(payload.get("operation", "")).strip() or "unknown"
+            operations[op] += 1
+
+        if event_name == "RoutingResolved":
+            routing_count += 1
+            engine = str(payload.get("engine", "")).strip() or "unknown"
+            agent = str(payload.get("agent", "")).strip() or "unknown"
+            engines[engine] += 1
+            agents[agent] += 1
+            if bool(payload.get("fallback", False)):
+                fallback_count += 1
+            if bool(payload.get("grounded", False)):
+                grounded_count += 1
+
+        if event_name == "SpanFinished":
+            try:
+                durations.append(float(payload.get("duration_ms") or 0.0))
+            except Exception:
+                pass
+
+        if event_name == "WarningGenerated" and str(payload.get("warning", "")) == "exporter_failed":
+            exporter = str(payload.get("exporter", "unknown")).strip() or "unknown"
+            exporter_failures[exporter] += 1
+
+    metric_totals = {
+        "tokens_input": 0.0,
+        "tokens_output": 0.0,
+        "total_tokens": 0.0,
+        "estimated_cost": 0.0,
+        "efficiency_score_samples": 0,
+        "efficiency_score_avg": 0.0,
+    }
+    efficiency_sum = 0.0
+    for row in metrics:
+        payload = row.get("payload", {}) if isinstance(row.get("payload"), dict) else {}
+        if str(row.get("event_name", "")) != "MetricCalculated":
+            continue
+        name = str(payload.get("name", "")).strip()
+        try:
+            value = float(payload.get("value") or 0.0)
+        except Exception:
+            continue
+
+        if name in {"tokens_input", "tokens_output", "total_tokens", "estimated_cost"}:
+            metric_totals[name] += value
+        elif name == "efficiency_score":
+            efficiency_sum += value
+            metric_totals["efficiency_score_samples"] += 1
+
+    samples = int(metric_totals["efficiency_score_samples"])
+    if samples > 0:
+        metric_totals["efficiency_score_avg"] = round(efficiency_sum / samples, 4)
+
+    avg_duration = round(sum(durations) / len(durations), 4) if durations else 0.0
+    p95_duration = 0.0
+    if durations:
+        sorted_d = sorted(durations)
+        idx = max(0, min(len(sorted_d) - 1, int(round(0.95 * (len(sorted_d) - 1)))))
+        p95_duration = round(sorted_d[idx], 4)
+
+    fallback_rate = round((fallback_count / routing_count), 4) if routing_count else 0.0
+    grounded_rate = round((grounded_count / routing_count), 4) if routing_count else 0.0
+
+    return {
+        "timestamp": _iso_now().isoformat(),
+        "source": {
+            "traces": str(traces_path),
+            "metrics": str(metrics_path),
+        },
+        "totals": {
+            "trace_records": len(traces),
+            "metric_records": len(metrics),
+            "executions": len(execution_ids),
+            "warnings": warnings,
+            "errors": errors,
+        },
+        "kpis": {
+            "routing_fallback_rate": fallback_rate,
+            "routing_grounded_rate": grounded_rate,
+            "avg_span_duration_ms": avg_duration,
+            "p95_span_duration_ms": p95_duration,
+            "tokens_input": int(metric_totals["tokens_input"]),
+            "tokens_output": int(metric_totals["tokens_output"]),
+            "total_tokens": int(metric_totals["total_tokens"]),
+            "total_cost_usd": round(float(metric_totals["estimated_cost"]), 6),
+            "efficiency_score_avg": metric_totals["efficiency_score_avg"],
+        },
+        "breakdown": {
+            "operation": dict(operations),
+            "session": dict(sessions),
+            "engine": dict(engines),
+            "agent": dict(agents),
+            "exporter_failures": dict(exporter_failures),
+        },
+    }
+
+
+def _build_chat_usage_snapshot(repo_root: Path) -> dict[str, Any]:
+    chat_path = repo_root / "observability" / "evals" / "chat-token-usage-report.json"
+    payload = _read_json(chat_path)
+    totals = payload.get("totals", {}) if isinstance(payload.get("totals", {}), dict) else {}
+    budget = payload.get("budget", {}) if isinstance(payload.get("budget", {}), dict) else {}
+    return {
+        "timestamp": payload.get("timestamp"),
+        "source": str(chat_path),
+        "kpis": {
+            "input_tokens": int(totals.get("input_tokens", 0) or 0),
+            "output_tokens": int(totals.get("output_tokens", 0) or 0),
+            "total_tokens": int(totals.get("total_tokens", 0) or 0),
+            "copilot_credits": float(totals.get("copilot_credits", 0.0) or 0.0),
+            "budget_utilization_rate": float(budget.get("budget_utilization_rate", 0.0) or 0.0),
+        },
+        "raw": payload,
+    }
+
+
 def _publish_run(
     client: Any,
     *,
@@ -104,12 +282,18 @@ def _publish_run(
 
 
 def _publish_feedback_metrics(client: Any, *, run_id: str, metrics: dict[str, Any], source: str) -> None:
+    min_score = -99999.9999
+    max_score = 99999.9999
     for key, raw_value in metrics.items():
         try:
             value = float(raw_value)
         except Exception:
             continue
 
+        if value < min_score or value > max_score:
+            # LangSmith feedback score has bounded range.
+            continue
+
         try:
             client.create_feedback(
                 run_id=run_id,
@@ -152,9 +336,38 @@ def main() -> int:
 
     learning_path = repo_root / "observability" / "evals" / "learning-loop-report.json"
     value_path = repo_root / "observability" / "evals" / "iteration-value-report.json"
+    telemetry_snapshot_path = repo_root / "observability" / "evals" / "telemetry-flow-cost-token-report.json"
+    chat_snapshot_path = repo_root / "observability" / "evals" / "chat-token-usage-report.json"
 
     learning = _read_json(learning_path)
     value = _read_json(value_path)
+    telemetry_snapshot = _build_telemetry_snapshot(repo_root)
+    _write_json(telemetry_snapshot_path, telemetry_snapshot)
+    chat_snapshot = _build_chat_usage_snapshot(repo_root)
+
+    project_traceability_path = (
+        repo_root
+        / "projects"
+        / "techriders"
+        / "analysis_mcpee"
+        / f"telemetry-recovery-{datetime.now(timezone.utc).strftime('%Y-%m-%d')}.json"
+    )
+    unified_snapshot = {
+        "timestamp": _iso_now().isoformat(),
+        "host_project": host_project,
+        "telemetry_scope": telemetry_scope,
+        "sources": {
+            "learning": str(learning_path),
+            "iteration_value": str(value_path),
+            "telemetry_snapshot": str(telemetry_snapshot_path),
+            "chat_usage": str(chat_snapshot_path),
+        },
+        "learning": learning,
+        "iteration_value": value,
+        "telemetry": telemetry_snapshot,
+        "chat_usage": chat_snapshot,
+    }
+    _write_json(project_traceability_path, unified_snapshot)
 
     published = 0
 
@@ -288,10 +501,92 @@ def main() -> int:
         _publish_feedback_metrics(client, run_id=run_id, metrics=alignment_feedback, source="alignment")
         published += 1
 
+    telemetry_kpis = telemetry_snapshot.get("kpis", {}) if isinstance(telemetry_snapshot.get("kpis", {}), dict) else {}
+    if telemetry_kpis:
+        telemetry_flat_kpis = _flatten_kpis(telemetry_kpis)
+        run_id = _publish_run(
+            client,
+            project=cfg.langsmith.project,
+            name="KPI::TelemetryFlowCostToken",
+            inputs={
+                "source_file": str(telemetry_snapshot_path),
+                "timestamp": telemetry_snapshot.get("timestamp"),
+            },
+            outputs={
+                "kpis": telemetry_kpis,
+                **telemetry_flat_kpis,
+                "totals": telemetry_snapshot.get("totals", {}),
+                "breakdown": telemetry_snapshot.get("breakdown", {}),
+            },
+            tags=[
+                "mcpee",
+                "kpi",
+                "telemetry",
+                "cost-token-flow",
+                "dashboard",
+                f"scope:{telemetry_scope}",
+                f"host:{host_slug}",
+            ],
+            metadata={
+                "kpi_source": "telemetry-flow-cost-token",
+                "kpi_kind": "snapshot",
+                "host_project": host_project,
+                "host_project_slug": host_slug,
+                "telemetry_scope": telemetry_scope,
+                **telemetry_flat_kpis,
+            },
+            total_cost=float(telemetry_kpis.get("total_cost_usd", 0.0) or 0.0),
+            total_tokens=int(telemetry_kpis.get("total_tokens", 0) or 0),
+            run_type="llm",
+        )
+        _publish_feedback_metrics(client, run_id=run_id, metrics=telemetry_flat_kpis, source="telemetry-flow-cost-token")
+        published += 1
+
+    chat_kpis = chat_snapshot.get("kpis", {}) if isinstance(chat_snapshot.get("kpis", {}), dict) else {}
+    if chat_kpis:
+        chat_flat_kpis = _flatten_kpis(chat_kpis)
+        run_id = _publish_run(
+            client,
+            project=cfg.langsmith.project,
+            name="KPI::ChatTokenUsage",
+            inputs={
+                "source_file": str(chat_snapshot_path),
+                "timestamp": chat_snapshot.get("timestamp"),
+            },
+            outputs={
+                "kpis": chat_kpis,
+                **chat_flat_kpis,
+                "budget": (chat_snapshot.get("raw", {}) or {}).get("budget", {}),
+            },
+            tags=[
+                "mcpee",
+                "kpi",
+                "chat-usage",
+                "cost-token-flow",
+                "dashboard",
+                f"scope:{telemetry_scope}",
+                f"host:{host_slug}",
+            ],
+            metadata={
+                "kpi_source": "chat-token-usage",
+                "kpi_kind": "snapshot",
+                "host_project": host_project,
+                "host_project_slug": host_slug,
+                "telemetry_scope": telemetry_scope,
+                **chat_flat_kpis,
+            },
+            total_tokens=int(chat_kpis.get("total_tokens", 0) or 0),
+            run_type="llm",
+        )
+        _publish_feedback_metrics(client, run_id=run_id, metrics=chat_flat_kpis, source="chat-token-usage")
+        published += 1
+
     print(
         f"Published KPI runs: {published} to project '{cfg.langsmith.project}' "
         f"(host_project='{host_project}', scope='{telemetry_scope}')."
     )
+    print(f"Local telemetry snapshot: {telemetry_snapshot_path}")
+    print(f"Project traceability snapshot: {project_traceability_path}")
     if published == 0:
         print("No local KPI report JSON files were found in observability/evals.")
 

package/scripts/ops/start-codegraph-mcp.ps1

@@ -0,0 +1,67 @@
+param(
+    [switch]$DryRun
+)
+
+$ErrorActionPreference = 'Stop'
+
+function Resolve-RepoRoot {
+    return (Resolve-Path (Join-Path $PSScriptRoot '..\..')).Path
+}
+
+function Has-CodegraphIndex([string]$path) {
+    return (Test-Path (Join-Path $path '.codegraph'))
+}
+
+function Resolve-TargetPath {
+    param([string]$RepoRoot)
+
+    $envPath = [Environment]::GetEnvironmentVariable('CODEGRAPH_PROJECT_PATH')
+    if (-not [string]::IsNullOrWhiteSpace($envPath)) {
+        $resolvedEnvPath = $null
+        try {
+            $resolvedEnvPath = (Resolve-Path $envPath).Path
+        }
+        catch {
+            $resolvedEnvPath = $null
+        }
+
+        if ($resolvedEnvPath -and (Has-CodegraphIndex $resolvedEnvPath)) {
+            return $resolvedEnvPath
+        }
+    }
+
+    $projectCandidates = @()
+    $projectsRoot = Join-Path $RepoRoot 'projects'
+    if (Test-Path $projectsRoot) {
+        foreach ($projectDir in Get-ChildItem -Path $projectsRoot -Directory -ErrorAction SilentlyContinue) {
+            if (Has-CodegraphIndex $projectDir.FullName) {
+                $projectCandidates += $projectDir.FullName
+            }
+        }
+    }
+
+    if ($projectCandidates.Count -eq 1) {
+        return $projectCandidates[0]
+    }
+
+    if (Has-CodegraphIndex $RepoRoot) {
+        return $RepoRoot
+    }
+
+    if ($projectCandidates.Count -gt 1) {
+        return $projectCandidates[0]
+    }
+
+    return $RepoRoot
+}
+
+$repoRoot = Resolve-RepoRoot
+$targetPath = Resolve-TargetPath -RepoRoot $repoRoot
+
+if ($DryRun) {
+    Write-Output $targetPath
+    exit 0
+}
+
+& codegraph serve --mcp --path $targetPath
+exit $LASTEXITCODE

package/scripts/ops/start-gitnexus-mcp.ps1

@@ -0,0 +1,85 @@
+param(
+    [switch]$DryRun
+)
+
+$ErrorActionPreference = 'Stop'
+
+function Resolve-RepoRoot {
+    return (Resolve-Path (Join-Path $PSScriptRoot '..\..')).Path
+}
+
+function Is-GitRepo([string]$path) {
+    return (Test-Path (Join-Path $path '.git'))
+}
+
+function Has-GitNexusIndex([string]$path) {
+    return (Test-Path (Join-Path $path '.gitnexus'))
+}
+
+function Resolve-TargetPath {
+    param([string]$RepoRoot)
+
+    $envPath = [Environment]::GetEnvironmentVariable('GITNEXUS_PROJECT_PATH')
+    if (-not [string]::IsNullOrWhiteSpace($envPath)) {
+        $resolvedEnvPath = $null
+        try {
+            $resolvedEnvPath = (Resolve-Path $envPath).Path
+        }
+        catch {
+            $resolvedEnvPath = $null
+        }
+
+        if ($resolvedEnvPath -and (Is-GitRepo $resolvedEnvPath)) {
+            return $resolvedEnvPath
+        }
+    }
+
+    $projectCandidates = @()
+    $indexedProjectCandidates = @()
+    $projectsRoot = Join-Path $RepoRoot 'projects'
+
+    if (Test-Path $projectsRoot) {
+        foreach ($projectDir in Get-ChildItem -Path $projectsRoot -Directory -ErrorAction SilentlyContinue) {
+            if (Is-GitRepo $projectDir.FullName) {
+                $projectCandidates += $projectDir.FullName
+                if (Has-GitNexusIndex $projectDir.FullName) {
+                    $indexedProjectCandidates += $projectDir.FullName
+                }
+            }
+        }
+    }
+
+    if ($indexedProjectCandidates.Count -eq 1) {
+        return $indexedProjectCandidates[0]
+    }
+
+    if ((Has-GitNexusIndex $RepoRoot) -and (Is-GitRepo $RepoRoot)) {
+        return $RepoRoot
+    }
+
+    if ($indexedProjectCandidates.Count -gt 1) {
+        return $indexedProjectCandidates[0]
+    }
+
+    if ($projectCandidates.Count -eq 1) {
+        return $projectCandidates[0]
+    }
+
+    if ($projectCandidates.Count -gt 1) {
+        return $projectCandidates[0]
+    }
+
+    return $RepoRoot
+}
+
+$repoRoot = Resolve-RepoRoot
+$targetPath = Resolve-TargetPath -RepoRoot $repoRoot
+
+if ($DryRun) {
+    Write-Output $targetPath
+    exit 0
+}
+
+Set-Location $targetPath
+& gitnexus mcp
+exit $LASTEXITCODE

package/scripts/ops/trace-command.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+
+
+def _bootstrap_repo_root() -> Path:
+    repo_root = Path(__file__).resolve().parents[2]
+    if str(repo_root) not in sys.path:
+        sys.path.insert(0, str(repo_root))
+    return repo_root
+
+
+def _parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Run a command wrapped with telemetry execution/span.")
+    parser.add_argument("--operation", required=True, help="Telemetry operation name.")
+    parser.add_argument("--session-id", default="mcpee-cli", help="Telemetry session identifier.")
+    parser.add_argument("--cwd", default=".", help="Working directory for the command.")
+    parser.add_argument("command", nargs=argparse.REMAINDER, help="Command to execute after --.")
+    return parser.parse_args()
+
+
+def _normalize_command(raw: list[str]) -> list[str]:
+    cmd = list(raw)
+    if cmd and cmd[0] == "--":
+        cmd = cmd[1:]
+    return cmd
+
+
+def main() -> int:
+    args = _parse_args()
+    command = _normalize_command(args.command)
+    if not command:
+        print("trace-command.py: missing command to execute", file=sys.stderr)
+        return 2
+
+    repo_root = _bootstrap_repo_root()
+    from telemetry import build_telemetry_collector
+
+    collector = build_telemetry_collector(repo_root)
+    cwd = Path(args.cwd).resolve()
+    exit_code = 0
+
+    try:
+        with collector.start_execution(operation=args.operation, session_id=args.session_id, model="mcpee-cli"):
+            with collector.start_span(
+                name="subprocess",
+                kind="TOOL",
+                attributes={
+                    "cwd": str(cwd),
+                    "command": command[0],
+                    "args_count": len(command) - 1,
+                },
+            ):
+                completed = subprocess.run(command, cwd=str(cwd), check=False)
+                exit_code = int(completed.returncode)
+                collector.record_metric("subprocess_exit_code", float(exit_code), unit="code")
+                if exit_code != 0:
+                    raise RuntimeError(f"command failed with exit code {exit_code}")
+    except RuntimeError:
+        pass
+
+    return exit_code
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/ops/uninstall-terminal-telemetry-hook.ps1

@@ -0,0 +1,53 @@
+param(
+    [switch]$AllHosts,
+    [switch]$CurrentProcess
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+function Remove-FromProfile {
+    param([string]$ProfilePath)
+
+    if (-not (Test-Path $ProfilePath)) {
+        return
+    }
+
+    $content = Get-Content -Path $ProfilePath -Raw -ErrorAction SilentlyContinue
+    if ($null -eq $content) {
+        return
+    }
+
+    if ($content -match 'MCPEE_TERMINAL_TELEMETRY_START') {
+        $updated = [regex]::Replace(
+            $content,
+            '(?s)\r?\n?# >>> MCPEE_TERMINAL_TELEMETRY_START >>>.*?# <<< MCPEE_TERMINAL_TELEMETRY_END <<<\r?\n?',
+            "`r`n"
+        )
+        Set-Content -Path $ProfilePath -Value $updated -Encoding UTF8
+        Write-Host "[ok] Hook eliminado de: $ProfilePath"
+    }
+}
+
+if ($CurrentProcess) {
+    Remove-Item Function:\global:prompt -ErrorAction SilentlyContinue
+    if (Test-Path Function:\global:MCPEE_ORIGINAL_PROMPT) {
+        Set-Item -Path Function:\global:prompt -Value ((Get-Command MCPEE_ORIGINAL_PROMPT -CommandType Function).ScriptBlock) -Force
+        Remove-Item Function:\global:MCPEE_ORIGINAL_PROMPT -ErrorAction SilentlyContinue
+    }
+
+    Remove-Item Function:\global:Invoke-McpeeTerminalTelemetry -ErrorAction SilentlyContinue
+    Remove-Item Function:\global:Get-McpeeTelemetryPythonCommand -ErrorAction SilentlyContinue
+    Remove-Variable MCPEE_TELEMETRY_REPO_ROOT -Scope Global -ErrorAction SilentlyContinue
+    Remove-Variable MCPEE_TELEMETRY_SESSION_ID -Scope Global -ErrorAction SilentlyContinue
+    Remove-Variable MCPEE_TELEMETRY_LAST_HISTORY_ID -Scope Global -ErrorAction SilentlyContinue
+    Remove-Variable MCPEE_TELEMETRY_LAST_STAMP -Scope Global -ErrorAction SilentlyContinue
+    Write-Host '[ok] Hook desactivado en la sesion actual.'
+}
+
+Remove-FromProfile -ProfilePath $PROFILE.CurrentUserCurrentHost
+if ($AllHosts) {
+    Remove-FromProfile -ProfilePath $PROFILE.CurrentUserAllHosts
+}
+
+Write-Host '[ok] Telemetria global de terminal desactivada.'