agent-inspect 6.14.2 → 6.15.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 6.15.0
+
+### Minor Changes
+
+- e70e3be: LangGraph fidelity classes A–E and persisted-trace developer APIs: relationship conformance, scaffolding diagnostics, openTraceFile/Directory/Text, TraceFacts/TraceContract conveniences, and stable AI\_\* remediation codes. No schema break; no new packages; no default network.
+
 ## 6.14.2
 
 ### Patch Changes
@@ -14,13 +20,9 @@
 
 ## Unreleased
 
-### Patch
-
-- Swarm relationship and safety precision (6.14.2): parent resolution before child index registration, self-parent capture/logical defenses, cycle-safe trees, contextual credential-key classification (token config fields such as `ls_max_tokens` are not credentials), and moderate/deep-swarm regression fixtures with packed check→gate→bundle→verify E2E.
-
-### Documentation
+### Minor
 
-- Activate the v6.14.1 swarm stability roadmap (`6.14.2` → `6.16.0` → conditional v7): baseline audit, release-train plans, and AGENTS/state precedence. No runtime or schema change in this docs activation.
+- LangGraph fidelity classes A–E and persisted-trace developer APIs (6.15.0): relationship conformance corpus, ambiguous scaffolding diagnostics, `openTraceFile` / `openTraceDirectory` / `openTraceText`, `buildTraceFacts(TraceReadResult)`, `evaluateTraceContractRead`, stable `AI_*` programmatic diagnostics with remediation, ESM/CJS quickstarts, and A–E cross-surface semantic parity. No schema break; no new packages; no default network.
 
 ## 6.14.0
 

package/README.md

