agent-inspect 0.1.2 → 1.0.1

package/docs/API.md

@@ -0,0 +1,152 @@
+# API (AgentInspect 1.0)
+
+This document describes the **public TypeScript API surface** of AgentInspect and classifies each area as **stable** or **experimental**.
+
+AgentInspect is a **local-first execution-tree debugger**. It is not a SaaS, not a production APM, not a sink/uploader, and not a replay engine.
+
+## 1. Stability policy
+
+- **Stable**: intended to be compatible across v1.x. Breaking changes require v2.0.
+- **Experimental**: available for adoption, but subject to refinement (including naming/shape changes) before a future stability declaration. Experimental APIs may change in v1.x.
+
+Notes:
+
+- The core guarantee of v1.0 is **stable local debugging**: manual tracing + CLI inspection.
+- Export formats (OpenInference / OTLP JSON) are **local-only** and **compatibility-oriented**. They do **not** upload anywhere.
+- There are **zero production sinks** in v1.0; sink/uploader APIs are not stable.
+
+## 2. Stable core APIs (manual tracing)
+
+These are the recommended entry points for manual instrumentation. They are designed to be dependency-light and safe-by-default.
+
+Import from `agent-inspect`:
+
+```ts
+import { inspectRun, step, observe } from "agent-inspect";
+```
+
+- **`inspectRun(name, fn, options?)`**: wraps a workflow in a local JSONL trace (`run_started` / `run_completed`), prints terminal progress, and swallows instrumentation failures (user errors are re-thrown).
+- **`step(name, fn, options?)`**: traces a named unit of work inside `inspectRun` (`step_started` / `step_completed`).
+  - **`step.llm(model, fn)`**: convenience wrapper (`type: "llm"`, `metadata.model`).
+  - **`step.tool(toolName, fn)`**: convenience wrapper (`type: "tool"`, `metadata.toolName`).
+- **`observe(agent, options?)`**: proxy wrapper that traces top-level `run` / `execute` / `invoke` methods via `inspectRun`.
+
+## 3. Stable local inspection APIs
+
+These APIs support local workflows like listing traces, extracting metadata/summaries, and safety checks for deletion.
+
+- **`TraceDirectory`**, **`resolveTraceDir`**
+- **`extractMetadata`**, **`buildRunSummary`**
+- **`filterTraces`**
+- **`isAgentInspectTrace`** (conservative trace verifier for cleanup)
+- **`parseDuration`**, **`formatDuration`**
+- Types: **`TraceMetadata`**, **`RunSummary`**
+
+## 4. Stable event/config model types
+
+### Manual trace JSONL model (stable)
+
+- **`TraceSchemaVersion`** (`"0.1"`)
+- **`TraceEvent`** union and specific event types:
+  - `RunStartedEvent` (`event: "run_started"`)
+  - `RunCompletedEvent` (`event: "run_completed"`)
+  - `StepStartedEvent` (`event: "step_started"`)
+  - `StepCompletedEvent` (`event: "step_completed"`)
+- Related types: `StepType`, `StepStatus`, `RunStatus`, `ErrorInfo`, `StepMetadata`, `TokenMetadata`
+
+### Log-derived normalized model (stable as a model, not necessarily the parsing APIs)
+
+- **`InspectKind`**
+- **`AttributionConfidence`**
+- **`InspectEvent`**, **`InspectNode`**, **`InspectRunTree`**
+- **`EventSource`**
+
+### Log ingest config types (stable)
+
+- **`LogIngestConfig`**
+- **`LogEventMapping`**
+- **`RedactionRule`**, **`RedactionStrategy`**
+
+## 5. Experimental log parsing APIs
+
+These are compatibility-oriented utilities for turning structured logs into normalized `InspectEvent` and grouped trees. They remain conservative: **no eval**, **no parsing JS object literals**, JSON logs first-class, log4js best-effort.
+
+- **`parseLogsToTrees`**
+- **`JsonLogParser`**, **`Log4jsParser`**
+- **`EventNormalizer`**
+- **`TreeBuilder`**
+- **`Redactor`**
+- **`renderRunTree`**, **`renderRunTrees`**
+- **`parseLogLine`**
+
+## 6. Experimental live tail APIs
+
+The CLI `tail` workflow is supported. The programmatic accumulator is experimental.
+
+- **`LiveLogAccumulator`**
+
+## 7. Experimental standards export APIs
+
+Exports are **read-only**, **local-only**, and **compatibility-oriented**. They do not upload, stream, or integrate vendor SDKs.
+
+- **`exportRunTree`**
+- **`exportMarkdown`**, **`exportHtml`**
+- **`exportOpenInference`** (OpenInference-compatible JSON)
+- **`exportOtlpJson`** (OTLP JSON, experimental until verified per backend)
+- **`validateExport`**, `validateExportContent` (validation helpers)
+
+## 8. Experimental diff APIs
+
+Diff is local and read-only. Programmatic diff surfaces are experimental until the comparison semantics are explicitly frozen.
+
+- **`diffRuns`**
+- **`diffTraceEvents`**
+- **`renderRunDiff`**
+- **`manualTraceEventsToComparableRun`**
+
+## 9. Experimental `@agent-inspect/langchain` APIs
+
+`@agent-inspect/langchain` is an optional adapter package.
+
+- **`AgentInspectCallback`** (experimental)
+- Metadata helpers: `extractModelName`, `extractTokenUsage`, `safePreview`, `toPlainMetadata`
+
+Rationale: v1.0 includes one official adapter and **zero production sinks**, so adapter surfaces remain experimental.
+
+## 10. Experimental `@agent-inspect/tui` APIs
+
+`@agent-inspect/tui` is an optional package. CLI integration via `agent-inspect view --tui` is supported; programmatic TUI APIs remain experimental.
+
+- `runTraceViewer`, `loadTraceForTui`, `buildTuiTraceModel`, etc.
+
+## 11. Deprecated APIs
+
+No deprecated APIs are declared in v1.0 Pass 1.
+
+## 12. Removal / deprecation policy
+
+- Stable APIs are not removed in v1.x.
+- If removal is necessary, the API should be **deprecated** first, documented, and kept for a reasonable window (target: at least one minor line) unless security requires faster action.
+
+## 13. Backward compatibility policy
+
+- Manual trace JSONL (`schemaVersion: "0.1"`) remains readable.
+- Additive schema changes are allowed in minor versions.
+- Breaking changes require a major version.
+- Unknown fields should be ignored where safe.
+
+## 14. Examples
+
+### Minimal manual trace
+
+```ts
+import { inspectRun, step } from "agent-inspect";
+
+await inspectRun("demo-agent", async () => {
+  const plan = await step("plan", async () => "ok");
+  const hits = await step.tool("search", async () => ({ count: 2 }));
+  const answer = await step.llm("fixture-model", async () => "done");
+  return { plan, hits, answer };
+});
+```
+

