@lanegrid/agtrace 0.4.1 → 0.5.0

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 +135 -0
  2. package/README.md +74 -70
  3. package/npm-shrinkwrap.json +2 -2
  4. package/package.json +2 -2
package/CHANGELOG.md CHANGED
@@ -2,6 +2,141 @@
2
2
 
3
3
  All notable changes to this project will be documented in this file.
4
4
 
5
+ ## [0.5.0] - 2026-01-03
6
+
7
+ ### Bug Fixes
8
+
9
+ - Session show displays correct ID, provider, and project info ([c72835b](https://github.com/lanegrid/agtrace/commit/c72835b2791098a962bc1f1e04ed805095001a79))
10
+
11
+ - Normalize turn snippets to single line in compact view ([5667977](https://github.com/lanegrid/agtrace/commit/56679774946434db89b865842ee8dece10ddcd48))
12
+
13
+ - Normalize text truncation in user-facing views to handle newlines ([f37a2f8](https://github.com/lanegrid/agtrace/commit/f37a2f8f128dc39ce1b01c15f0d70bee6e1f7450))
14
+
15
+ - Change default ViewMode to Compact and merge Standard into Verbose (#34) ([5c2d6e9](https://github.com/lanegrid/agtrace/commit/5c2d6e9356329954fb69a472f3878057b958c0bd))
16
+
17
+ - Normalize all session header fields to prevent newline display issues ([e87960b](https://github.com/lanegrid/agtrace/commit/e87960b6471b382ad112e260835c09f2829328f4))
18
+
19
+ - 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))
20
+
21
+
22
+ ### Documentation
23
+
24
+ - Add real-world MCP workflow example and fix broken links ([bcc5b9a](https://github.com/lanegrid/agtrace/commit/bcc5b9a069c959cd477c42787d858f4722e15c85))
25
+
26
+ - Update MCP tool references to Random Access APIs and remove unused legacy types ([f2b04a7](https://github.com/lanegrid/agtrace/commit/f2b04a7b9df598d82f0aa450f39af40d102605a9))
27
+
28
+ - Update MCP API references in comments and help text to Random Access APIs ([d176a0c](https://github.com/lanegrid/agtrace/commit/d176a0c774bb5bebba32032c024db1a46e7cad64))
29
+
30
+ - Reposition agtrace as memory system for AI agents via MCP ([ffb68ce](https://github.com/lanegrid/agtrace/commit/ffb68ce32033f17e7754348a81fba822709caabc))
31
+
32
+
33
+ ### Features
34
+
35
+ - Change --project-root to --project with --project-root as alias ([346ecda](https://github.com/lanegrid/agtrace/commit/346ecdaae4b095b01f531eaeeee8e34ea663c3ff))
36
+
37
+ - Display both project_hash and project_root in session show ([40b1e8d](https://github.com/lanegrid/agtrace/commit/40b1e8ddfb28a4eaba32948484827520c3b27ed7))
38
+
39
+ - Improve session show display with vertical layout and smart path formatting ([f6a4a32](https://github.com/lanegrid/agtrace/commit/f6a4a320322a77f16ad08a43ecc914d1f50dbfd0))
40
+
41
+ - *(mcp)* Add project filter to search_event_previews ([211d667](https://github.com/lanegrid/agtrace/commit/211d6678aa997ed4f4578f09764ba44a16363085))
42
+
43
+ - Limit project list to top 10 by session count ([11a49e5](https://github.com/lanegrid/agtrace/commit/11a49e5d822fa8135697d00d1cdf0d0b009a4c46))
44
+
45
+ - Improve compact session header with clear key-value format ([298e209](https://github.com/lanegrid/agtrace/commit/298e20990aa1a77a8ae33a18aa29e56fe7d4c7ce))
46
+
47
+ - Compact mode shows turn metadata and tool count only ([506a2cd](https://github.com/lanegrid/agtrace/commit/506a2cd69c79ec19edeada05319d244df01af972))
48
+
49
+ - Add project root column and aligned headers to session list ([6435acf](https://github.com/lanegrid/agtrace/commit/6435acf9af401ed903c0dce334beff9b5b221228))
50
+
51
+ - Auto-fix README version references in release script ([e8cd078](https://github.com/lanegrid/agtrace/commit/e8cd0786c44b5930c8f92898743519afd954497c))
52
+
53
+ - Add Random Access API service layer with safety valves ([197d61a](https://github.com/lanegrid/agtrace/commit/197d61a6fca01065e0bf72408d47030200bc3340))
54
+
55
+ - Update MCP test suite for Random Access APIs with UTF-8 safe truncation ([31196e0](https://github.com/lanegrid/agtrace/commit/31196e028c3f24b9a29e155992b4ef0dc913c277))
56
+
57
+ - Add SessionOrder parameter to session listing queries ([edc3544](https://github.com/lanegrid/agtrace/commit/edc3544cdbd90d83ba6674ebc083d2b4fd5b477d))
58
+
59
+
60
+ ### Refactor
61
+
62
+ - Simplify compact mode to show turn metadata and user msg only ([a07ea3b](https://github.com/lanegrid/agtrace/commit/a07ea3b6e3e167a6950b2702b2bc60a0c3b27915))
63
+
64
+ - Compact mode displays one line per turn ([4af279e](https://github.com/lanegrid/agtrace/commit/4af279e0f80282cbc5cfb15dc485ac57dbd8aaee))
65
+
66
+ - Remove legacy MCP APIs, keep only Random Access APIs ([63968e5](https://github.com/lanegrid/agtrace/commit/63968e533168f32255a66cf6e71f26562210f190))
67
+
68
+
69
+ ## [0.5.0] - 2026-01-03
70
+
71
+ ### Bug Fixes
72
+
73
+ - Session show displays correct ID, provider, and project info ([c72835b](https://github.com/lanegrid/agtrace/commit/c72835b2791098a962bc1f1e04ed805095001a79))
74
+
75
+ - Normalize turn snippets to single line in compact view ([5667977](https://github.com/lanegrid/agtrace/commit/56679774946434db89b865842ee8dece10ddcd48))
76
+
77
+ - Normalize text truncation in user-facing views to handle newlines ([f37a2f8](https://github.com/lanegrid/agtrace/commit/f37a2f8f128dc39ce1b01c15f0d70bee6e1f7450))
78
+
79
+ - Change default ViewMode to Compact and merge Standard into Verbose (#34) ([5c2d6e9](https://github.com/lanegrid/agtrace/commit/5c2d6e9356329954fb69a472f3878057b958c0bd))
80
+
81
+ - Normalize all session header fields to prevent newline display issues ([e87960b](https://github.com/lanegrid/agtrace/commit/e87960b6471b382ad112e260835c09f2829328f4))
82
+
83
+ - 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))
84
+
85
+
86
+ ### Documentation
87
+
88
+ - Add real-world MCP workflow example and fix broken links ([bcc5b9a](https://github.com/lanegrid/agtrace/commit/bcc5b9a069c959cd477c42787d858f4722e15c85))
89
+
90
+ - Update MCP tool references to Random Access APIs and remove unused legacy types ([f2b04a7](https://github.com/lanegrid/agtrace/commit/f2b04a7b9df598d82f0aa450f39af40d102605a9))
91
+
92
+ - Update MCP API references in comments and help text to Random Access APIs ([d176a0c](https://github.com/lanegrid/agtrace/commit/d176a0c774bb5bebba32032c024db1a46e7cad64))
93
+
94
+ - Reposition agtrace as memory system for AI agents via MCP ([ffb68ce](https://github.com/lanegrid/agtrace/commit/ffb68ce32033f17e7754348a81fba822709caabc))
95
+
96
+
97
+ ### Features
98
+
99
+ - Change --project-root to --project with --project-root as alias ([346ecda](https://github.com/lanegrid/agtrace/commit/346ecdaae4b095b01f531eaeeee8e34ea663c3ff))
100
+
101
+ - Display both project_hash and project_root in session show ([40b1e8d](https://github.com/lanegrid/agtrace/commit/40b1e8ddfb28a4eaba32948484827520c3b27ed7))
102
+
103
+ - Improve session show display with vertical layout and smart path formatting ([f6a4a32](https://github.com/lanegrid/agtrace/commit/f6a4a320322a77f16ad08a43ecc914d1f50dbfd0))
104
+
105
+ - *(mcp)* Add project filter to search_event_previews ([211d667](https://github.com/lanegrid/agtrace/commit/211d6678aa997ed4f4578f09764ba44a16363085))
106
+
107
+ - Limit project list to top 10 by session count ([11a49e5](https://github.com/lanegrid/agtrace/commit/11a49e5d822fa8135697d00d1cdf0d0b009a4c46))
108
+
109
+ - Improve compact session header with clear key-value format ([298e209](https://github.com/lanegrid/agtrace/commit/298e20990aa1a77a8ae33a18aa29e56fe7d4c7ce))
110
+
111
+ - Compact mode shows turn metadata and tool count only ([506a2cd](https://github.com/lanegrid/agtrace/commit/506a2cd69c79ec19edeada05319d244df01af972))
112
+
113
+ - Add project root column and aligned headers to session list ([6435acf](https://github.com/lanegrid/agtrace/commit/6435acf9af401ed903c0dce334beff9b5b221228))
114
+
115
+ - Auto-fix README version references in release script ([e8cd078](https://github.com/lanegrid/agtrace/commit/e8cd0786c44b5930c8f92898743519afd954497c))
116
+
117
+ - Add Random Access API service layer with safety valves ([197d61a](https://github.com/lanegrid/agtrace/commit/197d61a6fca01065e0bf72408d47030200bc3340))
118
+
119
+ - Update MCP test suite for Random Access APIs with UTF-8 safe truncation ([31196e0](https://github.com/lanegrid/agtrace/commit/31196e028c3f24b9a29e155992b4ef0dc913c277))
120
+
121
+ - Add SessionOrder parameter to session listing queries ([edc3544](https://github.com/lanegrid/agtrace/commit/edc3544cdbd90d83ba6674ebc083d2b4fd5b477d))
122
+
123
+
124
+ ### Refactor
125
+
126
+ - Simplify compact mode to show turn metadata and user msg only ([a07ea3b](https://github.com/lanegrid/agtrace/commit/a07ea3b6e3e167a6950b2702b2bc60a0c3b27915))
127
+
128
+ - Compact mode displays one line per turn ([4af279e](https://github.com/lanegrid/agtrace/commit/4af279e0f80282cbc5cfb15dc485ac57dbd8aaee))
129
+
130
+ - Remove legacy MCP APIs, keep only Random Access APIs ([63968e5](https://github.com/lanegrid/agtrace/commit/63968e533168f32255a66cf6e71f26562210f190))
131
+
132
+
133
+ ## [0.4.2] - 2026-01-03
134
+
135
+ ### Refactor
136
+
137
+ - Encapsulate sidechain filtering in SDK layer ([000cae9](https://github.com/lanegrid/agtrace/commit/000cae9f381660398ed52fe08683c78ed2246278))
138
+
139
+
5
140
  ## [0.4.1] - 2026-01-03
6
141
 
7
142
  ### Bug Fixes
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>Memory for AI Agents.</strong></p>
5
+ <p>Let your agents learn from their past sessions.</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)
@@ -10,50 +10,38 @@
10
10
 
11
11
  ---
12
12
 
13
- ![agtrace watch demo](https://raw.githubusercontent.com/lanegrid/agtrace/main/docs/assets/demo.gif)
13
+ ## The Problem
14
14
 
15
- **agtrace** is an observability platform for AI agent execution traces.
16
- Local-first, privacy-preserving, and zero-instrumentation.
15
+ AI coding agents start every session fresh. They can't remember:
16
+ - Why a decision was made yesterday
17
+ - What approaches already failed
18
+ - The context behind existing code
17
19
 
18
- ## Two Ways to Use agtrace
20
+ You end up re-explaining the same constraints, watching the same mistakes, and losing accumulated knowledge.
19
21
 
20
- ### 1. 🔍 Live Monitoring with `watch`
22
+ ## The Solution
21
23
 
22
- Real-time TUI dashboard for agent sessions. Like `top` + `tail -f` for AI agents.
24
+ **agtrace** gives AI agents access to their own execution history via [Model Context Protocol (MCP)](https://modelcontextprotocol.io).
23
25
 
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
27
- - **Universal timeline** — Unified view across all providers
26
+ Your agent can now:
27
+ - Query past sessions: *"What did we decide about the database schema?"*
28
+ - Learn from failures: *"Show me errors from previous attempts"*
29
+ - Maintain context: *"Continue where we left off yesterday"*
28
30
 
29
- ### 2. 🤖 Agent Self-Reflection via MCP
31
+ **Zero instrumentation.** agtrace auto-discovers logs from Claude Code, Codex, and Gemini. No code changes required
30
32
 
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
33
+ ## Quick Start
42
34
 
43
35
  ```bash
44
36
  npm install -g @lanegrid/agtrace
45
- cd my-project
46
- agtrace init # Initialize workspace (one-time setup)
47
- agtrace watch # Launch live dashboard
37
+ agtrace init
48
38
  ```
49
39
 
50
- ## 🔌 MCP Integration
51
-
52
- Enable agent self-reflection in your AI coding assistant:
40
+ Then connect to your AI assistant:
53
41
 
54
42
  **Claude Code:**
55
43
  ```bash
56
- claude code mcp add agtrace -- agtrace mcp serve
44
+ claude mcp add agtrace -- agtrace mcp serve
57
45
  ```
58
46
 
59
47
  **Codex (OpenAI):**
@@ -61,74 +49,90 @@ claude code mcp add agtrace -- agtrace mcp serve
61
49
  codex mcp add agtrace -- agtrace mcp serve
62
50
  ```
63
51
 
64
- **Claude Desktop:**
65
- Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
52
+ **Claude Desktop:** Add to `claude_desktop_config.json`:
66
53
  ```json
67
54
  {
68
55
  "mcpServers": {
69
- "agtrace": {
70
- "command": "agtrace",
71
- "args": ["mcp", "serve"]
72
- }
56
+ "agtrace": { "command": "agtrace", "args": ["mcp", "serve"] }
73
57
  }
74
58
  }
75
59
  ```
76
60
 
77
- **Example queries after setup:**
78
- - *"Show sessions from the last hour with failures"*
79
- - *"Search for tool calls containing 'write_file'"*
80
- - *"Analyze the most recent session for performance issues"*
61
+ That's it. Your agent now has memory.
62
+
63
+ ## How Agents Use It
64
+
65
+ Once connected, your agent can query its own history:
66
+
67
+ | You ask | Agent does |
68
+ |---------|------------|
69
+ | *"Why did we choose PostgreSQL?"* | Searches past sessions for database discussions |
70
+ | *"Fix this bug, we tried before"* | Retrieves previous failed attempts and avoids them |
71
+ | *"Continue the refactoring"* | Loads context from yesterday's session |
72
+
73
+ **Real example:** An agent retrieved 34KB of historical context across 5 sessions, then generated a specification that respected all past design constraints—without you re-explaining anything.
74
+
75
+ ## MCP Tools
76
+
77
+ agtrace exposes these tools to your agent:
78
+
79
+ | Tool | Purpose |
80
+ |------|---------|
81
+ | `list_sessions` | Browse session history with filters |
82
+ | `list_turns` | Get turn-by-turn overview of a session |
83
+ | `get_turns` | Retrieve detailed content of specific turns |
84
+ | `search_events` | Find specific tool calls or patterns |
85
+ | `analyze_session` | Detect failures, loops, and issues |
86
+ | `get_project_info` | List indexed projects |
81
87
 
82
- For detailed setup instructions and troubleshooting, see the [MCP Integration Guide](docs/mcp-integration.md).
88
+ See [MCP Integration Guide](docs/mcp-integration.md) for details.
83
89
 
84
- ## 🛠️ Building with the SDK
90
+ ## CLI Tools for Developers
85
91
 
86
- Embed agent observability into your own tools (vital-checkers, IDE plugins, dashboards).
92
+ Debug and inspect agent behavior manually:
93
+
94
+ ```bash
95
+ agtrace watch # Live TUI dashboard
96
+ agtrace session list # Browse session history
97
+ agtrace lab grep "error" # Search across sessions
98
+ ```
99
+
100
+ ![agtrace watch](https://raw.githubusercontent.com/lanegrid/agtrace/main/docs/assets/demo.gif)
101
+
102
+ ## SDK for Builders
103
+
104
+ Build custom tools on top of agtrace:
87
105
 
88
106
  ```toml
89
107
  [dependencies]
90
- agtrace-sdk = "0.3"
108
+ agtrace-sdk = "0.5"
91
109
  ```
92
110
 
93
- ```rust,no_run
111
+ ```rust
94
112
  use agtrace_sdk::{Client, Lens, types::SessionFilter};
95
113
 
96
114
  let client = Client::connect_default().await?;
97
115
  let sessions = client.sessions().list(SessionFilter::all())?;
98
- if let Some(summary) = sessions.first() {
99
- let handle = client.sessions().get(&summary.id)?;
100
- let report = handle.analyze()?.through(Lens::Failures).report()?;
101
- println!("Health: {}/100", report.score);
102
- }
116
+ let report = client.sessions().get(&sessions[0].id)?
117
+ .analyze()?.through(Lens::Failures).report()?;
103
118
  ```
104
119
 
105
- **See also**: [SDK Documentation](https://docs.rs/agtrace-sdk) | [Examples](crates/agtrace-sdk/examples/) | [SDK README](crates/agtrace-sdk/README.md)
106
-
107
- ## 📚 Documentation
120
+ See [SDK Documentation](https://docs.rs/agtrace-sdk) and [examples](crates/agtrace-sdk/examples/).
108
121
 
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
122
+ ## Supported Providers
116
123
 
117
124
  - **Claude Code** (Anthropic)
118
125
  - **Codex** (OpenAI)
119
126
  - **Gemini** (Google)
120
127
 
121
- ## 📦 Architecture
128
+ All providers auto-discovered. Logs stay local.
122
129
 
123
- ```mermaid
124
- graph TD
125
- CLI[agtrace-cli] --> SDK[agtrace-sdk]
126
- YourApp[Your Tool] --> SDK
127
- SDK --> Core[Core Engine & Providers]
128
- ```
130
+ ## Documentation
129
131
 
130
- - **Core SDK**: `agtrace-sdk`, `agtrace-engine`, `agtrace-providers`
131
- - **Applications**: `agtrace-cli` (Reference Implementation)
132
+ - [MCP Integration Guide](docs/mcp-integration.md)
133
+ - [Getting Started](docs/getting-started.md)
134
+ - [Architecture](docs/architecture.md)
135
+ - [Full Documentation](docs/README.md)
132
136
 
133
137
  ## License
134
138
 
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.1"
26
+ "version": "0.5.0"
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.1"
518
+ "version": "0.5.0"
519
519
  }
package/package.json CHANGED
@@ -1,5 +1,5 @@
1
1
  {
2
- "artifactDownloadUrl": "https://github.com/lanegrid/agtrace/releases/download/v0.4.1",
2
+ "artifactDownloadUrl": "https://github.com/lanegrid/agtrace/releases/download/v0.5.0",
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.1",
96
+ "version": "0.5.0",
97
97
  "volta": {
98
98
  "node": "18.14.1",
99
99
  "npm": "9.5.0"