log10x-mcp 1.8.2 → 1.12.0

package/README.md

@@ -25,11 +25,27 @@ Log10x fingerprints every log line into a stable `templateHash` — a structural
 
 | Tool | Answers | Tier |
 |---|---|---|
-| `log10x_investigate` | "Why is this spiking?" — single-call root-cause: anchor resolution, trajectory shape detection (acute-spike vs drift), cross-pattern lag correlation, causal chain with stat/lag/chain confidence sub-scores, drift cohort analysis, two-stage Retriever fallback, verification commands. Surfaces log-only signals (pool saturation, cache evictions, retry amplification) that APM structurally cannot see. | Reporter |
+| `log10x_investigate` | "Why is this spiking?" — single-call investigation: anchor resolution, trajectory shape (acute-spike vs drift), cross-pattern lag correlation, temporal-evidence chain with stat/lag/chain confidence sub-scores, drift cohort analysis, two-stage Retriever fallback, recommended next actions. Returns observations + suggestions, NOT verdicts — output framed as "strongest temporal evidence (lead by lag time, not proven cause)." Tags `threshold_basis: "unvalidated_default"` until the operator points `LOG10X_THRESHOLDS_FILE` at calibrated overrides. Surfaces log-only signals (pool saturation, cache evictions, retry amplification) that APM structurally cannot see. See [`docs/cross-pillar-primitives.md`](docs/cross-pillar-primitives.md) for the agent behavior contract. | Reporter |
 | `log10x_resolve_batch` | "Triage these events" — paste a file / array / text dump of raw log lines and get per-pattern frequency, severity, variable concentration, and next-action suggestions. Runs via the Log10x paste endpoint; works at any tier including CLI-only. | None |
 | `log10x_retriever_query` | "Get me the actual events" — direct retrieval from the Retriever archive by templateHash with JS filter expressions over event payloads. Queries the customer's own S3 via pre-computed Bloom filters. Answers forensic, audit, and out-of-retention retrieval. | Retriever |
 | `log10x_backfill_metric` | "Create a new Datadog metric backfilled with 90 days of history" — pulls historical events from the Retriever, aggregates into a bucketed time series, emits to the destination TSDB with historical timestamps preserved. Datadog + Prometheus remote_write supported today. | Retriever |
 
+### Cross-pillar correlation primitives
+
+Three deterministic primitives that take a log-pattern anchor and customer Prometheus metric candidates, then answer "which metrics moved with this log pattern, when, and by how much." They compose into a cascade narrative: filter → rank → overlay.
+
+| Tool | Answers | Tier |
+|---|---|---|
+| `log10x_metrics_that_moved` | "Of these N customer metrics, which ones moved with my log pattern?" — deterministic phase-gap filter. Returns `moved[]`, `not_moved[]`, `evaluation_failed[]`. | Reporter + customer Prometheus |
+| `log10x_rank_by_shape_similarity` | "Of the metrics that moved, which match the anchor's shape best, and which moved first?" — Pearson + signed lag scan. Returns ranked candidates with `lag_seconds`, `lag_at_bound`, `anchor_phase_aligned`. | Reporter + customer Prometheus |
+| `log10x_metric_overlay` | "Show me the two curves side by side." — aligned timeseries + deterministic peak facts (`peak_offset_seconds`, etc.). No Pearson, no tier — raw data. | Reporter + customer Prometheus |
+
+**Designed for AI callers, not humans.** Every output carries a unified envelope: `status`, `threshold_basis`, `anchor_ref` echo, `query_count`, `total_latency_ms`, `backend_pressure_hint`, and a `human_summary` field the agent can paste to a human. `metric_ref` round-trips identically across the three tools — pass it from one output to the next input verbatim.
+
+**Calibration honesty.** The default thresholds (15% phase gap, ±1800s lag search) are hand-picked from one synthetic chaos test, not calibrated against any real customer backend. Every tool tags `threshold_basis: "unvalidated_default"` until a caller-supplied override moves it to `caller_override`. Agents MUST NOT auto-mitigate based on uncalibrated findings. See [`docs/cross-pillar-primitives.md`](docs/cross-pillar-primitives.md) for the full agent behavior contract and the per-backend calibration playbook.
+
+**Structural guards.** When the anchor doesn't have a real busy/quiet split, the tool refuses with `status: "anchor_no_phase_separation"` rather than producing nonsense. When the candidate set produces zero meaningful signal, the tool returns `status: "no_signal"` so the agent stops searching cleanly. Backend errors surface as a structured `PrimitiveError` envelope (`error_type`, `retryable`, `suggested_backoff_ms`, `hint`), not thrown strings.
+
 All tools query `prometheus.log10x.com` (for Reporter-tier tools) over HTTPS, with the same `X-10X-Auth` header used by the rest of the Log10x stack. No log scanning; sub-second at any scale.
 
 ## ROI examples — three real flows
@@ -134,6 +150,15 @@ Every pattern is ranked by an interestingness score (severity-weighted); the dom
 
 ## Install
 
+### Engine compatibility
+
+| MCP version | tenx engine required | Notes |
+|---|---|---|
+| 1.8.13+ | **1.0.22+** (recommended) | `log10x_resolve_batch` `privacy_mode: true` invokes `tenx @apps/mcp` (stdin/stdout, no temp files). Requires `apps/mcp` shipped in the engine release — first available in 1.0.22. |
+| 1.8.x | 1.0.21 (with `TENX_CONFIG`+`TENX_MODULES` overrides) | Earlier engines can run the MCP only if the user clones `log-10x/config` + `log-10x/modules` at the apps/mcp branches and points `TENX_CONFIG`/`TENX_MODULES` at them. |
+
+`brew upgrade log10x` pulls the latest released engine. See https://doc.log10x.com/install/ for OS-specific installers.
+
 ### Claude Desktop
 
 Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
@@ -215,7 +240,7 @@ You never call tools directly. Just ask your AI assistant a question in plain En
 
 ## Cost driver algorithm
 
-When you ask about cost spikes, the server runs the same algorithm as the Log10x Slack bot:
+When you ask about cost spikes, the server runs this algorithm:
 
 1. **Query current window** — bytes per pattern for the selected timeframe
 2. **Query baseline** — average of the 3 prior windows of the same size

package/build/index.d.ts

@@ -5,4 +5,5 @@
  * Gives AI assistants real-time access to per-pattern log cost attribution data.
  * Queries pre-aggregated Prometheus metrics — no log scanning, sub-second at any scale.
  */
-export {};
+import { type ModeResolution } from './lib/mode-detect.js';
+export declare function getBootMode(): ModeResolution;