package/docs/ARCHITECTURE.md

@@ -0,0 +1,13 @@
+## Architecture
+
+This doc is a stable entry point for AgentInspect’s internal architecture and product boundaries.
+
+- **Canonical architecture overview**: see `docs-local/architecture/ARCHITECTURE.md`
+- **Event model**: `docs-local/architecture/EVENT-MODEL.md`
+- **Tree building rules**: `docs-local/architecture/TREE-BUILDING-RULES.md`
+- **Schema evolution policy**: `docs-local/architecture/SCHEMA-EVOLUTION.md`
+- **Dependency policy**: `docs-local/architecture/DEPENDENCY-POLICY.md`
+- **Redaction design**: `docs-local/architecture/REDACTION.md`
+
+If you’re new, start with `docs/GETTING-STARTED.md`, then `docs/API.md`, `docs/CLI.md`, and `docs/SCHEMA.md`.
+

package/docs/CLI.md

@@ -0,0 +1,212 @@
+# CLI (AgentInspect 1.0)
+
+This document describes the **stable CLI surface** of AgentInspect.
+
+AgentInspect is **local-first** and **read-only by default** where possible:
+
+- **No upload** (exports write local strings/files only)
+- **No vendor sinks**
+- **No external services required**
+- **No replay/fork execution**
+
+## 1. Overview
+
+The CLI command is:
+
+```bash
+agent-inspect <command> [options]
+```
+
+Core commands:
+
+- `list` — list local runs
+- `view` — render a single run
+- `clean` — safely delete old runs (verified traces only)
+- `logs` — parse structured logs into local execution trees
+- `tail` — live-tail logs into updating local trees
+- `export` — export manual traces to Markdown/HTML/OpenInference/OTLP JSON (local only)
+- `diff` — compare two manual traces (local, read-only)
+
+## 2. Environment variables
+
+- **`AGENT_INSPECT_TRACE_DIR`**: default directory for manual trace files (`.jsonl`) when not passed via `--dir` (or API options).
+- **`AGENT_INSPECT_SILENT`**: when `true`, suppresses live terminal tree output during manual tracing (`inspectRun` / `step`). Trace files are still written.
+
+## 3. Exit code policy
+
+- **0**: command succeeded (even if a diff reports “differences”)
+- **1**: command error (invalid args, missing files, missing runs, parse failures, validation failures, etc.)
+
+AgentInspect favors **human-readable errors without stack traces** for expected user mistakes.
+
+## 4. JSON output policy
+
+Many commands support `--json` for scripting. JSON output is intended to be:
+
+- machine-parseable
+- deterministic for the same input files
+- local-only (no network)
+
+## 5. Safety and redaction notes
+
+- Log-derived output includes **confidence** labels and avoids inventing parent-child relationships.
+- Redaction defaults are conservative (e.g. `authorization`, `cookie`, `token`, `apiKey`, `password`, `secret`, `email`).
+- Exported payloads are **redacted by default** unless explicitly configured otherwise.
+
+## 6. Command reference
+
+### 6.1 `list`
+
+List recent local runs (trace files).
+
+```bash
+agent-inspect list [options]
+```
+
+Options:
+
+- `--dir <path>`: trace directory
+- `--limit <number>`: max runs to show (default 20, max 100)
+- `--status <running|success|error|unknown>`: filter by status
+- `--name <query>`: substring match on run id/name
+- `--since <duration>`: only include recent runs (e.g. `30s`, `5m`, `2h`, `7d`)
+- `--json`: print list as JSON
+
+### 6.2 `view`
+
+Render a single manual trace by run id.
+
+```bash
+agent-inspect view <run-id> [options]
+```
+
+Options:
+
+- `--dir <path>`: trace directory
+- `--summary`: run summary (counts, max depth, longest step)
+- `--metadata`: file path/size + timestamps
+- `--errors-only`: only error events/failed steps
+- `--verbose`: include extra detail (types, metadata, stacks)
+- `--json`: print raw trace events as JSON
+- `--tui`: open optional interactive TUI viewer (requires `@agent-inspect/tui`)
+
+### 6.3 `clean`
+
+Safely delete old local trace files. This is safety-critical: the CLI verifies trace files before deletion.
+
+```bash
+agent-inspect clean --older-than <duration> [--dry-run] [--yes]
+agent-inspect clean --keep <count> [--dry-run] [--yes]
+```
+
+Options:
+
+- `--dir <path>`: trace directory
+- `--older-than <duration>`: delete runs older than a duration
+- `--keep <count>`: keep N most recent runs
+- `--dry-run`: show what would be deleted
+- `--yes`: skip confirmation prompt
+
+Recommendation: run with `--dry-run` first.
+
+### 6.4 `logs`
+
+Parse structured logs into local execution trees.
+
+```bash
+agent-inspect logs <file> [options]
+```
+
+Options:
+
+- `--format <auto|json|log4js>`
+- `--config <path>`: ingest config JSON (see `docs/SCHEMA.md` for config types)
+- `--run-id-key <keys>`: override runId keys (comma-separated)
+- `--event-key <key>`: override event key
+- `--timestamp-key <key>`: override timestamp key
+- `--message-key <key>`: override message key
+- `--level-key <key>`: override level key
+- `--parent-id-key <key>`: override parent id key
+- `--duration-key <key>`: override duration key
+- `--status-key <key>`: override status key
+- `--json`: emit JSON payload (events/trees/warnings/summary)
+- `--summary`: include summary section in human output
+- `--warnings <none|summary|all>`: warning output mode
+
+Example (fixtures):
+
+```bash
+agent-inspect logs fixtures/logs/proactive-json.log --format json --config fixtures/configs/proactive-agent-inspect.logs.json
+```
+
+### 6.5 `tail`
+
+Live-tail logs into updating execution trees in the terminal.
+
+```bash
+agent-inspect tail [options]
+```
+
+Options:
+
+- `--file <path>`: tail a file (otherwise reads stdin)
+- `--format <auto|json|log4js>`
+- `--config <path>`
+- `--once`: read once and exit (useful for CI/scripting with `--file`)
+- `--warnings <none|summary|all>`
+- `--refresh <ms>`: minimum time between renders
+- `--json`: newline-delimited JSON updates
+
+Important: `tail` is a local developer tool, not a production monitor.
+
+### 6.6 `export`
+
+Export a manual trace run to local formats. **No upload**.
+
+```bash
+agent-inspect export <run-id> --format <markdown|html|openinference|otlp-json> [options]
+```
+
+Options:
+
+- `--dir <path>`
+- `--format <format>`
+- `-o, --output <path>`: write file
+- `--json`: JSON wrapper output (includes content if not writing to file)
+- `--validate`: validate exported payload shape
+- `--include-attributes`: include bounded attributes (review before sharing)
+- `--no-metadata`: omit summary/metadata sections
+- `--no-errors`: omit error sections
+
+### 6.7 `diff`
+
+Compare two manual trace runs. Diff is **local** and **read-only** (does not rerun agents).
+
+```bash
+agent-inspect diff <left-run-id> <right-run-id> [options]
+```
+
+Options:
+
+- `--dir <path>`
+- `--json`
+- `--ignore-duration`
+- `--duration-threshold <duration>`
+- `--focus <all|errors|structure|outputs>`
+- `--check <all|structure|outputs|errors|timing>`
+
+## 7. Optional TUI behavior
+
+`view --tui` delegates to `@agent-inspect/tui` and requires an interactive terminal. If the package is not installed, the CLI prints a short install hint.
+
+## 8. Warnings behavior
+
+Log parsing emits warnings for malformed lines or missing required keys. `--warnings` controls whether warnings are hidden, summarized, or printed line-by-line.
+
+## 9. Limitations (reminder)
+
+See:
+
+- `docs/KNOWN-ISSUES.md`
+- `docs/LIMITATIONS.md`
+

