@lanegrid/agtrace 0.4.2 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/CHANGELOG.md +144 -0
  2. package/README.md +39 -56
  3. package/npm-shrinkwrap.json +2 -2
  4. package/package.json +2 -2
package/CHANGELOG.md CHANGED
@@ -2,6 +2,150 @@
2
2
 
3
3
  All notable changes to this project will be documented in this file.
4
4
 
5
+ ## [0.5.1] - 2026-01-04
6
+
7
+ ### Bug Fixes
8
+
9
+ - *(release)* Run clippy before version update to fail early ([70e96aa](https://github.com/lanegrid/agtrace/commit/70e96aa72ea90616b7401a4568e4ebe62fdf12d8))
10
+
11
+ - *(release)* Run lightweight checks before tests for faster failure ([66ec9fc](https://github.com/lanegrid/agtrace/commit/66ec9fc297795f08c7cf449450eba5d0a5eb7389))
12
+
13
+
14
+ ### Documentation
15
+
16
+ - Reposition agtrace as observability tool instead of memory system ([f2cb342](https://github.com/lanegrid/agtrace/commit/f2cb3429c51a48cee269bf965b93768aaff94fc6))
17
+
18
+ - Remove agent antipatterns documentation ([8b48857](https://github.com/lanegrid/agtrace/commit/8b4885744d9b6b0190993a299dedab0c0bd76d79))
19
+
20
+
21
+ ## [0.5.0] - 2026-01-03
22
+
23
+ ### Bug Fixes
24
+
25
+ - Session show displays correct ID, provider, and project info ([c72835b](https://github.com/lanegrid/agtrace/commit/c72835b2791098a962bc1f1e04ed805095001a79))
26
+
27
+ - Normalize turn snippets to single line in compact view ([5667977](https://github.com/lanegrid/agtrace/commit/56679774946434db89b865842ee8dece10ddcd48))
28
+
29
+ - Normalize text truncation in user-facing views to handle newlines ([f37a2f8](https://github.com/lanegrid/agtrace/commit/f37a2f8f128dc39ce1b01c15f0d70bee6e1f7450))
30
+
31
+ - Change default ViewMode to Compact and merge Standard into Verbose (#34) ([5c2d6e9](https://github.com/lanegrid/agtrace/commit/5c2d6e9356329954fb69a472f3878057b958c0bd))
32
+
33
+ - Normalize all session header fields to prevent newline display issues ([e87960b](https://github.com/lanegrid/agtrace/commit/e87960b6471b382ad112e260835c09f2829328f4))
34
+
35
+ - Tune MCP get_turns defaults to data-driven limits (3k chars, 30 steps) for safe token usage ([d47d295](https://github.com/lanegrid/agtrace/commit/d47d295cad45e85213f909ce46551c2498a6147b))
36
+
37
+
38
+ ### Documentation
39
+
40
+ - Add real-world MCP workflow example and fix broken links ([bcc5b9a](https://github.com/lanegrid/agtrace/commit/bcc5b9a069c959cd477c42787d858f4722e15c85))
41
+
42
+ - Update MCP tool references to Random Access APIs and remove unused legacy types ([f2b04a7](https://github.com/lanegrid/agtrace/commit/f2b04a7b9df598d82f0aa450f39af40d102605a9))
43
+
44
+ - Update MCP API references in comments and help text to Random Access APIs ([d176a0c](https://github.com/lanegrid/agtrace/commit/d176a0c774bb5bebba32032c024db1a46e7cad64))
45
+
46
+ - Reposition agtrace as memory system for AI agents via MCP ([ffb68ce](https://github.com/lanegrid/agtrace/commit/ffb68ce32033f17e7754348a81fba822709caabc))
47
+
48
+
49
+ ### Features
50
+
51
+ - Change --project-root to --project with --project-root as alias ([346ecda](https://github.com/lanegrid/agtrace/commit/346ecdaae4b095b01f531eaeeee8e34ea663c3ff))
52
+
53
+ - Display both project_hash and project_root in session show ([40b1e8d](https://github.com/lanegrid/agtrace/commit/40b1e8ddfb28a4eaba32948484827520c3b27ed7))
54
+
55
+ - Improve session show display with vertical layout and smart path formatting ([f6a4a32](https://github.com/lanegrid/agtrace/commit/f6a4a320322a77f16ad08a43ecc914d1f50dbfd0))
56
+
57
+ - *(mcp)* Add project filter to search_event_previews ([211d667](https://github.com/lanegrid/agtrace/commit/211d6678aa997ed4f4578f09764ba44a16363085))
58
+
59
+ - Limit project list to top 10 by session count ([11a49e5](https://github.com/lanegrid/agtrace/commit/11a49e5d822fa8135697d00d1cdf0d0b009a4c46))
60
+
61
+ - Improve compact session header with clear key-value format ([298e209](https://github.com/lanegrid/agtrace/commit/298e20990aa1a77a8ae33a18aa29e56fe7d4c7ce))
62
+
63
+ - Compact mode shows turn metadata and tool count only ([506a2cd](https://github.com/lanegrid/agtrace/commit/506a2cd69c79ec19edeada05319d244df01af972))
64
+
65
+ - Add project root column and aligned headers to session list ([6435acf](https://github.com/lanegrid/agtrace/commit/6435acf9af401ed903c0dce334beff9b5b221228))
66
+
67
+ - Auto-fix README version references in release script ([e8cd078](https://github.com/lanegrid/agtrace/commit/e8cd0786c44b5930c8f92898743519afd954497c))
68
+
69
+ - Add Random Access API service layer with safety valves ([197d61a](https://github.com/lanegrid/agtrace/commit/197d61a6fca01065e0bf72408d47030200bc3340))
70
+
71
+ - Update MCP test suite for Random Access APIs with UTF-8 safe truncation ([31196e0](https://github.com/lanegrid/agtrace/commit/31196e028c3f24b9a29e155992b4ef0dc913c277))
72
+
73
+ - Add SessionOrder parameter to session listing queries ([edc3544](https://github.com/lanegrid/agtrace/commit/edc3544cdbd90d83ba6674ebc083d2b4fd5b477d))
74
+
75
+
76
+ ### Refactor
77
+
78
+ - Simplify compact mode to show turn metadata and user msg only ([a07ea3b](https://github.com/lanegrid/agtrace/commit/a07ea3b6e3e167a6950b2702b2bc60a0c3b27915))
79
+
80
+ - Compact mode displays one line per turn ([4af279e](https://github.com/lanegrid/agtrace/commit/4af279e0f80282cbc5cfb15dc485ac57dbd8aaee))
81
+
82
+ - Remove legacy MCP APIs, keep only Random Access APIs ([63968e5](https://github.com/lanegrid/agtrace/commit/63968e533168f32255a66cf6e71f26562210f190))
83
+
84
+
85
+ ## [0.5.0] - 2026-01-03
86
+
87
+ ### Bug Fixes
88
+
89
+ - Session show displays correct ID, provider, and project info ([c72835b](https://github.com/lanegrid/agtrace/commit/c72835b2791098a962bc1f1e04ed805095001a79))
90
+
91
+ - Normalize turn snippets to single line in compact view ([5667977](https://github.com/lanegrid/agtrace/commit/56679774946434db89b865842ee8dece10ddcd48))
92
+
93
+ - Normalize text truncation in user-facing views to handle newlines ([f37a2f8](https://github.com/lanegrid/agtrace/commit/f37a2f8f128dc39ce1b01c15f0d70bee6e1f7450))
94
+
95
+ - Change default ViewMode to Compact and merge Standard into Verbose (#34) ([5c2d6e9](https://github.com/lanegrid/agtrace/commit/5c2d6e9356329954fb69a472f3878057b958c0bd))
96
+
97
+ - Normalize all session header fields to prevent newline display issues ([e87960b](https://github.com/lanegrid/agtrace/commit/e87960b6471b382ad112e260835c09f2829328f4))
98
+
99
+ - Tune MCP get_turns defaults to data-driven limits (3k chars, 30 steps) for safe token usage ([d47d295](https://github.com/lanegrid/agtrace/commit/d47d295cad45e85213f909ce46551c2498a6147b))
100
+
101
+
102
+ ### Documentation
103
+
104
+ - Add real-world MCP workflow example and fix broken links ([bcc5b9a](https://github.com/lanegrid/agtrace/commit/bcc5b9a069c959cd477c42787d858f4722e15c85))
105
+
106
+ - Update MCP tool references to Random Access APIs and remove unused legacy types ([f2b04a7](https://github.com/lanegrid/agtrace/commit/f2b04a7b9df598d82f0aa450f39af40d102605a9))
107
+
108
+ - Update MCP API references in comments and help text to Random Access APIs ([d176a0c](https://github.com/lanegrid/agtrace/commit/d176a0c774bb5bebba32032c024db1a46e7cad64))
109
+
110
+ - Reposition agtrace as memory system for AI agents via MCP ([ffb68ce](https://github.com/lanegrid/agtrace/commit/ffb68ce32033f17e7754348a81fba822709caabc))
111
+
112
+
113
+ ### Features
114
+
115
+ - Change --project-root to --project with --project-root as alias ([346ecda](https://github.com/lanegrid/agtrace/commit/346ecdaae4b095b01f531eaeeee8e34ea663c3ff))
116
+
117
+ - Display both project_hash and project_root in session show ([40b1e8d](https://github.com/lanegrid/agtrace/commit/40b1e8ddfb28a4eaba32948484827520c3b27ed7))
118
+
119
+ - Improve session show display with vertical layout and smart path formatting ([f6a4a32](https://github.com/lanegrid/agtrace/commit/f6a4a320322a77f16ad08a43ecc914d1f50dbfd0))
120
+
121
+ - *(mcp)* Add project filter to search_event_previews ([211d667](https://github.com/lanegrid/agtrace/commit/211d6678aa997ed4f4578f09764ba44a16363085))
122
+
123
+ - Limit project list to top 10 by session count ([11a49e5](https://github.com/lanegrid/agtrace/commit/11a49e5d822fa8135697d00d1cdf0d0b009a4c46))
124
+
125
+ - Improve compact session header with clear key-value format ([298e209](https://github.com/lanegrid/agtrace/commit/298e20990aa1a77a8ae33a18aa29e56fe7d4c7ce))
126
+
127
+ - Compact mode shows turn metadata and tool count only ([506a2cd](https://github.com/lanegrid/agtrace/commit/506a2cd69c79ec19edeada05319d244df01af972))
128
+
129
+ - Add project root column and aligned headers to session list ([6435acf](https://github.com/lanegrid/agtrace/commit/6435acf9af401ed903c0dce334beff9b5b221228))
130
+
131
+ - Auto-fix README version references in release script ([e8cd078](https://github.com/lanegrid/agtrace/commit/e8cd0786c44b5930c8f92898743519afd954497c))
132
+
133
+ - Add Random Access API service layer with safety valves ([197d61a](https://github.com/lanegrid/agtrace/commit/197d61a6fca01065e0bf72408d47030200bc3340))
134
+
135
+ - Update MCP test suite for Random Access APIs with UTF-8 safe truncation ([31196e0](https://github.com/lanegrid/agtrace/commit/31196e028c3f24b9a29e155992b4ef0dc913c277))
136
+
137
+ - Add SessionOrder parameter to session listing queries ([edc3544](https://github.com/lanegrid/agtrace/commit/edc3544cdbd90d83ba6674ebc083d2b4fd5b477d))
138
+
139
+
140
+ ### Refactor
141
+
142
+ - Simplify compact mode to show turn metadata and user msg only ([a07ea3b](https://github.com/lanegrid/agtrace/commit/a07ea3b6e3e167a6950b2702b2bc60a0c3b27915))
143
+
144
+ - Compact mode displays one line per turn ([4af279e](https://github.com/lanegrid/agtrace/commit/4af279e0f80282cbc5cfb15dc485ac57dbd8aaee))
145
+
146
+ - Remove legacy MCP APIs, keep only Random Access APIs ([63968e5](https://github.com/lanegrid/agtrace/commit/63968e533168f32255a66cf6e71f26562210f190))
147
+
148
+
5
149
  ## [0.4.2] - 2026-01-03
6
150
 
7
151
  ### Refactor
package/README.md CHANGED
@@ -1,8 +1,8 @@
1
1
  <div align="center">
2
2
  <img src="https://raw.githubusercontent.com/lanegrid/agtrace/main/docs/images/agtrace-icon.png" width="96" alt="agtrace logo">
3
3
  <h1>agtrace</h1>
4
- <p><strong>The Observability Platform for AI Agents.</strong></p>
5
- <p>Local-first OpenTelemetry for Claude, Codex, and Gemini.</p>
4
+ <p><strong>Observability for AI Agents</strong></p>
5
+ <p>Local-first monitoring for Claude Code, Codex, and Gemini.</p>
6
6
 
7
7
  [![npm](https://img.shields.io/npm/v/@lanegrid/agtrace.svg?style=flat&label=npm)](https://www.npmjs.com/package/@lanegrid/agtrace)
8
8
  [![crates.io](https://img.shields.io/crates/v/agtrace-sdk.svg?label=SDK)](https://crates.io/crates/agtrace-sdk)
@@ -12,33 +12,13 @@
12
12
 
13
13
  ![agtrace watch demo](https://raw.githubusercontent.com/lanegrid/agtrace/main/docs/assets/demo.gif)
14
14
 
15
- **agtrace** is an observability platform for AI agent execution traces.
16
- Local-first, privacy-preserving, and zero-instrumentation.
15
+ **agtrace** monitors AI agent sessions in real-time and lets agents query their own execution history via MCP.
17
16
 
18
- ## Two Ways to Use agtrace
19
-
20
- ### 1. 🔍 Live Monitoring with `watch`
21
-
22
- Real-time TUI dashboard for agent sessions. Like `top` + `tail -f` for AI agents.
23
-
24
- - **100% local and offline** — Privacy by design, no cloud dependencies
25
- - **Auto-discovery** — Finds logs from Claude Code, Codex, and Gemini automatically
26
- - **Zero instrumentation** — No code changes or configuration needed
17
+ - **Zero instrumentation** — Auto-discovers provider logs
18
+ - **100% local** — Privacy by design, no cloud dependencies
27
19
  - **Universal timeline** — Unified view across all providers
28
20
 
29
- ### 2. 🤖 Agent Self-Reflection via MCP
30
-
31
- Connects to AI coding assistants via [Model Context Protocol](https://modelcontextprotocol.io), enabling agents to query their own execution history.
32
-
33
- - **Query past sessions** — "Show me sessions with failures in the last hour"
34
- - **Search across traces** — Find specific tool calls, events, or patterns
35
- - **Analyze performance** — Detect loops, failures, and bottlenecks
36
- - **Debug behavior** — Inspect reasoning chains and tool usage
37
-
38
- **Supported MCP clients:** Claude Code, Codex (OpenAI), Claude Desktop
39
- **Note:** Gemini CLI support is planned (requires Content-Length framing implementation)
40
-
41
- ## 🚀 Quick Start
21
+ ## Quick Start
42
22
 
43
23
  ```bash
44
24
  npm install -g @lanegrid/agtrace
@@ -47,13 +27,13 @@ agtrace init # Initialize workspace (one-time setup)
47
27
  agtrace watch # Launch live dashboard
48
28
  ```
49
29
 
50
- ## 🔌 MCP Integration
30
+ ## MCP: Let Agents Query Their Own History
51
31
 
52
- Enable agent self-reflection in your AI coding assistant:
32
+ Connect your AI assistant to search past sessions via [Model Context Protocol](https://modelcontextprotocol.io):
53
33
 
54
34
  **Claude Code:**
55
35
  ```bash
56
- claude code mcp add agtrace -- agtrace mcp serve
36
+ claude mcp add agtrace -- agtrace mcp serve
57
37
  ```
58
38
 
59
39
  **Codex (OpenAI):**
@@ -74,23 +54,38 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
74
54
  }
75
55
  ```
76
56
 
77
- **Example queries after setup:**
78
- - *"Show sessions from the last hour with failures"*
79
- - *"Search for tool calls containing 'write_file'"*
57
+ Your agent can now:
58
+ - Search past sessions for tool calls and errors
59
+ - Retrieve tool calls and results from previous work
60
+ - Analyze failure patterns
61
+
62
+ **Example queries:**
63
+ - *"Show me sessions with failures in the last hour"*
64
+ - *"Search for tool calls that modified the database schema"*
80
65
  - *"Analyze the most recent session for performance issues"*
81
66
 
82
- For detailed setup instructions and troubleshooting, see the [MCP Integration Guide](docs/mcp-integration.md).
67
+ For detailed setup and examples, see the [MCP Integration Guide](docs/mcp-integration.md).
68
+
69
+ ## CLI Commands
70
+
71
+ Debug and inspect agent behavior manually:
72
+
73
+ ```bash
74
+ agtrace watch # Live TUI dashboard
75
+ agtrace session list # Browse session history
76
+ agtrace lab grep "error" # Search across sessions
77
+ ```
83
78
 
84
- ## 🛠️ Building with the SDK
79
+ ## Building with the SDK
85
80
 
86
81
  Embed agent observability into your own tools (vital-checkers, IDE plugins, dashboards).
87
82
 
88
83
  ```toml
89
84
  [dependencies]
90
- agtrace-sdk = "0.4"
85
+ agtrace-sdk = "0.5"
91
86
  ```
92
87
 
93
- ```rust,no_run
88
+ ```rust
94
89
  use agtrace_sdk::{Client, Lens, types::SessionFilter};
95
90
 
96
91
  let client = Client::connect_default().await?;
@@ -102,33 +97,21 @@ if let Some(summary) = sessions.first() {
102
97
  }
103
98
  ```
104
99
 
105
- **See also**: [SDK Documentation](https://docs.rs/agtrace-sdk) | [Examples](crates/agtrace-sdk/examples/) | [SDK README](crates/agtrace-sdk/README.md)
100
+ See [SDK Documentation](https://docs.rs/agtrace-sdk), [Examples](crates/agtrace-sdk/examples/), and [SDK README](crates/agtrace-sdk/README.md).
106
101
 
107
- ## 📚 Documentation
108
-
109
- - [Why agtrace?](docs/motivation.md) - Understanding the problem and solution
110
- - [Getting Started](docs/getting-started.md) - Detailed installation and usage guide
111
- - [Architecture](docs/architecture.md) - Platform design and principles
112
- - [SDK Documentation](crates/agtrace-sdk/README.md) - Building custom tools
113
- - [Full Documentation](docs/README.md) - Commands, FAQs, and more
114
-
115
- ## 🔌 Supported Providers
102
+ ## Supported Providers
116
103
 
117
104
  - **Claude Code** (Anthropic)
118
105
  - **Codex** (OpenAI)
119
106
  - **Gemini** (Google)
120
107
 
121
- ## 📦 Architecture
108
+ ## Documentation
122
109
 
123
- ```mermaid
124
- graph TD
125
- CLI[agtrace-cli] --> SDK[agtrace-sdk]
126
- YourApp[Your Tool] --> SDK
127
- SDK --> Core[Core Engine & Providers]
128
- ```
129
-
130
- - **Core SDK**: `agtrace-sdk`, `agtrace-engine`, `agtrace-providers`
131
- - **Applications**: `agtrace-cli` (Reference Implementation)
110
+ - [Getting Started](docs/getting-started.md) - Detailed installation and usage guide
111
+ - [MCP Integration](docs/mcp-integration.md) - Connect agents to their execution history
112
+ - [Architecture](docs/architecture.md) - Platform design and principles
113
+ - [Why agtrace?](docs/motivation.md) - Understanding the problem and solution
114
+ - [Full Documentation](docs/README.md) - Commands, FAQs, and more
132
115
 
133
116
  ## License
134
117
 
package/npm-shrinkwrap.json CHANGED
@@ -23,7 +23,7 @@
23
23
  "hasInstallScript": true,
24
24
  "license": "MIT OR Apache-2.0",
25
25
  "name": "@lanegrid/agtrace",
26
- "version": "0.4.2"
26
+ "version": "0.5.1"
27
27
  },
28
28
  "node_modules/@isaacs/balanced-match": {
29
29
  "engines": {
@@ -515,5 +515,5 @@
515
515
  }
516
516
  },
517
517
  "requires": true,
518
- "version": "0.4.2"
518
+ "version": "0.5.1"
519
519
  }
package/package.json CHANGED
@@ -1,5 +1,5 @@
1
1
  {
2
- "artifactDownloadUrl": "https://github.com/lanegrid/agtrace/releases/download/v0.4.2",
2
+ "artifactDownloadUrl": "https://github.com/lanegrid/agtrace/releases/download/v0.5.1",
3
3
  "bin": {
4
4
  "agtrace": "run-agtrace.js"
5
5
  },
@@ -93,7 +93,7 @@
93
93
  "zipExt": ".tar.xz"
94
94
  }
95
95
  },
96
- "version": "0.4.2",
96
+ "version": "0.5.1",
97
97
  "volta": {
98
98
  "node": "18.14.1",
99
99
  "npm": "9.5.0"