@lanegrid/agtrace 0.3.1 → 0.4.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 +141 -0
  2. package/README.md +59 -11
  3. package/npm-shrinkwrap.json +2 -2
  4. package/package.json +2 -2
package/CHANGELOG.md CHANGED
@@ -2,6 +2,147 @@
2
2
 
3
3
  All notable changes to this project will be documented in this file.
4
4
 
5
+ ## [0.4.1] - 2026-01-03
6
+
7
+ ### Bug Fixes
8
+
9
+ - Unify top-level help message between -h and --help ([5631f15](https://github.com/lanegrid/agtrace/commit/5631f15e0b7aeea3aebdc7a1b7c347fa29c9692f))
10
+
11
+
12
+ ### Documentation
13
+
14
+ - Add MCP troubleshooting for Node.js version managers ([0f99972](https://github.com/lanegrid/agtrace/commit/0f999728ef04e7b2cd6742de6ca4250c467906ce))
15
+
16
+ - Modernize MCP messaging and restructure README around watch and mcp values ([ef14681](https://github.com/lanegrid/agtrace/commit/ef146816220164b4e80b0104e836faa2214e732a))
17
+
18
+ - Fix Gemini CLI mcp add syntax (uses positional args, not -- separator) ([e458773](https://github.com/lanegrid/agtrace/commit/e4587732bac670a9228a6c44afde375744e8679c))
19
+
20
+ - Note Gemini CLI not yet supported (requires Content-Length framing) ([43a745d](https://github.com/lanegrid/agtrace/commit/43a745d130d9ac367201a01e382db72878a9710f))
21
+
22
+
23
+ ### Refactor
24
+
25
+ - Update MCP tools from get_session_details/search_events to specialized tools ([31a7919](https://github.com/lanegrid/agtrace/commit/31a791934b2c52cdbf271b19fc6e5768004fc9bc))
26
+
27
+ - Reorder subcommands by importance and improve descriptions ([59ad2eb](https://github.com/lanegrid/agtrace/commit/59ad2eb31943ddd5c3ec679cd588d88a503c86a1))
28
+
29
+ - Hide less-used global options in -h to shorten help output ([8589bf0](https://github.com/lanegrid/agtrace/commit/8589bf09987c29edb26a19b1b1b7f85fdbdf0c86))
30
+
31
+
32
+ ## [0.4.0] - 2026-01-02
33
+
34
+ ### Bug Fixes
35
+
36
+ - Use numeric id instead of null in MCP error responses for Zod validation ([2014a57](https://github.com/lanegrid/agtrace/commit/2014a575a2c5a523f8d14b7b1d8232cc634750b2))
37
+
38
+ - Add cursor parameter to MCP tool schemas for list_sessions and search_events ([d3dfdb5](https://github.com/lanegrid/agtrace/commit/d3dfdb5b232d95053dee4ebce89e0491d579af53))
39
+
40
+ - Move provider filter from app layer to DB layer for accurate session filtering ([5d2ef3f](https://github.com/lanegrid/agtrace/commit/5d2ef3f4df1b36b15714176c579bbf9c41e097db))
41
+
42
+ - Resolve clippy warnings in MCP tests (use cargo_bin! macro, remove unused import) ([a390e7d](https://github.com/lanegrid/agtrace/commit/a390e7de39940b8f868fcd8dac8adcdb895d6fdd))
43
+
44
+ - Change SessionMetadata.session_id from Uuid to String for test compatibility ([8a73f01](https://github.com/lanegrid/agtrace/commit/8a73f0132a55f4573611de55f9af15fc850fc3a4))
45
+
46
+ - *(providers)* Truncate session snippets to 200 chars to prevent oversized MCP responses ([9273aa9](https://github.com/lanegrid/agtrace/commit/9273aa9689ada47d4773234613e27ef45d14d95f))
47
+
48
+ - *(mcp)* Truncate session summary and turns to prevent token limit errors ([9bf6fd9](https://github.com/lanegrid/agtrace/commit/9bf6fd9a067c2e850fc7580b1f5ab6d774893832))
49
+
50
+ - *(cli)* Rename lab export --format to --export-format to avoid conflict with global --format ([dc2e583](https://github.com/lanegrid/agtrace/commit/dc2e583645cf3f691154d9c5eea6249857bef10a))
51
+
52
+
53
+ ### Documentation
54
+
55
+ - *(mcp)* Update tools interface for v0.4.0 with search_event_previews, get_event_details, structured errors, and migration guide ([821add1](https://github.com/lanegrid/agtrace/commit/821add115517c546e82ef189f2c1aacf0e85e677))
56
+
57
+ - *(mcp)* Update mcp-server.md for v0.4.0 tools and suppress deprecated search_events warning ([c3d8c7c](https://github.com/lanegrid/agtrace/commit/c3d8c7cb3f0f871acb9cf6553c6be8e5616bdbee))
58
+
59
+ - Replace XDG terminology with system data directory ([1e22a18](https://github.com/lanegrid/agtrace/commit/1e22a1836964d9375d1ad19f9c279845c7bd16cb))
60
+
61
+ - Fix command examples to match actual CLI implementation ([1c41c6e](https://github.com/lanegrid/agtrace/commit/1c41c6e3b26fc2a9b3c8f4aaa39f31d5a75a6ba8))
62
+
63
+ - Add MCP (Model Context Protocol) section for v0.4.0 ([a15fc90](https://github.com/lanegrid/agtrace/commit/a15fc900e5064dd4c554b1fdac450e9fbeb9c654))
64
+
65
+
66
+ ### Features
67
+
68
+ - Add idempotent resume mode and --yes flag to prepare-release.sh ([f862e15](https://github.com/lanegrid/agtrace/commit/f862e153d2e655dc63b96662106f3377cc7128e3))
69
+
70
+ - Add MCP server for AI-native observability (issue #32) ([a288dff](https://github.com/lanegrid/agtrace/commit/a288dff780fc8391ec56f2dc1745e43e100105b5))
71
+
72
+ - Add dev test-mcp command to diagnose MCP response sizes and fix list_sessions default limit ([54f0eef](https://github.com/lanegrid/agtrace/commit/54f0eef0e9460ae68be7d3d453426d5c6c4bc183))
73
+
74
+ - Add comprehensive tests for all detail_level options in dev test-mcp command ([d55e877](https://github.com/lanegrid/agtrace/commit/d55e877546da38777ec8efc83ea30cc43be0aebf))
75
+
76
+ - Implement cursor-based pagination for MCP tools per specification ([79d9176](https://github.com/lanegrid/agtrace/commit/79d9176fc4006e65cc4e89123a380bd7b13bce5c))
77
+
78
+ - *(mcp)* Add foundational types for MCP tools redesign (Provider, EventType, McpError, McpResponse) ([9eb77db](https://github.com/lanegrid/agtrace/commit/9eb77db2b8d1f9dc83990fed005f2bdead22fad9))
79
+
80
+ - *(mcp)* Complete tools redesign - split search_events, add structured errors, standardize responses ([ad8449e](https://github.com/lanegrid/agtrace/commit/ad8449e2c89759edb8692d463ab75fd22916609d))
81
+
82
+ - *(mcp)* Improve error responses per MCP spec 2024-11-05 and add project_root parameter ([602fce3](https://github.com/lanegrid/agtrace/commit/602fce3c8a2f5b3066707c23254c4f94fbf4259b))
83
+
84
+ - *(mcp)* Add workflow and data source hints to tool descriptions ([ce74fd7](https://github.com/lanegrid/agtrace/commit/ce74fd79f4dbf0dbda1d3f3129d86d013ee8dde2))
85
+
86
+ - *(mcp)* Implement approach-b specialized session tools with response metadata ([b919a73](https://github.com/lanegrid/agtrace/commit/b919a73009080b4a395c443dfe8630ddaf6ef155))
87
+
88
+ - *(types)* Add SessionMetadata for clean separation of DB-derived and event-derived data ([324784b](https://github.com/lanegrid/agtrace/commit/324784b97953da31197748194114a44bcfb3626c))
89
+
90
+ - *(mcp)* Add tool-aware smart truncation for turn steps ([1965937](https://github.com/lanegrid/agtrace/commit/1965937f46daf04b606eb23e35f50f69f8192b72))
91
+
92
+ - *(mcp)* Add minimal context to tool summaries in get_session_turns ([e67cab9](https://github.com/lanegrid/agtrace/commit/e67cab9069139156d8ad794aba719408392b64e4))
93
+
94
+
95
+ ### Miscellaneous Tasks
96
+
97
+ - Remove unnecessary docs ([7c7ff89](https://github.com/lanegrid/agtrace/commit/7c7ff897ffad19bc25ebb9143cd45c93cde43e7f))
98
+
99
+
100
+ ### Refactor
101
+
102
+ - Add typed DTOs for MCP tools interface to improve type safety and maintainability ([f7a77fb](https://github.com/lanegrid/agtrace/commit/f7a77fb4a5a564fb8a221178a0a210f780b7a738))
103
+
104
+ - Restructure MCP DTOs with hierarchical detail levels and smart tool summarization ([a59c55c](https://github.com/lanegrid/agtrace/commit/a59c55cf1a47cffa6e762e0f8cabd24bda03c0d5))
105
+
106
+ - Use schemars to auto-generate JSON Schema from Rust types, eliminating schema drift ([d767cac](https://github.com/lanegrid/agtrace/commit/d767cacf79b148d7bead8a2346d711864ab2d5c0))
107
+
108
+ - *(mcp)* Remove docs, consolidate design rationale into code comments ([d68ad61](https://github.com/lanegrid/agtrace/commit/d68ad61c79dbe018f1d34b61760eaf555f78fd96))
109
+
110
+ - *(mcp)* Remove deprecated SearchEventsArgs and fix all lint warnings ([55ab644](https://github.com/lanegrid/agtrace/commit/55ab644da53e645735e4a4c8b0527e6af839aa2d))
111
+
112
+ - *(mcp)* Remove hint fields from MCP responses ([45e537f](https://github.com/lanegrid/agtrace/commit/45e537f463fdc46ffb89b63c4eba577759c474e3))
113
+
114
+ - *(mcp)* Rename get_session_details to get_session_by_id ([489fc28](https://github.com/lanegrid/agtrace/commit/489fc28c5e1480a66db9782a3ddd42e66a311e6f))
115
+
116
+ - *(mcp)* Remove deprecated get_session_by_id and related code ([b4e04f9](https://github.com/lanegrid/agtrace/commit/b4e04f9cbb404e51825fba5055768ca09325dd42))
117
+
118
+ - *(mcp)* Enhance agent UX with content levels, index stability, semantic previews, and structured actions ([d53b0d1](https://github.com/lanegrid/agtrace/commit/d53b0d1cc32c3e28a93ef6da6bf6003dd346f65d))
119
+
120
+ - *(test)* Extract and prettify MCP response text content in snapshots ([4efbc1e](https://github.com/lanegrid/agtrace/commit/4efbc1e7feeff84cd8335d26fd9e049954c3989f))
121
+
122
+ - *(mcp/dto)* Return original models directly to preserve complete session data ([b472ad2](https://github.com/lanegrid/agtrace/commit/b472ad2ba3b7967845d6f554586684b08cc7ab63))
123
+
124
+ - *(mcp)* Unify dto/view_models into models with presenter layer ([1c467cc](https://github.com/lanegrid/agtrace/commit/1c467ccc60df036a519f98144a1ebc4992bd3098))
125
+
126
+ - *(mcp)* Consolidate request/response types into tool-specific files under models/types/ ([0122771](https://github.com/lanegrid/agtrace/commit/0122771b620c0532432d1bf5205e56c87e982efc))
127
+
128
+ - *(mcp)* Merge ToolSummarizer into event_previews for better cohesion ([94e9014](https://github.com/lanegrid/agtrace/commit/94e901498a64f4c1baa90c0460a91d423ab71bf9))
129
+
130
+ - *(mcp)* Remove _meta and add pagination fields directly to ViewModels ([e78b930](https://github.com/lanegrid/agtrace/commit/e78b9301f27ea428b47357b6af08e941a16c82ca))
131
+
132
+ - *(mcp)* Remove unused fields and wrapper types ([4b50bfb](https://github.com/lanegrid/agtrace/commit/4b50bfb6e10b92eadb148c6a90e9bd88ef897790))
133
+
134
+ - *(cli)* Rename serve to mcp serve and consolidate MCP commands ([e465b01](https://github.com/lanegrid/agtrace/commit/e465b0133b8bba3bbf6e1873f02d62d8a16681cb))
135
+
136
+ - *(cli)* Improve help text with option grouping and examples ([cf37d54](https://github.com/lanegrid/agtrace/commit/cf37d546dde282ac3abfe5fc762ca492f5e581f6))
137
+
138
+
139
+ ### Testing
140
+
141
+ - Add schema verification tests for auto-generated JSON schemas ([2119be3](https://github.com/lanegrid/agtrace/commit/2119be3eaca266c453aaa087749f39455f4c144c))
142
+
143
+ - *(mcp)* Add snapshot tests for MCP server JSON-RPC protocol ([b0c587e](https://github.com/lanegrid/agtrace/commit/b0c587ebbb2b55088a88db2b3a7e741c4b6ab8b6))
144
+
145
+
5
146
  ## [0.3.1] - 2026-01-01
6
147
 
7
148
  ### Documentation
package/README.md CHANGED
@@ -12,27 +12,75 @@
12
12
 
13
13
  ![agtrace watch demo](https://raw.githubusercontent.com/lanegrid/agtrace/main/docs/assets/demo.gif)
14
14
 
15
- **agtrace** provides a unified timeline and analysis layer for fragmented AI agent logs.
16
- Use the **CLI** for instant visualization, or build custom monitoring tools with the **SDK**.
15
+ **agtrace** is an observability platform for AI agent execution traces.
16
+ Local-first, privacy-preserving, and zero-instrumentation.
17
17
 
18
- ## 🌟 Core Value
18
+ ## Two Ways to Use agtrace
19
19
 
20
- 1. **Universal Normalization**: Converts diverse provider logs (Claude, Gemini, etc.) into a standard `AgentEvent` model.
21
- 2. **Schema-on-Read**: Resilient to provider updates. No database migrations needed.
22
- 3. **Local-First**: 100% offline. Privacy by design.
23
- 4. **Zero-Instrumentation**: Automatically detects and watches logs from standard locations (`~/.claude/projects`, `~/.codex/sessions`, `~/.gemini/tmp`). No code changes required.
20
+ ### 1. 🔍 Live Monitoring with `watch`
24
21
 
25
- ## 🚀 Quick Start (CLI)
22
+ Real-time TUI dashboard for agent sessions. Like `top` + `tail -f` for AI agents.
26
23
 
27
- The reference implementation of the agtrace platform.
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
28
+
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
28
42
 
29
43
  ```bash
30
44
  npm install -g @lanegrid/agtrace
31
45
  cd my-project
32
- agtrace init # initialize workspace (XDG data directory)
33
- agtrace watch # live dashboard
46
+ agtrace init # Initialize workspace (one-time setup)
47
+ agtrace watch # Launch live dashboard
48
+ ```
49
+
50
+ ## 🔌 MCP Integration
51
+
52
+ Enable agent self-reflection in your AI coding assistant:
53
+
54
+ **Claude Code:**
55
+ ```bash
56
+ claude code mcp add agtrace -- agtrace mcp serve
34
57
  ```
35
58
 
59
+ **Codex (OpenAI):**
60
+ ```bash
61
+ codex mcp add agtrace -- agtrace mcp serve
62
+ ```
63
+
64
+ **Claude Desktop:**
65
+ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
66
+ ```json
67
+ {
68
+ "mcpServers": {
69
+ "agtrace": {
70
+ "command": "agtrace",
71
+ "args": ["mcp", "serve"]
72
+ }
73
+ }
74
+ }
75
+ ```
76
+
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"*
81
+
82
+ For detailed setup instructions and troubleshooting, see the [MCP Integration Guide](docs/mcp-integration.md).
83
+
36
84
  ## 🛠️ Building with the SDK
37
85
 
38
86
  Embed agent observability into your own tools (vital-checkers, IDE plugins, dashboards).
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.3.1"
26
+ "version": "0.4.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.3.1"
518
+ "version": "0.4.1"
519
519
  }
package/package.json CHANGED
@@ -1,5 +1,5 @@
1
1
  {
2
- "artifactDownloadUrl": "https://github.com/lanegrid/agtrace/releases/download/v0.3.1",
2
+ "artifactDownloadUrl": "https://github.com/lanegrid/agtrace/releases/download/v0.4.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.3.1",
96
+ "version": "0.4.1",
97
97
  "volta": {
98
98
  "node": "18.14.1",
99
99
  "npm": "9.5.0"