agent-inspect 1.0.2 → 1.0.3

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 1.0.3
+
+### Patch Changes
+
+- Add `enabled` option and `maybeInspectRun` helper for env-gated tracing (`AGENT_INSPECT`).
+- Fix CJS/ESM conditional type exports for TypeScript consumers.
+- Add community contributor scaffold and issue drafts.
+
 ## 1.0.2
 
 ### Patch Changes

package/README.md

@@ -93,6 +93,18 @@ support-agent
 
 A runnable copy lives in [examples/00-quickstart-demo](examples/00-quickstart-demo/README.md).
 
+**Env-gated tracing** (eval harnesses, CI): use `maybeInspectRun` and set `AGENT_INSPECT=1` when you want a trace — otherwise no files are written.
+
+```ts
+import { maybeInspectRun } from "agent-inspect";
+
+await maybeInspectRun("eval-case-42", async () => runAgent());
+```
+
+```bash
+AGENT_INSPECT=1 node eval-runner.mjs
+```
+
 ## What the trace shows
 
 Each run produces a **JSONL** trace: `run_started` / `run_completed`, `step_started` / `step_completed`, with **nested steps**, **tool/LLM** types where you use `step.tool` / `step.llm`, and **durations** on completed steps. Failures are recorded on `step_completed` with `status: "error"` (there is no separate `step_failed` event). See [docs/SCHEMA.md](docs/SCHEMA.md).
@@ -155,7 +167,9 @@ Full flags and behavior: [docs/CLI.md](docs/CLI.md).
 - Inspect runs with **`list`** and **`view`**
 - Safely remove old trace files with **`clean`**
 
-**Stable APIs:** `inspectRun()`, `step()`, `step.llm()`, `step.tool()`, `observe()`.
+**Stable APIs:** `inspectRun()`, `maybeInspectRun()`, `step()`, `step.llm()`, `step.tool()`, `observe()`.
+
+Pass `enabled: false` to `inspectRun` for a no-trace passthrough. Use `maybeInspectRun` with `AGENT_INSPECT=1` (or `true` / `yes` / `on` / `enabled`) to toggle tracing in eval or CI jobs — see [docs/API.md](docs/API.md).
 
 **Stable CLI workflows:** `agent-inspect list`, `agent-inspect view`, `agent-inspect clean`.
 

package/docs/API.md

@@ -22,10 +22,12 @@ These are the recommended entry points for manual instrumentation. They are desi
 Import from `agent-inspect`:
 
 ```ts
-import { inspectRun, step, observe } from "agent-inspect";
+import { inspectRun, maybeInspectRun, 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).
+- **`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). **Traces by default** when `enabled` is omitted or `true`. Pass **`enabled: false`** to run `fn` with no trace file, no execution context, and no terminal output.
+- **`maybeInspectRun(name, fn, options?)`**: same as `inspectRun` when tracing is enabled; otherwise passthrough. Enablement: explicit **`options.enabled`** wins; when omitted, reads **`AGENT_INSPECT`** (`1`, `true`, `yes`, `on`, `enabled` — case-insensitive). Unset or other values disable tracing. Use in eval harnesses, CI, or jobs where tracing should be toggled by environment.
+- **`isAgentInspectEnabled(value?)`**: returns whether a string (or `process.env.AGENT_INSPECT`) matches an enable token.
 - **`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`).

package/docs/CLI.md

@@ -31,6 +31,7 @@ Core commands:
 
 - **`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.
+- **`AGENT_INSPECT`**: enables manual tracing for **`maybeInspectRun`** when set to `1`, `true`, `yes`, `on`, or `enabled` (case-insensitive). Unset or any other value disables tracing. Does **not** change default **`inspectRun`** behavior (which always traces unless `enabled: false` is passed in code). No network upload — local JSONL only.
 
 ## 3. Exit code policy
 

package/docs/GETTING-STARTED.md

@@ -38,6 +38,28 @@ This writes a local JSONL trace with stable v1.0 event names:
 - `run_started`, `run_completed`
 - `step_started`, `step_completed`
 
+### Always trace vs env-gated tracing
+
+Use **`inspectRun`** when you always want a local trace (default behavior).
+
+Use **`maybeInspectRun`** in eval harnesses, CI, or production-shaped jobs where tracing should be toggled by environment:
+
+```ts
+import { maybeInspectRun } from "agent-inspect";
+
+await maybeInspectRun("eval-case-42", async () => {
+  return runAgent();
+});
+```
+
+```bash
+AGENT_INSPECT=1 node eval-runner.mjs
+```
+
+Enable tokens: `1`, `true`, `yes`, `on`, `enabled` (case-insensitive). Explicit `enabled: true | false` in options overrides the env var.
+
+To skip tracing in code without env vars: `inspectRun(name, fn, { enabled: false })`.
+
 ## 3. View runs
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-inspect",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "license": "MIT",
   "type": "module",
   "description": "Local-first execution-tree debugger for TypeScript AI agents",
@@ -18,9 +18,14 @@
   "types": "./packages/core/dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./packages/core/dist/index.d.ts",
-      "import": "./packages/core/dist/index.mjs",
-      "require": "./packages/core/dist/index.cjs"
+      "import": {
+        "types": "./packages/core/dist/index.d.ts",
+        "default": "./packages/core/dist/index.mjs"
+      },
+      "require": {
+        "types": "./packages/core/dist/index.d.cts",
+        "default": "./packages/core/dist/index.cjs"
+      }
     }
   },
   "bin": {