agent-inspect 0.1.2 → 1.0.1

package/docs/LOG-TO-TREE-QUICKSTART.md

@@ -0,0 +1,54 @@
+## Log-to-tree quickstart
+
+AgentInspect can inspect **structured logs** and render a local execution tree without requiring you to wrap every function in manual tracing.
+
+## Example JSON log lines
+
+`agent.log` (JSONL):
+
+```json
+{"timestamp":"2026-05-08T10:00:00.000Z","requestId":"req_123","event":"agent.started","message":"Agent started"}
+{"timestamp":"2026-05-08T10:00:00.150Z","requestId":"req_123","event":"tool.search.started","tool":"searchDocs"}
+{"timestamp":"2026-05-08T10:00:00.420Z","requestId":"req_123","event":"tool.search.completed","tool":"searchDocs","durationMs":270}
+{"timestamp":"2026-05-08T10:00:00.500Z","requestId":"req_123","event":"llm.answer.started","model":"gpt-example"}
+{"timestamp":"2026-05-08T10:00:01.100Z","requestId":"req_123","event":"llm.answer.completed","model":"gpt-example","durationMs":600}
+{"timestamp":"2026-05-08T10:00:01.150Z","requestId":"req_123","event":"agent.completed","status":"ok"}
+```
+
+## Parse logs into trees
+
+```bash
+npx agent-inspect logs ./agent.log \
+  --format json \
+  --run-id-key requestId \
+  --event-key event \
+  --timestamp-key timestamp
+```
+
+Example output:
+
+```text
+Run req_123
+├─ agent.started
+├─ tool.search.started
+├─ tool.search.completed (270ms)
+├─ llm.answer.started
+├─ llm.answer.completed (600ms)
+└─ agent.completed (ok)
+```
+
+## Important notes
+
+- **JSON logs are first-class**. (Line-delimited JSON is the recommended input.)
+- **log4js text logs with embedded JSON are best-effort**.
+- AgentInspect does **not** evaluate JavaScript object strings (`eval` is not used).
+- **Flat timeline is the default** for log-derived events.
+- Nesting is conservative: **explicit parent/config wins**, and inferred relationships are labeled.
+- **Confidence labels** explain how relationships were inferred (`explicit`, `correlated`, `heuristic`, `unknown`).
+- **Redaction** is applied where configured/defaulted for log-derived attributes and exports.
+
+See also:
+- `docs/CLI.md` (`logs`, `tail`)
+- `docs/LOGS.md`
+- `docs/SCHEMA.md` (log ingest config types + confidence)
+

package/docs/LOGS.md

@@ -0,0 +1,13 @@
+## Logs (structured log → tree)
+
+AgentInspect can parse **existing logs** (line-delimited JSON, and best-effort log4js-style text with embedded JSON) into a local execution tree / grouped timeline.
+
+- **CLI usage**: `docs/CLI.md` (`logs`, `tail`)
+- **Quickstart**: `docs/LOG-TO-TREE-QUICKSTART.md`
+- **Log ingest config (field mapping + redaction)**: `docs-local/architecture/LOG-INGEST-CONFIG.md`
+- **Safety constraints** (no eval, no JS object parsing): `docs-local/architecture/ARCHITECTURE.md`
+
+Notes:
+- Log parsing APIs are documented as **experimental** in `docs/API.md`.
+- Log-derived events include **confidence labels**; AgentInspect is conservative about inferring parent/child structure.
+

package/docs/MIGRATION.md

