daimon-briefing 0.3.0__py3-none-any.whl

daimon_briefing/__init__.py

@@ -0,0 +1,25 @@
+"""Daimon dream-briefing — hermes plugin entrypoint (Slice 1, local-file, no Honcho)."""
+
+from pathlib import Path
+
+from . import hooks
+
+__version__ = "0.2.0"
+
+
+def register(ctx):
+    """Called once at hermes startup. Wires the two hooks and bundles the skill.
+
+    # VERIFIED website/docs/guides/build-a-hermes-plugin.md:
+    #   ctx.register_hook("<event>", callback)
+    #   ctx.register_skill(skill_name: str, skill_md_path: Path)
+    """
+    ctx.register_hook("on_session_end", hooks.on_session_end)
+    ctx.register_hook("pre_llm_call", hooks.pre_llm_call)
+
+    skills_dir = Path(__file__).parent.parent / "skills"
+    if skills_dir.is_dir():
+        for child in sorted(skills_dir.iterdir()):
+            skill_md = child / "SKILL.md"
+            if child.is_dir() and skill_md.exists():
+                ctx.register_skill(child.name, skill_md)

daimon_briefing/anchor.py

@@ -0,0 +1,103 @@
+"""Anchor cognitive items to code symbols and detect drift — stdlib only.
+
+A symbol is identified by (file, symbol) where symbol is `name` or `Class.method`.
+The fingerprint is a structural hash (`ast.dump` of the def node), so it is stable
+to formatting/comments/line-shift and changes only on real structural edits. No MCP,
+no LLM, no network — resolution and drift checks read the project's own source.
+
+Caveat: `ast.dump` output is stable only WITHIN a Python version. A checkpoint anchored
+under one interpreter and checked under another may report a spurious "soft" drift — it
+fails safe (toward verify-before-trusting, never a false "live"), and anchors are normally
+resolved and checked by the same interpreter.
+"""
+
+import ast
+import hashlib
+from pathlib import Path
+
+_DEF = (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)
+
+
+def _find_node(tree: ast.AST, symbol: str):
+    nodes = getattr(tree, "body", [])
+    node = None
+    for part in symbol.split("."):
+        node = next(
+            (n for n in nodes if isinstance(n, _DEF) and n.name == part), None
+        )
+        if node is None:
+            return None
+        nodes = getattr(node, "body", [])
+    return node
+
+
+def body_hash_of(source: str, symbol: str) -> str | None:
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return None
+    node = _find_node(tree, symbol)
+    if node is None:
+        return None
+    return hashlib.sha256(ast.dump(node).encode("utf-8")).hexdigest()
+
+
+def resolve(project_root, file: str, symbol: str) -> dict | None:
+    """Snapshot an anchor for (file, symbol), or None if it can't be resolved."""
+    try:
+        source = (Path(project_root) / file).read_text(encoding="utf-8")
+    except OSError:
+        return None
+    h = body_hash_of(source, symbol)
+    if h is None:
+        return None
+    return {
+        "qualified_name": f"{file}::{symbol}",
+        "file": file,
+        "symbol": symbol,
+        "body_hash": h,
+    }
+
+
+def check(anchor: dict, project_root) -> str:
+    """Classify drift: 'live' (unchanged), 'soft' (body changed), 'hard' (gone/unverifiable).
+
+    Degrades on a malformed anchor (missing/non-str file or symbol) by returning
+    'hard' — the offline check must never raise on hand-edited checkpoint data."""
+    file = anchor.get("file")
+    symbol = anchor.get("symbol")
+    if not isinstance(file, str) or not isinstance(symbol, str):
+        return "hard"
+    try:
+        source = (Path(project_root) / file).read_text(encoding="utf-8")
+    except OSError:
+        return "hard"
+    h = body_hash_of(source, symbol)
+    if h is None:
+        return "hard"
+    return "live" if h == anchor.get("body_hash") else "soft"
+
+
+def _all_items(checkpoint: dict):
+    wc = checkpoint.get("working_context") or {}
+    es = checkpoint.get("epistemic_snapshot") or {}
+    for key in ("open_questions", "recent_decisions"):
+        yield from (wc.get(key) or [])
+    for key in ("strong_beliefs", "uncertainties"):
+        yield from (es.get(key) or [])
+    active = wc.get("active_topic")
+    if isinstance(active, dict):
+        yield active
+
+
+def drifted(checkpoint: dict, project_root) -> list[dict]:
+    """Anchored items whose code has drifted (soft/hard); live ones omitted."""
+    out = []
+    for item in _all_items(checkpoint):
+        a = item.get("anchored_to") if isinstance(item, dict) else None
+        if not isinstance(a, dict):
+            continue
+        kind = check(a, project_root)
+        if kind != "live":
+            out.append({"item": item, "kind": kind, "anchor": a})
+    return out

