agent-inspect 1.0.1 → 1.0.3

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.1",
+  "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": {