agent-inspect 6.7.5 → 6.9.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 6.9.0
+
+### Minor Changes
+
+- 627f5f4: Safety precision and share policy: additive finding taxonomy, path-aware raw-content and detector precision, framework metadata sensitivity, source-vs-artifact verify-safe/bundle/MCP gating, --explain, and local override docs. No schema break; no new root/core dependencies; no default network upload; defaults not weakened.
+
+## 6.8.0
+
+### Minor Changes
+
+- 69b6515: LangGraph fidelity contract for `@agent-inspect/langchain`: per-invocation lifecycle, callback reuse isolation, conservative parent reconciliation, synthetic semantic groups, tool identity fields, persist-by-intent, flush/finalize/close, and bounded diagnostics. Includes no-provider LangGraph coverage and NestJS/swarm recipes. No schema break; no new root/core dependencies; no default network upload.
+
 ## 6.7.5
 
 ### Patch Changes

package/README.md

@@ -131,7 +131,7 @@ Details: [Safe sharing](https://github.com/rajudandigam/agent-inspect/blob/main/
 
 ## Project status
 
-**Current release:** **6.7.4** (eighteen linked npm packages). Technical launch candidate; external pilot evidence pending. Persisted schema **1.0**. Node.js **≥ 20**. **v7 not scheduled.**
+**Current release:** **6.9.0** (eighteen linked npm packages). Technical launch candidate; external pilot evidence pending. Persisted schema **1.0**. Node.js **≥ 20**. **v7 not scheduled.**
 
 [Roadmap](ROADMAP.md) · [Pilot kit](https://github.com/rajudandigam/agent-inspect/blob/main/docs/PRE-V7-PILOT-KIT.md) · [Changelog](CHANGELOG.md)
 

package/docs/CLI.md

@@ -457,16 +457,19 @@ agent-inspect verify-safe <trace-path-or-run-id> [options]
 Statuses:
 
 - `SAFE`: no safety findings and no reader warnings.
-- `SAFE WITH WARNINGS`: no safety findings, but the reader reported warnings or unsupported fields.
-- `UNSAFE`: safety findings were detected.
+- `SAFE WITH WARNINGS`: no blocking safety findings, but warnings (reader or findings) remain.
+- `UNSAFE`: blocking safety findings were detected.
 - `UNKNOWN`: the input could not be read, normalized, or selected conservatively.
 
+`verify-safe` assesses the **source** trace and a **share-redacted artifact**. The printed/exit `status` follows the **artifact** assessment when a single-file (or stdin) artifact can be derived. `scan` remains source-oriented.
+
 Options:
 
 - `--dir <path>`: trace directory for run-id lookup
 - `--format <agent-inspect-jsonl|openinference-json|otlp-json>`: explicit reader format override
 - `--run <run-id>`: select a run when input contains multiple runs
 - `--json`: print deterministic JSON safety result
+- `--explain`: explain each finding (detector/path/category/confidence/redaction/override/bundle gate) without printing matched secret values
 - `--max-string-length <number>`: unsafe threshold for string values
 - `--max-array-length <number>`: unsafe threshold for array values
 - `--max-object-keys <number>`: unsafe threshold for object key counts
@@ -474,11 +477,15 @@ Options:
 
 The scan looks for raw prompt/output-like capture paths, unredacted sensitive-looking keys, secret-like string patterns, and oversized values. It reports evidence paths rather than raw prompt, output, request/response, header, API key, secret, or full tool payload values. Secret detection is best-effort and should not be treated as exhaustive.
 
+Policy and overrides: [SAFETY-POLICY.md](SAFETY-POLICY.md).
+
 Examples:
 
 ```bash
 npx agent-inspect scan fixtures/traces-v0.2/manual-basic.jsonl --json
+npx agent-inspect scan trace.jsonl --explain
 npx agent-inspect verify-safe minimal-success --dir fixtures/traces
+npx agent-inspect verify-safe trace.jsonl --explain --json
 npx agent-inspect verify-safe trace.jsonl --max-string-length 8192 --json
 ```
 
@@ -866,7 +873,7 @@ If `@agent-inspect/index-sqlite` is not installed, these subcommands print a sho
 
 ### 6.24 `bundle`
 
-Create a **share-safe offline trace bundle** as a local folder (v4.3+). Bundles are derived copies: original traces are read-only and never mutated. Automatic `verify-safe` runs before write; the command fails on `UNSAFE` unless `--allow-unsafe`. See [BUNDLES.md](BUNDLES.md).
+Create a **share-safe offline trace bundle** as a local folder (v4.3+). Bundles are derived copies: original traces are read-only and never mutated. Automatic safety assessment runs on the **redacted artifact** before write; the command fails when the artifact is `UNSAFE`/`UNKNOWN` unless `--allow-unsafe`. Source-only findings that redaction removes do not refuse the bundle. See [BUNDLES.md](BUNDLES.md) and [SAFETY-POLICY.md](SAFETY-POLICY.md).
 
 ```bash
 agent-inspect bundle <run-id> [options]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-inspect",
-  "version": "6.7.5",
+  "version": "6.9.0",
   "license": "MIT",
   "type": "module",
   "description": "Debug, regression-test, and safely share TypeScript AI-agent behavior locally — no account, no default upload, metadata-only by default",

package/packages/cli/dist/{chunk-TO4VENHV.mjs → chunk-WQ5XMFH2.mjs}

@@ -3804,8 +3804,9 @@ function buildBundleSummaryMarkdown(parts) {
     ""
   ];
   for (const run of checks.runs) {
+    const source = run.sourceStatus !== void 0 && run.sourceStatus !== run.status ? `; source ${run.sourceStatus}` : "";
     lines.push(
-      `- \`${run.runId}\`: ${run.status} (${run.findings} finding(s), ${run.errors} error(s), ${run.warnings} warning(s))`
+      `- \`${run.runId}\`: artifact ${run.status}${source} (${run.findings} finding(s), ${run.errors} error(s), ${run.warnings} warning(s))`
     );
   }
   lines.push("", "## Redaction", "", `Total findings: ${redaction.totalFindings}`, "");