@@ -0,0 +1,109 @@
+# Migration guide (to AgentInspect 1.0)
+
+This guide summarizes how to move from early AgentInspect MVP usage to **AgentInspect 1.0**.
+
+AgentInspect remains local-first: it does not introduce any network upload or vendor sink workflows.
+
+## Scope
+
+Covered:
+
+- manual tracing (`inspectRun`, `step`, `observe`)
+- trace directory behavior
+- CLI commands (`list`, `view`, `clean`, `logs`, `tail`, `export`, `diff`)
+- optional packages (`@agent-inspect/langchain`, `@agent-inspect/tui`)
+- schema compatibility guarantees
+
+Not covered:
+
+- publish/version bump workflows (see `docs-local/RELEASE-CHECKLIST.md`)
+- vendor sinks (not implemented)
+- replay (not implemented)
+- cost engine (not implemented)
+
+## Manual tracing API
+
+If you were using:
+
+```ts
+import { inspectRun, step } from "agent-inspect";
+```
+
+that remains the recommended stable path. AgentInspect 1.0 is specifically about keeping these entry points compatible.
+
+### Event names and failure representation
+
+Manual JSONL event names remain stable:
+
+- `run_started`
+- `run_completed`
+- `step_started`
+- `step_completed`
+
+There is **no `step_failed` event**. Step failures are represented as:
+
+- `step_completed` with `status: "error"`
+
+Existing `schemaVersion: "0.1"` traces remain readable. No migration command is required.
+
+## Trace directory behavior
+
+- `AGENT_INSPECT_TRACE_DIR` is supported.
+- When unset, AgentInspect uses its default local directory (see `docs/CLI.md` and `docs/API.md`).
+- Trace files are JSONL and are not automatically rewritten.
+
+## CLI changes and additive commands
+
+Manual inspection commands (`list`, `view`) are stable and local-only.
+
+The following commands are additive workflows that remain local-only:
+
+- `logs`: parse structured logs into normalized trees
+- `tail`: live-tail structured logs in the terminal
+- `export`: export a manual trace as Markdown/HTML/OpenInference-compatible JSON/OTLP JSON (local-only)
+- `diff`: compare two manual traces (local, read-only)
+
+### `clean` is safety-critical
+
+`clean` verifies traces before deletion using conservative heuristics. If a file cannot be verified as an AgentInspect trace, it is skipped.
+
+## Logs and tail
+
+- JSON logs are first-class.
+- log4js parsing is best-effort.
+- No JS object literal parsing or `eval`.
+- Redaction is applied to log-derived attributes based on config/default rules.
+
+## Export and share safety
+
+- Exports are **generated locally** and do not upload anywhere.
+- Exporters default to **redacted** and **bounded** attribute previews.
+- Always review exports before sharing.
+
+## Diff and compare
+
+- Diff compares two existing local traces.
+- Diff does not rerun agents, mutate trace files, or call an LLM.
+
+## Optional LangChain adapter
+
+`@agent-inspect/langchain` is optional and separate from core. It uses `@langchain/core` as a **peer dependency**.
+
+## Optional TUI
+
+`@agent-inspect/tui` is optional and separate from core. It contains `ink`/`react` dependencies so the main `agent-inspect` install remains lean.
+
+## Breaking changes
+
+This stabilization effort aims to avoid breaking changes. If a breaking change is ever required:
+
+- it requires a major version
+- it must preserve trace readability where possible
+- it must be explicitly documented
+
+## Known non-migrations
+
+- No vendor sink migration exists because there are **no vendor sinks** in core.
+- No replay migration exists because replay is **not implemented**.
+- No cost engine migration exists because cost calculation is **not implemented**.
+

package/docs/SCHEMA.md