package/docs/COMPARE.md

@@ -0,0 +1,69 @@
+## Compare AgentInspect
+
+AgentInspect is a local-first execution-tree debugger for TypeScript AI agents. It’s designed for inner-loop debugging and quick inspection — not as a replacement for hosted observability, evaluation, or production monitoring platforms.
+
+## AgentInspect vs console.log
+
+- **console.log is flat**: logs are a stream of lines without run grouping or step boundaries.
+- **AgentInspect adds structure**: runs, nested steps, step types (tool/LLM), durations, status summaries, and local trace files you can inspect later.
+- **console.log still matters**: use it for quick values or ad-hoc debugging inside a step.
+- **AgentInspect helps you understand flow**: especially when your agent fans out, retries, or has nested tool/LLM calls.
+
+## AgentInspect vs LangSmith
+
+LangSmith is a hosted/platform workflow for tracing, evaluation, and observability in the LangChain ecosystem.
+
+AgentInspect is local-first CLI debugging:
+
+- Use AgentInspect to debug locally before/alongside LangSmith when iterating on agent logic.
+- AgentInspect does not provide hosted dashboards, dataset/eval workflows, or production tracing pipelines.
+
+## AgentInspect vs Langfuse
+
+Langfuse provides broader LLM observability (tracing, prompt management, datasets/evals, dashboards).
+
+AgentInspect focuses on local execution trees and CLI workflows:
+
+- Complementary: use AgentInspect for quick local run understanding; use Langfuse for dashboards and longer-lived observability workflows.
+- Not a replacement.
+
+## AgentInspect vs Braintrust
+
+Braintrust is strong for evals, regressions, datasets, and production AI quality workflows.
+
+AgentInspect is lighter and local-first:
+
+- Use AgentInspect to understand a single run locally.
+- Use Braintrust when you want repeatable evals, comparisons at scale, and production quality workflows.
+
+## AgentInspect vs Phoenix / OpenInference
+
+Phoenix and the OpenInference ecosystem are standards-oriented and useful for trace visualization and interoperability.
+
+AgentInspect can export **OpenInference-compatible JSON** and **OTLP JSON** as local files:
+
+- Exports are **compatibility-oriented** and should be validated against your target backend/collector.
+- AgentInspect does not claim that every backend will accept these exports without configuration.
+
+## AgentInspect vs OpenTelemetry setup
+
+OpenTelemetry is powerful, but setup can be heavier (SDK configuration, exporters, collectors, backend).
+
+AgentInspect avoids SDK/collector setup for local debugging:
+
+- Use AgentInspect when you want quick, local execution trees with no collector required.
+- Use OpenTelemetry when you need organization-wide production telemetry pipelines.
+- Exports can help bridge later, but AgentInspect is not an OpenTelemetry SDK replacement.
+
+## Quick decision table
+
+| Need | AgentInspect fit |
+| --- | --- |
+| Local agent debugging | Strong fit |
+| No-account CLI tracing | Strong fit |
+| Production dashboards | Not the goal |
+| Hosted eval datasets | Not the goal |
+| Prompt management | Not the goal |
+| Standards-aligned local export | Partial (compatibility-oriented) |
+| Full observability platform | Use a dedicated platform |
+

