agent-workflow-inspector 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 1.0.0 — Unreleased
+
+Initial local V1: canonical AWI JSON and OTLP subset; strict validation; SHA-256 fingerprints; six bounded rules; CLI/library; human/JSON reports; configuration; synthetic examples; security/regression/CLI tests; schemas; cross-platform CI. No npm publication or public release performed.
+
+### Release preparation
+
+Added package homepage, issue tracker, keywords and optional funding metadata; clearer installation and maintainer guidance; release notes and an explicit approval-gated publication procedure. The audited commit passed all nine hosted CI jobs. Release-preparation commits require a fresh matrix before publication. No runtime behavior or dependencies changed.
+
+### Pre-release audit fixes
+
+Fixed canonicalization CPU amplification, bounded ignored-path compilation/caching, missing-identity evidence handling, repeated tools hidden by interleaved model spans, nanosecond/concurrent sequence false positives, retry-storm recovery handling, partial AWI002 defaults, impossible thresholds, source-reference validation, metadata amplification, malformed OTLP coercions, blank failure evidence, fragment determinism, public-renderer injection, symlink ancestors, invalid UTF-8 and broken pipes. Packed maintainer documents are included; the isolated-consumer smoke test now checks all examples, executable mode and TypeScript declarations. CI actions are SHA-pinned with no persisted checkout credentials.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,5 @@
+# Code of conduct
+
+Be respectful, constructive and inclusive. Harassment, threats, discrimination, doxxing, sexual harassment and deliberate disruption are unacceptable in project spaces.
+
+Maintainers may remove harmful contributions, warn, restrict or ban participants according to severity and recurrence. Protect affected participants and preserve confidentiality. Report conduct issues privately through a maintainer channel listed on the repository owner's profile; do not publish private details in issues. Maintainers should recuse themselves from reports about their own conduct.

package/CONTRIBUTING.md

