@lanegrid/agtrace 0.5.0 → 0.5.2

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 +75 -0
  2. package/README.md +42 -63
  3. package/npm-shrinkwrap.json +2 -2
  4. package/package.json +2 -2
package/CHANGELOG.md CHANGED
@@ -2,6 +2,81 @@
2
2
 
3
3
  All notable changes to this project will be documented in this file.
4
4
 
5
+ ## [0.5.2] - 2026-01-04
6
+
7
+ ### Bug Fixes
8
+
9
+ - *(providers)* Extract agentId from UserRecord for Claude subagents ([c092f2d](https://github.com/lanegrid/agtrace/commit/c092f2da5b2bca4a3ccf1237f163b5bd221ac5c1))
10
+
11
+ - *(cli)* Display sidechain link in Task tool results instead of (empty) ([c8be7fd](https://github.com/lanegrid/agtrace/commit/c8be7fd530cc2ba75d703ff85e9b408092c8c8ad))
12
+
13
+ - *(providers)* Handle array type in toolUseResult deserialization ([3134b8c](https://github.com/lanegrid/agtrace/commit/3134b8cca2c0867b023335d04582e292f95aed63))
14
+
15
+ - *(tests)* Add include_children() to spawn_context tests for top_level_only filter ([8058c91](https://github.com/lanegrid/agtrace/commit/8058c911139bd3746c88c39316445fdcc3cadf25))
16
+
17
+ - *(tests)* Add missing top_level_only argument to list_sessions calls ([5ac0e17](https://github.com/lanegrid/agtrace/commit/5ac0e1750eb568ab4429ebaa30a2682b429f3282))
18
+
19
+ - *(index)* Show actionable error message for schema mismatch ([7b4a1b7](https://github.com/lanegrid/agtrace/commit/7b4a1b7b8879408f08917a265cdd012acd5a6b14))
20
+
21
+
22
+ ### Features
23
+
24
+ - *(session)* Add log_files display to session show command ([ea42163](https://github.com/lanegrid/agtrace/commit/ea421635d4dcd452da742272719fe0b033f6b1ba))
25
+
26
+ - *(subagent)* Add subagent tracking infrastructure across all providers ([f0de519](https://github.com/lanegrid/agtrace/commit/f0de519ff43a672db93dfc5ea76b6e4de81aeccd))
27
+
28
+ - *(session)* Add stream_id field to AgentSession for multi-stream support(Closes #35) ([e19ea69](https://github.com/lanegrid/agtrace/commit/e19ea69ec90a073cbe19c4909e1fed7daa144634))
29
+
30
+ - *(cli)* Display stream_id in session show command ([8b118e4](https://github.com/lanegrid/agtrace/commit/8b118e4537ec96fd50bed7fc06c06806aeca4cff))
31
+
32
+ - *(session)* Link sidechains to parent turn/step via spawned_by context ([27db190](https://github.com/lanegrid/agtrace/commit/27db19069151d59231a98dfd0256111ab3e07d61))
33
+
34
+ - *(codex)* Add subagent multi-stream support ([2f20f66](https://github.com/lanegrid/agtrace/commit/2f20f6622394bba6eed0c24a2255f4751c8255ad))
35
+
36
+ - *(codex)* Add subagent parent linking via timestamp correlation ([0cca643](https://github.com/lanegrid/agtrace/commit/0cca6432fe6e9ebf00d84f92b732221539377cb6))
37
+
38
+ - *(cli)* Filter child sessions from session list by default ([f2143aa](https://github.com/lanegrid/agtrace/commit/f2143aa6a191c7e3243788b082d310d829cf5a4e))
39
+
40
+
41
+ ### Performance
42
+
43
+ - *(watch)* Reduce poll interval from 500ms to 100ms for faster event detection ([684d103](https://github.com/lanegrid/agtrace/commit/684d10369e2d82bceb8c0f49b6004bdc11af404c))
44
+
45
+
46
+ ### Refactor
47
+
48
+ - *(schema)* Remove session-level subagent fields for event-level stream tracking (v4) ([ce2b262](https://github.com/lanegrid/agtrace/commit/ce2b2621c5b7490bfab251d4af44631238f44248))
49
+
50
+ - *(cli)* Move session assembly to runtime and improve layer responsibilities ([424813f](https://github.com/lanegrid/agtrace/commit/424813f56b9e975055551ff4a8b8e18505abde95))
51
+
52
+ - *(watch)* Batch event processing and extract common handlers ([14cc8b4](https://github.com/lanegrid/agtrace/commit/14cc8b4fccae57902ee884fa0ab85fcb998559e9))
53
+
54
+
55
+ ### Testing
56
+
57
+ - *(subagent)* Add tests for SessionSource and header extraction ([75f9463](https://github.com/lanegrid/agtrace/commit/75f94638dc2daf5731bf6aa95bdae4b54ac05e58))
58
+
59
+ - *(sdk)* Add edge case tests for codex subagent filtering and child_sessions API ([168fcab](https://github.com/lanegrid/agtrace/commit/168fcaba2743e122ade93463f71fe099dd1ff5d5))
60
+
61
+ - *(index)* Add integration tests for schema migration ([ab8b7b2](https://github.com/lanegrid/agtrace/commit/ab8b7b28783b2fc6a2ceeddff9c9f619d2faf1e2))
62
+
63
+
64
+ ## [0.5.1] - 2026-01-04
65
+
66
+ ### Bug Fixes
67
+
68
+ - *(release)* Run clippy before version update to fail early ([70e96aa](https://github.com/lanegrid/agtrace/commit/70e96aa72ea90616b7401a4568e4ebe62fdf12d8))
69
+
70
+ - *(release)* Run lightweight checks before tests for faster failure ([66ec9fc](https://github.com/lanegrid/agtrace/commit/66ec9fc297795f08c7cf449450eba5d0a5eb7389))
71
+
72
+
73
+ ### Documentation
74
+
75
+ - Reposition agtrace as observability tool instead of memory system ([f2cb342](https://github.com/lanegrid/agtrace/commit/f2cb3429c51a48cee269bf965b93768aaff94fc6))
76
+
77
+ - Remove agent antipatterns documentation ([8b48857](https://github.com/lanegrid/agtrace/commit/8b4885744d9b6b0190993a299dedab0c0bd76d79))
78
+
79
+
5
80
  ## [0.5.0] - 2026-01-03
6
81
 
7
82
  ### 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>Memory for AI Agents.</strong></p>
5
- <p>Let your agents learn from their past sessions.</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)
@@ -10,34 +10,26 @@
10
10
 
11
11
  ---
12
12
 
13
- ## The Problem
13
+ ![agtrace watch demo](https://raw.githubusercontent.com/lanegrid/agtrace/main/docs/assets/demo.gif)
14
14
 
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
15
+ **agtrace** monitors AI agent sessions in real-time and lets agents query their own execution history via MCP.
19
16
 
20
- You end up re-explaining the same constraints, watching the same mistakes, and losing accumulated knowledge.
21
-
22
- ## The Solution
23
-
24
- **agtrace** gives AI agents access to their own execution history via [Model Context Protocol (MCP)](https://modelcontextprotocol.io).
25
-
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"*
30
-
31
- **Zero instrumentation.** agtrace auto-discovers logs from Claude Code, Codex, and Gemini. No code changes required
17
+ - **Zero instrumentation** — Auto-discovers provider logs
18
+ - **100% local** — Privacy by design, no cloud dependencies
19
+ - **Universal timeline** — Unified view across all providers
32
20
 
33
21
  ## Quick Start
34
22
 
35
23
  ```bash
36
24
  npm install -g @lanegrid/agtrace
37
- agtrace init
25
+ cd my-project
26
+ agtrace init # Initialize workspace (one-time setup)
27
+ agtrace watch # Launch live dashboard
38
28
  ```
39
29
 
40
- Then connect to your AI assistant:
30
+ ## MCP: Let Agents Query Their Own History
31
+
32
+ Connect your AI assistant to search past sessions via [Model Context Protocol](https://modelcontextprotocol.io):
41
33
 
42
34
  **Claude Code:**
43
35
  ```bash
@@ -49,45 +41,32 @@ claude mcp add agtrace -- agtrace mcp serve
49
41
  codex mcp add agtrace -- agtrace mcp serve
50
42
  ```
51
43
 
52
- **Claude Desktop:** Add to `claude_desktop_config.json`:
44
+ **Claude Desktop:**
45
+ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
53
46
  ```json
54
47
  {
55
48
  "mcpServers": {
56
- "agtrace": { "command": "agtrace", "args": ["mcp", "serve"] }
49
+ "agtrace": {
50
+ "command": "agtrace",
51
+ "args": ["mcp", "serve"]
52
+ }
57
53
  }
58
54
  }
59
55
  ```
60
56
 
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:
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
78
61
 
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 |
62
+ **Example queries:**
63
+ - *"Show me sessions with failures in the last hour"*
64
+ - *"Search for tool calls that modified the database schema"*
65
+ - *"Analyze the most recent session for performance issues"*
87
66
 
88
- See [MCP Integration Guide](docs/mcp-integration.md) for details.
67
+ For detailed setup and examples, see the [MCP Integration Guide](docs/mcp-integration.md).
89
68
 
90
- ## CLI Tools for Developers
69
+ ## CLI Commands
91
70
 
92
71
  Debug and inspect agent behavior manually:
93
72
 
@@ -97,11 +76,9 @@ agtrace session list # Browse session history
97
76
  agtrace lab grep "error" # Search across sessions
98
77
  ```
99
78
 
100
- ![agtrace watch](https://raw.githubusercontent.com/lanegrid/agtrace/main/docs/assets/demo.gif)
101
-
102
- ## SDK for Builders
79
+ ## Building with the SDK
103
80
 
104
- Build custom tools on top of agtrace:
81
+ Embed agent observability into your own tools (vital-checkers, IDE plugins, dashboards).
105
82
 
106
83
  ```toml
107
84
  [dependencies]
@@ -113,11 +90,14 @@ use agtrace_sdk::{Client, Lens, types::SessionFilter};
113
90
 
114
91
  let client = Client::connect_default().await?;
115
92
  let sessions = client.sessions().list(SessionFilter::all())?;
116
- let report = client.sessions().get(&sessions[0].id)?
117
- .analyze()?.through(Lens::Failures).report()?;
93
+ if let Some(summary) = sessions.first() {
94
+ let handle = client.sessions().get(&summary.id)?;
95
+ let report = handle.analyze()?.through(Lens::Failures).report()?;
96
+ println!("Health: {}/100", report.score);
97
+ }
118
98
  ```
119
99
 
120
- See [SDK Documentation](https://docs.rs/agtrace-sdk) and [examples](crates/agtrace-sdk/examples/).
100
+ See [SDK Documentation](https://docs.rs/agtrace-sdk), [Examples](crates/agtrace-sdk/examples/), and [SDK README](crates/agtrace-sdk/README.md).
121
101
 
122
102
  ## Supported Providers
123
103
 
@@ -125,14 +105,13 @@ See [SDK Documentation](https://docs.rs/agtrace-sdk) and [examples](crates/agtra
125
105
  - **Codex** (OpenAI)
126
106
  - **Gemini** (Google)
127
107
 
128
- All providers auto-discovered. Logs stay local.
129
-
130
108
  ## Documentation
131
109
 
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)
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
136
115
 
137
116
  ## License
138
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.5.0"
26
+ "version": "0.5.2"
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.5.0"
518
+ "version": "0.5.2"
519
519
  }
package/package.json CHANGED
@@ -1,5 +1,5 @@
1
1
  {
2
- "artifactDownloadUrl": "https://github.com/lanegrid/agtrace/releases/download/v0.5.0",
2
+ "artifactDownloadUrl": "https://github.com/lanegrid/agtrace/releases/download/v0.5.2",
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.5.0",
96
+ "version": "0.5.2",
97
97
  "volta": {
98
98
  "node": "18.14.1",
99
99
  "npm": "9.5.0"