threadkeeper 0.4.0__py3-none-any.whl

threadkeeper/tools/correlation.py

@@ -0,0 +1,116 @@
+"""Task↔signals correlation MCP tools.
+
+Extracted from server.py. Lets a session manually attach a signal to a
+spawned task (when auto-tagging at emit-time missed it) and replay a
+spawned task as a chronological thread of signals plus relevant notes.
+"""
+
+import sqlite3
+import time
+
+from .._mcp import mcp
+from ..db import get_db
+from ..helpers import fmt_age, q
+from ..identity import _ensure_session
+
+
+@mcp.tool()
+def tag_signal(signal_id: int, task_id: str) -> str:
+    """Manually attach a signal to a task. Useful when retroactively building
+    a task-thread (auto-tagging happens at signal-emit time when the cid
+    matches a known spawned_cid)."""
+    conn = get_db()
+    _ensure_session(conn)
+    if not conn.execute(
+        "SELECT 1 FROM signals WHERE id=?", (int(signal_id),)
+    ).fetchone():
+        return f"ERR signal_not_found={signal_id}"
+    if not conn.execute(
+        "SELECT 1 FROM tasks WHERE id=?", (task_id.strip(),)
+    ).fetchone():
+        return f"ERR task_not_found={task_id}"
+    conn.execute(
+        "UPDATE signals SET task_id=? WHERE id=?",
+        (task_id.strip(), int(signal_id)),
+    )
+    conn.commit()
+    return f"ok signal={signal_id} → task={task_id}"
+
+
+@mcp.tool()
+def task_thread(task_id: str, include_notes: bool = True,
+                k: int = 50) -> str:
+    """Replay a spawned task as a chronological thread: every signal tagged
+    with the task_id (or to/from the task's spawned_cid), plus optionally
+    notes added during the task window."""
+    conn = get_db()
+    t = conn.execute(
+        "SELECT pid, parent_cid, spawned_cid, prompt, started_at, ended_at "
+        "FROM tasks WHERE id=?", (task_id.strip(),)
+    ).fetchone()
+    if not t:
+        return f"ERR task_not_found={task_id}"
+    end_t = t["ended_at"] or int(time.time())
+    start_t = t["started_at"]
+    spawned = t["spawned_cid"]
+    parent = t["parent_cid"]
+    # signals: explicitly tagged OR (to/from spawned_cid within window)
+    query = """
+        SELECT id, from_cid, to_cid, kind, content, created_at
+        FROM signals
+        WHERE (task_id = ?)
+           OR (created_at BETWEEN ? AND ?
+               AND ((from_cid = ? OR to_cid = ?)
+                    OR (from_cid = ? AND to_cid = ?)
+                    OR (from_cid = ? AND to_cid = ?)))
+        ORDER BY created_at ASC LIMIT ?
+    """
+    sigs = conn.execute(
+        query,
+        (task_id.strip(), start_t - 5, end_t + 60,
+         spawned or "_none_", spawned or "_none_",
+         spawned or "_none_", parent or "_none_",
+         parent or "_none_", spawned or "_none_",
+         max(1, int(k))),
+    ).fetchall()
+    notes_rows = []
+    if include_notes and spawned:
+        notes_rows = conn.execute(
+            "SELECT id, thread_id, kind, content, created_at "
+            "FROM notes WHERE session_id LIKE ? AND created_at BETWEEN ? AND ? "
+            "ORDER BY created_at ASC",
+            (f"%", start_t - 5, end_t + 60),
+        ).fetchall()
+        # narrow notes to ones actually authored by spawned (cid not session_id)
+        # session_id in notes is mcp-internal; we don't have direct cid match.
+        # Best heuristic: include notes whose content references the task or
+        # whose thread last_touched within window.
+        notes_rows = [
+            n for n in notes_rows
+            if (task_id.strip() in (n["content"] or "")
+                or n["thread_id"] in {None, "Tcd1"})
+        ][:10]
+    lines = [
+        f"task={task_id} parent={(parent or '-')[:8]} child={(spawned or '-')[:8]} "
+        f"started={fmt_age(int(time.time()) - start_t)}_ago "
+        f"{'ended' if t['ended_at'] else 'open'}"
+    ]
+    if not sigs and not notes_rows:
+        lines.append("  (no signals or notes in window)")
+        return "\n".join(lines)
+    for s in sigs:
+        ago = fmt_age(int(time.time()) - s["created_at"])
+        snip = (s["content"] or "")[:140].replace("\n", " ")
+        scope = "*" if s["to_cid"] is None else "→" + (s["to_cid"][:8])
+        lines.append(
+            f"  sig#{s['id']} {scope} from={s['from_cid'][:8]} "
+            f"+{s['kind']} {ago}_ago {q(snip)}"
+        )
+    for n in notes_rows:
+        ago = fmt_age(int(time.time()) - n["created_at"])
+        snip = (n["content"] or "")[:140].replace("\n", " ")
+        lines.append(
+            f"  note#{n['id']} thread={n['thread_id'] or '-'} "
+            f"+{n['kind']} {ago}_ago {q(snip)}"
+        )
+    return "\n".join(lines)