@@ -4180,8 +4181,35 @@ var DEFAULT_RAW_CONTENT_KEYS = [
   "toolinput",
   "tool_input",
   "tooloutput",
-  "tool_output"
+  "tool_output",
+  // Framework / agent metadata that carries user or task text
+  "currenttask",
+  "current_task",
+  "task",
+  "userinput",
+  "user_input",
+  "requesttext",
+  "request_text",
+  "conversationtext",
+  "conversation_text"
 ];
+var DEFAULT_SAFE_RAW_CONTENT_PATH_PREFIXES = ["tokenUsage", "usage"];
+var SAFE_USAGE_LEAF_KEYS = /* @__PURE__ */ new Set([
+  "input",
+  "output",
+  "total",
+  "cached",
+  "input_tokens",
+  "inputtokens",
+  "output_tokens",
+  "outputtokens",
+  "total_tokens",
+  "totaltokens",
+  "prompt_tokens",
+  "prompttokens",
+  "completion_tokens",
+  "completiontokens"
+]);
 var DEFAULT_SECRET_PATTERNS = [
   { id: "bearer-token", pattern: /Bearer\s+[A-Za-z0-9._~+/-]{12,}=*/ },
   { id: "openai-key", pattern: /sk-[A-Za-z0-9_-]{16,}/ },
@@ -4359,7 +4387,11 @@ function normalizeFinding(rule, finding) {
     message: finding.message,
     ...finding.expected !== void 0 ? { expected: finding.expected } : {},
     ...finding.actual !== void 0 ? { actual: finding.actual } : {},
-    evidence: [...finding.evidence ?? []]
+    evidence: [...finding.evidence ?? []],
+    ...finding.category !== void 0 ? { category: finding.category } : {},
+    ...finding.confidence !== void 0 ? { confidence: finding.confidence } : {},
+    ...finding.detector !== void 0 ? { detector: finding.detector } : {},
+    ...finding.action !== void 0 ? { action: finding.action } : {}
   };
 }
 function summarize(findings, diagnostics) {
@@ -4417,15 +4449,19 @@ function eventEvidence(event, path12) {
 function runEvidence(run) {
   return run ? [{ runId: run.runId, name: run.name, status: run.status }] : [];
 }
-function failFinding(ruleId, message, evidence, expected, actual) {
+function failFinding(ruleId, message, evidence, expected, actual, meta) {
   return {
     ruleId,
-    severity: "error",
-    status: "fail",
+    severity: meta?.severity ?? "error",
+    status: meta?.status ?? "fail",
     message,
     ...expected !== void 0 ? { expected } : {},
     ...actual !== void 0 ? { actual } : {},
-    evidence: [...evidence]
+    evidence: [...evidence],
+    ...meta?.category !== void 0 ? { category: meta.category } : {},
+    ...meta?.confidence !== void 0 ? { confidence: meta.confidence } : {},
+    ...meta?.detector !== void 0 ? { detector: meta.detector } : {},
+    ...meta?.action !== void 0 ? { action: meta.action } : {}
   };
 }
 function toolName(event) {
@@ -4546,6 +4582,19 @@ function isRawContentKey(key, forbiddenKeys) {
   const normalized = normalizedKey(key);
   return forbiddenKeys.some((forbidden) => normalized === normalizedKey(forbidden));
 }
+function isSafeRawContentMetricPath(path12, key, safePathPrefixes) {
+  const leaf = normalizedKey(key ?? lastPathSegment(path12));
+  if (!SAFE_USAGE_LEAF_KEYS.has(leaf)) return false;
+  const parts = path12.split(".").filter(Boolean);
+  if (parts.length < 2) return false;
+  const parent = parts[parts.length - 2] ?? "";
+  const parentNorm = normalizedKey(parent);
+  return safePathPrefixes.some((prefix) => parentNorm === normalizedKey(prefix));
+}
+function isRawContentPath(path12, key, forbiddenKeys, safePathPrefixes) {
+  if (isSafeRawContentMetricPath(path12, key, safePathPrefixes)) return false;
+  return isRawContentKey(key ?? lastPathSegment(path12), forbiddenKeys);
+}
 function parentMarkedUnresolved(event) {
   if (booleanAttr(event, [
     "parentUnresolved",
@@ -5185,7 +5234,13 @@ function createSafetyRedactionRule(options = {}) {
               `Sensitive-looking field at ${entry.path} is not redacted.`,
               [eventEvidence(event, entry.path)],
               "redaction marker",
-              { path: entry.path, valueType: valueType(entry.value) }
+              { path: entry.path, valueType: valueType(entry.value) },
+              {
+                category: "credential",
+                confidence: "high",
+                detector: "safety.redaction",
+                action: "redact"
+              }
             )
           );
         }
@@ -5196,6 +5251,7 @@ function createSafetyRedactionRule(options = {}) {
 }
 function createSafetyRawContentRule(options = {}) {
   const forbiddenKeys = options.forbiddenKeys ?? DEFAULT_RAW_CONTENT_KEYS;
+  const safePathPrefixes = options.safePathPrefixes ?? DEFAULT_SAFE_RAW_CONTENT_PATH_PREFIXES;
   return {
     id: "safety.rawPrompt",
     category: "safety",
@@ -5205,14 +5261,20 @@ function createSafetyRawContentRule(options = {}) {
       for (const event of context.events) {
         for (const entry of eventValueEntries(event, { includeSummaries: options.includeSummaries })) {
           const key = entry.key ?? lastPathSegment(entry.path);
-          if (!isRawContentKey(key, forbiddenKeys)) continue;
+          if (!isRawContentPath(entry.path, key, forbiddenKeys, safePathPrefixes)) continue;
           findings.push(
             failFinding(
               "safety.rawPrompt",
               `Raw content-like field ${entry.path} is present.`,
               [eventEvidence(event, entry.path)],
               "metadata-only trace fields",
-              { path: entry.path, valueType: valueType(entry.value) }
+              { path: entry.path, valueType: valueType(entry.value) },
+              {
+                category: "raw-content",
+                confidence: "high",
+                detector: "safety.rawPrompt",
+                action: "redact-or-omit"
+              }
             )
           );
         }
@@ -5244,7 +5306,13 @@ function createSafetySecretPatternRule(options = {}) {
                 `Secret-like pattern ${pattern.id} matched at ${entry.path}.`,
                 [eventEvidence(event, entry.path)],
                 "no secret-like strings",
-                { pattern: pattern.id, path: entry.path }
+                { pattern: pattern.id, path: entry.path },
+                {
+                  category: "credential",
+                  confidence: "high",
+                  detector: pattern.id,
+                  action: "redact"
+                }
               )
             );
             break;
@@ -5271,7 +5339,13 @@ function createSafetyOversizedAttributeRule(options) {
                 `String at ${entry.path} exceeds ${options.maxStringLength} characters.`,
                 [eventEvidence(event, entry.path)],
                 { maxStringLength: options.maxStringLength },
-                { path: entry.path, length: entry.value.length }
+                { path: entry.path, length: entry.value.length },
+                {
+                  category: "size",
+                  confidence: "high",
+                  detector: "safety.oversizedAttribute",
+                  action: "truncate-or-omit"
+                }
               )
             );
           }
@@ -5282,7 +5356,13 @@ function createSafetyOversizedAttributeRule(options) {
                 `Array at ${entry.path} exceeds ${options.maxArrayLength} items.`,
                 [eventEvidence(event, entry.path)],
                 { maxArrayLength: options.maxArrayLength },
-                { path: entry.path, length: entry.value.length }
+                { path: entry.path, length: entry.value.length },
+                {
+                  category: "size",
+                  confidence: "high",
+                  detector: "safety.oversizedAttribute",
+                  action: "truncate-or-omit"
+                }
               )
             );
           }
@@ -5293,7 +5373,13 @@ function createSafetyOversizedAttributeRule(options) {
                 `Object at ${entry.path} exceeds ${options.maxObjectKeys} keys.`,
                 [eventEvidence(event, entry.path)],
                 { maxObjectKeys: options.maxObjectKeys },
-                { path: entry.path, keys: Object.keys(entry.value).length }
+                { path: entry.path, keys: Object.keys(entry.value).length },
+                {
+                  category: "size",
+                  confidence: "high",
+                  detector: "safety.oversizedAttribute",
+                  action: "truncate-or-omit"
+                }
               )
             );
           }
@@ -5306,7 +5392,13 @@ function createSafetyOversizedAttributeRule(options) {
                   `Value at ${entry.path} exceeds ${options.maxSerializedBytes} serialized bytes.`,
                   [eventEvidence(event, entry.path)],
                   { maxSerializedBytes: options.maxSerializedBytes },
-                  { path: entry.path, bytes }
+                  { path: entry.path, bytes },
+                  {
+                    category: "size",
+                    confidence: "high",
+                    detector: "safety.oversizedAttribute",
+                    action: "truncate-or-omit"
+                  }
                 )
               );
             }
@@ -9055,5 +9147,5 @@ function renderGateReport(result, options = {}) {
 }
 
 export { COHORT_METRIC_IDS, DEFAULT_SUITE_ARTIFACTS_DIR, Redactor, TraceDirectory, TraceReadError, TreeBuilder, aggregateBundleSafeStatus, aggregateSessionCheckResults, analyzeCohort, applyProfileMetadataCaps, assertBundlePathContained, buildActivitySummary, buildBundleMetadata, buildBundleSummaryMarkdown, buildLocalExplanation, buildPlaceholderArtifact, buildRunSummary, buildRunTimeline, buildRunWhatSummary, buildSessionIndex, buildTraceStats, bundleFailsOnSafety, bundleRunAssetRelativePath, compactAttributes3 as compactAttributes, createBaselineRegressionRule, createLlmUsageRule, createMaxStepDurationRule, createObservedOutcomeRule, createRequireCompletedRule, createRunDepthRule, createRunDurationRule, createRunStatusRule, createSafetyOversizedAttributeRule, createSafetyRawContentRule, createSafetyRedactionRule, createSafetySecretPatternRule, createStallDetectionRule, createStructureCycleRule, createStructureOrphanRule, createStructureParallelWidthRule, createStructureRelationshipRule, createToolUsageRule, defaultBundleOutputPath, defaultSuiteConfigTemplate, enrichSessionRunRecord, escapeHtml, escapeMarkdown, extractMetadata, extractOutcomesFromTraceEvents, filterMetasBySessionScope, filterTraces, flattenTree, formatDuration2 as formatDuration, formatTimestamp, gateHasThresholds, getIndent, getTraceFilePath, isAgentInspectTrace, isPersistedInspectEvent, loadSessionRunRecords, loadSuiteConfig, loadTraceMetadataList, nanoid, normalizeBundleOutputPath, openTrace, parseCohortMetricList, parseDuration, parseDurationFilter, parseGateList, parseTraceJsonl, persistedInspectEventsToTraceEvents, renderActivitySummaryHuman, renderCohortReport, renderErrorLine, renderGateReport, renderObservedOutcomesHtml, renderObservedOutcomesMarkdown, renderRunWhat, renderStepLine, renderSuiteReport, renderTimeline, renderTraceStats, resolveBundleRunIds, resolveRedactionProfile, resolveSuiteTemplate, resolveTraceDir, runGate, runSuite, runTraceChecks, safeString, sanitizeBundleRunId, searchTraces, source_default, stableJson, summarizeObservedOutcomes, traceEventToPersistedInspectEvent, truncateName, truncateStringForProfile, validateEvent, validateSuiteConfig, zeroKinds };
-//# sourceMappingURL=chunk-TO4VENHV.mjs.map
-//# sourceMappingURL=chunk-TO4VENHV.mjs.map
+//# sourceMappingURL=chunk-WQ5XMFH2.mjs.map
+//# sourceMappingURL=chunk-WQ5XMFH2.mjs.map