@agent-inspect/mcp-server 6.31.21 → 6.31.23

package/dist/cli.mjs

@@ -1,4 +1,4 @@
-import { runReadOnlyMcpServer } from './chunk-L5YP42Q6.mjs';
+import { runReadOnlyMcpServer } from './chunk-XLIQEKWB.mjs';
 import { readFileSync } from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';

package/dist/index.cjs

@@ -4092,6 +4092,184 @@ function runTraceChecks(input, options = {}) {
   };
 }
 
+// packages/core/src/checks/canonical-equality.ts
+var DEFAULT_MAX_DEPTH = 8;
+var DEFAULT_MAX_BYTES = 16384;
+function sortKeysDeep(input, depth, maxDepth) {
+  if (depth > maxDepth) {
+    throw new Error("AI_CHECK_CANONICAL_DEPTH_EXCEEDED");
+  }
+  if (input === null || typeof input !== "object") return input;
+  if (Array.isArray(input)) {
+    return input.map((item) => sortKeysDeep(item, depth + 1, maxDepth));
+  }
+  const record = input;
+  const out = {};
+  for (const key of Object.keys(record).sort()) {
+    out[key] = sortKeysDeep(record[key], depth + 1, maxDepth);
+  }
+  return out;
+}
+function encodeCanonicalStructured(value, limits) {
+  const maxDepth = DEFAULT_MAX_DEPTH;
+  const maxBytes = DEFAULT_MAX_BYTES;
+  try {
+    const sorted = sortKeysDeep(value, 0, maxDepth);
+    const encoded = JSON.stringify(sorted);
+    if (encoded === void 0) {
+      return {
+        ok: false,
+        reason: "Value is not JSON-serializable for canonical comparison.",
+        code: "AI_CHECK_CANONICAL_UNSERIALIZABLE"
+      };
+    }
+    if (Buffer.byteLength(encoded, "utf8") > maxBytes) {
+      return {
+        ok: false,
+        reason: "Canonical structured value exceeds bounded size limit.",
+        code: "AI_CHECK_CANONICAL_SIZE_EXCEEDED"
+      };
+    }
+    return { ok: true, value: encoded };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (message === "AI_CHECK_CANONICAL_DEPTH_EXCEEDED") {
+      return {
+        ok: false,
+        reason: "Canonical structured value exceeds bounded depth limit.",
+        code: "AI_CHECK_CANONICAL_DEPTH_EXCEEDED"
+      };
+    }
+    return {
+      ok: false,
+      reason: "Canonical structured encoding failed.",
+      code: "AI_CHECK_CANONICAL_UNSERIALIZABLE"
+    };
+  }
+}
+
+// packages/core/src/persisted/delivery-identity.ts
+var DELIVERY_CONFLICT_ATTR = "agent_inspect.delivery_conflict";
+var DELIVERY_EVENT_BASE_ATTR = "agent_inspect.delivery_event_base";
+var IDENTITY_CONFLICT_ATTR = {
+  operationId: "agent_inspect.identity_conflict.operation_id",
+  attemptId: "agent_inspect.identity_conflict.attempt_id",
+  retryOf: "agent_inspect.identity_conflict.retry_of",
+  attemptNumber: "agent_inspect.identity_conflict.attempt_number",
+  /** Comma-separated field names when a conflict survives lossy bounding. */
+  fields: "agent_inspect.identity_conflict.fields"
+};
+var MAX_DELIVERY_BASE_LEN = 500;
+function stripReaderDeliveryDiscriminator(eventId, attributes) {
+  if (!eventId) return eventId;
+  const rawBase = attributes?.[DELIVERY_EVENT_BASE_ATTR];
+  if (typeof rawBase !== "string" || rawBase.trim() === "") return eventId;
+  const base = rawBase.trim().slice(0, MAX_DELIVERY_BASE_LEN);
+  if (eventId === base) return base;
+  const prefix = `${base}:`;
+  if (!eventId.startsWith(prefix)) return eventId;
+  const suffix = eventId.slice(prefix.length);
+  if (/^\d+$/.test(suffix)) return base;
+  return eventId;
+}
+function deliveryEventBaseFromIndexedId(eventId) {
+  if (!/:\d+$/.test(eventId)) return void 0;
+  const base = eventId.replace(/:\d+$/, "");
+  return base.length > 0 ? base.slice(0, MAX_DELIVERY_BASE_LEN) : void 0;
+}
+function canonicalDigest(value) {
+  if (value === void 0) return null;
+  const encoded = encodeCanonicalStructured(value);
+  return encoded.ok ? encoded.value : `unencodable:${encoded.code}`;
+}
+function capturedContentDigest(attributes) {
+  if (!attributes || typeof attributes !== "object") {
+    return { args: null, result: null };
+  }
+  const nested = attributes.metadata && typeof attributes.metadata === "object" ? attributes.metadata : void 0;
+  const args = attributes.arguments ?? attributes.args ?? attributes.input ?? nested?.arguments ?? nested?.args ?? nested?.input;
+  const result = attributes.result ?? attributes.output ?? attributes.response ?? nested?.result ?? nested?.output ?? nested?.response;
+  return {
+    args: args === void 0 ? null : canonicalDigest(args),
+    result: result === void 0 ? null : canonicalDigest(result)
+  };
+}
+function timeKey(fields) {
+  if (typeof fields.startedAt === "string" && fields.startedAt.trim() !== "") {
+    return fields.startedAt;
+  }
+  if (typeof fields.timestamp === "string" && fields.timestamp.trim() !== "") {
+    return fields.timestamp;
+  }
+  if (typeof fields.timestamp === "number" && Number.isFinite(fields.timestamp)) {
+    return String(fields.timestamp);
+  }
+  return null;
+}
+function deliverySemanticFingerprint(fields) {
+  const content = capturedContentDigest(fields.attributes);
+  return JSON.stringify({
+    stableEventId: stripReaderDeliveryDiscriminator(fields.eventId, fields.attributes),
+    runId: fields.runId,
+    kind: fields.kind,
+    name: fields.name,
+    status: fields.status ?? null,
+    parentId: fields.parentId ?? null,
+    sourceType: fields.sourceType ?? null,
+    time: timeKey(fields),
+    operationId: fields.operationId ?? null,
+    attemptId: fields.attemptId ?? null,
+    attemptNumber: fields.attemptNumber ?? null,
+    retryOf: fields.retryOf ?? null,
+    argsDigest: content.args,
+    resultDigest: content.result
+  });
+}
+function identityFieldsFromAttributes(attributes) {
+  if (!attributes || typeof attributes !== "object") {
+    return {
+      operationId: null,
+      attemptId: null,
+      attemptNumber: null,
+      retryOf: null
+    };
+  }
+  const nested = attributes.metadata && typeof attributes.metadata === "object" && !Array.isArray(attributes.metadata) ? attributes.metadata : void 0;
+  const pickString3 = (key) => {
+    const direct = attributes[key];
+    if (typeof direct === "string" && direct.trim() !== "") return direct.trim();
+    const nestedValue = nested?.[key];
+    if (typeof nestedValue === "string" && nestedValue.trim() !== "") {
+      return nestedValue.trim();
+    }
+    return null;
+  };
+  const pickNumber2 = () => {
+    const direct = attributes.attemptNumber ?? attributes.attempt;
+    if (typeof direct === "number" && Number.isFinite(direct)) return direct;
+    const nestedValue = nested?.attemptNumber ?? nested?.attempt;
+    if (typeof nestedValue === "number" && Number.isFinite(nestedValue)) {
+      return nestedValue;
+    }
+    return null;
+  };
+  return {
+    operationId: pickString3("operationId"),
+    attemptId: pickString3("attemptId"),
+    retryOf: pickString3("retryOf"),
+    attemptNumber: pickNumber2()
+  };
+}
+function stampDeliveryConflict(event) {
+  return {
+    ...event,
+    attributes: {
+      ...event.attributes ?? {},
+      [DELIVERY_CONFLICT_ATTR]: true
+    }
+  };
+}
+
 // packages/core/src/checks/contract.ts
 new Set(OBSERVED_OUTCOME_METHODS);
 
