feat(lsp): indicizzazione globale, goto definition cross-file e rename multi-file

Author: Christian Quintino De Luca

README.md

@@ -108,6 +108,39 @@ python aspera_cli.py run --aspera aspera/lang/examples/empathetic.aspera --signa
 python aspera_cli.py validate ast.json
 ```
 
+### LSP (Language Server) Setup
+
+Per abilitare diagnostica in editor e completamento base:
+
+```powershell
+# Avvio server LSP (stdin/stdout)
+python -m aspera.tools.lsp_server
+# oppure, se installato come script
+aspera-lsp
+```
+
+In VS Code, configura un client LSP generico puntando al comando sopra. Aggiungi anche `.vscode/settings.json` con:
+
+```json
+{
+  "ltex.language": "it-IT",
+  "python.analysis.diagnosticMode": "openFilesOnly"
+}
+```
+
+Funzionalità attuali: diagnostica parser in tempo reale, completion basica (`concept.`, `signals.`, `state.`, `threshold(`).
+
+### Telemetry (OpenTelemetry)
+
+ASPERA emette traces/metrics OTLP (HTTP) per observe/step/decide. Per provare in locale:
+
+```powershell
+$env:OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"
+python aspera_cli.py run --aspera agents\enterprise\ecommerce_conversion_optimizer\conversion_optimizer.aspera --signals examples\signals_ecommerce.json --mode mock
+```
+
+Metriche principali: `aspera_observe_total`, `aspera_step_total`, `aspera_decide_total`. Configura il tuo collector OTLP (es. OpenTelemetry Collector) e visualizza in Grafana/Tempo.
+
 ### Smoke test con Groq (tutti gli agent)
 
 ```powershell

aspera/runtime/engine.py

@@ -27,6 +27,8 @@
     retry_with_backoff,
     log_error_structured,
 )
+from aspera.runtime.otel import init_otel
+from opentelemetry import trace, metrics
 
 logger = logging.getLogger(__name__)
 
@@ -115,6 +117,20 @@ def __init__(
         }
 
         logger.info("CognitiveEngine initialized")
+        # OpenTelemetry (best effort)
+        try:
+            init_otel()
+            self._tracer = trace.get_tracer("aspera.engine")
+            self._meter = metrics.get_meter("aspera.engine")
+            self._obs_step = self._meter.create_counter("aspera_observe_total")
+            self._step_counter = self._meter.create_counter("aspera_step_total")
+            self._decide_counter = self._meter.create_counter("aspera_decide_total")
+        except Exception:
+            self._tracer = None
+            self._meter = None
+            self._obs_step = None
+            self._step_counter = None
+            self._decide_counter = None
 
     def load_ast(self, ast: Dict[str, Any]):
         """
@@ -186,6 +202,11 @@ def observe(self, signals: Dict[str, Any], context: Dict[str, Any] = None):
         )
 
         logger.info(f"Observed signals: {list(signals.keys())}")
+        try:
+            if self._obs_step:
+                self._obs_step.add(1)
+        except Exception:
+            pass
         self.metrics["durations"]["observe"] = round((time.perf_counter() - t0) * 1000, 2)
 
     def step(self) -> Dict[str, Any]:
@@ -295,6 +316,11 @@ def step(self) -> Dict[str, Any]:
         })
 
         self.metrics["durations"]["step"] = round((time.perf_counter() - t0) * 1000, 2)
+        try:
+            if self._step_counter:
+                self._step_counter.add(1)
+        except Exception:
+            pass
         logger.info(f"Step completed: {len(applied_inferences)} inferences applied, {len(all_changes)} changes")
         return step_result
 
@@ -321,6 +347,11 @@ def decide(self) -> List[Dict[str, Any]]:
         })
 
         self.metrics["counts"]["actions"] = len(actions)
+        try:
+            if self._decide_counter:
+                self._decide_counter.add(1)
+        except Exception:
+            pass
         logger.info(f"Decision completed: {len(actions)} actions selected")
         return actions
 

aspera/runtime/otel.py

@@ -0,0 +1,37 @@
+"""
+OpenTelemetry setup per ASPERA Runtime (traces + metrics OTLP).
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+from opentelemetry import trace, metrics
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.metrics import MeterProvider
+from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter
+from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
+
+
+def init_otel(service_name: str = "aspera-runtime", endpoint: Optional[str] = None) -> None:
+    endpoint = endpoint or os.getenv("OTEL_EXPORTER_OTLP_ENDPOINT", "http://localhost:4318")
+    resource = Resource.create({"service.name": service_name})
+
+    # Traces
+    tracer_provider = TracerProvider(resource=resource)
+    trace.set_tracer_provider(tracer_provider)
+    span_exporter = OTLPSpanExporter(endpoint=f"{endpoint}/v1/traces")
+    tracer_provider.add_span_processor(BatchSpanProcessor(span_exporter))
+
+    # Metrics
+    metric_exporter = OTLPMetricExporter(endpoint=f"{endpoint}/v1/metrics")
+    reader = PeriodicExportingMetricReader(metric_exporter)
+    meter_provider = MeterProvider(resource=resource, metric_readers=[reader])
+    metrics.set_meter_provider(meter_provider)
+
+
+