sessionwiki 2.0.0__py3-none-any.whl

sessionwiki/synth/agent_delegate.py

@@ -0,0 +1,327 @@
+"""Agent-delegate synthesizer (#316).
+
+This backend implements :class:`BaseSynthesizer` but **never calls any
+HTTP API**.  Instead it writes the rendered prompt to a scratch file
+under ``.llmwiki-pending-prompts/`` and returns a placeholder body.
+The accompanying slash-command wrapper (``/wiki-sync``,
+``/wiki-ingest``) is expected to read those pending prompts on the
+next agent turn, synthesize the actual content inside the agent's
+existing Claude Code / Codex CLI session (via the ``Skill`` tool or
+inline generation), and write the final page back.
+
+Why this exists
+---------------
+
+Mode A (``anthropic`` backend, issue #315) uses the user's API key
+and counts against their token budget.  Some users either don't have
+an API key or would rather piggyback on their existing Claude Code
+subscription — in that case Mode B (this module) defers the actual
+generation to the agent that's already running, at zero incremental
+cost.
+
+Contract with the agent
+-----------------------
+
+1. On :meth:`synthesize_source_page` the backend:
+
+   * Allocates a UUID.
+   * Writes ``<repo>/.llmwiki-pending-prompts/<uuid>.md`` with the
+     full rendered prompt (body + meta).
+   * Returns a placeholder body whose first line is the sentinel
+     ``<!-- sessionwiki-pending: <uuid> -->``.
+
+2. The caller writes the page to ``wiki/sources/.../<slug>.md`` as
+   usual — the sentinel gives the slash-command layer a machine-
+   readable hook to find which pages are still pending.
+
+3. The slash command reads the pending prompt inside the agent's
+   session, produces a synthesized body, and calls
+   :func:`complete_pending` to rewrite the source page in place.
+
+The backend itself never calls the agent — that loop lives outside
+this module.  This file is pure file-I/O + sentinel handling.
+
+Design goals
+------------
+
+* **No network.** The test suite can assert via ``socket`` that no
+  HTTP call ever happens.
+* **No secrets.** Works when ``ANTHROPIC_API_KEY`` is unset.
+* **Idempotent.** Re-running ``synthesize`` on the same slug
+  overwrites the pending prompt instead of accumulating orphans.
+* **Graceful outside an agent.** ``is_available()`` returns ``False``
+  (with a helpful hint via :attr:`unavailable_reason`) when no agent
+  runtime is detected, so the pipeline can fall back to the dummy
+  backend instead of silently producing placeholders.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Optional
+
+from sessionwiki import REPO_ROOT
+from sessionwiki.synth.base import BaseSynthesizer
+
+
+# ─── paths ───────────────────────────────────────────────────────────
+
+PENDING_DIR_NAME = ".llmwiki-pending-prompts"
+
+
+def pending_dir(override: Optional[Path] = None) -> Path:
+    """Return the pending-prompts directory (created on demand).
+
+    If ``override`` is given, it's used **as-is** (tests pass a
+    ``tmp_path``).  Otherwise the standard location is
+    ``REPO_ROOT/.llmwiki-pending-prompts``.
+    """
+    d = override if override is not None else REPO_ROOT / PENDING_DIR_NAME
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+# ─── sentinel ────────────────────────────────────────────────────────
+
+# Emitted as the first line of the placeholder body so downstream
+# tooling can find + replace pending pages cheaply.
+_SENTINEL_RE = re.compile(
+    r"^\s*<!--\s*sessionwiki-pending:\s*(?P<uuid>[0-9a-f-]{36})\s*-->\s*$",
+    re.IGNORECASE | re.MULTILINE,
+)
+
+
+def sentinel_for(uid: str) -> str:
+    return f"<!-- sessionwiki-pending: {uid} -->"
+
+
+def is_pending(body: str) -> bool:
+    """Return ``True`` iff ``body`` contains the pending sentinel."""
+    return bool(_SENTINEL_RE.search(body or ""))
+
+
+def extract_pending_uuid(body: str) -> Optional[str]:
+    """Pull the ``<uuid>`` out of the sentinel, or ``None``."""
+    m = _SENTINEL_RE.search(body or "")
+    return m.group("uuid") if m else None
+
+
+# ─── runtime detection ───────────────────────────────────────────────
+
+
+def _agent_runtime_detected() -> bool:
+    """Heuristic: are we running inside an agent session?
+
+    We trust (in order):
+
+    * ``LLMWIKI_AGENT_MODE`` set to a truthy value — explicit opt-in,
+      wins over everything else.
+    * ``CLAUDE_CODE`` or ``CLAUDECODE`` — set by Claude Code sessions.
+    * ``CODEX_CLI`` — set by Codex CLI.
+    * ``CURSOR_AGENT`` — set by Cursor's chat pane.
+
+    If none of the above are set, we consider the backend unavailable
+    and return ``False`` so the pipeline falls back to dummy.
+    """
+    explicit = os.environ.get("LLMWIKI_AGENT_MODE", "").strip().lower()
+    if explicit in {"1", "true", "yes", "on"}:
+        return True
+    if explicit in {"0", "false", "no", "off"}:
+        return False
+    for env_var in ("CLAUDE_CODE", "CLAUDECODE", "CODEX_CLI", "CURSOR_AGENT"):
+        if os.environ.get(env_var):
+            return True
+    return False
+
+
+# ─── the backend ─────────────────────────────────────────────────────
+
+
+@dataclass
+class AgentDelegateSynthesizer(BaseSynthesizer):
+    """Defer synthesis to the agent — no HTTP calls.
+
+    The backend's job is to write the rendered prompt to disk and
+    return a placeholder page.  The slash-command layer picks up the
+    pending prompt on the next agent turn.
+    """
+
+    pending_root: Optional[Path] = None
+
+    # Public so tests can assert on the message surface.
+    unavailable_reason: str = (
+        "Agent runtime not detected. Run /wiki-sync from inside Claude "
+        "Code or Codex CLI, or export LLMWIKI_AGENT_MODE=1 to force."
+    )
+
+    # ─── BaseSynthesizer contract ────────────────────────────────────
+
+    def is_available(self) -> bool:
+        return _agent_runtime_detected()
+
+    def synthesize_source_page(
+        self,
+        raw_body: str,
+        meta: dict[str, Any],
+        prompt_template: str,
+    ) -> str:
+        """Defer synthesis: write the prompt + return a placeholder.
+
+        The placeholder's first line is a machine-readable sentinel
+        (``<!-- sessionwiki-pending: <uuid> -->``).  Idempotency: if a
+        pending prompt already exists for this slug, we reuse its
+        uuid instead of orphaning it.
+        """
+        slug = str(meta.get("slug", "unknown")).strip() or "unknown"
+        project = str(meta.get("project", "unknown")).strip() or "unknown"
+        date = str(meta.get("date", "unknown")).strip() or "unknown"
+
+        # Reuse the uuid for this slug if a pending prompt already exists.
+        pd = pending_dir(self.pending_root)
+        existing = _find_existing_uuid(pd, slug)
+        uid = existing or str(uuid.uuid4())
+
+        prompt_text = (
+            prompt_template
+            .replace("{body}", raw_body[:8000] if raw_body else "")
+            .replace(
+                "{meta}",
+                "\n".join(f"{k}: {v}" for k, v in (meta or {}).items()),
+            )
+        )
+
+        # Write the prompt with a small header so a human can hand-process.
+        out_path = pd / f"{uid}.md"
+        out_path.write_text(
+            "\n".join([
+                f"<!-- pending-slug: {slug} -->",
+                f"<!-- pending-project: {project} -->",
+                f"<!-- pending-date: {date} -->",
+                "",
+                prompt_text,
+            ]),
+            encoding="utf-8",
+        )
+
+        # Return a placeholder the pipeline stores on disk.  The
+        # sentinel MUST be on its own line so ``extract_pending_uuid``
+        # finds it.
+        return (
+            f"{sentinel_for(uid)}\n"
+            f"\n"
+            f"## Summary\n"
+            f"\n"
+            f"*Pending agent synthesis — uuid `{uid}`.  Prompt at "
+            f"`{PENDING_DIR_NAME}/{uid}.md`.*\n"
+            f"\n"
+            f"The slash-command layer will rewrite this page on the next "
+            f"`/wiki-sync` turn.\n"
+        )
+
+
+# ─── completion helpers ──────────────────────────────────────────────
+
+
+def _find_existing_uuid(pending_root: Path, slug: str) -> Optional[str]:
+    """Scan ``pending_root`` for an existing pending prompt tagged with
+    ``slug``.  Returns the uuid or ``None``.
+    """
+    if not pending_root.exists():
+        return None
+    needle = f"<!-- pending-slug: {slug} -->"
+    for p in pending_root.glob("*.md"):
+        try:
+            text = p.read_text(encoding="utf-8", errors="ignore")
+        except OSError:
+            continue
+        if needle in text:
+            return p.stem
+    return None
+
+
+def complete_pending(
+    uid: str,
+    synthesized_body: str,
+    target_page: Path,
+    pending_root: Optional[Path] = None,
+) -> None:
+    """Replace the placeholder body in ``target_page`` with the
+    synthesized body + delete the pending prompt file.
+
+    Preserves the frontmatter + appends any lines the agent wrote
+    after the sentinel (so hand edits survive).  Raises
+    ``FileNotFoundError`` if the target page doesn't exist;
+    ``ValueError`` if the target page doesn't carry the pending
+    sentinel; :class:`OSError` for filesystem errors.
+    """
+    if not target_page.exists():
+        raise FileNotFoundError(f"target page not found: {target_page}")
+
+    text = target_page.read_text(encoding="utf-8")
+    found_uid = extract_pending_uuid(text)
+    if found_uid is None:
+        raise ValueError(
+            f"page has no pending sentinel: {target_page}"
+        )
+    if found_uid != uid:
+        raise ValueError(
+            f"uuid mismatch: page carries {found_uid}, caller passed {uid}"
+        )
+
+    # Split frontmatter (``---\n...\n---\n``) from body.
+    if text.startswith("---\n"):
+        end = text.find("\n---\n", 4)
+        if end > 0:
+            frontmatter = text[: end + len("\n---\n")]
+        else:
+            frontmatter = ""
+    else:
+        frontmatter = ""
+
+    rest = text[len(frontmatter):] if frontmatter else text
+    # Strip the sentinel + placeholder body; keep whatever the body
+    # writer appended after ``\n`` (usually nothing).
+    _head, _sep, _tail = rest.partition(sentinel_for(uid))
+    # Replace with the agent's synthesized body.
+    new_body = synthesized_body.lstrip("\n")
+    target_page.write_text(frontmatter + new_body, encoding="utf-8")
+
+    # Delete the pending prompt file (best-effort — not an error if
+    # it's already gone).
+    pd = pending_root or pending_dir()
+    prompt_file = pd / f"{uid}.md"
+    if prompt_file.exists():
+        try:
+            prompt_file.unlink()
+        except OSError:
+            pass
+
+
+def list_pending(pending_root: Optional[Path] = None) -> list[dict[str, str]]:
+    """Enumerate every pending prompt.  Returns a list of dicts with
+    keys ``uuid``, ``slug``, ``project``, ``date``, ``path``.
+    """
+    pd = pending_root or pending_dir()
+    if not pd.exists():
+        return []
+    out: list[dict[str, str]] = []
+    for p in sorted(pd.glob("*.md")):
+        try:
+            text = p.read_text(encoding="utf-8", errors="ignore")
+        except OSError:
+            continue
+        slug_m = re.search(r"^<!-- pending-slug:\s*(.*?)\s*-->", text, re.MULTILINE)
+        project_m = re.search(r"^<!-- pending-project:\s*(.*?)\s*-->", text, re.MULTILINE)
+        date_m = re.search(r"^<!-- pending-date:\s*(.*?)\s*-->", text, re.MULTILINE)
+        out.append({
+            "uuid": p.stem,
+            "slug": slug_m.group(1) if slug_m else "",
+            "project": project_m.group(1) if project_m else "",
+            "date": date_m.group(1) if date_m else "",
+            "path": str(p),
+        })
+    return out

sessionwiki/synth/base.py

@@ -0,0 +1,125 @@
+"""Synthesizer backends — ABC + built-in implementations (v0.5 · #36).
+
+The `BaseSynthesizer` defines the contract: given a raw session markdown
+body + its frontmatter, produce a wiki source-page body (the part under
+the frontmatter). The concrete backend handles the actual LLM call.
+
+Built-in backends:
+- `DummySynthesizer` — returns a canned response. Used for testing and
+  for the `--dry-run` path so users can preview what would be generated.
+- (Future) `OllamaSynthesizer` — calls a local Ollama instance (#35)
+- (Future) `ClaudeAPISynthesizer` — calls the Anthropic API
+"""
+
+from __future__ import annotations
+
+import re
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Any
+
+
+class BaseSynthesizer(ABC):
+    """Interface for LLM-backed wiki-page synthesizers."""
+
+    @abstractmethod
+    def synthesize_source_page(
+        self,
+        raw_body: str,
+        meta: dict[str, Any],
+        prompt_template: str,
+    ) -> str:
+        """Given a raw session body + frontmatter, return a wiki
+        source-page body (markdown). The caller handles frontmatter
+        generation and file writing — the backend only generates the
+        prose content (Summary, Key Claims, Key Quotes, Connections).
+
+        `prompt_template` is the contents of `prompts/source_page.md`
+        with `{body}` and `{meta}` placeholders.
+        """
+        ...
+
+    @abstractmethod
+    def is_available(self) -> bool:
+        """Return True if the backend is ready to use (e.g. the API
+        key is set, or the Ollama server is running)."""
+        ...
+
+    @property
+    def name(self) -> str:
+        return self.__class__.__name__
+
+
+class DummySynthesizer(BaseSynthesizer):
+    """Test/preview backend — returns a canned wiki page without
+    calling any LLM. Useful for `--dry-run` and unit tests.
+
+    G-12 (#298): the dummy output used to copy every ``[[wikilink]]``
+    mention straight out of the raw body into ``## Connections``.  That
+    fabricated 371 dangling links on the compiled demo site because
+    those targets almost never existed as wiki pages.  The dummy now
+    emits only a single **real** connection — the project entity page,
+    which the ingest workflow guarantees exists — and surfaces raw
+    mentions as plain text in ``## Raw Mentions`` so the information
+    isn't lost but ``check-links`` doesn't cry wolf.
+    """
+
+    def _title_case_project(self, project: str) -> str:
+        """``ai-newsletter`` → ``AiNewsletter`` (matches entity filenames)."""
+        return "".join(part.capitalize() for part in re.split(r"[-_\s]+", project) if part)
+
+    def synthesize_source_page(
+        self,
+        raw_body: str,
+        meta: dict[str, Any],
+        prompt_template: str,
+    ) -> str:
+        slug = meta.get("slug", "unknown")
+        project = meta.get("project", "unknown")
+        date = meta.get("date", "unknown")
+
+        # Extract a naive summary from the first 500 chars
+        first_para = raw_body.strip().split("\n\n")[0][:500] if raw_body else ""
+
+        # Plain-text mentions — kept for human readers, but NOT emitted as
+        # [[wikilinks]] so check-links stays clean on auto-synthesized pages.
+        mentions = sorted(set(re.findall(r"\[\[([^\]]+)\]\]", raw_body)))
+        raw_mentions_block = (
+            "\n".join(f"- {m}" for m in mentions[:10])
+            if mentions
+            else "*(no mentions detected)*"
+        )
+
+        project_entity = self._title_case_project(project) if project and project != "unknown" else ""
+        if project_entity:
+            connections_block = f"- [[{project_entity}]] — parent project"
+        else:
+            connections_block = "*(connections auto-extracted by a real synthesizer will appear here)*"
+
+        return f"""## Summary
+
+Auto-synthesized from session `{slug}` on {date} (project: {project}).
+
+{first_para}
+
+## Key Claims
+
+- Session covered project `{project}`
+- Model: {meta.get('model', 'unknown')}
+- {meta.get('user_messages', '?')} user messages, {meta.get('tool_calls', '?')} tool calls
+
+## Key Quotes
+
+> (Auto-synthesis — replace with actual quotes from the session)
+
+## Connections
+
+{connections_block}
+
+## Raw Mentions
+
+{raw_mentions_block}
+"""
+
+    def is_available(self) -> bool:
+        return True  # Always available — no external deps

sessionwiki/synth/cli_helpers.py

@@ -0,0 +1,98 @@
+"""CLI helpers for ``sessionwiki synthesize`` extracted from cli.py
+(#691 / #arch-h8).
+
+These two helpers (`list_pending`, `complete`) wrap
+``sessionwiki.synth.agent_delegate`` for the ``--list-pending`` and
+``--complete <uuid>`` command-line subactions. They're synth-domain
+logic with file I/O + stdin handling, not argparse glue, so they
+move out of ``cli.py``. ``cli.py`` re-exports under the original
+underscored names for back-compat.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from sessionwiki import REPO_ROOT
+
+
+def list_pending() -> int:
+    """Print the pending-prompts table for ``--list-pending``.
+
+    Two-column layout: uuid │ slug · project · date. Exit 0 even when
+    empty — the slash-command layer treats "nothing pending" as a
+    success signal.
+    """
+    from sessionwiki.synth.agent_delegate import list_pending as _list_pending
+
+    rows = _list_pending()
+    if not rows:
+        print("No pending prompts.")
+        return 0
+    # Max-width uuid column for alignment.
+    uuid_w = max(len(r["uuid"]) for r in rows)
+    print(f"{'UUID':<{uuid_w}}  SLUG · PROJECT · DATE")
+    print(f"{'-' * uuid_w}  " + "-" * 40)
+    for r in rows:
+        meta = " · ".join(
+            part for part in (r["slug"], r["project"], r["date"]) if part
+        )
+        print(f"{r['uuid']:<{uuid_w}}  {meta}")
+    print(f"\n{len(rows)} pending prompt(s).")
+    return 0
+
+
+def complete(args: argparse.Namespace) -> int:
+    """Rewrite a placeholder wiki page with the agent's synthesis.
+
+    Reads the synthesized body from ``args.body`` (file) or stdin,
+    calls :func:`sessionwiki.synth.agent_delegate.complete_pending` to
+    replace the sentinel + prompt-file pair with the real content.
+
+    Exit codes:
+
+    * ``0`` — success
+    * ``1`` — missing --page, uuid mismatch, missing sentinel, or I/O
+      error
+    """
+    from sessionwiki.synth.agent_delegate import complete_pending
+
+    if not args.page:
+        print("error: --complete requires --page <path>", file=sys.stderr)
+        return 1
+
+    page_path = Path(args.page)
+    if not page_path.is_absolute():
+        page_path = REPO_ROOT / page_path
+
+    if args.body:
+        body_path = Path(args.body)
+        if not body_path.is_absolute():
+            body_path = REPO_ROOT / body_path
+        try:
+            body = body_path.read_text(encoding="utf-8")
+        except OSError as e:
+            print(f"error: reading --body {body_path}: {e}", file=sys.stderr)
+            return 1
+    else:
+        body = sys.stdin.read()
+        if not body:
+            print(
+                "error: --complete expects a body on stdin or via --body",
+                file=sys.stderr,
+            )
+            return 1
+
+    try:
+        complete_pending(args.complete, body, page_path)
+    except FileNotFoundError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+    except ValueError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+
+    print(f"completed: {page_path}")
+    return 0

sessionwiki/synth/estimate.py

@@ -0,0 +1,146 @@
+"""Synthesize cost-estimate report — pulled out of cli.py (#arch-h8 / #611).
+
+Pre-#611 ``synthesize_estimate_report`` lived inside ``cli.py``. The
+function is non-trivial business logic (G-07 / #293 cost-model walk)
+that belongs next to the rest of the synth pipeline.
+
+The function is re-exported from ``sessionwiki.cli`` so the existing
+``from sessionwiki.cli import synthesize_estimate_report`` import path keeps
+working for any test or caller that reached for it.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from sessionwiki import REPO_ROOT
+
+
+def synthesize_estimate_report(
+    *,
+    raw_sessions: Optional[list[tuple[Any, dict, str]]] = None,
+    state_keys: Optional[set[str]] = None,
+    prefix_tokens: Optional[int] = None,
+    output_tokens_per_call: int = 1000,
+    model: Optional[str] = None,
+) -> dict:
+    """Compute the incremental vs full-force cost report (G-07 · #293).
+
+    Returns a plain dict so the CLI can render it AND tests can inspect
+    the numbers without parsing stdout. Keys:
+
+    * ``corpus`` — total raw sessions discovered under ``raw/sessions/``
+    * ``synthesized`` — count already synthesized (from state file)
+    * ``new`` — ``corpus - synthesized``
+    * ``incremental_usd`` — dollars to synthesize the ``new`` bucket
+    * ``full_force_usd`` — dollars to re-synthesize the **whole** corpus
+      with ``--force`` (one cache write + N-1 cache hits)
+    * ``prefix_tokens`` — tokens in the stable CLAUDE.md + index.md +
+      overview.md prefix
+    * ``model`` — model id used for pricing
+    * ``warnings`` — list of human-readable warnings (e.g. prefix too
+      small to be cached)
+
+    Any of the args can be injected for tests; the default reads from
+    disk and is what the CLI invokes.
+    """
+    from sessionwiki.cache import (
+        DEFAULT_MODEL,
+        estimate_cost,
+        estimate_tokens,
+        warn_prefix_too_small,
+    )
+    from sessionwiki.synth.pipeline import RAW_SESSIONS as _RAW
+    from sessionwiki.synth.pipeline import _discover_raw_sessions, _load_state
+
+    chosen_model = model or DEFAULT_MODEL
+    warnings: list[str] = []
+
+    if prefix_tokens is None:
+        prefix_parts: list[str] = []
+        for rel in ("CLAUDE.md", "wiki/index.md", "wiki/overview.md"):
+            p = REPO_ROOT / rel
+            if p.is_file():
+                prefix_parts.append(p.read_text(encoding="utf-8"))
+        prefix_tokens = estimate_tokens("\n".join(prefix_parts))
+    prefix_warning = warn_prefix_too_small(prefix_tokens)
+    if prefix_warning:
+        warnings.append(prefix_warning)
+
+    if raw_sessions is None:
+        raw_sessions = _discover_raw_sessions()
+    if state_keys is None:
+        state_keys = set(_load_state().keys())
+
+    corpus = len(raw_sessions)
+
+    # The real synth state stores rel-paths under ``raw/sessions/``
+    # (e.g. ``proj/2026-04-09-slug.md``). Match against those first;
+    # fall back to bare filename + suffix-endswith for tests that
+    # inject simpler keys. A session counts as "synthesized" if any
+    # of those three keys already appears in state_keys.
+    # #py-m10 (#596): single-pass walk. The previous version walked
+    # raw_sessions twice — once to bucket new vs synthesised + collect
+    # body strings, once via a list comprehension to materialise the
+    # full-force body list — and then ran estimate_tokens(body) twice
+    # on each new session inside _bucket_usd. On a 5k-corpus that's
+    # 10k token-estimate calls + 2 full body materialisations in RAM.
+    # The pass below computes per-session tokens once, accumulates
+    # both bucket totals incrementally, and never holds more than one
+    # body string at a time.
+    synthed = 0
+    new = 0
+    incremental_usd = 0.0
+    full_force_usd = 0.0
+    incremental_first = True
+    full_force_first = True
+
+    def _add_to_bucket(fresh_tokens: int, first: bool) -> tuple[float, bool]:
+        """Return (cost, was_first?). Cost-of-this-call uses cache_hit=
+        not first, mirroring the old _bucket_usd semantics."""
+        est = estimate_cost(
+            cached_tokens=prefix_tokens,
+            fresh_tokens=fresh_tokens,
+            output_tokens=output_tokens_per_call,
+            model=chosen_model,
+            cache_hit=not first,
+        )
+        return est.usd, False  # second-and-later calls hit the cache
+
+    for p, _meta, body in raw_sessions:
+        keys_to_try: set[str] = set()
+        name = getattr(p, "name", str(p))
+        keys_to_try.add(name)
+        if hasattr(p, "relative_to"):
+            try:
+                keys_to_try.add(str(p.relative_to(_RAW)))
+            except (ValueError, AttributeError):
+                pass
+        keys_to_try.add(str(p))
+        matched = bool(keys_to_try & state_keys) or any(
+            isinstance(k, str) and k.endswith(name) for k in state_keys
+        )
+        body_tokens = estimate_tokens(body)
+        # Full-force bucket: every session contributes regardless of state.
+        ff_cost, full_force_first = _add_to_bucket(body_tokens, full_force_first)
+        full_force_usd += ff_cost
+        # Incremental bucket: only un-synthesised sessions contribute.
+        if matched:
+            synthed += 1
+        else:
+            new += 1
+            inc_cost, incremental_first = _add_to_bucket(
+                body_tokens, incremental_first
+            )
+            incremental_usd += inc_cost
+
+    return {
+        "corpus": corpus,
+        "synthesized": synthed,
+        "new": new,
+        "incremental_usd": incremental_usd,
+        "full_force_usd": full_force_usd,
+        "prefix_tokens": prefix_tokens,
+        "model": chosen_model,
+        "warnings": warnings,
+    }