diff --git a/AGENTS.md b/AGENTS.md index 7252246..bdf8a23 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -48,10 +48,10 @@ python -m pytest tests/test_watch.py -v ## Version bumping -Current version: `0.51.0` in `src/agent_trace/__init__.py`. +Current version: `0.51.1` in `src/agent_trace/__init__.py`. -- New feature (new command, new flag, new integration): bump minor (`0.51.0` → `0.52.0`) -- Bug fix or small improvement: bump patch (`0.51.0` → `0.51.1`) +- New feature (new command, new flag, new integration): bump minor (`0.51.1` → `0.52.0`) +- Bug fix or small improvement: bump patch (`0.51.1` → `0.51.2`) - Breaking change to CLI or storage format: bump major — check with maintainer first ## docs/ structure diff --git a/README.md b/README.md index d70ea74..685d2bd 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ [![Python](https://img.shields.io/pypi/pyversions/agent-strace)](https://pypi.org/project/agent-strace/) [![CI](https://github.com/Siddhant-K-code/agent-trace/actions/workflows/test.yml/badge.svg)](https://github.com/Siddhant-K-code/agent-trace/actions/workflows/test.yml) [![Open VSX](https://img.shields.io/open-vsx/v/Siddhant-K-code/agent-strace)](https://open-vsx.org/extension/Siddhant-K-code/agent-strace) -[![VS Marketplace](https://img.shields.io/badge/VS%20Marketplace-v0.2.0-blue?logo=visual-studio-code)](https://marketplace.visualstudio.com/items?itemName=Siddhant-K-code.agent-strace) +[![VS Marketplace](https://img.shields.io/badge/VS%20Marketplace-v0.2.1-blue?logo=visual-studio-code)](https://marketplace.visualstudio.com/items?itemName=Siddhant-K-code.agent-strace) [![License](https://img.shields.io/github/license/Siddhant-K-code/agent-trace)](LICENSE) `strace` for AI agents. diff --git a/src/agent_trace/__init__.py b/src/agent_trace/__init__.py index 071f1f3..59770b3 100644 --- a/src/agent_trace/__init__.py +++ b/src/agent_trace/__init__.py @@ -1,3 +1,3 @@ """agent-trace: strace for AI agents.""" -__version__ = "0.51.0" +__version__ = "0.51.1" diff --git a/vscode-extension/README.md b/vscode-extension/README.md index e95d14c..21038ab 100644 --- a/vscode-extension/README.md +++ b/vscode-extension/README.md @@ -1,50 +1,88 @@ # agent-trace for VS Code -Live session overlay for [agent-trace](https://github.com/Siddhant-K-code/agent-trace). Shows what your agent is doing without leaving the editor. +Live session overlay for [agent-trace](https://github.com/Siddhant-K-code/agent-trace). See what your agent is doing without leaving the editor. + +Works in VS Code, Cursor, and any Open VSX-compatible editor. ## Features -**Status bar** — cost, tool call count, and active tool name, updated on every event. Click to open the event stream panel. +**Status bar** — live cost, tool call count, and active tool name, updated on every event. Click to open the event stream panel. ``` $(pulse) agent $0.0042 47 calls [Read] ``` -**Gutter annotations** — files the agent has read or modified get a colored left border and inline label: +**Gutter annotations** — files the agent has read or modified get a colored left border and inline label. ``` src/auth/middleware.ts ← agent read 3×, modified 1× this session src/db/schema.ts ← agent read 1× this session ``` -**Event stream panel** — live feed of every tool call, file op, LLM request, and error in the Explorer sidebar. Same information as `agent-strace watch` but in the editor. +**Event stream panel** — live feed of every tool call, file op, LLM request, and error in the Explorer sidebar. + +**Session browser** — Explorer sidebar tree listing all sessions with timestamp, duration, tool calls, and error count. Click any session to open a summary. -**Pause button** — stop the agent mid-session without killing it. Writes a signal file that `agent-strace watch` picks up and sends SIGSTOP to the agent process. Resume resumes it. +**Post-mortem viewer** — when `agent-strace watch` kills a session (timeout, budget, or rule), the viewer opens automatically. Shows kill reason, cost at death, last tool call, and a copyable recovery context for pasting into a new session. + +**Pause button** — stop the agent mid-session without killing it. Sends SIGSTOP to the agent process via `agent-strace watch`. Resume resumes it. ## Requirements -- [agent-trace](https://pypi.org/project/agent-strace/) installed (`pip install agent-strace` or `uv tool install agent-strace`) +- [agent-strace](https://pypi.org/project/agent-strace/) installed: `pip install agent-strace` or `uv tool install agent-strace` - A session started via `agent-strace setup` (Claude Code hooks) or `agent-strace record` (MCP proxy) The extension activates automatically when a `.agent-traces/` directory exists in the workspace root. -## Usage +## Setup + +```bash +# 1. Install agent-strace +pip install agent-strace + +# 2. Add hooks to Claude Code (one-time) +agent-strace setup + +# 3. Open your project in VS Code / Cursor +# Extension activates automatically when .agent-traces/ exists + +# 4. Start Claude Code — status bar appears immediately +``` -1. Install agent-trace and set up hooks: - ```bash - agent-strace setup # adds hooks to .claude/settings.json - ``` -2. Open your project in VS Code / Cursor. -3. Start Claude Code — the status bar item appears as soon as the session starts. -4. Open the **Agent Trace** panel in the Explorer sidebar for the full event stream. +## Commands -The **Pause** button in the panel (or `agent-trace: Pause Agent` command) sends SIGSTOP to the agent. This requires `agent-strace watch` to be running in a terminal alongside the session. +All commands are available from the Command Palette (`Cmd/Ctrl+Shift+P`): + +| Command | Description | +|---|---| +| `agent-trace: Open Live Stream` | Open the event stream panel | +| `agent-trace: Open Event Stream` | Open the main agent-strace panel | +| `agent-trace: View Post-Mortem` | View the watchdog post-mortem for the latest killed session | +| `agent-trace: Refresh Session Browser` | Reload the session list | +| `agent-trace: Reveal Session in Browser` | Jump to a session by ID | +| `agent-trace: Pause Agent` | Send SIGSTOP to the agent (requires `watch` running) | +| `agent-trace: Resume Agent` | Send SIGCONT to resume a paused agent | +| `agent-trace: Clear File Decorations` | Remove all gutter annotations from the editor | + +## Watchdog integration + +Run `agent-strace watch` alongside your session to enable the pause button and post-mortem viewer: + +```bash +# Kill session after 30 minutes or $5 spend +agent-strace watch --timeout 30m --budget 5.00 --on-violation kill +``` + +When the watchdog kills a session, the post-mortem viewer opens automatically. The "Copy recovery context" button copies a summary you can paste into a new session to resume where the agent left off. ## Configuration | Setting | Default | Description | |---|---|---| | `agentTrace.traceDir` | `.agent-traces` | Path to trace store, relative to workspace root | +| `agentTrace.collectorEndpoint` | `""` | Remote collector URL (leave empty for local mode) | +| `agentTrace.watchdogPollIntervalSeconds` | `5` | How often (seconds) the status bar polls for updates | +| `agentTrace.sessionBrowserRefreshInterval` | `5` | How often (seconds) the session browser refreshes | | `agentTrace.showGutterAnnotations` | `true` | Gutter icons on agent-touched files | | `agentTrace.showInlineText` | `true` | Inline read/write counts at top of file | @@ -53,3 +91,5 @@ The **Pause** button in the panel (or `agent-trace: Pause Agent` command) sends The extension watches `.agent-traces/.active-session` for the current session ID, then tails `events.ndjson` for new events using `fs.watch`. No polling when idle. No network calls. No new processes. Pause works by writing `.agent-traces/.pause-request` — `agent-strace watch` checks for this file on every poll cycle and sends SIGSTOP / SIGCONT to the agent PID. + +The post-mortem viewer reads `watchdog-postmortem.json` from the session directory, written by `agent-strace watch` on kill. diff --git a/vscode-extension/package.json b/vscode-extension/package.json index 00ad5c9..1f39476 100644 --- a/vscode-extension/package.json +++ b/vscode-extension/package.json @@ -2,7 +2,7 @@ "name": "agent-strace", "displayName": "agent-strace", "description": "Live session overlay for agent-strace: status bar, gutter annotations, and event stream panel.", - "version": "0.2.0", + "version": "0.2.1", "publisher": "Siddhant-K-code", "license": "MIT", "repository": { @@ -12,8 +12,17 @@ "engines": { "vscode": "^1.85.0" }, - "categories": ["Other"], - "keywords": ["ai", "agent", "trace", "observability", "claude", "mcp"], + "categories": [ + "Other" + ], + "keywords": [ + "ai", + "agent", + "trace", + "observability", + "claude", + "mcp" + ], "icon": "icon.png", "activationEvents": [ "workspaceContains:.agent-traces"