@@ -0,0 +1,199 @@
+# Schema (AgentInspect 1.0)
+
+This document describes the **persisted manual trace JSONL schema** and the **log-derived normalized model** used by AgentInspect.
+
+## 1. Overview
+
+AgentInspect has two related (but distinct) data models:
+
+1. **Manual trace JSONL** (persisted): lines of `TraceEvent` written by `inspectRun()` / `step()`.
+2. **Log-derived normalized model** (in-memory): `InspectEvent` / `InspectRunTree` built from structured logs or adapters.
+
+Important: log-derived trees are **normalized views**, not the same persisted JSONL schema.
+
+## 2. Manual trace JSONL schema
+
+### 2.1 File format
+
+- One JSON object per line (JSONL)
+- Lines may be skipped if invalid JSON or invalid event shape
+- AgentInspect does **not** automatically rewrite old trace files
+
+### 2.2 Current schemaVersion
+
+Manual trace events use:
+
+- **`schemaVersion: "0.1"`**
+
+Existing `0.1` traces remain readable in v1.0.
+
+### 2.3 TraceEvent union
+
+The stable event names are:
+
+- `run_started`
+- `run_completed`
+- `step_started`
+- `step_completed`
+
+There is **no** `step_failed` event. Failures are represented by `step_completed` with `status: "error"`.
+
+### 2.4 Common fields
+
+Every trace line contains:
+
+- `schemaVersion: "0.1"`
+- `event: string`
+- `timestamp: number` (ms since epoch)
+
+## 3. Event definitions
+
+### 3.1 `run_started`
+
+```ts
+{
+  schemaVersion: "0.1",
+  event: "run_started",
+  timestamp: number,
+  runId: string,
+  name: string,
+  startTime: number,
+  metadata?: Record<string, unknown>
+}
+```
+
+### 3.2 `run_completed`
+
+```ts
+{
+  schemaVersion: "0.1",
+  event: "run_completed",
+  timestamp: number,
+  runId: string,
+  status: "success" | "error",
+  endTime: number,
+  durationMs: number,
+  error?: { message: string, stack?: string }
+}
+```
+
+### 3.3 `step_started`
+
+```ts
+{
+  schemaVersion: "0.1",
+  event: "step_started",
+  timestamp: number,
+  runId: string,
+  stepId: string,
+  parentId?: string,
+  name: string,
+  type: "run" | "llm" | "tool" | "decision" | "logic" | "state" | "custom",
+  startTime: number,
+  metadata?: Record<string, unknown>
+}
+```
+
+### 3.4 `step_completed`
+
+```ts
+{
+  schemaVersion: "0.1",
+  event: "step_completed",
+  timestamp: number,
+  runId: string,
+  stepId: string,
+  status: "success" | "error",
+  endTime: number,
+  durationMs: number,
+  error?: { message: string, stack?: string }
+}
+```
+
+## 4. Error representation
+
+- Errors are structured as `{ message, stack? }`.
+- AgentInspect prints short human errors by default; verbose modes may include stack strings.
+
+## 5. Status representation
+
+Manual trace statuses:
+
+- Run: `status: "success" | "error"` on `run_completed`
+- Step: `status: "success" | "error"` on `step_completed`
+
+There is no `"unknown"` status in the persisted manual trace event itself; `"unknown"` can appear in **derived metadata** when status cannot be determined safely.
+
+Unknown status must **not** be treated as success.
+
+## 6. Metadata policy
+
+- Runs may include `metadata` on `run_started`.
+- Steps may include `metadata` on `step_started`.
+- Manual traces intentionally avoid full prompt/output capture by default.
+
+## 7. Additive fields and unknown fields
+
+- Additive changes are allowed in minor versions.
+- Readers should ignore unknown fields where safe.
+- Breaking schema changes require a major version.
+
+## 8. Malformed lines
+
+Manual trace reading:
+
+- invalid JSON lines are skipped
+- JSON objects that fail strict `TraceEvent` validation are skipped
+
+## 9. Backward compatibility
+
+- v0.1 JSONL traces remain readable in v1.0.
+- No automatic migrations or rewriting of old files.
+
+## 10. Breaking change policy
+
+- Breaking changes require a major version.
+- Stable v1.x policy: avoid removing stable fields/events; prefer additive extensions.
+
+## 11. Log-derived InspectEvent model
+
+Log-derived events normalize into:
+
+```ts
+interface InspectEvent {
+  eventId: string;
+  runId: string;
+  parentId?: string;
+  name: string;
+  kind: "RUN" | "AGENT" | "LLM" | "TOOL" | "CHAIN" | "RETRIEVER" | "DECISION" | "RESULT" | "ERROR" | "LOGIC" | "LOG";
+  timestamp: number;
+  status?: "running" | "ok" | "error";
+  durationMs?: number;
+  attributes?: Record<string, unknown>;
+  confidence: "explicit" | "correlated" | "heuristic" | "unknown";
+  source: { type: "manual" | "json-log" | "log4js" | "pino" | "winston" | "adapter"; file?: string; line?: number };
+}
+```
+
+## 12. Confidence labels (required)
+
+Log-derived trees must remain honest:
+
+- `explicit`: parent relationship is directly known (parentId, adapter parent, etc.)
+- `correlated`: grouped by run id / request id keys
+- `heuristic`: inferred from patterns (used sparingly)
+- `unknown`: missing key evidence (e.g. missing timestamp)
+
+## 13. Redaction considerations
+
+Redaction is applied to log-derived attributes and to exports by default. **Manual trace metadata is user-controlled** and should be treated as potentially sensitive.
+
+Always review any exported content (Markdown/HTML/OpenInference/OTLP JSON) before sharing, especially if you enable richer attribute inclusion.
+
+See: `docs-local/architecture/REDACTION.md`.
+
+## 14. Migration notes
+
+- Minor releases may add optional fields/events, but must keep existing v0.1 traces readable.
+- Migration guides (v0.1 → v1.0) are out of scope for this pass, but this document is the canonical schema reference for that future guide.
+

package/docs/SCREENSHOTS.md

