threadkeeper 0.17.2__tar.gz → 0.17.3__tar.gz

{threadkeeper-0.17.2 → threadkeeper-0.17.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: threadkeeper
-Version: 0.17.2
+Version: 0.17.3
 Summary: Multi-agent shared brain across Claude Code/Desktop, Codex, Antigravity CLI, Copilot, and VS Code. Cross-session memory, self-improving skill loops, inter-agent signaling — one local MCP server.
 Author: thread-keeper contributors
 License: MIT
@@ -1058,7 +1058,10 @@ Three detection sources per tick:
    from an exhausted subscription; the real outcome only lands in
    `tasks.return_code`. The reason is read from the child's log tail.
 3. **Materialization** — `skill_materialized` / `skill_create` (skill) and
-   `lesson_append` (lesson).
+   `lesson_append` (lesson). Each notification contains one readable artifact
+   name: the skill's first heading (falling back to its directory name), or
+   the lesson name with slug separators replaced by spaces. Paths, provenance,
+   and operation metadata stay out of the notification text.
 
 A per-loop cooldown collapses a lapsed-subscription storm into one actionable
 alert; the first run seeds its cursor to the current position, so historical
@@ -1089,12 +1092,16 @@ will register the app in **System Settings ▸ Notifications** and show banners;
 banners are titled **Thread-Keeper** (`CFBundleDisplayName`). The first launch
 after an update shows a one-time permission prompt.
 
-`agent_status` feeds the app two lists — `recent_results` (positive: captured
-skills/lessons) and `recent_failures` (the two failure sources above) — each item
-tagged with a `notify` flag computed from the toggles below. The app **lists**
+`agent_status` feeds the app two lists — `recent_results` (named skill/lesson
+write events plus completed-task history) and `recent_failures` (the two failure
+sources above) — each item tagged with a `notify` flag computed from the toggles
+below. The app **lists**
 every item in its menu but only **posts a banner** for flagged ones, so turning a
-category off silences the banner without hiding the history. Enabling a toggle
-never replays backlog.
+category off silences the banner without hiding the history. Each materialization
+uses its own skill or lesson toggle; generic task reports are history-only.
+Foreground writes appear too, without waiting for a background child to finish.
+A pathless skill mark only silences its reminder and has no materialization
+banner. Enabling a toggle never replays backlog.
 
 **Settings in the app.** The menu-bar app's **Settings ▸ Notifications** tab
 edits these same `THREADKEEPER_NOTIFY_*` keys visually — switches for the

{threadkeeper-0.17.2 → threadkeeper-0.17.3}/README.md

@@ -1014,7 +1014,10 @@ Three detection sources per tick:
    from an exhausted subscription; the real outcome only lands in
    `tasks.return_code`. The reason is read from the child's log tail.
 3. **Materialization** — `skill_materialized` / `skill_create` (skill) and
-   `lesson_append` (lesson).
+   `lesson_append` (lesson). Each notification contains one readable artifact
+   name: the skill's first heading (falling back to its directory name), or
+   the lesson name with slug separators replaced by spaces. Paths, provenance,
+   and operation metadata stay out of the notification text.
 
 A per-loop cooldown collapses a lapsed-subscription storm into one actionable
 alert; the first run seeds its cursor to the current position, so historical
@@ -1045,12 +1048,16 @@ will register the app in **System Settings ▸ Notifications** and show banners;
 banners are titled **Thread-Keeper** (`CFBundleDisplayName`). The first launch
 after an update shows a one-time permission prompt.
 
-`agent_status` feeds the app two lists — `recent_results` (positive: captured
-skills/lessons) and `recent_failures` (the two failure sources above) — each item
-tagged with a `notify` flag computed from the toggles below. The app **lists**
+`agent_status` feeds the app two lists — `recent_results` (named skill/lesson
+write events plus completed-task history) and `recent_failures` (the two failure
+sources above) — each item tagged with a `notify` flag computed from the toggles
+below. The app **lists**
 every item in its menu but only **posts a banner** for flagged ones, so turning a
-category off silences the banner without hiding the history. Enabling a toggle
-never replays backlog.
+category off silences the banner without hiding the history. Each materialization
+uses its own skill or lesson toggle; generic task reports are history-only.
+Foreground writes appear too, without waiting for a background child to finish.
+A pathless skill mark only silences its reminder and has no materialization
+banner. Enabling a toggle never replays backlog.
 
 **Settings in the app.** The menu-bar app's **Settings ▸ Notifications** tab
 edits these same `THREADKEEPER_NOTIFY_*` keys visually — switches for the

{threadkeeper-0.17.2 → threadkeeper-0.17.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "threadkeeper"
-version = "0.17.2"
+version = "0.17.3"
 description = "Multi-agent shared brain across Claude Code/Desktop, Codex, Antigravity CLI, Copilot, and VS Code. Cross-session memory, self-improving skill loops, inter-agent signaling — one local MCP server."
 requires-python = ">=3.11"
 authors = [{ name = "thread-keeper contributors" }]

{threadkeeper-0.17.2 → threadkeeper-0.17.3}/tests/test_agent_status.py

@@ -4,6 +4,8 @@ import json
 import os
 import time
 
+import pytest
+
 
 _FAKE_CID = "33334444-5555-6666-7777-888899990000"
 
@@ -468,6 +470,42 @@ def test_agent_status_recent_results_for_useful_completed_tasks(mp_with_cid):
     assert snap["recent_results"][0]["summary"] == (
         "Processed 2 candidates into durable notes."
     )
+    assert snap["recent_results"][0]["notify"] is False
+
+
+@pytest.mark.parametrize("poll,skill,lesson", [
+    (30, True, True), (30, True, False), (30, False, True), (0, True, True),
+])
+def test_materialization_results_name_actual_writes(mp_with_cid, poll, skill, lesson):
+    pkg = mp_with_cid(_FAKE_CID)
+    pkg["config"].NOTIFY_POLL_S = poll
+    pkg["config"].NOTIFY_SKILL_MATERIALIZED = skill
+    pkg["config"].NOTIFY_LESSON = lesson
+    result = _txt(_tool(pkg, "skill_manage")(
+        action="create", name="api-contract-testing",
+        description="Test API contracts.", content="# API contract testing\n\nUse schemas.",
+    ))
+    assert result.startswith("ok"), result
+    result = _txt(_tool(pkg, "lesson_append")(
+        title="Verify state transitions", body="Assert the state after the action.",
+        source="T1",
+    ))
+    assert result.startswith("ok"), result
+    _insert_completed_task(pkg, "tk_generic_done",
+                           "You are a CANDIDATE REVIEWER for thread-keeper's extract queue.",
+                           "Processed 2 candidates into durable notes.\n")
+
+    from threadkeeper.agent_status import agent_status_snapshot
+
+    items = agent_status_snapshot(refresh=False)["recent_results"]
+    by_role = {item["role"]: item for item in items}
+    assert by_role["skill"]["summary"] == "API contract testing"
+    assert by_role["lesson"]["summary"] == "Verify state transitions"
+    assert by_role["skill"]["notify"] is bool(poll and skill)
+    assert by_role["lesson"]["notify"] is bool(poll and lesson)
+    assert by_role["candidate_reviewer"]["notify"] is False
+    assert all(item["id"].startswith("materialization:")
+               for item in items if item["role"] in ("skill", "lesson"))
 
 
 def test_agent_status_mcp_json_output(mp_with_cid):

{threadkeeper-0.17.2 → threadkeeper-0.17.3}/tests/test_notify_daemon.py

@@ -228,8 +228,48 @@ def test_positives_on_fire(tmp_path, monkeypatch, caplog):
     with caplog.at_level(logging.WARNING, logger="threadkeeper.notify"):
         out = notify.run_notify_pass(force=True)
     assert out == "ok fired=2", out
-    assert "skill materialized" in caplog.text
-    assert "lesson added" in caplog.text and "my-lesson" in caplog.text
+    assert "skill materialized | Foo" in caplog.text
+    assert "lesson added | My lesson" in caplog.text
+    assert "/skills/" not in caplog.text
+    assert "op=create" not in caplog.text and "source=shadow" not in caplog.text
+
+
+@pytest.mark.parametrize("directory", [False, True])
+def test_skill_notification_uses_heading(tmp_path, monkeypatch, directory):
+    m = _bootstrap(tmp_path, monkeypatch, skill="true")
+    md = tmp_path / "api-contract-testing" / "SKILL.md"
+    md.parent.mkdir()
+    md.write_text("---\nname: api-contract-testing\ndescription: |\n"
+                  "  Internal description\n---\n\n# API contract testing\n"
+                  "\nLong implementation details that do not belong in a banner.\n")
+    notify = m["notify"]
+    conn = m["db"].get_db()
+    sent = []
+    monkeypatch.setattr(notify, "_dispatch", lambda *args: sent.append(args))
+    assert notify.run_notify_pass(force=True) == "seed"
+    _ev(conn, "skill_materialized", target="T1",
+        summary=str(md.parent if directory else md))
+    assert notify.run_notify_pass(force=True) == "ok fired=1"
+    assert sent == [("Thread-keeper: skill materialized", "API contract testing")]
+    assert notify.run_notify_pass(force=True) == "ok fired=0"
+
+
+@pytest.mark.parametrize("body", [b"---\nname: foo\n---\nNo heading.", b"\xff"])
+def test_skill_notification_falls_back_to_name(tmp_path, monkeypatch, body):
+    notify = _bootstrap(tmp_path, monkeypatch)["notify"]
+    md = tmp_path / "api-contract-testing" / "SKILL.md"
+    md.parent.mkdir()
+    md.write_bytes(body)
+    assert notify._fmt_skill({"kind": "skill_create", "target": "api-contract-testing",
+                              "summary": str(md)})[1] == "Api contract testing"
+
+
+def test_pathless_skill_mark_does_not_claim_a_materialization(tmp_path, monkeypatch):
+    m = _bootstrap(tmp_path, monkeypatch, skill="true")
+    notify, conn = m["notify"], m["db"].get_db()
+    assert notify.run_notify_pass(force=True) == "seed"
+    _ev(conn, "skill_materialized", target="T1", summary="(no path recorded)")
+    assert notify.run_notify_pass(force=True) == "ok fired=0"
 
 
 # ── disabled ────────────────────────────────────────────────────────────────

{threadkeeper-0.17.2 → threadkeeper-0.17.3}/threadkeeper/agent_status.py

@@ -878,17 +878,47 @@ def _extract_useful_result(task_id: str) -> str:
     return ""
 
 
-def _recent_results(conn, now: int, limit: int = 10) -> list[dict[str, Any]]:
+def _recent_materializations(conn, now: int, limit: int) -> list[dict[str, Any]]:
+    """Name actual writes, including foreground writes without a child task."""
     from . import config
-    # Positive materialization notifications (#257). These are captured skills /
-    # lessons surfaced as useful loop output; the app posts a banner only when
-    # notifications are enabled (NOTIFY_POLL_S master gate) and a positive toggle
-    # is on, but the menu always lists them (`notify` flag).
+    from .notify import _fmt_skill, _fmt_lesson
+
     enabled = float(getattr(config, "NOTIFY_POLL_S", 0) or 0) > 0
-    positive_notify = enabled and bool(
-        getattr(config, "NOTIFY_SKILL_MATERIALIZED", False)
-        or getattr(config, "NOTIFY_LESSON", False)
-    )
+    rows = conn.execute(
+        "SELECT id, kind, target, summary, created_at FROM events "
+        "WHERE kind IN ('skill_create', 'skill_materialized', 'lesson_append') "
+        "AND created_at>=? ORDER BY created_at DESC, id DESC LIMIT ?",
+        (now - _RESULT_WINDOW_S, int(limit)),
+    ).fetchall()
+    results = []
+    for row in rows:
+        skill = row["kind"] != "lesson_append"
+        title, summary = (_fmt_skill if skill else _fmt_lesson)(dict(row))
+        if not summary:
+            continue
+        age_s = max(0, now - row["created_at"])
+        results.append({
+            "id": f"materialization:{row['id']}",
+            "task_id": "",
+            "role": "skill" if skill else "lesson",
+            "loop_id": "",
+            "loop_name": "Skill" if skill else "Lesson",
+            "title": title,
+            "summary": summary,
+            "ended_at": row["created_at"],
+            "age_s": age_s,
+            "age": fmt_age(age_s),
+            "notify": enabled and bool(
+                config.NOTIFY_SKILL_MATERIALIZED if skill else config.NOTIFY_LESSON
+            ),
+        })
+    return results
+
+
+def _recent_results(conn, now: int, limit: int = 10) -> list[dict[str, Any]]:
+    # Event-backed materializations carry names and per-category toggles.
+    # Generic completion reports remain in history without duplicate banners.
+    materializations = _recent_materializations(conn, now, limit)
     role_loop = _role_to_loop()
     rows = conn.execute(
         "SELECT id, prompt, ended_at, return_code FROM tasks "
@@ -919,11 +949,12 @@ def _recent_results(conn, now: int, limit: int = 10) -> list[dict[str, Any]]:
             "ended_at": ended_at,
             "age_s": age_s,
             "age": fmt_age(age_s),
-            "notify": positive_notify,
+            "notify": False,
         })
         if len(results) >= limit:
             break
-    return results
+    return sorted(materializations + results, key=lambda r: r["ended_at"],
+                  reverse=True)[:limit]
 
 
 def _recent_failures(conn, now: int, limit: int = 10) -> list[dict[str, Any]]:

{threadkeeper-0.17.2 → threadkeeper-0.17.3}/threadkeeper/notify.py

@@ -27,6 +27,8 @@ from __future__ import annotations
 
 import logging
 import os
+from pathlib import Path
+import re
 import sqlite3
 import subprocess
 import threading
@@ -349,11 +351,43 @@ def _fmt_child(c: dict) -> tuple[str, str]:
 
 
 def _fmt_skill(s: dict) -> tuple[str, str]:
-    return ("Thread-keeper: skill materialized", (s["summary"] or s["target"])[:200])
+    path = (s.get("summary") or "").strip()
+    name = s.get("target", "") if s.get("kind") == "skill_create" else ""
+    if path and path != "(no path recorded)":
+        md = Path(path).expanduser()
+        if md.name == "SKILL.md":
+            name = md.parent.name
+        else:
+            name = md.name
+            md = md / "SKILL.md"
+        try:
+            # A title is near the top. Never load an entire skill (or follow
+            # paths mentioned in its body) just to render a notification.
+            body = ""
+            if md.is_file():
+                with md.open(encoding="utf-8") as stream:
+                    body = stream.read(8192)
+            if body.startswith("---\n"):
+                body = body.split("\n---", 1)[-1]
+            heading = re.search(r"^#\s+(.+?)(?:\s+#+)?\s*$", body, re.MULTILINE)
+            if heading:
+                name = heading.group(1)
+        except (OSError, ValueError):
+            pass
+    return ("Thread-keeper: skill materialized", _artifact_name(name))
+
+
+def _artifact_name(name: str) -> str:
+    """One readable name, without slug separators or Markdown decoration."""
+    name = " ".join((name or "").replace("`", "").split())
+    if " " not in name:
+        name = re.sub(r"[-_]+", " ", name)
+        name = name[:1].upper() + name[1:]
+    return name[:200]
 
 
 def _fmt_lesson(l: dict) -> tuple[str, str]:
-    return ("Thread-keeper: lesson added", f"{l['target']} ({l['summary']})"[:200])
+    return ("Thread-keeper: lesson added", _artifact_name(l["target"]))
 
 
 # ── pass + daemon lifecycle ─────────────────────────────────────────────────
@@ -401,8 +435,10 @@ def run_notify_pass(force: bool = False, *, scheduled: bool = False) -> str:
                 _dispatch(*_fmt_child(c))
                 fired += 1
         for s in skills:
-            _dispatch(*_fmt_skill(s))
-            fired += 1
+            title, body = _fmt_skill(s)
+            if body:  # A pathless mark only silences a nudge; no named artifact.
+                _dispatch(title, body)
+                fired += 1
         for l in lessons:
             _dispatch(*_fmt_lesson(l))
             fired += 1

{threadkeeper-0.17.2 → threadkeeper-0.17.3}/threadkeeper.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: threadkeeper
-Version: 0.17.2
+Version: 0.17.3
 Summary: Multi-agent shared brain across Claude Code/Desktop, Codex, Antigravity CLI, Copilot, and VS Code. Cross-session memory, self-improving skill loops, inter-agent signaling — one local MCP server.
 Author: thread-keeper contributors
 License: MIT
@@ -1058,7 +1058,10 @@ Three detection sources per tick:
    from an exhausted subscription; the real outcome only lands in
    `tasks.return_code`. The reason is read from the child's log tail.
 3. **Materialization** — `skill_materialized` / `skill_create` (skill) and
-   `lesson_append` (lesson).
+   `lesson_append` (lesson). Each notification contains one readable artifact
+   name: the skill's first heading (falling back to its directory name), or
+   the lesson name with slug separators replaced by spaces. Paths, provenance,
+   and operation metadata stay out of the notification text.
 
 A per-loop cooldown collapses a lapsed-subscription storm into one actionable
 alert; the first run seeds its cursor to the current position, so historical
@@ -1089,12 +1092,16 @@ will register the app in **System Settings ▸ Notifications** and show banners;
 banners are titled **Thread-Keeper** (`CFBundleDisplayName`). The first launch
 after an update shows a one-time permission prompt.
 
-`agent_status` feeds the app two lists — `recent_results` (positive: captured
-skills/lessons) and `recent_failures` (the two failure sources above) — each item
-tagged with a `notify` flag computed from the toggles below. The app **lists**
+`agent_status` feeds the app two lists — `recent_results` (named skill/lesson
+write events plus completed-task history) and `recent_failures` (the two failure
+sources above) — each item tagged with a `notify` flag computed from the toggles
+below. The app **lists**
 every item in its menu but only **posts a banner** for flagged ones, so turning a
-category off silences the banner without hiding the history. Enabling a toggle
-never replays backlog.
+category off silences the banner without hiding the history. Each materialization
+uses its own skill or lesson toggle; generic task reports are history-only.
+Foreground writes appear too, without waiting for a background child to finish.
+A pathless skill mark only silences its reminder and has no materialization
+banner. Enabling a toggle never replays backlog.
 
 **Settings in the app.** The menu-bar app's **Settings ▸ Notifications** tab
 edits these same `THREADKEEPER_NOTIFY_*` keys visually — switches for the