release(v1.6.16): agent observability + state_cache bake fix

.claude-plugin/marketplace.json

@@ -1,16 +1,16 @@
 {
   "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
   "name": "dreamrec-TDPilot",
-  "description": "AI copilot for TouchDesigner \u2014 104 MCP tools for live node graph control, parameter management, diagnostics, safety, streaming, technique memory, knowledge corpus, focus + locations, hint injection, component notes, and typed patch sessions.",
+  "description": "AI copilot for TouchDesigner \u2014 106 MCP tools for live node graph control, parameter management, diagnostics, safety, streaming, technique memory, knowledge corpus, focus + locations, hint injection, component notes, typed patch sessions, agent activity log, and one-tool self-update.",
   "owner": {
     "name": "dreamrec",
     "email": "dreamrec@users.noreply.github.com"
   },
   "plugins": [
     {
       "name": "tdpilot",
-      "description": "AI copilot for TouchDesigner with live MCP control \u2014 104 tools, focus + locations, hint injection, component notes, POPx inspection, knowledge corpus, project lifecycle, custom parameter authoring, snapshots, undo-block safety, and typed patch sessions. Works with Claude Desktop, Claude Code, and any MCP-compatible client.",
-      "version": "1.6.15",
+      "description": "AI copilot for TouchDesigner with live MCP control \u2014 106 tools, focus + locations, hint injection, component notes, POPx inspection, knowledge corpus, project lifecycle, custom parameter authoring, snapshots, undo-block safety, typed patch sessions, agent activity log, and one-tool self-update. Works with Claude Desktop, Claude Code, and any MCP-compatible client.",
+      "version": "1.6.16",
       "author": {
         "name": "silviu"
       },

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "tdpilot",
-  "version": "1.6.15",
-  "description": "TDPilot \u2014 AI copilot for TouchDesigner. 104 MCP tools for live node graph control, parameter management, diagnostics, safety, streaming, knowledge corpus, focus + locations, hint injection, component notes, technique memory, and typed patch sessions.",
+  "version": "1.6.16",
+  "description": "TDPilot \u2014 AI copilot for TouchDesigner. 106 MCP tools for live node graph control, parameter management, diagnostics, safety, streaming, knowledge corpus, focus + locations, hint injection, component notes, technique memory, typed patch sessions, agent activity log, and one-tool self-update.",
   "author": {
     "name": "silviu"
   },

CHANGELOG.md

@@ -1,6 +1,92 @@
 # Changelog
 
 
+## 1.6.16 - 2026-05-18 — Agent observability (read journal + activity log) + one-tool self-update
+
+### Added
+
+- **`_read_journal` response hint on every dispatched tool** (`src/td_mcp/read_journal.py`,
+  wired in `src/td_mcp/tool_registry.py:_forward`). Each tool response now carries a
+  `{call_count, first_seen_at, last_seen_at, result_unchanged}` envelope keyed by
+  (tool_name, args_fingerprint). The model can see, across MCP request boundaries,
+  whether a repeat call returned the same result hash — eliminating the wasted
+  token cycles of re-fetching `td_get_nodes("/project1")` seven times when nothing
+  has moved. The journal is **advisory only**: every call still executes against
+  TD, so a mutating scene never serves stale data. Bounded to 500 distinct
+  fingerprints, oldest-by-`last_seen_at` evicted under pressure. Thread-safe
+  module-level dict (same pattern as `state_cache`).
+- **`td_get_activity_log` MCP tool + 200-entry server-side ring buffer**
+  (`src/td_mcp/activity_log.py`, `src/td_mcp/registry/tools_meta.py`).
+  Every `_forward` dispatch appends one entry: `{ts, tool, args_summary,
+  result_summary, duration_ms, ok}`. `td_get_activity_log(limit, tool_filter)`
+  returns recent entries newest-first so Claude can ask "what have I done
+  this session?" without scrolling its own context. Optimized for time
+  ordering (vs `_read_journal`, which dedupes by fingerprint).
+- **In-TD `activity_log` Table DAT mirror** (`td_component/build_export_mcp_tox.py`,
+  `td_component/event_emitter.py:append_activity_row`,
+  `td_component/mcp_webserver_callbacks.py:_record_request_safe`). A new
+  Table DAT at `/local/mcp_server/activity_log` is populated on every MCP
+  HTTP request with the same five-column schema as the server-side buffer.
+  Users can chain this DAT into their visuals (Select DAT → Text TOP / CHOP
+  pipeline) so the AI's actions become an addressable, time-windowed
+  data source inside the live patch. Rolling window of 200 rows.
+- **`td_self_update` MCP tool + `td_mcp/self_updater.py`**. Hits the GitHub
+  releases API for `dreamrec/TDPilot`, compares the latest semver against
+  the running `__version__`, and (when `check_only=False`) downloads the
+  release asset and writes it to all three install paths the user-memory
+  staleness saga identified: the repo working-tree `td_component/`, the
+  Claude Code plugin cache `~/.claude/plugins/cache/dreamrec-TDPilot/.../`,
+  and the user-data dir `~/.tdpilot/td_component/`. Reports md5 sums per
+  path so the caller can verify three-way sync. The follow-up step
+  ("re-run setup_mcp_in_td.py inside TD Textport to refresh `/local/mcp_server`")
+  is included in the response payload so the seventh staleness layer
+  (live in-TD COMP) doesn't get forgotten. Pure stdlib (`urllib.request`,
+  `hashlib`) so it also runs inside TouchDesigner's Python interpreter via
+  `python -m td_mcp.self_updater`.
+
+### Changed
+
+- **Tool count 104 → 106** (`src/td_mcp/release_gates.py:EXPECTED_MIN_TOOL_COUNT`).
+  Two new tools above. All user-facing copies bumped: README badges, npm
+  description, plugin manifests, marketplace.json, skills, docs, CHANGELOG.
+- **`_forward` dispatch wrapper** (`src/td_mcp/tool_registry.py:839`) now runs
+  the read-journal + activity-log hooks in `try/finally` blocks. Failures
+  inside either observability layer are swallowed — they must never break
+  a tool response. Timing precision via `time.perf_counter` so reported
+  `duration_ms` includes only the TD round-trip + serialization.
+
+### Fixed
+
+- **`state_cache.py` source was never baked into the textDAT**
+  (`td_component/build_export_mcp_tox.py:build_and_export`). The file
+  was added to `_TOX_SOURCE_FILES` in v1.6.7 for freshness-hash tracking
+  but the `_populate_component` callers never passed `state_cache_code`,
+  so the DAT shipped with empty `.text`. Accessing `.module` on an empty
+  Text DAT raises `td.tdError: Module compilation error`, which
+  propagated through `hasattr(cache, 'module')` (only catches
+  `AttributeError`) and aborted the surrounding state_cache writer. v1.6.16
+  reads `td_component/state_cache.py` and threads it through both
+  `_populate_component` call sites. Latent since v1.6.7; surfaced when
+  the new dual-writer in `_record_request_safe` exposed the same code
+  path more directly.
+- **`_record_request_safe` lost the activity_log mirror when state_cache
+  raised** (`td_component/mcp_webserver_callbacks.py`). The state_cache
+  and activity_log writers shared one outer try/except, so a state_cache
+  `tdError` (above) killed both. v1.6.16 splits them into independent
+  try blocks and switches the `parent()` global to the always-defined
+  `me.parent()` instance method, so the activity_log mirror is resilient
+  to any future state_cache breakage.
+
+### Migration
+
+- No breaking surface changes. Every existing tool keeps its current
+  signature; the new `_read_journal` field is purely additive on responses.
+- Users who already have v1.6.15 installed can either reinstall the plugin
+  the normal way OR call the new `td_self_update(check_only=False)` from
+  Claude after upgrading to v1.6.16. The latter is the single-command flow
+  the rest of this release was built to enable.
+
+
 ## 1.6.15 - 2026-05-15 — TD 2025+ auth-handshake fix + Pydantic v2 ClassVar fix + auto-versioned .tox sidecars
 
 ### Fixed

README.md

@@ -7,14 +7,14 @@
    ╚═╝   ╚═════╝ ╚═╝     ╚═╝╚══════╝ ╚═════╝    ╚═╝
 ```
 
-# TDPilot Runtime v1.6.15
+# TDPilot Runtime v1.6.16
 
 [![CI](https://github.com/dreamrec/TDPilot/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/dreamrec/TDPilot/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/tdpilot?label=npm)](https://www.npmjs.com/package/tdpilot)
 [![downloads](https://img.shields.io/npm/dm/tdpilot?label=downloads)](https://www.npmjs.com/package/tdpilot)
 [![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
 [![python](https://img.shields.io/badge/python-3.10%2B-blue)](./pyproject.toml)
-[![MCP tools](https://img.shields.io/badge/MCP%20tools-104-blueviolet)](./docs/API_REFERENCE.md)
+[![MCP tools](https://img.shields.io/badge/MCP%20tools-106-blueviolet)](./docs/API_REFERENCE.md)
 [![TouchDesigner](https://img.shields.io/badge/TouchDesigner-2025.30000%2B-ff6200)](https://derivative.ca)
 
 **TDPilot Runtime** is an MCP server for TouchDesigner.
@@ -31,7 +31,7 @@ It lets an AI agent inspect, build, wire, optimize, and stabilize live TD networ
 /plugin install tdpilot@dreamrec-TDPilot
 ```
 
-That installs all **104 MCP tools**, 3 skills (`tdpilot-core`, `tdpilot-production`, `popx-touchdesigner`), 2 slash commands (`/td-check`, `/td-snapshot`), and the TD-side `.tox` component — one command, no Python setup required.
+That installs all **106 MCP tools**, 3 skills (`tdpilot-core`, `tdpilot-production`, `popx-touchdesigner`), 2 slash commands (`/td-check`, `/td-snapshot`), and the TD-side `.tox` component — one command, no Python setup required.
 
 **Shell one-liner alternative:**
 
@@ -70,11 +70,11 @@ Using Claude Desktop instead of Claude Code? See [`docs/INSTALL_CLAUDE_PLUGIN.md
 - A structured toolset for scene edits, diagnostics, event monitoring, and recovery.
 - A workflow-oriented MCP built for iterative patch development, not one-shot guessing.
 - A technique memory system that learns from your projects and builds a reusable library.
-- 104-tool runtime surface with focus + locations, hint injection, component notes, knowledge corpus, vision diagnostics, TD 2025 native inspection, official recommendations, job resources, memory, optimizer, safety, POPx inspection, project lifecycle control, custom parameter authoring, and typed patch sessions.
+- 106-tool runtime surface with focus + locations, hint injection, component notes, knowledge corpus, vision diagnostics, TD 2025 native inspection, official recommendations, job resources, memory, optimizer, safety, POPx inspection, project lifecycle control, custom parameter authoring, typed patch sessions, agent activity log, and one-tool self-update.
 
 ## Start Here: Core Workflow
 
-You don't need all 104 tools. Start with these and expand as needed:
+You don't need all 106 tools. Start with these and expand as needed:
 
 | Step | Tools | What You're Doing |
 |------|-------|-------------------|
@@ -89,9 +89,11 @@ You don't need all 104 tools. Start with these and expand as needed:
 
 Everything else (vision, streaming, optimization, planning, TD2025 inspection) builds on top of this core.
 
-## What's New In 1.6.15 – 1.6.14
+## What's New In 1.6.16 – 1.6.14
 
-Stability + ergonomics run since v1.6.0. Tool count unchanged at 104; hint corpus grew to 73 hints across 20 packs. Headlines:
+Stability + ergonomics run since v1.6.0. v1.6.16 adds two new agent-observability tools (`td_get_activity_log`, `td_self_update`); tool count 104 → 106. Hint corpus stays at 73 hints across 20 packs. Headlines:
+
+- **v1.6.16** — Agent-observability + self-update. Every tool response now carries a `_read_journal` hint (`call_count`, `result_unchanged`, `first_seen_at`, `last_seen_at`) so Claude can see across MCP request boundaries which reads have moved and which haven't — no more wasted token cycles re-fetching the same view of `td_get_nodes`. A 200-entry server-side activity ring buffer mirrors to an in-TD Table DAT (`/local/mcp_server/activity_log`) so users can wire agent activity into their visuals. New `td_self_update` MCP tool hits the GitHub releases API and (optionally) writes the latest `tdpilot.tox` to all three install paths (repo, Claude Code plugin cache, `~/.tdpilot/`) with md5 sync reporting — closing the seven-layer staleness saga documented in user memory.
 
 - **v1.6.14** — MCP-server-side auth fix: `TDClient` now resolves the shared secret fresh on every request (env → `~/.tdpilot/.tdpilot.env` → constructor fallback, with 5s cache) and retries once on a 401 after invalidating the cache. Symmetric with the v1.6.13 TD-side fallback — closes the asymmetric half that was still 401ing real sessions when `bootstrap_auth` ran late and a stale module-level secret got baked into the cached `httpx.AsyncClient` headers. Also ships the **TD 2025.32820 release card** (Math Mix / Math Combine POPs, EXR compression, GLSL MAT `TDProjTextureLod`/`TDProjTextureSize`, Blackmagic SDK 16, CUDA 12.9.1, NDI 6.3.1) and a **CI freshness gate** (`scripts/check_release_notes_freshness.py`) that fails when seed cards trail `docs.derivative.ca/Release_Notes` by more than one build.
 - **v1.6.13** — Permanent TD-side auth-race fix: `_current_shared_secret()` in `td_component/mcp_webserver_callbacks.py` now has a file fallback that reads `~/.tdpilot/.tdpilot.env` when `os.environ` is empty. Stops the 401 cascade when TD is opened directly (Dock icon, double-click `.toe`) and inherits an empty env, then `npx tdpilot` later writes the secret to the file.
@@ -205,7 +207,7 @@ Use this loop for every non-trivial task:
 
 6. **Control token cost** — Prefer metadata checks over continuous image payloads. Ask the user before enabling high-token frame streaming.
 
-## Tool Map (104 Tools)
+## Tool Map (106 Tools)
 
 ### 1) Scene + Timeline + Project Lifecycle
 Use for global context, playback control, save/load, and undo operations.

docs/API_REFERENCE.md

@@ -1,6 +1,6 @@
 # TDPilot API Reference
 
-> Auto-generated from TDPilot v1.6.15 | 104 tools | Source: `src/td_mcp/tool_registry.py`
+> Auto-generated from TDPilot v1.6.16 | 106 tools | Source: `src/td_mcp/tool_registry.py`
 
 ---
 

docs/GETTING_STARTED.md

@@ -153,7 +153,7 @@ This is how you keep the patch understandable.
 
 ## The Small Set Of Tools That Matter Most
 
-You do not need to learn all 104 tools to get real value.
+You do not need to learn all 106 tools to get real value.
 
 If you are new, focus on these:
 

docs/MANUAL.md

@@ -1,4 +1,4 @@
-# TDPilot v1.6.15 Production Manual
+# TDPilot v1.6.16 Production Manual
 
 This manual is for people who need real output in TouchDesigner, not theory. It explains what TDPilot does well, what it does not do, and how to run it with repeatable production discipline.
 

docs/USER_GUIDE.md

@@ -241,7 +241,7 @@ Prompt:
 
 ## Your "Good Enough" TDPilot Starter Stack
 
-If you do not want to learn all 104 tools, focus on this stack:
+If you do not want to learn all 106 tools, focus on this stack:
 
 - inspect:
   `td_get_info`, `td_get_nodes`, `td_get_node_detail`, `td_get_params`

mcp/manifest.json

@@ -2,7 +2,7 @@
   "schema_version": 1,
   "name": "TDPilot",
   "slug": "tdpilot",
-  "version": "1.6.15",
+  "version": "1.6.16",
   "repository": "https://github.com/dreamrec/TDPilot",
   "description": "MCP server for TouchDesigner with live graph control, diagnostics, safety, streaming, knowledge corpus, technique memory, and typed patch sessions.",
   "entrypoints": {
@@ -32,7 +32,7 @@
     "transport": "stdio"
   },
   "surface": {
-    "tool_count": 104,
+    "tool_count": 106,
     "resource_template_count": 6,
     "static_resource_count": 1
   },

npm/README.md

@@ -1,12 +1,12 @@
-# TDPilot v1.6.15
+# TDPilot v1.6.16
 
 [![CI](https://github.com/dreamrec/TDPilot/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/dreamrec/TDPilot/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/tdpilot?label=npm)](https://www.npmjs.com/package/tdpilot)
 [![downloads](https://img.shields.io/npm/dm/tdpilot?label=downloads)](https://www.npmjs.com/package/tdpilot)
 [![license](https://img.shields.io/badge/license-MIT-blue)](https://github.com/dreamrec/TDPilot/blob/main/LICENSE)
-[![MCP tools](https://img.shields.io/badge/MCP%20tools-104-blueviolet)](https://github.com/dreamrec/TDPilot/blob/main/docs/API_REFERENCE.md)
+[![MCP tools](https://img.shields.io/badge/MCP%20tools-106-blueviolet)](https://github.com/dreamrec/TDPilot/blob/main/docs/API_REFERENCE.md)
 
-AI copilot for TouchDesigner — 104 tools for full live control via MCP, with technique memory, knowledge corpus, POPx inspection, project lifecycle control, focus + locations, hint injection, component notes, and custom parameter authoring.
+AI copilot for TouchDesigner — 106 tools for full live control via MCP, with technique memory, knowledge corpus, POPx inspection, project lifecycle control, focus + locations, hint injection, component notes, custom parameter authoring, agent activity log, and one-tool self-update.
 
 ## Quick start
 

npm/package.json

@@ -1,7 +1,7 @@
 {
   "name": "tdpilot",
-  "version": "1.6.15",
-  "description": "AI copilot for TouchDesigner with live MCP control \u2014 104 tools, focus + locations, hint injection, component notes, POPx inspection, knowledge corpus, project lifecycle control, technique memory, typed patch sessions, Claude Code plugin marketplace install.",
+  "version": "1.6.16",
+  "description": "AI copilot for TouchDesigner with live MCP control \u2014 106 tools, focus + locations, hint injection, component notes, POPx inspection, knowledge corpus, project lifecycle control, technique memory, typed patch sessions, agent activity log, one-tool self-update, Claude Code plugin marketplace install.",
   "keywords": [
     "touchdesigner",
     "mcp",