agent-inspect 1.0.0 → 1.0.2

package/docs/KNOWN-ISSUES.md

@@ -0,0 +1,34 @@
+# Known issues
+
+AgentInspect is **local-first** and **CLI-first**. These behaviors are intentional constraints or best-effort areas—not silent guarantees.
+
+## Logs
+
+- **log4js-style parsing** is **best-effort**: embedded JSON must be recoverable from the line; unusual layouts may lose fields or warn.
+- **JavaScript object-style log payloads** (e.g. `{ msg: '...', meta: ... }` printed without JSON) are **not** a supported interchange format for ingestion.
+
+## Exports
+
+- **OpenInference** and **OTLP JSON** exports are **compatibility-oriented** and **experimental**. Validate against your target collector or backend before relying on them.
+- Exports generate **strings/files locally** only—there is **no** automatic upload.
+
+## Integrations
+
+- **Vendor sinks** (hosted dashboards, Langfuse/Braintrust/New Relic/Datadog native uploads, OTLP gRPC streaming, etc.) are **not implemented** in the core packages described here.
+- **LangChain adapter** captures **metadata-oriented** signals by default; it does not replace full framework observability.
+
+## UI / replay
+
+- **Optional TUI** (`@agent-inspect/tui`) is separate from the default CLI and requires an interactive terminal where documented.
+- **Live streaming tree inside the TUI** is not the same as **live tail** over logs; product scope varies by version—see roadmap docs.
+- **Full replay / fork execution** of historical traces is **out of scope** for current MVP-style releases.
+
+## Cost / tokens
+
+- **Token counting** and **cost calculation** are **not** core features.
+
+## Confidence labels
+
+- Log-derived trees carry **confidence** (`explicit`, `correlated`, `heuristic`, `unknown`). Labels explain **how** relationships were inferred—they are not semantic proof.
+
+When in doubt, treat AgentInspect as a **debugging aid**, not a compliance or billing system of record.

package/docs/LIMITATIONS.md

@@ -0,0 +1,32 @@
+# Limitations
+
+This document states what AgentInspect **does not** provide today. It complements [KNOWN-ISSUES.md](./KNOWN-ISSUES.md).
+
+## Product boundaries
+
+- **No SaaS dashboard** or hosted multi-tenant product in the open-source core workflow.
+- **No production APM replacement**: no sampling agents, no fleet-wide aggregation, no uptime SLAs.
+- **No vendor upload pipeline**: no built-in Langfuse/Braintrust/New Relic/Datadog direct exporters as live sinks.
+- **No automatic universal instrumentation** of every framework: integration is explicit (manual traces, log ingest, optional adapters).
+
+## Data fidelity
+
+- **No full prompt/output capture by default** for manual traces (by design: safety and PII risk).
+- **Log-derived runs** and **manual JSONL traces** may differ in fidelity (timestamps, nesting, confidence).
+- **Confidence labels** qualify inferred relationships; they do not guarantee correctness.
+
+## Execution semantics
+
+- **No replay / fork** of past runs from traces alone.
+- **No time-travel debugging** across arbitrary runtime state.
+- **No multi-run statistical evaluation** built into core.
+
+## Economics
+
+- **No cost engine**: no pricing tables, invoice-grade usage, or provider billing reconciliation.
+
+## Scale
+
+- Designed for **developer machines** and **inner-loop debugging**, not petabyte log warehouses.
+
+For roadmap intent, see `docs-local/roadmap/VERSION-ROADMAP.md` and `docs-local/prd/v1.0-STABLE-LOCAL-INSPECTOR-PRD.md` (planning docs; not a promise of future features).

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/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": "1.0.0",
+  "version": "1.0.2",
   "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,21 +63,14 @@
   "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 && pnpm exec tsup --config tsup.langchain.config.ts && pnpm exec tsup --config tsup.tui.config.ts",
@@ -70,6 +81,8 @@
     "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 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",
@@ -78,5 +91,15 @@
     "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"
   }
-}
+}

package/packages/cli/dist/index.cjs

@@ -4272,7 +4272,7 @@ function runCommand(action) {
   });
 }
 function createCliProgram() {
-  const program = new commander.Command("agent-inspect").description("Local-first execution-tree debugger for AI agents").version("0.1.0");
+  const program = new commander.Command("agent-inspect").description("Local-first execution-tree debugger for AI agents").version("1.0.0");
   program.command("list").description("List recent AgentInspect runs").option("--dir <path>", "trace directory").option("--limit <number>", "max runs to show (default 20, max 100)").addOption(
     new commander.Option("--status <status>", "filter by run status").choices([
       "running",