@lanegrid/agtrace 0.1.12 → 0.1.14

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 +65 -1
  2. package/README.md +60 -16
  3. package/npm-shrinkwrap.json +2 -2
  4. package/package.json +3 -3
package/CHANGELOG.md CHANGED
@@ -2,7 +2,71 @@
2
2
 
3
3
  All notable changes to this project will be documented in this file.
4
4
 
5
- ## [0.1.11] - 2025-12-29
5
+ ## [0.1.14] - 2025-12-31
6
+
7
+ ### Bug Fixes
8
+
9
+ - *(sdk)* Make SessionFilter::default() equivalent to new() with reasonable limit ([2f1f481](https://github.com/lanegrid/agtrace/commit/2f1f481e28c76118a4821f0290f47221bcf96540))
10
+
11
+
12
+ ### Documentation
13
+
14
+ - Complete SDK-CLI refactor ExecPlan with outcomes and retrospective ([2f4e456](https://github.com/lanegrid/agtrace/commit/2f4e45604fbefe55dd001021ada08b86b2119170))
15
+
16
+ - Remove completed SDK-CLI refactor planning documents ([cb2a668](https://github.com/lanegrid/agtrace/commit/cb2a6689f4a309e088f779e38c1116ecde6b0305))
17
+
18
+
19
+ ### Refactor
20
+
21
+ - *(cli)* Migrate all handlers to use agtrace-sdk instead of internal crates ([548a7b7](https://github.com/lanegrid/agtrace/commit/548a7b7c53f46d63b9a552fa6de8946bf3a8bc4c))
22
+
23
+ - *(cli)* Replace internal crate imports with SDK in presentation layer ([2e0da9a](https://github.com/lanegrid/agtrace/commit/2e0da9acdd9b8ff3b4f3cfd7a05dcf141c57e513))
24
+
25
+ - *(cli)* Achieve strict SDK-only dependency by eliminating all internal crate usage ([22a0590](https://github.com/lanegrid/agtrace/commit/22a059038689dd80b7c1d51ead50fa1cf5e826e7))
26
+
27
+ - *(sdk)* Introduce utils module for low-level API, remove internal re-exports, add SessionHandle::from_events() ([4e48516](https://github.com/lanegrid/agtrace/commit/4e485169ad818ffa8a91ebce3c1a10c11cef717f))
28
+
29
+
30
+ ### Testing
31
+
32
+ - Migrate integration tests to use agtrace-sdk types ([aeb458e](https://github.com/lanegrid/agtrace/commit/aeb458ee8d259200335f52daed5b97fc722fa10c))
33
+
34
+
35
+ ## [0.1.13] - 2025-12-30
36
+
37
+ ### Features
38
+
39
+ - *(sdk)* Add agtrace-sdk facade for building observability tools ([1f99847](https://github.com/lanegrid/agtrace/commit/1f99847bc2e081cabfe87eaf6d6135f946e33489))
40
+
41
+ - *(sdk)* Add working examples demonstrating SDK usage (connection, analysis, watch) ([d1cc697](https://github.com/lanegrid/agtrace/commit/d1cc69760fc14eafcb482f339a1d5562c8304857))
42
+
43
+ - *(sdk)* Implement Iterator trait for LiveStream and structured Insight type with Severity ([c8e38f0](https://github.com/lanegrid/agtrace/commit/c8e38f0ef846433669558e310da2acc5f61f331e))
44
+
45
+
46
+ ### Bug Fixes
47
+
48
+ - *(sdk)* Remove unused mut and Duration import from watch_events example ([1adfd62](https://github.com/lanegrid/agtrace/commit/1adfd6296349c5eb9a9b4b8bdb5d02a77ea8a6f5))
49
+
50
+
51
+ ### Documentation
52
+
53
+ - Reframe agtrace as observability platform with SDK and CLI applications ([891caad](https://github.com/lanegrid/agtrace/commit/891caad8c6290f0a7767e71965ef93b1c06baea9))
54
+
55
+ - Improve README with Iterator usage, workspace context, and Mermaid architecture diagram ([1910bf0](https://github.com/lanegrid/agtrace/commit/1910bf0ee907951bfcca230c240ab55820d808ec))
56
+
57
+
58
+ ### Refactor
59
+
60
+ - Replace String-based project_hash with type-safe ProjectHash throughout codebase ([958233b](https://github.com/lanegrid/agtrace/commit/958233bb737068b1f270cee7d199fca8331f83e6), [2261ac1](https://github.com/lanegrid/agtrace/commit/2261ac1d7e89199cfaf001d0b5d71a3abac36848), [04cc841](https://github.com/lanegrid/agtrace/commit/04cc84124249ddb9f4eb16e6e7abc0a2e0f050cb))
61
+
62
+ - Migrate from context_window_tokens() to total_tokens() and remove legacy methods ([d59ebec](https://github.com/lanegrid/agtrace/commit/d59ebec8681af13eb9905357acdc496a5bd4fda4), [f2870e6](https://github.com/lanegrid/agtrace/commit/f2870e68e3ceb22d3fa009f3e3bdda711daf22eb), [0d62675](https://github.com/lanegrid/agtrace/commit/0d6267522a326e9aea30983a27be82e0d6a88c8f))
63
+
64
+ - *(agtrace-types)* Reorganize into domain/, event/, and tool/ modules ([af061aa](https://github.com/lanegrid/agtrace/commit/af061aaab26847291386a4fe5c1d0195439cb8d6))
65
+
66
+ - *(agtrace-index)* Reorganize db.rs into modular structure (records, schema, queries) ([dec1721](https://github.com/lanegrid/agtrace/commit/dec17219c10daf0bbc61d6a25484268388fff7be))
67
+
68
+
69
+ ## [0.1.12] - 2025-12-29
6
70
 
7
71
  ### Bug Fixes
8
72
 
package/README.md CHANGED
@@ -1,7 +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>top + tail -f for AI Coding Agent Sessions.</strong></p>
4
+ <p><strong>The Observability Platform for AI Agents.</strong></p>
5
+ <p>Local-first OpenTelemetry for Claude, Codex, and Gemini.</p>
5
6
 
6
7
  [![npm version](https://img.shields.io/npm/v/@lanegrid/agtrace.svg?style=flat)](https://www.npmjs.com/package/@lanegrid/agtrace)
7
8
  [![crates.io](https://img.shields.io/crates/v/agtrace.svg)](https://crates.io/crates/agtrace)
@@ -11,40 +12,83 @@
11
12
 
12
13
  ![agtrace watch demo](https://raw.githubusercontent.com/lanegrid/agtrace/main/docs/assets/demo.gif)
13
14
 
14
- ## What it does
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
17
 
16
- - Live dashboard for context pressure, tool activity, and costs
17
- - Session history you can query and compare
18
- - Works with Claude Code, Codex, and Gemini
19
- - 100% local, no cloud
18
+ ## 🌟 Core Value
20
19
 
21
- ## Install
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
+
24
+ ## 🚀 Quick Start (CLI)
25
+
26
+ The reference implementation of the agtrace platform.
22
27
 
23
28
  ```bash
24
29
  npm install -g @lanegrid/agtrace
25
- # or
26
- cargo install agtrace
30
+ cd my-project
31
+ agtrace init # initialize workspace (~/.agtrace)
32
+ agtrace watch # live dashboard
27
33
  ```
28
34
 
29
- ## Usage
35
+ ## 🛠️ Building with the SDK
30
36
 
31
- ```bash
32
- agtrace init # once
33
- agtrace watch # in project dir, then start your agent
37
+ Embed agent observability into your own tools (vital-checkers, IDE plugins, dashboards).
38
+
39
+ ```toml
40
+ [dependencies]
41
+ agtrace-sdk = "0.1.13"
34
42
  ```
35
43
 
36
- ## Learn More
44
+ ```rust
45
+ use agtrace_sdk::{Client, Lens, analyze_session, assemble_session};
46
+
47
+ // Connect to the local workspace
48
+ let client = Client::connect("~/.agtrace")?;
49
+
50
+ // 1. Real-time Monitoring
51
+ for event in client.watch().all_providers().start()? {
52
+ println!("Activity: {:?}", event);
53
+ }
54
+
55
+ // 2. Session Diagnosis
56
+ let events = client.session("session_123").events()?;
57
+ if let Some(session) = assemble_session(&events) {
58
+ let report = analyze_session(session)
59
+ .through(Lens::Failures)
60
+ .through(Lens::Loops)
61
+ .report()?;
62
+ println!("Health: {}", report.score);
63
+ }
64
+ ```
65
+
66
+ ## 📚 Documentation
37
67
 
38
68
  - [Why agtrace?](docs/motivation.md) - Understanding the problem and solution
39
69
  - [Getting Started](docs/getting-started.md) - Detailed installation and usage guide
40
- - [Full Documentation](docs/README.md) - Commands, architecture, and FAQs
70
+ - [Architecture](docs/architecture.md) - Platform design and principles
71
+ - [SDK Documentation](crates/agtrace-sdk/README.md) - Building custom tools
72
+ - [Full Documentation](docs/README.md) - Commands, FAQs, and more
41
73
 
42
- ## Supported Providers
74
+ ## 🔌 Supported Providers
43
75
 
44
76
  - **Claude Code** (Anthropic)
45
77
  - **Codex** (OpenAI)
46
78
  - **Gemini** (Google)
47
79
 
80
+ ## 📦 Architecture
81
+
82
+ ```mermaid
83
+ graph TD
84
+ CLI[agtrace-cli] --> SDK[agtrace-sdk]
85
+ YourApp[Your Tool] --> SDK
86
+ SDK --> Core[Core Engine & Providers]
87
+ ```
88
+
89
+ - **Core SDK**: `agtrace-sdk`, `agtrace-engine`, `agtrace-providers`
90
+ - **Applications**: `agtrace-cli` (Reference Implementation)
91
+
48
92
  ## License
49
93
 
50
94
  Dual-licensed under the MIT and Apache 2.0 licenses.
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.1.12"
26
+ "version": "0.1.14"
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.1.12"
518
+ "version": "0.1.14"
519
519
  }
package/package.json CHANGED
@@ -1,5 +1,5 @@
1
1
  {
2
- "artifactDownloadUrl": "https://github.com/lanegrid/agtrace/releases/download/v0.1.12",
2
+ "artifactDownloadUrl": "https://github.com/lanegrid/agtrace/releases/download/v0.1.14",
3
3
  "bin": {
4
4
  "agtrace": "run-agtrace.js"
5
5
  },
@@ -10,7 +10,7 @@
10
10
  "detect-libc": "^2.1.2",
11
11
  "rimraf": "^6.1.2"
12
12
  },
13
- "description": "A CLI tool to visualize and analyze AI agent execution traces (Claude, Gemini, etc.) in a unified timeline.",
13
+ "description": "The official CLI for agtrace, built on top of agtrace-sdk. Visualize and analyze AI agent execution traces.",
14
14
  "devDependencies": {
15
15
  "prettier": "^3.7.4"
16
16
  },
@@ -93,7 +93,7 @@
93
93
  "zipExt": ".tar.xz"
94
94
  }
95
95
  },
96
- "version": "0.1.12",
96
+ "version": "0.1.14",
97
97
  "volta": {
98
98
  "node": "18.14.1",
99
99
  "npm": "9.5.0"