threadkeeper/tools/curator.py

@@ -0,0 +1,121 @@
+"""MCP tools for the Curator (lessons + skills library audit).
+
+The age-based archival pass `curator_run` lives in tools.skills (it
+mutates skill_usage state). These tools are about the *LLM-driven*
+audit pass:
+
+  curator_review(force=False, dry_run=False)
+    Trigger one curator pass NOW. Spawns a slim child with the inventory
+    of every lesson + skill, child writes a REPORT.md with KEEP / PATCH
+    / CONSOLIDATE / PRUNE recommendations.
+
+  curator_review_status()
+    Diagnostic: env config, last cursor, last 5 passes, latest REPORT
+    path.
+"""
+
+from __future__ import annotations
+
+import time
+
+from .._mcp import mcp
+from ..db import get_db
+from ..identity import _ensure_session
+from ..curator import (
+    CURATOR_PROMPT,
+    _collect_inventory,
+    _last_curator_ts,
+    run_curator_pass,
+)
+from ..config import (
+    CURATOR_INTERVAL_S,
+    CURATOR_MIN_LESSONS,
+    CURATOR_REPORTS_DIR,
+    CURATOR_DESTRUCTIVE,
+)
+
+
+@mcp.tool()
+def curator_review(force: bool = False, dry_run: bool = False) -> str:
+    """Fire one curator pass.
+
+    `force=True` runs even when CURATOR_INTERVAL_S=0 (daemon disabled).
+    Use for one-shot triage or testing the prompt.
+
+    `dry_run=True` short-circuits before the spawn — returns the
+    inventory that WOULD be passed plus n_lessons/n_skills. No spawn,
+    no cursor advance. Use to inspect what the curator child would see
+    before paying for the spawn.
+    """
+    conn = get_db()
+    _ensure_session(conn)
+    if dry_run:
+        inventory, n_lessons, n_skills = _collect_inventory(conn)
+        below = n_lessons < CURATOR_MIN_LESSONS
+        head = inventory[:2000]
+        suffix = "…(truncated for display)" if len(inventory) > 2000 else ""
+        return (
+            f"dry_run: lessons={n_lessons} skills={n_skills} "
+            f"min_lessons={CURATOR_MIN_LESSONS} "
+            f"would_spawn={'no (below_threshold)' if below else 'yes'}\n\n"
+            f"--- prompt preview ---\n"
+            f"{CURATOR_PROMPT[:400]}…\n\n"
+            f"--- inventory head ---\n{head}{suffix}"
+        )
+    return run_curator_pass(force=force)
+
+
+@mcp.tool()
+def curator_review_status() -> str:
+    """Show curator configuration + last 5 passes + latest REPORT path.
+
+    Sanity-check for whether the daemon is alive, advancing the cursor,
+    and producing REPORTs the user can read."""
+    conn = get_db()
+    _ensure_session(conn)
+    floor = _last_curator_ts(conn)
+    now = int(time.time())
+    age_s = (now - floor) if floor else None
+    mode = "destructive" if CURATOR_DESTRUCTIVE else "advisory"
+    lines = [
+        f"interval_s={CURATOR_INTERVAL_S:.0f} "
+        f"min_lessons={CURATOR_MIN_LESSONS} "
+        f"mode={mode} "
+        f"reports_dir={CURATOR_REPORTS_DIR}",
+        f"cursor_ts={floor} (age={age_s}s)" if floor
+        else "cursor_ts=0 (no prior pass)",
+        "",
+        "recent passes (newest first):",
+    ]
+    try:
+        rows = conn.execute(
+            "SELECT created_at, summary FROM events "
+            "WHERE kind='curator_pass' "
+            "ORDER BY id DESC LIMIT 5"
+        ).fetchall()
+    except Exception:
+        rows = []
+    if not rows:
+        lines.append("  (none)")
+    else:
+        for r in rows:
+            ts = r["created_at"]
+            age = now - int(ts) if ts else 0
+            snip = (r["summary"] or "")[:120]
+            lines.append(f"  {age}s_ago  {snip}")
+
+    # Latest REPORT.md the curator wrote, if any.
+    try:
+        reports = sorted(
+            CURATOR_REPORTS_DIR.glob("REPORT-*.md"),
+            key=lambda p: p.stat().st_mtime,
+            reverse=True,
+        )
+    except FileNotFoundError:
+        reports = []
+    lines.append("")
+    if reports:
+        lines.append(f"latest_report={reports[0]}")
+    else:
+        lines.append("latest_report=(none yet)")
+    return "\n".join(lines)