package/docs/DIFF.md

@@ -0,0 +1,11 @@
+## Diff / compare
+
+AgentInspect can compare two runs (manual traces) locally and render a diff summary.
+
+- **CLI usage**: `docs/CLI.md` (`diff`)
+- **Schema expectations for diff inputs**: `docs/SCHEMA.md` (manual trace JSONL, `schemaVersion: "0.1"`)
+
+Notes:
+- Programmatic diff APIs are documented as **experimental** in `docs/API.md`.
+- `diff` is read-only and does **not** rerun agents; “differences” do not necessarily imply failure (command errors do).
+

package/docs/EXPORTS.md

@@ -0,0 +1,12 @@
+## Exports
+
+AgentInspect supports local-only exports from run trees and traces. Exports are intended for **compatibility and sharing**, but should be reviewed before sending to others.
+
+- **CLI usage**: `docs/CLI.md` (`export`)
+- **Schema + compatibility guarantees**: `docs/SCHEMA.md`
+- **Safety / redaction notes**: `docs/CLI.md`, `SECURITY.md`, and `docs-local/architecture/REDACTION.md`
+
+Notes:
+- Export formats (Markdown/HTML/OpenInference/OTLP JSON) are documented as **experimental / compatibility-oriented** in `docs/API.md`.
+- AgentInspect does **not** upload anywhere; exports write local strings/files only.
+