@@ -4129,18 +4307,18 @@ function escapeMarkdown(value) {
 function escapeHtml(value) {
   return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
 }
-function sortKeysDeep(input) {
+function sortKeysDeep2(input) {
   if (input === null || typeof input !== "object") return input;
-  if (Array.isArray(input)) return input.map(sortKeysDeep);
+  if (Array.isArray(input)) return input.map(sortKeysDeep2);
   const o = input;
   const out = {};
   for (const k of Object.keys(o).sort()) {
-    out[k] = sortKeysDeep(o[k]);
+    out[k] = sortKeysDeep2(o[k]);
   }
   return out;
 }
 function stableJson(value, pretty) {
-  const sorted = sortKeysDeep(value);
+  const sorted = sortKeysDeep2(value);
   return pretty === true ? JSON.stringify(sorted, null, 2) : JSON.stringify(sorted);
 }
 function compactAttributes(attrs2, options) {
@@ -4677,6 +4855,11 @@ function compactAttributes2(entries) {
   }
   return Object.keys(out).length > 0 ? out : void 0;
 }
+function stampDeliveryEventBase(eventId, attributes) {
+  const base = deliveryEventBaseFromIndexedId(eventId);
+  if (!base) return attributes;
+  return { ...attributes ?? {}, [DELIVERY_EVENT_BASE_ATTR]: base };
+}
 function traceEventToPersistedInspectEvent(event, options) {
   const eventIndex = options?.eventIndex ?? 0;
   const eventId = createPersistedEventId(event, eventIndex);
@@ -4706,7 +4889,7 @@ function traceEventToPersistedInspectEvent(event, options) {
         startedAt: tsStart.iso,
         confidence: "explicit",
         source,
-        attributes
+        attributes: stampDeliveryEventBase(eventId, attributes)
       };
     }
     case "run_completed": {
@@ -4729,7 +4912,7 @@ function traceEventToPersistedInspectEvent(event, options) {
         durationMs: event.durationMs,
         confidence: "explicit",
         source,
-        attributes,
+        attributes: stampDeliveryEventBase(eventId, attributes),
         error
       };
     }
@@ -4754,7 +4937,7 @@ function traceEventToPersistedInspectEvent(event, options) {
         startedAt: tsStart.iso,
         confidence: "explicit",
         source,
-        attributes
+        attributes: stampDeliveryEventBase(eventId, attributes)
       };
       if (event.parentId !== void 0) {
         out.parentId = event.parentId;
@@ -4785,7 +4968,7 @@ function traceEventToPersistedInspectEvent(event, options) {
         durationMs: event.durationMs,
         confidence: "explicit",
         source,
-        attributes,
+        attributes: stampDeliveryEventBase(eventId, attributes),
         error
       };
     }
@@ -4812,7 +4995,7 @@ function traceEventToPersistedInspectEvent(event, options) {
         timestamp: tsMain.iso,
         confidence: "explicit",
         source,
-        attributes
+        attributes: stampDeliveryEventBase(eventId, attributes)
       };
       if (event.parentId !== void 0) {
         out.parentId = event.parentId;
@@ -4965,7 +5148,47 @@ var TreeBuilder = class {
       const sorted = [...runEvents].sort((a, b) => a.timestamp - b.timestamp);
       const nodes = /* @__PURE__ */ new Map();
       for (const e of sorted) {
-        nodes.set(e.eventId, { event: e, children: [], depth: 0 });
+        const existing = nodes.get(e.eventId);
+        if (!existing) {
+          nodes.set(e.eventId, { event: e, children: [], depth: 0 });
+          continue;
+        }
+        const existingAttrs = existing.event.attributes && typeof existing.event.attributes === "object" ? existing.event.attributes : void 0;
+        const nextAttrs = e.attributes && typeof e.attributes === "object" ? e.attributes : void 0;
+        const existingIdentity = identityFieldsFromAttributes(existingAttrs);
+        const nextIdentity = identityFieldsFromAttributes(nextAttrs);
+        const existingFp = deliverySemanticFingerprint({
+          eventId: existing.event.eventId,
+          runId: existing.event.runId,
+          kind: existing.event.kind,
+          name: existing.event.name,
+          status: existing.event.status,
+          parentId: existing.event.parentId,
+          timestamp: existing.event.timestamp,
+          sourceType: existing.event.source?.type,
+          attributes: existingAttrs,
+          ...existingIdentity
+        });
+        const nextFp = deliverySemanticFingerprint({
+          eventId: e.eventId,
+          runId: e.runId,
+          kind: e.kind,
+          name: e.name,
+          status: e.status,
+          parentId: e.parentId,
+          timestamp: e.timestamp,
+          sourceType: e.source?.type,
+          attributes: nextAttrs,
+          ...nextIdentity
+        });
+        if (existingFp === nextFp) {
+          continue;
+        }
+        nodes.set(e.eventId, {
+          event: stampDeliveryConflict(e),
+          children: [],
+          depth: 0
+        });
       }
       const { roots, summary } = linkNodesVisibilityFirst(nodes);
       const confidenceBreakdown = {
@@ -6430,6 +6653,12 @@ function promoteAgentInspectWorkflowIdentity(attributes, pathPrefix) {
     ["agent_inspect.retry_of", "retryOf", "string"],
     ["agent_inspect.attempt_number", "attemptNumber", "int"]
   ];
+  const conflictMapping = [
+    ["agent_inspect.identity_conflict.operation_id", "operationId", "string"],
+    ["agent_inspect.identity_conflict.attempt_id", "attemptId", "string"],
+    ["agent_inspect.identity_conflict.retry_of", "retryOf", "string"],
+    ["agent_inspect.identity_conflict.attempt_number", "attemptNumber", "int"]
+  ];
   const metadata = attributes.metadata && typeof attributes.metadata === "object" && !Array.isArray(attributes.metadata) ? { ...attributes.metadata } : {};
   for (const [dotted, camel, kind] of mapping) {
     const raw = attributes[dotted];
@@ -6481,6 +6710,55 @@ function promoteAgentInspectWorkflowIdentity(attributes, pathPrefix) {
     if (direct === void 0) attributes[camel] = promoted;
     if (nested === void 0) metadata[camel] = promoted;
   }
+  for (const [dotted, camel, kind] of conflictMapping) {
+    const raw = attributes[dotted];
+    if (raw === void 0 || raw === null) continue;
+    let alternate;
+    if (kind === "int") {
+      const n = typeof raw === "number" ? raw : typeof raw === "string" ? Number(raw) : NaN;
+      if (!Number.isFinite(n) || n < 1) {
+        warnings.push({
+          code: "otlp_identity_invalid",
+          message: `Ignoring invalid ${dotted} identity conflict value.`,
+          severity: "warning",
+          field: `${pathPrefix}.${dotted}`
+        });
+        continue;
+      }
+      alternate = Math.trunc(n);
+    } else if (typeof raw === "string" && raw.trim() !== "") {
+      alternate = raw.trim();
+    } else {
+      warnings.push({
+        code: "otlp_identity_invalid",
+        message: `Ignoring non-string ${dotted} identity conflict value.`,
+        severity: "warning",
+        field: `${pathPrefix}.${dotted}`
+      });
+      continue;
+    }
+    const preferred = attributes[camel];
+    if (preferred !== void 0 && preferred !== alternate) {
+      metadata[camel] = alternate;
+      warnings.push({
+        code: "otlp_identity_conflict",
+        message: `Conflicting ${camel}: attributes.${camel} vs nested alternate from ${dotted}; retaining both.`,
+        severity: "warning",
+        field: `${pathPrefix}.${dotted}`
+      });
+    } else if (preferred === void 0) {
+      metadata[camel] = alternate;
+    }
+  }
+  const conflictFields = attributes["agent_inspect.identity_conflict.fields"];
+  if (typeof conflictFields === "string" && conflictFields.trim() !== "") {
+    warnings.push({
+      code: "otlp_identity_conflict",
+      message: `Identity representation conflict fields retained after OTLP bounding: ${conflictFields.trim().slice(0, 200)}.`,
+      severity: "warning",
+      field: `${pathPrefix}.agent_inspect.identity_conflict.fields`
+    });
+  }
   if (Object.keys(metadata).length > 0) {
     attributes.metadata = metadata;
   }
@@ -7667,43 +7945,85 @@ var STRUCTURAL_IDENTITY_KEYS = [
   "attemptNumber",
   "attempt"
 ];
-function pickBoundedIdentityString(bag, key, maxLen) {
+function nestedBag(bag) {
   if (!bag || typeof bag !== "object") return void 0;
-  const direct = bag[key];
-  if (typeof direct === "string" && direct.trim() !== "") {
-    return direct.trim().slice(0, maxLen);
-  }
-  const nested = bag.metadata && typeof bag.metadata === "object" ? bag.metadata[key] : void 0;
-  if (typeof nested === "string" && nested.trim() !== "") {
-    return nested.trim().slice(0, maxLen);
+  const nested = bag.metadata;
+  if (!nested || typeof nested !== "object" || Array.isArray(nested)) return void 0;
+  return nested;
+}
+function pickBoundedIdentityString(bag, key, maxLen) {
+  if (!bag || typeof bag !== "object") return {};
+  const directRaw = bag[key];
+  const nestedRaw = nestedBag(bag)?.[key];
+  const directFull = typeof directRaw === "string" && directRaw.trim() !== "" ? directRaw.trim() : void 0;
+  const nestedFull = typeof nestedRaw === "string" && nestedRaw.trim() !== "" ? nestedRaw.trim() : void 0;
+  const direct = directFull !== void 0 ? directFull.slice(0, maxLen) : void 0;
+  const nested = nestedFull !== void 0 ? nestedFull.slice(0, maxLen) : void 0;
+  if (directFull !== void 0 && nestedFull !== void 0 && directFull !== nestedFull) {
+    return {
+      value: direct,
+      conflictAlternate: nested,
+      truncatedCollision: direct === nested
+    };
   }
-  return void 0;
+  if (direct !== void 0) return { value: direct };
+  if (nested !== void 0) return { value: nested };
+  return {};
 }
 function pickBoundedIdentityNumber(bag, key) {
-  if (!bag || typeof bag !== "object") return void 0;
-  const direct = bag[key];
-  if (typeof direct === "number" && Number.isFinite(direct)) return direct;
-  const nested = bag.metadata && typeof bag.metadata === "object" ? bag.metadata[key] : void 0;
-  if (typeof nested === "number" && Number.isFinite(nested)) return nested;
-  return void 0;
+  if (!bag || typeof bag !== "object") return {};
+  const directRaw = bag[key];
+  const nestedRaw = nestedBag(bag)?.[key];
+  const direct = typeof directRaw === "number" && Number.isFinite(directRaw) ? directRaw : void 0;
+  const nested = typeof nestedRaw === "number" && Number.isFinite(nestedRaw) ? nestedRaw : void 0;
+  if (direct !== void 0 && nested !== void 0 && direct !== nested) {
+    return { value: direct, conflictAlternate: nested };
+  }
+  if (direct !== void 0) return { value: direct };
+  if (nested !== void 0) return { value: nested };
+  return {};
 }
 function appendStructuralIdentityAttrs(attrs2, meta, maxLen) {
-  const operationId = pickBoundedIdentityString(meta, "operationId", maxLen);
-  if (operationId !== void 0) {
-    attrs2.push(stringAttr2("agent_inspect.operation_id", operationId));
+  const conflicts = [];
+  const emitString = (key, otlpKey, conflictKey) => {
+    const picked = pickBoundedIdentityString(meta, key, maxLen);
+    if (picked.value !== void 0) {
+      attrs2.push(stringAttr2(otlpKey, picked.value));
+    }
+    if (picked.conflictAlternate !== void 0 || picked.truncatedCollision) {
+      if (picked.conflictAlternate !== void 0) {
+        attrs2.push(stringAttr2(conflictKey, picked.conflictAlternate));
+      }
+      conflicts.push(key);
+    }
+  };
+  emitString("operationId", "agent_inspect.operation_id", IDENTITY_CONFLICT_ATTR.operationId);
+  emitString("attemptId", "agent_inspect.attempt_id", IDENTITY_CONFLICT_ATTR.attemptId);
+  emitString("retryOf", "agent_inspect.retry_of", IDENTITY_CONFLICT_ATTR.retryOf);
+  const attemptNumberPrimary = pickBoundedIdentityNumber(meta, "attemptNumber");
+  const attemptNumber = attemptNumberPrimary.value !== void 0 || attemptNumberPrimary.conflictAlternate !== void 0 ? attemptNumberPrimary : pickBoundedIdentityNumber(meta, "attempt");
+  if (attemptNumber.value !== void 0) {
+    attrs2.push(intAttr("agent_inspect.attempt_number", attemptNumber.value));
+  }
+  if (attemptNumber.conflictAlternate !== void 0) {
+    attrs2.push(
+      intAttr(IDENTITY_CONFLICT_ATTR.attemptNumber, attemptNumber.conflictAlternate)
+    );
+    conflicts.push("attemptNumber");
   }
-  const attemptId = pickBoundedIdentityString(meta, "attemptId", maxLen);
-  if (attemptId !== void 0) {
-    attrs2.push(stringAttr2("agent_inspect.attempt_id", attemptId));
+  if (conflicts.length > 0) {
+    attrs2.push(
+      stringAttr2(IDENTITY_CONFLICT_ATTR.fields, conflicts.join(",").slice(0, maxLen))
+    );
   }
-  const retryOf = pickBoundedIdentityString(meta, "retryOf", maxLen);
-  if (retryOf !== void 0) {
-    attrs2.push(stringAttr2("agent_inspect.retry_of", retryOf));
+  if (meta?.[DELIVERY_CONFLICT_ATTR] === true) {
+    attrs2.push(boolAttr(DELIVERY_CONFLICT_ATTR, true));
   }
-  const attemptNumber = pickBoundedIdentityNumber(meta, "attemptNumber") ?? pickBoundedIdentityNumber(meta, "attempt");
-  if (attemptNumber !== void 0) {
-    attrs2.push(intAttr("agent_inspect.attempt_number", attemptNumber));
+  const deliveryBase = meta?.[DELIVERY_EVENT_BASE_ATTR];
+  if (typeof deliveryBase === "string" && deliveryBase.trim() !== "") {
+    attrs2.push(stringAttr2(DELIVERY_EVENT_BASE_ATTR, deliveryBase.trim().slice(0, maxLen)));
   }
+  return conflicts;
 }
 function resolveSpanTimes(ev) {
   const startedAtMs = typeof ev.attributes?.startedAtMs === "number" && Number.isFinite(ev.attributes.startedAtMs) ? ev.attributes.startedAtMs : void 0;
@@ -7726,7 +8046,8 @@ function exportOtlpJson(tree, options) {
     "OTLP JSON export uses OTel GenAI-aligned attributes where applicable; experimental until verified against specific collectors.",
     "Not OTLP gRPC/protobuf \u2014 JSON mapping only. Generated locally; no network upload.",
     "Status and span kind use OTLP numeric enums (StatusCode 0/1/2, SpanKind INTERNAL=1).",
-    "When present on source events, operationId/attemptId/retryOf/attemptNumber are emitted as bounded agent_inspect.* identity attributes (not a broad attribute dump)."
+    "When present on source events, operationId/attemptId/retryOf/attemptNumber are emitted as bounded agent_inspect.* identity attributes (not a broad attribute dump).",
+    "When direct and nested identity disagree, export prefers direct for non-strict consumers and emits agent_inspect.identity_conflict.* for the nested alternate; this does not certify conflicting identity."
   ];
   const traceId = hexFrom2(`trace:${tree.runId}`, 16);
   const includeAttributes = options?.includeAttributes ?? false;
@@ -7774,11 +8095,16 @@ function exportOtlpJson(tree, options) {
       if (typeof inp === "number") attrs2.push(intAttr("gen_ai.usage.input_tokens", inp));
       if (typeof outp === "number") attrs2.push(intAttr("gen_ai.usage.output_tokens", outp));
     }
-    appendStructuralIdentityAttrs(
+    const identityConflicts = appendStructuralIdentityAttrs(
       attrs2,
       meta && typeof meta === "object" ? meta : void 0,
       maxLen
     );
+    if (identityConflicts.length > 0) {
+      warnings.push(
+        `Identity representation conflict on event ${ev.eventId}: ${identityConflicts.join(", ")} (direct preferred; nested retained on agent_inspect.identity_conflict.*).`
+      );
+    }
     if (includeAttributes && meta && typeof meta === "object") {
       const skipKeys = /* @__PURE__ */ new Set([
         "tokens",