@agent-inspect/mcp-server 6.14.0 → 6.14.2

package/README.md

@@ -1,64 +1,73 @@
 # @agent-inspect/mcp-server
 
-Read-only MCP server exposing local trace listings (no tool invocation, no mutation).
+Read-only MCP server for the **local coding-agent debug loop**: list runs, summarize failures, inspect trees, evaluate contracts, and fetch **TraceFacts** (`get_trace_facts`) — without invoking agent tools or mutating traces.
 
 
 **Support level:** Preview — see [SUPPORT-LEVELS.md](https://github.com/rajudandigam/agent-inspect/blob/main/docs/SUPPORT-LEVELS.md).
 
 ## When to use
 
-- Let MCP-compatible clients **read** trace metadata from disk
-- Local dev assistants that browse `.agent-inspect/`
+- Let Cursor, Claude Code, Codex, Gemini, or other MCP clients inspect local `.agent-inspect/` evidence
+- Debug failed trajectories with the same TraceFacts used by CLI checks
 
 ## When not to use
 
-- Invoking agent tools through MCP
-- Uploading traces to a remote MCP host
+- Invoking target-app tools through MCP
+- Uploading traces to a remote MCP host / collector
+- Expecting the server to edit application code
 
 ## Install
 
 ```bash
 npm install @agent-inspect/mcp-server
+# optional helper:
+npx agent-inspect mcp configure --client cursor
 ```
 
 ## Example
 
 ```bash
 npx @agent-inspect/mcp-server --dir .agent-inspect
-# or after install:
-# npx agent-inspect-mcp-server --dir .agent-inspect
 ```
 
+## Flagship tools (read-only)
+
+| Tool | Role |
+|------|------|
+| `list_recent_runs` / `list_recent_failures` | Browse local runs |
+| `get_run_summary` / `get_execution_tree` | Bounded summaries |
+| `get_first_causal_failure` | Deterministic first causal failure |
+| `get_contract_failures` | TraceContract / check failures |
+| `get_trace_facts` | TraceFacts / semantic parity summary |
+| `compare_runs` | Structural diff |
+| `create_share_checked_evidence` | Share-gated Evidence package |
+
+Results are redacted (share profile by default), bounded, and deterministic for the same inputs.
+
 ## Privacy
 
 - Reads local trace directory only
 - Tool results go through a share-profile redaction / size boundary
 - Exposes configured local evidence to the **connected MCP client** — treat that client as a trust boundary
-- No trace mutation; no agent tool invocation
+- No trace mutation; no agent tool invocation; no default upload
 
 ## Limitations
 
 - Preview surface — tool catalog and bounds may evolve
 - Not a gateway or remote upload service
-
-## API
-
-CLI entry: read-only resources for trace listing/search.
-
-## CLI
-
-Prefer `agent-inspect list` / `view` for humans; MCP server for tool integrations.
+- Not a substitute for hosted APM
 
 ## Docs
 
-- [Root README](https://github.com/rajudandigam/agent-inspect#readme)
+- [CODING-AGENT-LOOP.md](https://github.com/rajudandigam/agent-inspect/blob/main/docs/CODING-AGENT-LOOP.md)
+- [TRACE-FACTS.md](https://github.com/rajudandigam/agent-inspect/blob/main/docs/TRACE-FACTS.md)
+- [NO-EGRESS-POLICY.md](https://github.com/rajudandigam/agent-inspect/blob/main/docs/NO-EGRESS-POLICY.md)
 
 ## Troubleshooting
 
 - **Empty resources:** Confirm `--dir` points at JSONL traces
 - **Security:** Do not expose server beyond localhost without redaction review
 
-
 ## Version
 
 Part of the fixed AgentInspect release line. See the npm badge / package manifest for the current version.

package/dist/{chunk-C6EBJS57.mjs → chunk-7AL325ZU.mjs}

@@ -2568,6 +2568,73 @@ function diffRuns(left, right, options) {
   return table;
 })();
 
+// packages/core/src/safety/sensitive-key.ts
+function normalizeSensitiveKey(value) {
+  return value.toLowerCase().replace(/[^a-z0-9_]/g, "");
+}
+var NON_CREDENTIAL_TOKEN_CONFIG_KEYS = new Set(
+  [
+    "tokens",
+    "max_tokens",
+    "min_tokens",
+    "ls_max_tokens",
+    "token_count",
+    "token_limit",
+    "token_budget",
+    "input_tokens",
+    "output_tokens",
+    "total_tokens",
+    "cached_tokens",
+    "prompt_tokens",
+    "completion_tokens"
+  ].map(normalizeSensitiveKey)
+);
+var DEFAULT_CREDENTIAL_SENSITIVE_KEYS = [
+  "authorization",
+  "cookie",
+  "token",
+  "access_token",
+  "accesstoken",
+  "auth_token",
+  "authtoken",
+  "refresh_token",
+  "refreshtoken",
+  "id_token",
+  "idtoken",
+  "bearer_token",
+  "bearertoken",
+  "api_token",
+  "apitoken",
+  "apikey",
+  "api_key",
+  "password",
+  "secret",
+  "email"
+];
+function isTokenCredentialKey(normalized) {
+  if (NON_CREDENTIAL_TOKEN_CONFIG_KEYS.has(normalized)) return false;
+  if (normalized === "token") return true;
+  if (normalized.endsWith("tokens")) return false;
+  return normalized.endsWith("token");
+}
+function isCredentialSensitiveKey(key, sensitiveKeys = DEFAULT_CREDENTIAL_SENSITIVE_KEYS) {
+  if (!key) return false;
+  const normalized = normalizeSensitiveKey(key);
+  if (!normalized) return false;
+  if (NON_CREDENTIAL_TOKEN_CONFIG_KEYS.has(normalized)) return false;
+  for (const sensitive of sensitiveKeys) {
+    const s = normalizeSensitiveKey(sensitive);
+    if (!s) continue;
+    if (s === "token") {
+      if (isTokenCredentialKey(normalized)) return true;
+      continue;
+    }
+    if (normalized === s) return true;
+    if (normalized.endsWith(`_${s}`) || normalized.startsWith(`${s}_`)) return true;
+  }
+  return false;
+}
+
 // packages/core/src/checks/logical-events.ts
 function isRecord6(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -2763,6 +2830,23 @@ function projectLogicalEvents(events) {
       }
     }
     if (!remapped) {
+      if (originalParentId === event.eventId) {
+        diagnostics.push({
+          code: "AI_LOGICAL_SELF_PARENT_REMOVED",
+          message: `Removed self-parent edge on ${event.eventId}.`,
+          eventIds: [event.eventId]
+        });
+        const { parentId: _drop, ...rest } = event;
+        normalized.push({
+          ...rest,
+          projection: {
+            ...event.projection,
+            parentNormalized: true,
+            originalParentId
+          }
+        });
+        continue;
+      }
       if (!logicalById.has(originalParentId) && !logicalByRawId.has(originalParentId)) {
         const mapping = event.attributes?.parentMapping;
         const unresolved = mapping === "unresolved" || event.attributes?.parentUnresolved === true || event.attributes?.unresolvedParent === true || // LangGraph/framework scaffolding sentinel labels are not event ids.
@@ -2778,6 +2862,23 @@ function projectLogicalEvents(events) {
       normalized.push(event);
       continue;
     }
+    if (nextParent === event.eventId) {
+      diagnostics.push({
+        code: "AI_LOGICAL_SELF_PARENT_REMOVED",
+        message: `Removed self-parent edge on ${event.eventId} (was ${originalParentId}).`,
+        eventIds: [event.eventId]
+      });
+      const { parentId: _drop, ...rest } = event;
+      normalized.push({
+        ...rest,
+        projection: {
+          ...event.projection,
+          parentNormalized: true,
+          originalParentId
+        }
+      });
+      continue;
+    }
     diagnostics.push({
       code: "AI_LOGICAL_PARENT_REMAPPED",
       message: `Remapped parent ${originalParentId} \u2192 ${nextParent} for ${event.eventId}.`,
@@ -2894,16 +2995,7 @@ var STATUS_RANK = {
   warning: 1,
   pass: 2
 };
-var DEFAULT_SENSITIVE_KEYS = [
-  "authorization",
-  "cookie",
-  "token",
-  "apikey",
-  "api_key",
-  "password",
-  "secret",
-  "email"
-];
+var DEFAULT_SENSITIVE_KEYS = DEFAULT_CREDENTIAL_SENSITIVE_KEYS;
 var DEFAULT_RAW_CONTENT_KEYS = [
   "body",
   "headers",
@@ -3258,9 +3350,7 @@ function hasRedactionMarker(value, markers) {
   return markers.some((marker) => value.includes(marker)) || /^\[HASH:[A-Za-z0-9_-]+\]$/.test(value);
 }
 function isSensitiveKey(key, sensitiveKeys) {
-  if (!key) return false;
-  const normalized = normalizedKey(key);
-  return sensitiveKeys.some((sensitive) => normalized.includes(normalizedKey(sensitive)));
+  return isCredentialSensitiveKey(key, sensitiveKeys);
 }
 function isRawContentKey(key, forbiddenKeys) {
   if (!key) return false;
@@ -3830,6 +3920,20 @@ function traceEventsToPersistedInspectEvents(events, options) {
 function inc(map, key) {
   map[key] = (map[key] ?? 0) + 1;
 }
+function confidenceRank(confidence) {
+  switch (confidence) {
+    case "unknown":
+      return 0;
+    case "heuristic":
+      return 1;
+    case "correlated":
+      return 2;
+    case "explicit":
+      return 3;
+    default:
+      return 0;
+  }
+}
 function computeRunStatus(events) {
   let runTerminal;
   let sawRunEvent = false;
@@ -3850,6 +3954,84 @@ function computeRunStatus(events) {
   }
   return hasRunning ? "running" : "ok";
 }
+function linkNodesVisibilityFirst(nodes) {
+  let selfParentCount = 0;
+  let unresolvedParentCount = 0;
+  let normalizedEdgeCount = 0;
+  let cycleCount = 0;
+  const pending = [];
+  for (const node of nodes.values()) {
+    const parentId = node.event.parentId;
+    if (!parentId) continue;
+    if (parentId === node.event.eventId) {
+      selfParentCount += 1;
+      normalizedEdgeCount += 1;
+      continue;
+    }
+    if (!nodes.has(parentId)) {
+      unresolvedParentCount += 1;
+      continue;
+    }
+    pending.push({
+      childId: node.event.eventId,
+      parentId,
+      childTimestamp: node.event.timestamp,
+      childConfidence: node.event.confidence
+    });
+  }
+  pending.sort((a, b) => {
+    const conf = confidenceRank(b.childConfidence) - confidenceRank(a.childConfidence);
+    if (conf !== 0) return conf;
+    return a.childTimestamp - b.childTimestamp;
+  });
+  const parentOf = /* @__PURE__ */ new Map();
+  for (const edge of pending) {
+    parentOf.set(edge.childId, edge.parentId);
+    let cursor = edge.parentId;
+    const seen = /* @__PURE__ */ new Set([edge.childId]);
+    let cyclic = false;
+    while (cursor) {
+      if (seen.has(cursor)) {
+        cyclic = true;
+        break;
+      }
+      seen.add(cursor);
+      cursor = parentOf.get(cursor);
+    }
+    if (cyclic) {
+      parentOf.delete(edge.childId);
+      cycleCount += 1;
+      normalizedEdgeCount += 1;
+    }
+  }
+  for (const [childId, parentId] of parentOf) {
+    nodes.get(parentId).children.push(nodes.get(childId));
+  }
+  const roots = [];
+  for (const node of nodes.values()) {
+    if (!parentOf.has(node.event.eventId)) {
+      roots.push(node);
+    }
+  }
+  const assignDepth = (n, depth, stack) => {
+    if (stack.has(n.event.eventId)) return;
+    n.depth = depth;
+    stack.add(n.event.eventId);
+    for (const c of n.children) assignDepth(c, depth + 1, stack);
+    stack.delete(n.event.eventId);
+  };
+  for (const r of roots) assignDepth(r, 0, /* @__PURE__ */ new Set());
+  return {
+    roots,
+    summary: {
+      rootCount: roots.length,
+      selfParentCount,
+      cycleCount,
+      unresolvedParentCount,
+      normalizedEdgeCount
+    }
+  };
+}
 var TreeBuilder = class {
   constructor(options) {
     void options?.config;
@@ -3867,20 +4049,7 @@ var TreeBuilder = class {
       for (const e of sorted) {
         nodes.set(e.eventId, { event: e, children: [], depth: 0 });
       }
-      const roots = [];
-      for (const node of nodes.values()) {
-        const parentId = node.event.parentId;
-        if (parentId && nodes.has(parentId)) {
-          nodes.get(parentId).children.push(node);
-        } else {
-          roots.push(node);
-        }
-      }
-      const assignDepth = (n, depth) => {
-        n.depth = depth;
-        for (const c of n.children) assignDepth(c, depth + 1);
-      };
-      for (const r of roots) assignDepth(r, 0);
+      const { roots, summary } = linkNodesVisibilityFirst(nodes);
       const confidenceBreakdown = {
         explicit: 0,
         correlated: 0,
@@ -3908,7 +4077,8 @@ var TreeBuilder = class {
         metadata: {
           totalEvents: sorted.length,
           confidenceBreakdown,
-          kinds
+          kinds,
+          relationshipSummary: summary
         }
       });
     }
@@ -6322,6 +6492,53 @@ function exportRunTree(tree, options) {
     }
   }
 }
+
+// packages/redact/src/sensitive-key.ts
+function normalizeSensitiveKey2(value) {
+  return value.toLowerCase().replace(/[^a-z0-9_]/g, "");
+}
+var NON_CREDENTIAL_TOKEN_CONFIG_KEYS2 = new Set(
+  [
+    "tokens",
+    "max_tokens",
+    "min_tokens",
+    "ls_max_tokens",
+    "token_count",
+    "token_limit",
+    "token_budget",
+    "input_tokens",
+    "output_tokens",
+    "total_tokens",
+    "cached_tokens",
+    "prompt_tokens",
+    "completion_tokens"
+  ].map(normalizeSensitiveKey2)
+);
+function isTokenCredentialKey2(normalized) {
+  if (NON_CREDENTIAL_TOKEN_CONFIG_KEYS2.has(normalized)) return false;
+  if (normalized === "token") return true;
+  if (normalized.endsWith("tokens")) return false;
+  return normalized.endsWith("token");
+}
+function isCredentialSensitiveKey2(key, sensitiveKeys) {
+  if (!key) return false;
+  const normalized = normalizeSensitiveKey2(key);
+  if (!normalized) return false;
+  if (NON_CREDENTIAL_TOKEN_CONFIG_KEYS2.has(normalized)) return false;
+  for (const sensitive of sensitiveKeys) {
+    const s = normalizeSensitiveKey2(sensitive);
+    if (!s) continue;
+    if (s === "token") {
+      if (isTokenCredentialKey2(normalized)) return true;
+      continue;
+    }
+    if (normalized === s) return true;
+    if (normalized.endsWith(`_${s}`) || normalized.startsWith(`${s}_`)) return true;
+  }
+  return false;
+}
+
+// packages/redact/src/index.ts
 var DEFAULT_REDACT_KEYS2 = [
   "authorization",
   "cookie",
@@ -6383,6 +6600,12 @@ function isRecord11(value) {
 function toKey2(key) {
   return key.toLowerCase();
 }
+function findCompiledKeyRule(key, rules) {
+  const exact = toKey2(key);
+  const direct = rules.find((candidate) => candidate.key === exact);
+  if (direct) return direct;
+  return rules.find((candidate) => isCredentialSensitiveKey2(key, [candidate.key]));
+}
 function stableHash2(value) {
   const hash = crypto.createHash("sha256").update(value, "utf8").digest("hex");
   return hash.slice(0, 8);
@@ -6704,7 +6927,7 @@ var Redactor2 = class {
       return "[Truncated]";
     }
     if (key !== void 0) {
-      const rule = this.#rules.find((candidate) => candidate.key === toKey2(key));
+      const rule = findCompiledKeyRule(key, this.#rules);
       if (rule) {
         this.#recordFinding(
           state,
@@ -7586,5 +7809,5 @@ async function runReadOnlyMcpServer(options = {}) {
 }
 
 export { MCP_MAX_REQUEST_BYTES, MCP_PROTOCOL_VERSION, READ_ONLY_TOOLS, callReadOnlyTool, createMcpServerContext, handleMcpProtocolLine, runReadOnlyMcpServer };
-//# sourceMappingURL=chunk-C6EBJS57.mjs.map
-//# sourceMappingURL=chunk-C6EBJS57.mjs.map
+//# sourceMappingURL=chunk-7AL325ZU.mjs.map
+//# sourceMappingURL=chunk-7AL325ZU.mjs.map