@@ -0,0 +1,9 @@
+# Contributing
+
+Use supported Node and pinned pnpm. Run pnpm install --frozen-lockfile, pnpm check and pnpm format:check. Add positive/negative behavior tests for detector changes and adversarial cases for security changes. Use only synthetic credential-free fixtures.
+
+Changes to rule IDs, fingerprint identity, schema versions or exit codes require compatibility review and changelog entries. Update documentation and regenerate schemas with pnpm schemas. Check dependency engines and pnpm audit. Never weaken tests to accept defects.
+
+Describe the problem, resulting behavior, limitations and verification in PRs. No automated publishing occurs. Maintainer approval is required for releases and remote actions.
+
+Read the [release procedure](docs/releasing.md) before proposing package or release-workflow changes. Contact maintainer [Jigar Prajapati](https://github.com/jigar48) through GitHub for project questions; use [Security](SECURITY.md) for sensitive reports. Do not post private traces or credentials in issues.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jigar Prajapati
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,96 @@
-# Temporary Holding Version
+# Agent Workflow Inspector (AWI)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Local-first, deterministic diagnostics for AI agent execution traces.**
+
+Agent Workflow Inspector is a local-first, deterministic linter for AI agent execution traces that detects suspicious retry loops, repeated tool calls, execution cycles, and resource burn. It reads versioned AWI JSON or a documented subset of OTLP JSON and produces evidence for local review or CI. Analysis requires no account, LLM, network, browser, or service. AWI sends no automatic telemetry.
+
+Findings are heuristics, not proof of bugs or waste. Repeated polling and intentional retries can match. AWI does not infer agent intent or causal dependencies from timestamps.
+
+## Install and quick start
+
+Version 1.0.0 is a release candidate and is **not yet published to npm**. Once publication is confirmed, install the exact release with:
+
+```sh
+npm install --global agent-workflow-inspector@1.0.0
+awi --help
+awi --version
+awi inspect trace.json --format json
+```
+
+Create `trace.json` using the [minimal trace example](docs/getting-started.md). Until publication, use the source or tarball instructions below. Supported Node versions are **22.18+ (22.x), 24.11+ (24.x), or 26.x**.
+
+## Run from source
+
+Use Node **22.18+ (22.x), 24.11+ (24.x), or 26.x** and pnpm **11.25.0**.
+
+```sh
+pnpm install --frozen-lockfile
+pnpm check
+node dist/cli/index.js inspect examples/healthy/basic.json
+node dist/cli/index.js inspect examples/suspicious/retries.json --format json
+node dist/cli/index.js inspect examples/opentelemetry/tools.json --input-format otel
+```
+
+The suspicious example exits 2 by default. For a local installation, run `pnpm pack --out agent-workflow-inspector-1.0.0.tgz`, then `pnpm add --global ./agent-workflow-inspector-1.0.0.tgz`. The package exposes the `awi` executable and an ESM TypeScript library.
+
+The npm registry returned 404 for `agent-workflow-inspector` on October 19, 2026; this neither reserves the name nor guarantees future availability.
+
+## CLI
+
+```sh
+awi inspect trace.json --format human
+awi inspect ./traces --format json --fail-on medium --output report.json
+awi inspect first.json second.json --config awi.config.example.json
+```
+
+| Rule   | Default severity | Recorded pattern                                                   |
+| ------ | ---------------- | ------------------------------------------------------------------ |
+| AWI001 | medium           | Four equivalent tool calls in a bounded window                     |
+| AWI002 | high             | Three equivalent failing calls with matching error evidence        |
+| AWI003 | medium           | A cycle of 2–6 calls repeating three times                         |
+| AWI004 | high             | Five rapid equivalent attempts, preceded by explicit failures      |
+| AWI005 | medium           | More than 100 operations or parent depth over 20                   |
+| AWI006 | medium           | Recorded leaf usage/cost directly associated with suspicious calls |
+
+Exit codes: **0** completed below threshold; **1** invalid input/configuration, operational failure, or incomplete analysis; **2** completed with findings at or above threshold. Default threshold: high. `--fail-on none` disables finding-based failure.
+
+Directories are recursive, bounded, deterministic, and restricted to JSON files. Symlinks and existing output paths are refused. Raw arguments, results, messages, prompts, and metadata are absent from ordinary reports. IDs remain visible for evidence; avoid putting secrets in identifiers. `--show-content` includes content with limited key-based redaction and can expose private data.
+
+## Library
+
+```ts
+import { readFile } from 'node:fs/promises';
+import { analyze, ingest, parseJson } from 'agent-workflow-inspector';
+
+const traces = ingest(parseJson(await readFile('trace.json', 'utf8')));
+const report = analyze(traces, { rules: { AWI001: { threshold: 5 } } });
+console.log(report.findings);
+```
+
+Library and CLI share validators, limits, detectors, and report contracts. Use ingest/analyze for resource and graph checks; exported structural schemas alone are not a security boundary. The library does no filesystem access or networking. Optional properties represent unknown values; they are never silently replaced with zero.
+
+## Documentation
+
+- [Getting started](docs/getting-started.md)
+- [Trace formats and OTLP mapping](docs/trace-formats.md)
+- [Detection rules](docs/detection-rules.md)
+- [Configuration](docs/configuration.md)
+- [Architecture and dependency choices](docs/architecture.md)
+- [Security](docs/security.md)
+- [CI integration](docs/ci-integration.md)
+- [Report contract](docs/report-schema.md)
+- [Troubleshooting](docs/troubleshooting.md)
+- [Limitations](docs/limitations.md)
+- [Pre-release audit](docs/audit.md)
+- [Verification record](docs/verification.md)
+- [Contributing](CONTRIBUTING.md)
+- [Release notes](docs/releases/v1.0.0.md)
+- [Maintainer release procedure](docs/releasing.md)
+
+MIT licensed. No framework-specific compatibility claims are made beyond the documented input mappings.
+
+## Work With Me
+
+Maintained by [Jigar Prajapati](https://github.com/jigar48). For automation and AI tooling projects, visit my [portfolio](https://jigar48.github.io/automatewithjigar/) or connect on [LinkedIn](https://www.linkedin.com/in/buildaiwith-jigar-prajapati/).
+
+If AWI is useful, [optional support](https://buymeacoffee.com/buildwithjigar) helps sustain maintenance. Contributions and reproducible bug reports are welcome; see [Contributing](CONTRIBUTING.md) and [Security](SECURITY.md).

package/SECURITY.md

@@ -0,0 +1,5 @@
+# Security policy
+
+The 1.x line receives security fixes. Never post credentials, private traces or sensitive exploit details publicly. Use GitHub private vulnerability reporting if enabled, or contact the maintainer privately through their GitHub profile. If no private channel exists, open a minimal issue requesting one without sensitive details.
+
+Provide affected version, synthetic reproduction, expected/observed behavior and impact. There is no guaranteed response SLA. Read docs/security.md for threat model, redaction limitations and resource bounds.

package/awi.config.example.json

@@ -0,0 +1,34 @@
+{
+  "version": 1,
+  "rules": {
+    "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
+    }
+  },
+  "fingerprint": {
+    "ignorePaths": []
+  }
+}

package/dist/cli/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node