@@ -157,7 +157,7 @@ Details: [Safe sharing](https://github.com/rajudandigam/agent-inspect/blob/main/
 
 ## Project status
 
-**Current release:** **6.14.1** · schema **1.0** · Node.js **≥ 20** · **MIT** · **actively maintained** (eighteen linked npm packages).
+**Current release:** **6.14.2** · schema **1.0** · Node.js **≥ 20** · **MIT** · **actively maintained** (eighteen linked npm packages).
 
 The 6.14 line is actively maintained for correctness, compatibility, documentation, security, and framework evolution.
 

package/docs/API.md

@@ -487,8 +487,12 @@ import {
   detectTraceFormat,
   openInferenceJsonReader,
   openTrace,
+  openTraceDirectory,
+  openTraceFile,
+  openTraceText,
   otlpJsonReader,
   readTrace,
+  formatProgrammaticDiagnostic,
 } from "agent-inspect/readers";
 import type { TraceReader } from "agent-inspect/readers";
 ```
@@ -498,12 +502,14 @@ import type { TraceReader } from "agent-inspect/readers";
 - **`detectTraceFormat(input, { readers?, format? })`**: deterministic, conservative format detection. Explicit `format` acts as an override only when a matching reader is registered.
 - **`readTrace(input, { readers?, format? })`**: detects a reader and returns `TraceReadResult`; unsupported or ambiguous input throws `TraceReadError`.
 - **`openTrace(input, options?)`**: alias for `readTrace()` and the API path used by the universal `agent-inspect open` command.
+- **`openTraceFile(path)` / `openTraceDirectory(path)` / `openTraceText(content)`**: additive conveniences that wrap structured `TraceInput` (prefer these over bare path strings).
+- **`assertTraceInput` / `formatProgrammaticDiagnostic`**: runtime input guard and stable `AI_*` message helpers (lowercase `TraceReadError.code` values remain published).
 - **`agentInspectJsonlReader`**: built-in local AgentInspect JSONL reader for v0.1, v0.2, and mixed files/directories.
 - **`openInferenceJsonReader`**: local OpenInference JSON compatibility reader. Prompt/output-like attributes are summarized and bounded rather than stored as raw content.
 - **`otlpJsonReader`**: local OTLP/HTTP JSON trace payload reader. Resource, scope, span, status, event, and parent metadata are preserved where possible with warnings for unsupported fields.
 - **`DEFAULT_TRACE_READERS`**: ordered built-in reader registry used when no custom `readers` array is supplied.
 
-The reader contract does not silently accept arbitrary JSON and does not add OTel SDK, database, hosted ingestion, or network upload dependencies.
+The reader contract does not silently accept arbitrary JSON and does not add OTel SDK, database, hosted ingestion, or network upload dependencies. See also [PROGRAMMATIC-TRACE-ANALYSIS.md](./PROGRAMMATIC-TRACE-ANALYSIS.md).
 
 ## 21. Experimental Checks
 
@@ -512,11 +518,21 @@ The reader contract does not silently accept arbitrary JSON and does not add OTe
 Import from `agent-inspect/checks`:
 
 ```ts
-import { runTraceChecks } from "agent-inspect/checks";
-import type { TraceCheckRule, TraceCheckResult } from "agent-inspect/checks";
+import {
+  runTraceChecks,
+  buildTraceFacts,
+  defineTraceContract,
+  evaluateTraceContract,
+  evaluateTraceContractRead,
+  formatProgrammaticDiagnostic,
+} from "agent-inspect/checks";
+import type { TraceCheckRule, TraceCheckResult, TraceFacts } from "agent-inspect/checks";
 ```
 
 - **`runTraceChecks({ read }, { rules?, select?, runId? })`**: executes provided rules against a `TraceReadResult` from `agent-inspect/readers`.
+- **`buildTraceFacts(read | events)`**: experimental TraceFacts over logical projection; accepts `TraceReadResult` or normalized `PersistedInspectEvent[]`.
+- **`defineTraceContract` / `evaluateTraceContract` / `evaluateTraceContractRead`**: experimental contract helpers; `evaluateTraceContractRead(read, contract)` wraps `{ read }`.
+- **`formatProgrammaticDiagnostic` / `PROGRAMMATIC_DIAGNOSTIC_SPECS`**: stable `AI_*` codes with remediation hints.
 - **Built-in rule factories**: run, tool, LLM, structure, retrieval, guardrail, decision, safety, and baseline helpers including `createRunStatusRule`, `createToolUsageRule`, `createLlmUsageRule`, `createStructureOrphanRule`, `createStructureCycleRule`, `createStructureRelationshipRule`, `createRetrievalRule`, `createGuardrailRule`, `createDecisionRule`, `createSafetyRawContentRule`, `createSafetySecretPatternRule`, and `createBaselineRegressionRule`.
 - **`TraceCheckRule`**: synchronous pure rule contract.
 - **`TraceCheckResult`**: deterministic aggregate result with findings, evidence, summary counts, and execution diagnostics.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-inspect",
-  "version": "6.14.2",
+  "version": "6.15.0",
   "license": "MIT",
   "type": "module",
   "description": "Local evidence debugger and trajectory-test toolkit for TypeScript AI agents — execution trees, TraceContract checks, Evidence v2, and read-only MCP",

package/packages/cli/dist/{chunk-AACUXCHT.mjs → chunk-LFSBMUCD.mjs}

@@ -5852,6 +5852,59 @@ function defaultSuiteConfigTemplate() {
   };
 }
 
+// packages/core/src/diagnostics/programmatic.ts
+var PROGRAMMATIC_DIAGNOSTIC_SPECS = Object.freeze({
+  AI_TRACE_INPUT_INVALID: {
+    code: "AI_TRACE_INPUT_INVALID",
+    summary: 'Expected { type: "file", path }, { type: "directory", path }, { type: "string", content }, { type: "buffer", content }, or { type: "stdin" }.',
+    remediation: "For a file path, use openTraceFile(path).",
+    relatedCodes: ["invalid_input"]
+  },
+  AI_TRACE_FORMAT_UNSUPPORTED: {
+    code: "AI_TRACE_FORMAT_UNSUPPORTED",
+    summary: "No trace reader could detect the input format.",
+    remediation: "Pass an AgentInspect JSONL file via openTraceFile, or set options.format to a registered reader.",
+    relatedCodes: ["unsupported_format"]
+  },
+  AI_TRACE_FORMAT_AMBIGUOUS: {
+    code: "AI_TRACE_FORMAT_AMBIGUOUS",
+    summary: "Multiple trace readers matched the input with equal confidence.",
+    remediation: "Set options.format explicitly to disambiguate the reader.",
+    relatedCodes: ["ambiguous_format"]
+  },
+  AI_TRACE_FACTS_INPUT_NOT_NORMALIZED: {
+    code: "AI_TRACE_FACTS_INPUT_NOT_NORMALIZED",
+    summary: "TraceFacts requires TraceReadResult or PersistedInspectEvent[].",
+    remediation: "Use openTraceFile() to normalize a JSONL trace first."
+  },
+  AI_TRACE_CONTRACT_RUN_SELECTION_REQUIRED: {
+    code: "AI_TRACE_CONTRACT_RUN_SELECTION_REQUIRED",
+    summary: "Multiple runs are available; select a run before executing checks.",
+    remediation: "Pass options.runId or TraceCheckInput.selectedRun.",
+    relatedCodes: ["AI_CHECK_RUN_SELECTION_REQUIRED"]
+  },
+  AI_TRACE_RELATIONSHIP_SELF_PARENT: {
+    code: "AI_TRACE_RELATIONSHIP_SELF_PARENT",
+    summary: "A parentId equals its own event/step id.",
+    remediation: "Reject at capture (AI_LANGGRAPH_SELF_PARENT_REJECTED) or drop via logical projection; do not invent replacement parents.",
+    relatedCodes: [
+      "AI_LANGGRAPH_SELF_PARENT_REJECTED",
+      "AI_LOGICAL_SELF_PARENT_REMOVED"
+    ]
+  },
+  AI_TRACE_RELATIONSHIP_CYCLE: {
+    code: "AI_TRACE_RELATIONSHIP_CYCLE",
+    summary: "Trace contains a parentId cycle.",
+    remediation: "Use visibility-first tree linking for legacy fixtures; prefer acyclic capture for new adapter output.",
+    relatedCodes: ["structure.cycle"]
+  }
+});
+function formatProgrammaticDiagnostic(code, detail) {
+  const spec = PROGRAMMATIC_DIAGNOSTIC_SPECS[code];
+  const summary = detail?.trim() ? detail.trim() : spec.summary;
+  return `${code}: ${summary} Remediation: ${spec.remediation}`;
+}
+
 // packages/core/src/checks/logical-events.ts
 function isRecord7(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -6050,7 +6103,10 @@ function projectLogicalEvents(events) {
       if (originalParentId === event.eventId) {
         diagnostics.push({
           code: "AI_LOGICAL_SELF_PARENT_REMOVED",
-          message: `Removed self-parent edge on ${event.eventId}.`,
+          message: formatProgrammaticDiagnostic(
+            "AI_TRACE_RELATIONSHIP_SELF_PARENT",
+            `Removed self-parent edge on ${event.eventId}.`
+          ),
           eventIds: [event.eventId]
         });
         const { parentId: _drop, ...rest } = event;
@@ -6082,7 +6138,10 @@ function projectLogicalEvents(events) {
     if (nextParent === event.eventId) {
       diagnostics.push({
         code: "AI_LOGICAL_SELF_PARENT_REMOVED",
-        message: `Removed self-parent edge on ${event.eventId} (was ${originalParentId}).`,
+        message: formatProgrammaticDiagnostic(
+          "AI_TRACE_RELATIONSHIP_SELF_PARENT",
+          `Removed self-parent edge on ${event.eventId} (was ${originalParentId}).`
+        ),
         eventIds: [event.eventId]
       });
       const { parentId: _drop, ...rest } = event;
@@ -6168,6 +6227,9 @@ function summarizeSemanticParity(events) {
     diagnostics: projection.diagnostics
   };
 }
+formatProgrammaticDiagnostic(
+  "AI_TRACE_FACTS_INPUT_NOT_NORMALIZED"
+);
 
 // packages/core/src/safety/sensitive-key.ts
 function normalizeSensitiveKey(value) {
@@ -6411,7 +6473,13 @@ function resolveSelectedRun(input, runId) {
   if (input.read.runs.length === 0) {
     return {
       diagnostics: [
-        diagnostic3("AI_CHECK_RUN_SELECTION_REQUIRED", "No runs are available for checks.")
+        diagnostic3(
+          "AI_CHECK_RUN_SELECTION_REQUIRED",
+          formatProgrammaticDiagnostic(
+            "AI_TRACE_CONTRACT_RUN_SELECTION_REQUIRED",
+            "No runs are available for checks."
+          )
+        )
       ]
     };
   }
@@ -6419,7 +6487,7 @@ function resolveSelectedRun(input, runId) {
     diagnostics: [
       diagnostic3(
         "AI_CHECK_RUN_SELECTION_REQUIRED",
-        "Multiple runs are available; select a run before executing checks."
+        formatProgrammaticDiagnostic("AI_TRACE_CONTRACT_RUN_SELECTION_REQUIRED")
       )
     ]
   };
@@ -7148,7 +7216,7 @@ function createStructureCycleRule() {
               findings.push(
                 failFinding(
                   "structure.cycle",
-                  "Trace contains a parentId cycle.",
+                  formatProgrammaticDiagnostic("AI_TRACE_RELATIONSHIP_CYCLE"),
                   cycle.map((item) => eventEvidence(item, "parentId")),
                   "acyclic parentId graph",
                   cycle.map((item) => item.eventId).sort()
@@ -8372,6 +8440,38 @@ var TraceReadError = class extends Error {
     this.warnings = warnings;
   }
 };
+var TRACE_INPUT_INVALID_MESSAGE = formatProgrammaticDiagnostic(
+  "AI_TRACE_INPUT_INVALID"
+);
+function isTraceInput(input) {
+  if (typeof input !== "object" || input === null || Array.isArray(input)) {
+    return false;
+  }
+  const record = input;
+  switch (record.type) {
+    case "file":
+    case "directory":
+      return typeof record.path === "string";
+    case "string":
+      return typeof record.content === "string";
+    case "buffer":
+      return Buffer.isBuffer(record.content);
+    case "stdin":
+      return true;
+    default:
+      return false;
+  }
+}
+function assertTraceInput(input) {
+  if (isTraceInput(input)) return;
+  throw new TraceReadError("invalid_input", TRACE_INPUT_INVALID_MESSAGE, [
+    {
+      code: "AI_TRACE_INPUT_INVALID",
+      message: TRACE_INPUT_INVALID_MESSAGE,
+      severity: "error"
+    }
+  ]);
+}
 function normalizeCandidate(reader, candidate) {
   const confidence = Number.isFinite(candidate.confidence) ? Math.max(0, Math.min(1, candidate.confidence)) : 0;
   return {
@@ -9726,6 +9826,7 @@ var DEFAULT_TRACE_READERS = [
   otlpJsonReader
 ];
 async function detectTraceFormat(input, options = {}) {
+  assertTraceInput(input);
   const readers = options.readers ?? DEFAULT_TRACE_READERS;
   if (options.format !== void 0) {
     const reader = findReaderByFormat(options.format, readers);
@@ -9822,19 +9923,20 @@ async function detectTraceFormat(input, options = {}) {
   };
 }
 async function readTrace(input, options = {}) {
+  assertTraceInput(input);
   const readers = options.readers ?? DEFAULT_TRACE_READERS;
   const detection = await detectTraceFormat(input, options);
   if (detection.status === "unsupported" || detection.format === void 0) {
     throw new TraceReadError(
       "unsupported_format",
-      "No trace reader could detect the input format.",
+      formatProgrammaticDiagnostic("AI_TRACE_FORMAT_UNSUPPORTED"),
       detection.warnings
     );
   }
   if (detection.status === "ambiguous") {
     throw new TraceReadError(
       "ambiguous_format",
-      "Multiple trace readers matched the input with equal confidence.",
+      formatProgrammaticDiagnostic("AI_TRACE_FORMAT_AMBIGUOUS"),
       detection.warnings
     );
   }
@@ -9842,7 +9944,10 @@ async function readTrace(input, options = {}) {
   if (!reader) {
     throw new TraceReadError(
       "unsupported_format",
-      `No trace reader is registered for format "${detection.format}".`,
+      formatProgrammaticDiagnostic(
+        "AI_TRACE_FORMAT_UNSUPPORTED",
+        `No trace reader is registered for format "${detection.format}".`
+      ),
       detection.warnings
     );
   }
@@ -11216,5 +11321,5 @@ function renderGateReport(result, options = {}) {
 }
 
 export { COHORT_METRIC_IDS, DEFAULT_SUITE_ARTIFACTS_DIR, EVIDENCE_FORMAT_VERSION, EVIDENCE_HTML_FILENAME, EVIDENCE_MANIFEST_FILENAME, Redactor, TraceDirectory, TraceReadError, TreeBuilder, aggregateBundleSafeStatus, aggregateSessionCheckResults, analyzeCohort, applyProfileMetadataCaps, assertBundlePathContained, assertEvidenceRelativePath, buildActivitySummary, buildBundleMetadata, buildBundleSummaryMarkdown, buildEvidenceCausalFailureViewHtml, buildEvidenceCiPackage, buildEvidenceCircuitViewHtml, buildEvidenceContractsViewHtml, buildEvidenceDiffViewHtml, buildEvidenceHtmlShell, buildEvidenceManifest, buildEvidenceOutcomesViewHtml, buildEvidenceProvenanceViewHtml, buildEvidenceSafetyViewHtml, buildEvidenceTimelineViewHtml, buildEvidenceToolsLlmViewHtml, buildEvidenceTreeViewHtml, buildLocalExplanation, buildPlaceholderArtifact, buildRunSummary, buildRunTimeline, buildRunWhatSummary, buildSessionIndex, buildTraceStats, buildZipArchive, bundleFailsOnSafety, bundleRunAssetRelativePath, collectTraceSchemaVersions, compactAttributes, createBaselineRegressionRule, createLlmUsageRule, createMaxStepDurationRule, createObservedOutcomeRule, createRequireCompletedRule, createRunDepthRule, createRunDurationRule, createRunStatusRule, createSafetyOversizedAttributeRule, createSafetyRawContentRule, createSafetyRedactionRule, createSafetySecretPatternRule, createStallDetectionRule, createStructureCycleRule, createStructureOrphanRule, createStructureParallelWidthRule, createStructureRelationshipRule, createToolUsageRule, defaultBundleOutputPath, defaultSuiteConfigTemplate, diffRuns, diffTraceEvents, enrichSessionRunRecord, escapeHtml, escapeMarkdown, extractMetadata, extractOutcomesFromTraceEvents, filterMetasBySessionScope, filterTraces, flattenTree, formatDuration2 as formatDuration, formatStepLabel, formatTimestamp, gateHasThresholds, getIndent, getTraceFilePath, inferEvidenceFileRole, isAgentInspectTrace, isPersistedInspectEvent, loadSessionRunRecords, loadSuiteConfig, loadTraceMetadataList, manualTraceEventsToComparableRun, nanoid, normalizeBundleOutputPath, openTrace, parseCohortMetricList, parseDuration, parseDurationFilter, parseGateList, parseTraceJsonl, persistedInspectEventsToTraceEvents, renderActivitySummaryHuman, renderCohortReport, renderErrorLine, renderGateReport, renderObservedOutcomesHtml, renderObservedOutcomesMarkdown, renderRunDiff, renderRunWhat, renderStepLine, renderSuiteReport, renderTimeline, renderTraceStats, resolveBundleRunIds, resolveRedactionProfile, resolveSuiteTemplate, resolveTraceDir, runGate, runSuite, runTraceChecks, safeString, sanitizeBundleRunId, searchTraces, serializeEvidenceManifest, sha256Hex, stableJson, summarizeObservedOutcomes, summarizeSemanticParity, traceEventToPersistedInspectEvent, truncateName, truncateStringForProfile, validateEvent, validateSuiteConfig, verifyEvidenceDirectory, zeroKinds };
-//# sourceMappingURL=chunk-AACUXCHT.mjs.map
-//# sourceMappingURL=chunk-AACUXCHT.mjs.map
+//# sourceMappingURL=chunk-LFSBMUCD.mjs.map
+//# sourceMappingURL=chunk-LFSBMUCD.mjs.map