package/docs/GETTING-STARTED.md

@@ -0,0 +1,128 @@
+# Getting started
+
+AgentInspect is a **local-first execution-tree debugger** for TypeScript AI agents. It helps you produce and inspect an execution tree of steps, safely and deterministically, without uploading data anywhere.
+
+## 1. Install
+
+```bash
+pnpm add agent-inspect
+```
+
+The `agent-inspect` package includes the CLI binary via its `bin` field:
+
+```bash
+npx agent-inspect --help
+```
+
+For local repo development (this monorepo), build and run the CLI from `packages/cli`:
+
+```bash
+pnpm build
+node packages/cli/dist/index.cjs --help
+```
+
+## 2. Basic manual trace
+
+```ts
+import { inspectRun, step } from "agent-inspect";
+
+await inspectRun("demo-agent", async () => {
+  await step("plan", async () => "ok");
+  await step.tool("search", async () => ({ count: 2 }));
+  await step.llm("fixture-model", async () => "done");
+});
+```
+
+This writes a local JSONL trace with stable v1.0 event names:
+
+- `run_started`, `run_completed`
+- `step_started`, `step_completed`
+
+## 3. View runs
+
+```bash
+agent-inspect list
+agent-inspect view <runId>
+```
+
+## 4. Clean old runs (safely)
+
+Always start with `--dry-run`:
+
+```bash
+agent-inspect clean --older-than 7d --dry-run
+agent-inspect clean --older-than 7d --yes
+```
+
+## 5. Parse existing logs
+
+```bash
+agent-inspect logs fixtures/logs/proactive-json.log \
+  --format json \
+  --config fixtures/configs/proactive-agent-inspect.logs.json
+```
+
+## 6. Tail logs
+
+For scripting/CI-style usage, `--once` reads and exits:
+
+```bash
+agent-inspect tail \
+  --file fixtures/logs/proactive-json.log \
+  --format json \
+  --config fixtures/configs/proactive-agent-inspect.logs.json \
+  --once
+```
+
+## 7. Export a run
+
+```bash
+agent-inspect export minimal-success --dir fixtures/traces --format markdown
+agent-inspect export minimal-success --dir fixtures/traces --format openinference --validate
+```
+
+Exports are **local-only** and do not upload anywhere.
+
+## 8. Diff two runs
+
+```bash
+agent-inspect diff minimal-success minimal-error --dir fixtures/traces
+```
+
+## 9. Try recipes
+
+See `examples/recipes/README.md`.
+
+## 10. Optional LangChain adapter
+
+`@agent-inspect/langchain` is optional and **experimental**:
+
+```bash
+pnpm add @agent-inspect/langchain
+```
+
+## 11. Optional TUI
+
+`@agent-inspect/tui` is optional and **experimental**. The CLI can invoke it with:
+
+```bash
+agent-inspect view <runId> --tui
+```
+
+## 12. Safety notes
+
+- Redaction is on by default for log-derived attributes and exports.
+- Confidence labels are required to keep attribution honest.
+- AgentInspect is for local debugging, not production monitoring.
+
+## 13. Next docs
+
+- `docs/API.md`
+- `docs/CLI.md`
+- `docs/SCHEMA.md`
+- `docs/COMPARE.md`
+- `docs/LOG-TO-TREE-QUICKSTART.md`
+- `docs/KNOWN-ISSUES.md`
+- `docs/LIMITATIONS.md`
+- `docs-local/V1-READINESS-CHECKLIST.md`
+

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).