daimon_briefing/briefing.py

@@ -0,0 +1,274 @@
+"""Checkpoint -> 'while you were away' briefing text.
+
+Default rendering is a DETERMINISTIC template over the checkpoint JSON — no LLM call.
+Rationale: injection happens on the user's critical path (latency matters), and the
+checkpoint is already the trusted extract (D-006); re-narrating via LLM reintroduces
+generation risk for zero recall gain. LLM rendering is opt-in via DAIMON_LLM_BRIEFING.
+
+Ordering is load-bearing: external-state items (the user-acted-outside-AI gap) come
+FIRST under a 'verify before trusting' marker, then open loops, then decisions, then
+beliefs, then uncertainties, then contradictions flagged. Verbatim items are marked
+distinctly from inferred ones.
+"""
+
+import re
+import time
+
+from . import config, llm, scoring
+
+_VERBATIM_MARK = "✓ verbatim"
+_INFERRED_MARK = "~ inferred"
+
+
+def _mark(item) -> str:
+    return _VERBATIM_MARK if item.get("trust") == "verbatim" else _INFERRED_MARK
+
+
+def _line(item) -> str:
+    text = item.get("text", "").strip()
+    quote = item.get("quote", "").strip()
+    base = f'- [{_mark(item)}] {text}'
+    if item.get("carried_from"):
+        # Epistemic honesty, same philosophy as trust marks: a loop carried
+        # from an older session must not read as fresh context (#33 Phase 2).
+        base += " [carried]"
+    if quote:
+        base += f'  — "{quote}"'
+    return base
+
+
+def _nonempty(item) -> bool:
+    return bool(item and isinstance(item, dict) and item.get("text", "").strip())
+
+
+def _overflow_note(dropped: int) -> str | None:
+    """Marker text when the briefing capped older decisions, or None. Single source
+    for both the plain and rich render paths (DRY + one singular/plural rule)."""
+    if dropped <= 0:
+        return None
+    plural = "s" if dropped != 1 else ""
+    return f"(+{dropped} earlier decision{plural} — full history in checkpoint)"
+
+
+def _by_weight(items, item_type, now):
+    """Sort a section by #78 effective weight, heaviest first. sorted() is stable,
+    so legacy items (no first_seen / no importance -> equal neutral weights) keep
+    their serializer order — pre-D-011 checkpoints render exactly as before."""
+    return sorted(items, key=lambda i: scoring.effective_weight(i, item_type, now),
+                  reverse=True)
+
+
+def build(checkpoint, now=None) -> dict | None:
+    """Structured briefing sections, or None if nothing is worth surfacing.
+    Deterministic — no LLM; `now` is injectable for tests. Sections order by #78
+    effective weight EXCEPT recent_decisions, which stay chronological (the
+    serializer's CHRONOLOGY contract; the tail-cap below depends on it)."""
+    if not checkpoint or not isinstance(checkpoint, dict):
+        return None
+    if now is None:
+        now = time.time()
+
+    wc = checkpoint.get("working_context") or {}
+    es = checkpoint.get("epistemic_snapshot") or {}
+
+    open_qs = _by_weight([i for i in (wc.get("open_questions") or []) if _nonempty(i)],
+                         "open_question", now)
+    decisions = [i for i in (wc.get("recent_decisions") or []) if _nonempty(i)]
+    beliefs = _by_weight([i for i in (es.get("strong_beliefs") or []) if _nonempty(i)],
+                         "strong_belief", now)
+    uncertainties = _by_weight([i for i in (es.get("uncertainties") or []) if _nonempty(i)],
+                               "uncertainty", now)
+    contradictions = [i for i in (es.get("contradictions_flagged") or []) if _nonempty(i)]
+    active = wc.get("active_topic")
+
+    if not (open_qs or decisions or beliefs or uncertainties or contradictions
+            or _nonempty(active)):
+        return None
+
+    # Cap to the most-recent N decisions (tail — recent_decisions is chronological,
+    # oldest→newest, per the serializer's CHRONOLOGY instruction). Render-time only:
+    # the checkpoint keeps every decision. 0 = unbounded.
+    n = config.max_briefing_decisions()
+    kept = decisions[-n:] if n and len(decisions) > n else decisions
+
+    return {
+        "external": [i for i in open_qs if i.get("external_state")],
+        "open_loops": [i for i in open_qs if not i.get("external_state")],
+        "decisions": kept,
+        "decisions_overflow": len(decisions) - len(kept),
+        "active_topic": active if _nonempty(active) else None,
+        "beliefs": beliefs,
+        "uncertainties": uncertainties,
+        "contradictions": contradictions,
+    }
+
+
+# ---- #79: token budget — section-preserving truncation ----
+
+# A bold-labeled section (**Problem:** / **Root Cause:** / **Fix:** ...) plus
+# its immediate continuation line — the load-bearing shape ACB's truncation
+# preserved (hierarchical_content_generator:774), without its per-label list:
+# any **Label:** counts, so user vocabularies survive too.
+_SECTION_RE = re.compile(r"\*\*[^*\n]+:\*\*[^\n]*(?:\n(?![*\s])[^\n]+)?")
+
+_TRUNCATION_MARKER = " …[truncated — full text in checkpoint]"
+
+# When a briefing is over budget, single items longer than this get
+# section-preserving truncation before anything is dropped outright.
+_ITEM_TRUNCATE_CHARS = 400
+
+
+def estimate_tokens(text: str) -> int:
+    """Honest chars//4 estimate (#79) — no tokenizer dependency, and the error
+    margin is fine for a budget whose point is order-of-magnitude control."""
+    return len(text) // 4
+
+
+def truncate_preserving_sections(text: str, max_chars: int) -> str:
+    """Cut `text` to max_chars, keeping **Label:** sections over filler: if the
+    labeled sections alone fit, they ARE the truncation; only a section-less
+    text falls back to a blind head-cut. Always appends a visible marker —
+    silent truncation reads as 'this is everything' when it isn't."""
+    if len(text) <= max_chars:
+        return text
+    parts = _SECTION_RE.findall(text)
+    if parts:
+        key = "\n".join(parts)
+        if len(key) + len(_TRUNCATION_MARKER) <= max_chars:
+            return key + _TRUNCATION_MARKER
+    return text[:max(0, max_chars - len(_TRUNCATION_MARKER))] + _TRUNCATION_MARKER
+
+
+def _trim_note(dropped: int) -> str:
+    plural = "s" if dropped != 1 else ""
+    return f"  (+{dropped} item{plural} trimmed for budget — full history in checkpoint)"
+
+
+# Budget drop order (#79): background sections go before actionable ones, and
+# within a section the LOWEST-weight items go first — beliefs/uncertainties are
+# #78-sorted heaviest-first, so their tail is the lightest; decisions are
+# chronological, so their head is the oldest. external / active_topic /
+# contradictions are never dropped: they are the skeleton.
+_DROP_ORDER = (("beliefs", "tail"), ("uncertainties", "tail"),
+               ("decisions", "head"), ("open_loops", "tail"))
+
+
+def render_plain(b: dict) -> str:
+    """The deterministic briefing text. Under the #79 budget this is
+    BYTE-IDENTICAL to the legacy render(); over it, long items truncate
+    (sections preserved) and then whole items drop, lowest value first,
+    each cut announced with a trim note."""
+    budget = config.brief_max_tokens()
+    text = _render_parts(b, {})
+    if not budget or estimate_tokens(text) <= budget:
+        return text
+
+    # Stage 1: shorten monster items in place of dropping them.
+    b = dict(b)
+    for key, _end in _DROP_ORDER:
+        b[key] = [
+            {**i, "text": truncate_preserving_sections(
+                i.get("text", ""), _ITEM_TRUNCATE_CHARS)}
+            for i in (b.get(key) or [])
+        ]
+    trimmed = {key: 0 for key, _ in _DROP_ORDER}
+    text = _render_parts(b, trimmed)
+
+    # Stage 2: drop whole items, least valuable first, until the budget holds
+    # or only the skeleton remains.
+    for key, end in _DROP_ORDER:
+        while estimate_tokens(text) > budget and b.get(key):
+            items = list(b[key])
+            items.pop(-1 if end == "tail" else 0)
+            b[key] = items
+            trimmed[key] += 1
+            text = _render_parts(b, trimmed)
+        if estimate_tokens(text) <= budget:
+            break
+    return text
+
+
+def _render_parts(b: dict, trimmed: dict) -> str:
+    parts = ["While you were away — here's where we left off."]
+
+    def _section(header: str, key: str) -> None:
+        items = b.get(key) or []
+        note = trimmed.get(key, 0)
+        if not items and not note:
+            return
+        parts.append("")
+        parts.append(header)
+        parts.extend(_line(i) for i in items)
+        if key == "decisions":
+            overflow = _overflow_note(b.get("decisions_overflow", 0))
+            if overflow:
+                parts.append(f"  {overflow}")
+        if note:
+            parts.append(_trim_note(note))
+
+    if b["external"]:
+        parts.append("")
+        parts.append("VERIFY BEFORE TRUSTING (state may have changed outside this session):")
+        parts.extend(_line(i) for i in b["external"])
+
+    _section("Open loops:", "open_loops")
+    _section("Decisions made:", "decisions")
+
+    if b["active_topic"]:
+        parts.append("")
+        parts.append(f'Active topic: {b["active_topic"].get("text", "").strip()}')
+
+    _section("Beliefs held:", "beliefs")
+    _section("Was uncertain about:", "uncertainties")
+
+    # .get(): hand-built b dicts predating #101 may lack the key (defensive,
+    # same spirit as decisions_overflow).
+    if b.get("contradictions"):
+        parts.append("")
+        parts.append("Contradictions flagged:")
+        parts.extend(_line(i) for i in b["contradictions"])
+
+    return "\n".join(parts)
+
+
+def render(checkpoint) -> str | None:
+    """Render the briefing, or None if there is nothing worth surfacing.
+    LLM rendering is opt-in (DAIMON_LLM_BRIEFING) and falls back to deterministic."""
+    b = build(checkpoint)
+    if b is None:
+        return None
+    if config.llm_briefing():
+        rendered = _render_llm(checkpoint)
+        if rendered:
+            return rendered
+    return render_plain(b)
+
+
+# Seeded from research/experiments/track-a/prompts/02-reconstruct.md, tuned for a
+# skimmable briefing rather than a two-part reconstruction.
+_RECONSTRUCT_SYS = """You are resuming a work session. Your only memory of the previous session is the cognitive checkpoint below. You do NOT have the original transcript.
+
+Write a <30-second, skimmable "while you were away / here's where we left off" briefing.
+ORDER IT: items flagged external_state FIRST under a clear "verify before trusting" heading
+(their state may have changed outside the session); then open loops; then decisions; then beliefs;
+then any contradictions_flagged (as their own "contradictions flagged" section — omit it when empty).
+Mark each item as verbatim or inferred.
+
+CRITICAL: base every claim ONLY on the checkpoint. Do NOT add plausible-sounding detail that is
+not in the checkpoint. If the checkpoint is thin, the briefing should be thin. Do not embellish."""
+
+
+def _render_llm(checkpoint) -> str | None:
+    import json
+
+    try:
+        return llm.chat(
+            [
+                {"role": "system", "content": _RECONSTRUCT_SYS},
+                {"role": "user", "content": "CHECKPOINT:\n" + json.dumps(checkpoint, indent=2)},
+            ],
+            # temperature comes from config (default 0.0 for determinism;
+            # DAIMON_LLM_TEMPERATURE overrides).
+        )
+    except Exception:
+        return None