@@ -0,0 +1,14 @@
+## Screenshots / GIFs (planned)
+
+This repo does not currently include screenshots or recorded GIFs in the npm package.
+
+Recommended captures to add (when convenient):
+
+- [ ] Basic trace tree (`inspectRun` + `step`)
+- [ ] Failed tool call / failed step rendering
+- [ ] `agent-inspect logs` output (JSON logs)
+- [ ] `agent-inspect diff` output
+- [ ] Optional TUI (`agent-inspect view <run-id> --tui`)
+
+<!-- Add screenshots after running `examples/00-quickstart-demo` locally. -->
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-inspect",
-  "version": "0.1.2",
+  "version": "1.0.1",
   "license": "MIT",
   "type": "module",
   "description": "Local-first execution-tree debugger for TypeScript AI agents",
@@ -12,6 +12,7 @@
     "url": "https://github.com/rajudandigam/agent-inspect/issues"
   },
   "homepage": "https://github.com/rajudandigam/agent-inspect#readme",
+  "packageManager": "pnpm@9.15.0",
   "main": "./packages/core/dist/index.cjs",
   "module": "./packages/core/dist/index.mjs",
   "types": "./packages/core/dist/index.d.ts",
@@ -29,7 +30,24 @@
     "packages/core/dist",
     "packages/cli/dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "SECURITY.md",
+    "CHANGELOG.md",
+    "docs/GETTING-STARTED.md",
+    "docs/API.md",
+    "docs/CLI.md",
+    "docs/SCHEMA.md",
+    "docs/LIMITATIONS.md",
+    "docs/KNOWN-ISSUES.md",
+    "docs/MIGRATION.md",
+    "docs/ARCHITECTURE.md",
+    "docs/LOGS.md",
+    "docs/EXPORTS.md",
+    "docs/DIFF.md",
+    "docs/ADAPTERS.md",
+    "docs/COMPARE.md",
+    "docs/LOG-TO-TREE-QUICKSTART.md",
+    "docs/SCREENSHOTS.md"
   ],
   "sideEffects": false,
   "keywords": [
@@ -45,35 +63,43 @@
   "publishConfig": {
     "access": "public"
   },
+  "engines": {
+    "node": ">=20"
+  },
   "dependencies": {
     "chalk": "^5.3.0",
     "nanoid": "^5.0.9",
     "commander": "^12.1.0"
   },
-  "devDependencies": {
-    "@changesets/cli": "^2.27.10",
-    "@size-limit/preset-small-lib": "^11.1.6",
-    "@types/node": "^22.10.2",
-    "@vitest/coverage-v8": "^2.1.8",
-    "size-limit": "^11.1.6",
-    "tsup": "^8.3.5",
-    "typescript": "^5.7.2",
-    "vitest": "^2.1.8"
-  },
   "scripts": {
     "clean": "pnpm -r exec -- rm -rf dist",
-    "build": "pnpm exec tsup --config tsup.core.config.ts && pnpm exec tsup --config tsup.cli.config.ts",
+    "build": "pnpm exec tsup --config tsup.core.config.ts && pnpm exec tsup --config tsup.cli.config.ts && pnpm exec tsup --config tsup.langchain.config.ts && pnpm exec tsup --config tsup.tui.config.ts",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "size": "size-limit --config size-limit.config.mjs",
     "test:all": "pnpm run typecheck && pnpm run test && pnpm run build && pnpm run size",
-    "prepublish:checks": "pnpm run typecheck && pnpm run test && pnpm run build && pnpm run size && pnpm run pack:smoke",
+    "prepublish:checks": "pnpm run typecheck && pnpm run test && pnpm run test:coverage && pnpm run build && pnpm run fixtures:check && pnpm run recipes:check && pnpm run size && pnpm run pack:smoke",
+    "prepublishOnly": "pnpm run prepublish:checks",
+    "prepack": "pnpm run clean && pnpm run build",
     "pack:dry-run": "pnpm run build && npm pack --dry-run",
     "pack:smoke": "pnpm run build && node scripts/package-smoke.mjs",
+    "fixtures:check": "node scripts/validate-fixtures.mjs",
+    "recipes:check": "node scripts/validate-recipes.mjs",
+    "perf:baseline": "node scripts/performance-baseline.mjs",
     "examples:check": "pnpm install && pnpm --filter agent-inspect-example-01-basic run start",
     "changeset": "changeset",
     "release": "changeset publish"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.27.10",
+    "@size-limit/preset-small-lib": "^11.1.6",
+    "@types/node": "^22.10.2",
+    "@vitest/coverage-v8": "^2.1.8",
+    "size-limit": "^11.1.6",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
   }
-}
+}