agent-workflow-inspector 1.0.0 → 2.0.0

package/dist/cli/index.js

@@ -7,6 +7,91 @@ import { open, lstat, opendir, realpath, link, unlink } from "fs/promises";
 import { resolve, join, dirname, parse as parsePath } from "path";
 import { randomUUID } from "crypto";
 
+// package.json
+var package_default = {
+  name: "agent-workflow-inspector",
+  version: "2.0.0",
+  description: "Local-first, deterministic linter for AI agent traces: detect suspicious retries, repeated tool calls, execution cycles, and resource burn.",
+  type: "module",
+  license: "MIT",
+  author: "Jigar Prajapati",
+  homepage: "https://github.com/jigar48/awi#readme",
+  bugs: {
+    url: "https://github.com/jigar48/awi/issues"
+  },
+  funding: {
+    type: "individual",
+    url: "https://buymeacoffee.com/buildwithjigar"
+  },
+  keywords: [
+    "ai-agents",
+    "agent-observability",
+    "opentelemetry",
+    "developer-tools",
+    "typescript",
+    "cli",
+    "ai-debugging",
+    "trace-analysis"
+  ],
+  repository: {
+    type: "git",
+    url: "https://github.com/jigar48/awi.git"
+  },
+  engines: {
+    node: "^22.18.0 || ^24.11.0 || ^26.0.0"
+  },
+  packageManager: "pnpm@11.25.0",
+  bin: {
+    awi: "dist/cli/index.js"
+  },
+  main: "dist/index.js",
+  types: "dist/index.d.ts",
+  exports: {
+    ".": {
+      types: "./dist/index.d.ts",
+      import: "./dist/index.js"
+    }
+  },
+  files: [
+    "dist",
+    "docs",
+    "examples",
+    "README.md",
+    "LICENSE",
+    "awi.config.example.json",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "CONTRIBUTING.md",
+    "CODE_OF_CONDUCT.md"
+  ],
+  scripts: {
+    build: "tsup",
+    test: "vitest run",
+    typecheck: "tsc --noEmit",
+    lint: "eslint .",
+    format: "prettier --write .",
+    "format:check": "prettier --check .",
+    check: "pnpm typecheck && pnpm lint && pnpm test && pnpm build",
+    prepack: "pnpm build",
+    schemas: "pnpm build && node scripts/schemas.mjs",
+    "smoke:package": "node scripts/package-smoke.mjs",
+    "verify:quickstart": "node scripts/verify-quickstart.mjs"
+  },
+  dependencies: {
+    commander: "14.0.3",
+    zod: "4.6.7"
+  },
+  devDependencies: {
+    typescript: "~5.9.3",
+    "@types/node": "^22.19.0",
+    tsup: "9.0.0",
+    vitest: "5.0.5",
+    eslint: "10.13.0",
+    "typescript-eslint": "^8.46.0",
+    prettier: "^3.6.2"
+  }
+};
+
 // src/core/analysis.ts
 import { z as z3 } from "zod";
 
@@ -435,14 +520,20 @@ var configSchema = z2.strictObject({
       maxOperations: positive.max(5e4).default(100),
       maxDepth: positive.max(1e3).default(20)
     }).default({ enabled: true, maxOperations: 100, maxDepth: 20 }),