daimon_briefing/carry.py

@@ -0,0 +1,97 @@
+"""Deterministic cross-session carry (#33 Phase 2).
+
+Multicycle run-01 (LOGBOOK 2026-07-02) proved LLM re-emission loses whole
+items even from lossless input, while exact-copy carry held 1.0 fidelity and
+zero first_seen churn. So carry is CODE: fold the previous checkpoint's
+unresolved items into the new one verbatim, expire by #78 weight, dedup by
+salient-term overlap, label with carried_from. No I/O, no LLM, no env — the
+caller injects clock and knobs (scar: a default wall-clock anywhere silently
+freezes time math under simulation)."""
+
+import copy
+
+from . import recall, scoring, store
+
+# (section, key, scoring TYPE_RULES type). Beliefs regenerate cheaply and
+# active_topic is per-session by definition — neither carries (v1).
+_CARRIED_KINDS = (
+    ("working_context", "open_questions", "open_question"),
+    ("working_context", "recent_decisions", "recent_decision"),
+    ("epistemic_snapshot", "uncertainties", "uncertainty"),
+)
+
+_MIN_SHARED = 3     # shared salient terms for same-item
+_MIN_RATIO = 0.6    # or this fraction of the shorter term list
+
+
+def _same_item(a_text: str, b_text: str) -> bool:
+    """Term-overlap identity: the serializer rewords constantly (run-01), so
+    exact text misses twins. Shared >=3 salient terms, or >=60% of the shorter
+    list, means same item. Short texts (<2 salient terms) never fuzzy-match —
+    the exact-text guard still catches identical ones."""
+    a = set(recall.salient_terms(a_text))
+    b = set(recall.salient_terms(b_text))
+    if not a or not b:
+        return False
+    shared = len(a & b)
+    return shared >= _MIN_SHARED or shared / min(len(a), len(b)) >= _MIN_RATIO
+
+
+def merge(new_cp: dict, prev_cp: dict | None, now: float,
+          floor: float = 0.05, cap: int = 8) -> dict:
+    """Fold prev_cp's carry-eligible items into a COPY of new_cp.
+
+    Native items are never dropped or reordered — carry only appends, and (on
+    a dedup hit) copies the older first_seen onto the native twin so decay age
+    survives rewording. Anachronism guard: healing an old session must not
+    swallow a newer checkpoint's state.
+
+    No-op paths (non-dict inputs, anachronism guard) return new_cp UNCHANGED,
+    not a copy — callers reassign the result immediately, so a defensive
+    deepcopy there would just be wasted work."""
+    if not isinstance(new_cp, dict) or not isinstance(prev_cp, dict):
+        return new_cp
+    new_epoch = store._created_epoch(new_cp.get("created"))
+    prev_epoch = store._created_epoch(prev_cp.get("created"))
+    if new_epoch is not None and prev_epoch is not None and new_epoch < prev_epoch:
+        return new_cp
+
+    out = copy.deepcopy(new_cp)
+    prev_sid = str(prev_cp.get("session_id") or "")
+    for section, key, item_type in _CARRIED_KINDS:
+        native = (out.get(section) or {}).get(key)
+        if not isinstance(native, list):
+            continue
+        prev_items = (prev_cp.get(section) or {}).get(key) or []
+        native_texts = {i.get("text") for i in native if isinstance(i, dict)}
+        carried = []
+        for item in prev_items:
+            if not isinstance(item, dict) or not str(item.get("text") or "").strip():
+                continue
+            text = item["text"]
+            if text in native_texts:
+                continue  # exact twin already present (idempotency)
+            twin = next((n for n in native if isinstance(n, dict)
+                         and _same_item(text, str(n.get("text") or ""))), None)
+            if twin is not None:
+                # Session re-discussed it: the new wording wins, but the item's
+                # AGE does not reset (run-01: 8-12 resets/20 cycles killed the
+                # #128 overdue boost). Keep the older birth stamp.
+                if item.get("first_seen") and not twin.get("first_seen"):
+                    twin["first_seen"] = item["first_seen"]
+                elif item.get("first_seen") and twin.get("first_seen"):
+                    old = store._created_epoch(item["first_seen"])
+                    cur = store._created_epoch(twin["first_seen"])
+                    if old is not None and (cur is None or old < cur):
+                        twin["first_seen"] = item["first_seen"]
+                continue
+            if scoring.effective_weight(item, item_type, now) < floor:
+                continue  # expired — deterministic exit (noise budget)
+            kept = copy.deepcopy(item)
+            kept.setdefault("carried_from", prev_sid)
+            carried.append(kept)
+            native_texts.add(text)  # two identical prev items must carry once
+        carried.sort(key=lambda i: scoring.effective_weight(i, item_type, now),
+                     reverse=True)
+        native.extend(carried[:cap])
+    return out