threadkeeper/tools/dialectic.py

@@ -0,0 +1,359 @@
+"""Dialectic user model — discrete claims about the user backed by
+evidence that accumulates over time. Inspired by Honcho's Theory of Mind.
+
+Confidence emerges from evidence rather than being asserted. We use a
+smoothed ratio so that magnitude matters (3 supports < 5 supports), not
+just sign:
+
+  ratio = (support_count - contradict_count) / (support_count + contradict_count + 3)
+
+    < -0.2  → 'disputed'  (more contradictions than supports by margin)
+    < 0.2   → 'low'
+    < 0.6   → 'medium'
+    else    → 'high'
+
+A claim with no evidence stays 'low' regardless of age. The smoothing
+constant (3) means a single piece of evidence does not jump to 'high':
+3 supports lands at medium (3/6=0.5), 5 supports at high (5/8=0.625).
+Heavy contradiction can still drag a claim back: 1 support + 3 contradicts
+→ -2/7 → disputed.
+
+Tools:
+  dialectic_claim       — register a new claim with optional initial evidence
+  dialectic_evidence    — attach evidence (support/contradict) to existing claim
+  dialectic_review      — list claims by confidence/domain/state
+  dialectic_synthesis   — terse 'who is this user' rendering for brief()
+  dialectic_supersede   — retire claim A in favor of claim B (claim_B refines A)
+
+Confidence is recomputed on every evidence add. domain is free-text but a
+small enumeration is recommended:
+  'style','workflow','values','context','skills','other'.
+"""
+from __future__ import annotations
+
+import sqlite3
+import time
+from typing import Optional
+
+from .._mcp import mcp
+from ..db import get_db
+from ..helpers import fmt_age, q, gen_dialectic_id
+from ..identity import _ensure_session, _detect_self_cid, _emit
+
+
+VALID_KINDS = ("support", "contradict")
+VALID_CONFIDENCE = ("low", "medium", "high", "disputed")
+VALID_STATE = ("active", "retired", "superseded")
+SUGGESTED_DOMAINS = (
+    "style", "workflow", "values", "context", "skills", "other",
+)
+SMOOTHING = 3  # see module docstring for rationale
+
+
+def _recompute_confidence(conn: sqlite3.Connection, claim_id: str) -> str:
+    """Recalculate confidence from current support/contradict counts and
+    persist. Returns the new label."""
+    row = conn.execute(
+        "SELECT support_count, contradict_count FROM user_dialectic WHERE id=?",
+        (claim_id,),
+    ).fetchone()
+    if not row:
+        return "low"
+    s, c = row["support_count"], row["contradict_count"]
+    total = s + c
+    if total == 0:
+        new_conf = "low"
+    else:
+        ratio = (s - c) / (total + SMOOTHING)
+        if ratio < -0.2:
+            new_conf = "disputed"
+        elif ratio < 0.2:
+            new_conf = "low"
+        elif ratio < 0.6:
+            new_conf = "medium"
+        else:
+            new_conf = "high"
+    conn.execute(
+        "UPDATE user_dialectic SET confidence=? WHERE id=?",
+        (new_conf, claim_id),
+    )
+    return new_conf
+
+
+def _insert_evidence(conn: sqlite3.Connection, claim_id: str, kind: str,
+                     quote: str, source: str, weight: float,
+                     cid: Optional[str], now_t: int) -> int:
+    """Write evidence row and bump the claim's counter. Caller commits."""
+    cur = conn.execute(
+        "INSERT INTO dialectic_evidence (claim_id, kind, source, quote, "
+        "weight, created_by_cid, created_at) VALUES (?,?,?,?,?,?,?)",
+        (claim_id, kind, source or None, quote or None, float(weight),
+         cid, now_t),
+    )
+    col = "support_count" if kind == "support" else "contradict_count"
+    conn.execute(
+        f"UPDATE user_dialectic SET {col}={col}+1, last_evidence_at=? "
+        "WHERE id=?",
+        (now_t, claim_id),
+    )
+    return cur.lastrowid
+
+
+@mcp.tool()
+def dialectic_claim(claim: str, domain: str = "", evidence: str = "",
+                    evidence_kind: str = "support") -> str:
+    """Register a new claim about the user. Optionally seed with first
+    piece of evidence — pass the supporting (or contradicting) quote in
+    `evidence` and set `evidence_kind` to 'support' (default) or
+    'contradict'.
+
+    `domain` is free-text; recommended values:
+      'style','workflow','values','context','skills','other'.
+
+    Returns: 'ok id=<UCxxx> conf=<level>'."""
+    claim = claim.strip()
+    if not claim:
+        return "ERR empty_claim"
+    if len(claim) > 1000:
+        return "ERR claim_too_long max=1000"
+    dom = domain.strip() or None
+    if dom and len(dom) > 64:
+        return "ERR domain_too_long max=64"
+    if evidence_kind not in VALID_KINDS:
+        return f"ERR bad_kind={evidence_kind} valid={'/'.join(VALID_KINDS)}"
+    conn = get_db()
+    _ensure_session(conn)
+    cid = _detect_self_cid()
+    cid_short = cid
+    cid_db = cid
+    pid = gen_dialectic_id(conn)
+    now_t = int(time.time())
+    conn.execute(
+        "INSERT INTO user_dialectic (id, claim, domain, created_by_cid, "
+        "created_at) VALUES (?,?,?,?,?)",
+        (pid, claim, dom, cid_db, now_t),
+    )
+    seed_quote = evidence.strip()
+    if seed_quote:
+        _insert_evidence(conn, pid, evidence_kind, seed_quote,
+                         "manual", 1.0, cid_short, now_t)
+    new_conf = _recompute_confidence(conn, pid)
+    _emit(conn, "dialectic_claim", target=pid, summary=claim[:140])
+    conn.commit()
+    return f"ok id={pid} conf={new_conf}"
+
+
+@mcp.tool()
+def dialectic_evidence(claim_id: str, kind: str = "support",
+                       quote: str = "", source: str = "",
+                       weight: float = 1.0) -> str:
+    """Attach evidence to a claim. `kind`: 'support' | 'contradict'.
+
+    `source` is a freeform pointer like 'thread:T7f3', 'verbatim:42',
+    'dialog:<uuid>', or 'manual'. `weight` ∈ [0,1] (default 1.0) is
+    captured for future reweighting; counts increment by 1 regardless.
+
+    Bumps support_count or contradict_count and recomputes confidence."""
+    claim_id = claim_id.strip()
+    if kind not in VALID_KINDS:
+        return f"ERR bad_kind={kind} valid={'/'.join(VALID_KINDS)}"
+    try:
+        w = float(weight)
+    except (TypeError, ValueError):
+        return f"ERR bad_weight={weight}"
+    if w < 0.0 or w > 1.0:
+        return f"ERR weight_out_of_range value={w} valid=0..1"
+    conn = get_db()
+    _ensure_session(conn)
+    row = conn.execute(
+        "SELECT state FROM user_dialectic WHERE id=?", (claim_id,)
+    ).fetchone()
+    if not row:
+        return f"ERR claim_not_found={claim_id}"
+    if row["state"] != "active":
+        return f"ERR claim_not_active state={row['state']} id={claim_id}"
+    cid = _detect_self_cid()
+    now_t = int(time.time())
+    eid = _insert_evidence(conn, claim_id, kind, quote.strip(),
+                           source.strip(), w, cid, now_t)
+    new_conf = _recompute_confidence(conn, claim_id)
+    _emit(conn, f"dialectic_evidence:{kind}", target=claim_id,
+          summary=(quote or "")[:140])
+    conn.commit()
+    return f"ok evidence_id={eid} claim={claim_id} conf={new_conf}"
+
+
+@mcp.tool()
+def dialectic_review(min_confidence: str = "low",
+                     domain: str = "",
+                     k: int = 20) -> str:
+    """List active claims filtered by confidence floor and optional
+    domain. Retired/superseded claims are omitted.
+
+    `min_confidence`: one of 'low','medium','high','disputed'. Note that
+    'disputed' is treated as its own bucket (not ordered against the
+    others) — passing `min_confidence='disputed'` returns only disputed.
+
+    Format: '<id> [conf] domain=<d> support=N contradict=N <claim>'."""
+    rank = {"low": 0, "medium": 1, "high": 2}
+    if min_confidence not in VALID_CONFIDENCE:
+        return f"ERR bad_confidence={min_confidence}"
+    try:
+        klim = max(1, int(k))
+    except (TypeError, ValueError):
+        return f"ERR bad_k={k}"
+    conn = get_db()
+    sql = (
+        "SELECT id, claim, domain, support_count, contradict_count, "
+        "confidence, last_evidence_at, created_at FROM user_dialectic "
+        "WHERE state='active'"
+    )
+    params: list = []
+    dom_filter = domain.strip()
+    if dom_filter:
+        sql += " AND domain=?"
+        params.append(dom_filter)
+    sql += " ORDER BY last_evidence_at DESC, created_at DESC"
+    rows = conn.execute(sql, tuple(params)).fetchall()
+    out: list[str] = []
+    for r in rows:
+        conf = r["confidence"]
+        if min_confidence == "disputed":
+            if conf != "disputed":
+                continue
+        else:
+            if conf == "disputed":
+                # disputed is not above low/medium/high in normal ranks —
+                # surface it only when the caller explicitly asked.
+                continue
+            if rank.get(conf, 0) < rank[min_confidence]:
+                continue
+        dom_str = r["domain"] or "-"
+        out.append(
+            f"{r['id']} [{conf}] domain={dom_str} "
+            f"support={r['support_count']} contradict={r['contradict_count']} "
+            f"{r['claim']}"
+        )
+        if len(out) >= klim:
+            break
+    if not out:
+        return (
+            f"no_claims (min_confidence={min_confidence}"
+            + (f" domain={dom_filter}" if dom_filter else "")
+            + ")"
+        )
+    return "\n".join([f"claims n={len(out)}"] + out)
+
+
+@mcp.tool()
+def dialectic_synthesis(domain: str = "") -> str:
+    """Terse rendering of accumulated beliefs about the user, grouped by
+    domain. Used as brief() input. Excludes low/disputed claims and
+    non-active states. Returns at most 12 lines.
+
+    If `domain` is provided, restricts to that domain (no group headers
+    in that case)."""
+    conn = get_db()
+    sql = (
+        "SELECT id, claim, domain, confidence, support_count, "
+        "contradict_count FROM user_dialectic "
+        "WHERE state='active' AND confidence IN ('medium','high')"
+    )
+    params: list = []
+    dom_filter = domain.strip()
+    if dom_filter:
+        sql += " AND domain=?"
+        params.append(dom_filter)
+    # high before medium; within each, more evidence first
+    sql += (
+        " ORDER BY "
+        "  CASE confidence WHEN 'high' THEN 0 ELSE 1 END, "
+        "  (support_count - contradict_count) DESC, "
+        "  domain ASC"
+    )
+    rows = conn.execute(sql, tuple(params)).fetchall()
+    if not rows:
+        return "no_synthesis"
+    # Group by domain, render with at most 12 total output lines (including
+    # group headers when no single-domain filter is active).
+    lines: list[str] = []
+    if dom_filter:
+        for r in rows:
+            if len(lines) >= 12:
+                break
+            tag = "★" if r["confidence"] == "high" else "·"
+            lines.append(f"  {tag} {r['claim']}")
+    else:
+        grouped: dict[str, list[sqlite3.Row]] = {}
+        order: list[str] = []
+        for r in rows:
+            key = r["domain"] or "other"
+            if key not in grouped:
+                grouped[key] = []
+                order.append(key)
+            grouped[key].append(r)
+        for dom in order:
+            if len(lines) >= 12:
+                break
+            lines.append(f"[{dom}]")
+            for r in grouped[dom]:
+                if len(lines) >= 12:
+                    break
+                tag = "★" if r["confidence"] == "high" else "·"
+                lines.append(f"  {tag} {r['claim']}")
+    return "\n".join(lines)
+
+
+@mcp.tool()
+def dialectic_supersede(old_claim_id: str, new_claim: str,
+                        domain: str = "", quote: str = "") -> str:
+    """Retire `old_claim_id` and register `new_claim` that refines or
+    replaces it. The old claim moves to state='superseded' with
+    superseded_by=<new_id>; its evidence is preserved (not deleted).
+
+    If `quote` is provided, it seeds the new claim with one supporting
+    piece of evidence sourced as 'supersede:<old_id>'.
+
+    If `domain` is empty, the new claim inherits the old claim's domain.
+
+    Returns: 'ok new=<UCxxx> old=<UCxxx> conf=<level>'."""
+    old_id = old_claim_id.strip()
+    new_claim = new_claim.strip()
+    if not new_claim:
+        return "ERR empty_new_claim"
+    if len(new_claim) > 1000:
+        return "ERR new_claim_too_long max=1000"
+    conn = get_db()
+    _ensure_session(conn)
+    old = conn.execute(
+        "SELECT id, domain, state FROM user_dialectic WHERE id=?", (old_id,)
+    ).fetchone()
+    if not old:
+        return f"ERR old_claim_not_found={old_id}"
+    if old["state"] != "active":
+        return f"ERR old_claim_not_active state={old['state']} id={old_id}"
+    dom = domain.strip() or old["domain"] or None
+    if dom and len(dom) > 64:
+        return "ERR domain_too_long max=64"
+    cid = _detect_self_cid()
+    pid = gen_dialectic_id(conn)
+    now_t = int(time.time())
+    conn.execute(
+        "INSERT INTO user_dialectic (id, claim, domain, created_by_cid, "
+        "created_at) VALUES (?,?,?,?,?)",
+        (pid, new_claim, dom, cid, now_t),
+    )
+    seed_quote = quote.strip()
+    if seed_quote:
+        _insert_evidence(conn, pid, "support", seed_quote,
+                         f"supersede:{old_id}", 1.0, cid, now_t)
+    new_conf = _recompute_confidence(conn, pid)
+    conn.execute(
+        "UPDATE user_dialectic SET state='superseded', superseded_by=? "
+        "WHERE id=?",
+        (pid, old_id),
+    )
+    _emit(conn, "dialectic_supersede", target=pid,
+          summary=f"{old_id}→{pid} {new_claim[:100]}")
+    conn.commit()
+    return f"ok new={pid} old={old_id} conf={new_conf}"