-    AWI006: z2.strictObject({ enabled: z2.boolean().default(true) }).default({ enabled: true })
+    AWI006: z2.strictObject({ enabled: z2.boolean().default(true) }).default({ enabled: true }),
+    AWI007: z2.strictObject({
+      enabled: z2.boolean().default(false),
+      threshold: positive.min(4).max(LIMITS.repetitionWindow).default(4),
+      minDistinctArguments: positive.min(3).max(LIMITS.repetitionWindow).default(3)
+    }).default({ enabled: false, threshold: 4, minDistinctArguments: 3 })
   }).default({
     AWI001: { enabled: true, threshold: 4 },
     AWI002: { enabled: true, threshold: 3 },
     AWI003: { enabled: true, minRepetitions: 3, maxCycleLength: 6 },
     AWI004: { enabled: true, threshold: 5, windowSeconds: 30 },
     AWI005: { enabled: true, maxOperations: 100, maxDepth: 20 },
-    AWI006: { enabled: true }
+    AWI006: { enabled: true },
+    AWI007: { enabled: false, threshold: 4, minDistinctArguments: 3 }
   }),
   fingerprint: z2.strictObject({
     ignorePaths: z2.array(
@@ -625,7 +716,8 @@ var titles = {
   AWI003: "Repeating execution cycle",
   AWI004: "Retry storm",
   AWI005: "Excessive execution steps or depth",
-  AWI006: "Recorded resource usage associated with suspicious execution"
+  AWI006: "Recorded resource usage associated with suspicious execution",
+  AWI007: "Repeated failure with argument drift"
 };
 function analyze(traces, configInput = {}, showContent = false) {
   const config = resolveConfig(configInput);
@@ -675,7 +767,7 @@ function analyze(traces, configInput = {}, showContent = false) {
     validated.push(result.data);
   }
   const report = {
-    version: 1,
+    version: 2,
     fingerprintVersion: "awi-sha256-v1",
     complete: true,
     summaries: [],
@@ -702,7 +794,7 @@ function analyze(traces, configInput = {}, showContent = false) {
       title: titles[ruleId],
       description: "Heuristic finding based on recorded execution evidence; intentional behavior may match.",
       explanation,
-      remediation: "Review the referenced operations and configured policy before changing the workflow.",
+      remediation: ruleId === "AWI007" ? "Review the shared error code and retry policy; consider bounded retries or escalation before varying arguments further." : "Review the referenced operations and configured policy before changing the workflow.",
       operationIds: ops.map((o) => o.id),
       evidence: {
         ...evidence,
@@ -713,9 +805,10 @@ function analyze(traces, configInput = {}, showContent = false) {
       }
     });
   }
-  for (const trace of [...grouped.values()].sort(
-    (a, b) => a.traceId < b.traceId ? -1 : a.traceId > b.traceId ? 1 : 0
-  )) {
+  const orderedTraces = [...grouped.values()].sort(
+    (a, b) => compare(a.traceId, b.traceId)
+  );
+  for (const trace of orderedTraces) {
     trace.operations.sort((a, b) => compare(a.id, b.id));
     const normalized = normalize(trace);
     report.warnings.push(...normalized.warnings);
@@ -782,6 +875,43 @@ function analyze(traces, configInput = {}, showContent = false) {
           "Overlapping sibling operations excluded from sequence rules."
         );
       for (const run of runs) {
+        if (config.rules.AWI007.enabled) {
+          const policy2 = config.rules.AWI007;
+          let failures = [];
+          const distinct = /* @__PURE__ */ new Set();
+          let tool;
+          let code;
+          const flush = () => {
+            if (failures.length >= policy2.threshold && distinct.size >= policy2.minDistinctArguments)
+              add(
+                "AWI007",
+                trace.traceId,
+                failures,
+                {
+                  failedCalls: failures.length,
+                  distinctArgumentFingerprints: distinct.size
+                },
+                "Consecutive recorded failures share a tool and explicit error code while argument fingerprints vary. This does not establish intent or lack of progress."
+              );
+            failures = [];
+            distinct.clear();
+          };
+          for (const op of run) {
+            if (op.type !== "tool") continue;
+            const fp = fps.get(op.id);
+            if (op.status !== "error" || !op.error?.code?.trim() || op.arguments === void 0 || !fp) {
+              flush();
+              continue;
+            }
+            const name = op.toolName ?? op.name;
+            if (name !== tool || op.error.code !== code) flush();
+            tool = name;
+            code = op.error.code;
+            failures.push(op);
+            distinct.add(fp);
+          }
+          flush();
+        }
         let segment = [];
         const segments = [];
         for (const op of run) {
@@ -936,7 +1066,12 @@ function analyze(traces, configInput = {}, showContent = false) {
           recorded,
           {
             recordedUsage: tokens,
-            recordedCosts: costs,
+            recordedCosts: Object.fromEntries(
+              Object.keys(costs).sort(compare).map((currency, index) => [
+                `currency-${index + 1}`,
+                costs[currency]
+              ])
+            ),
             coverage: "Only implicated leaf operations with recorded usage or cost",
             relatedRules: [...new Set(related.map((f) => f.ruleId))]
           },
@@ -952,6 +1087,28 @@ function analyze(traces, configInput = {}, showContent = false) {
   report.findings.sort(
     (a, b) => severityRank[b.severity] - severityRank[a.severity] || compare(a.traceId, b.traceId) || compare(a.ruleId, b.ruleId) || compare(a.operationIds.join("\0"), b.operationIds.join("\0"))
   );
+  const traceRefs = new Map(
+    orderedTraces.map((trace, index) => [
+      trace.traceId,
+      {
+        id: `trace-${index + 1}`,
+        operations: new Map(
+          trace.operations.map((op, index2) => [op.id, `op-${index2 + 1}`])
+        )
+      }
+    ])
+  );
+  for (const summary of report.summaries)
+    summary.traceId = traceRefs.get(summary.traceId).id;
+  for (const finding of report.findings) {
+    const refs = traceRefs.get(finding.traceId);
+    finding.traceId = refs.id;
+    finding.operationIds = finding.operationIds.map(
+      (id) => refs.operations.get(id)
+    );
+    for (const reference of finding.evidence.references)
+      reference.operationId = refs.operations.get(reference.operationId);
+  }
   report.warnings = [...new Set(report.warnings)].sort();
   try {
     validateValue(report);
@@ -961,8 +1118,9 @@ function analyze(traces, configInput = {}, showContent = false) {
     throw error;
   }
   if (showContent)
-    report.content = [...grouped.values()].sort((a, b) => compare(a.traceId, b.traceId)).map((t) => ({
-      traceId: t.traceId,
+    report.content = orderedTraces.map((t) => ({
+      traceId: traceRefs.get(t.traceId).id,
+      recordedTraceId: t.traceId,
       operations: redact(t.operations)
     }));
   return report;
@@ -990,7 +1148,8 @@ function humanReport(report, options = {}) {
 ${paint("[" + f.severity.toUpperCase() + "]", f.severity)} ${safeText(f.ruleId)} ${safeText(f.title)} (${safeText(f.confidence)} evidence)`,
       `  Trace: ${safeText(f.traceId)}; operations: ${f.operationIds.map(safeText).join(", ") || "trace-wide"}`,
       `  ${safeText(f.explanation)}`,
-      `  Evidence: ${safeText(JSON.stringify(f.evidence))}`
+      `  Evidence: ${safeText(JSON.stringify(f.evidence))}`,
+      `  Remediation: ${safeText(f.remediation)}`
     );
   for (const warning of report.warnings)
     lines.push("Warning: " + safeText(warning));
@@ -1126,7 +1285,7 @@ var program = new Command().configureOutput({
   writeErr: (text) => {
     process.stderr.write(safeText(text) + "\n");
   }
-}).name("awi").description("Find loops, retries, and wasted work in AI agent traces.").version("1.0.0");
+}).name("awi").description("Find loops, retries, and wasted work in AI agent traces.").version(package_default.version);
 program.command("inspect").argument("<paths...>", "JSON files or directories (recursive; no symlinks)").addOption(
   new Option("--format <format>").choices(["human", "json"]).default("human")
 ).addOption(
@@ -1138,7 +1297,7 @@ program.command("inspect").argument("<paths...>", "JSON files or directories (re
   "Create a new report file; existing paths are refused"
 ).option("--no-color", "Disable colors (output is plain text)").option(
   "--show-content",
-  "Include recorded content with key-based redaction; may expose private data"
+  "Include recorded IDs, labels and payloads with key-based redaction; may expose private data"
 ).action(
   async (paths, options) => {
     const files = await collect(paths);