sessionwiki 2.0.0__py3-none-any.whl

sessionwiki/__init__.py

@@ -0,0 +1,74 @@
+"""sessionwiki — LLM-powered knowledge base from Claude Code, Codex CLI, Cursor,
+Gemini CLI, and Obsidian sessions.
+
+Follows Andrej Karpathy's LLM Wiki pattern:
+    https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f
+
+Public API:
+    - sessionwiki.cli.main()              — the command-line entry point
+    - sessionwiki.convert.convert_all()   — .jsonl → markdown
+    - sessionwiki.build.build_site()      — markdown → HTML
+    - sessionwiki.serve.serve_site()      — local HTTP server
+    - sessionwiki.graph.build_and_report() — knowledge graph
+    - sessionwiki.exporters.export_all()  — AI-consumable exports
+    - sessionwiki.adapters.REGISTRY       — adapter registry
+    - sessionwiki.mcp.server.main()       — MCP server (stdio)
+"""
+
+__version__ = "2.0.0"
+__author__ = "Igor Lashkevich"  # based on llmwiki by Pratiyush (MIT)
+__license__ = "MIT"
+
+from pathlib import Path
+
+# Repo root (sessionwiki/ clone), resolved from this file's location.
+REPO_ROOT = Path(__file__).resolve().parent.parent
+PACKAGE_ROOT = Path(__file__).resolve().parent
+
+# #arch-m4 (#617): the docstring above promised a "public API" but
+# nothing was actually exported. Wire the listed symbols up as real
+# re-exports so `from sessionwiki import build_site` etc. actually works.
+# Lazy via __getattr__ so importing sessionwiki itself stays cheap (most
+# CLI invocations don't touch the public API surface, just REPO_ROOT).
+__all__ = [
+    "REPO_ROOT",
+    "PACKAGE_ROOT",
+    "__version__",
+    "main",
+    "convert_all",
+    "build_site",
+    "serve_site",
+    "build_and_report",
+    "export_all",
+    "REGISTRY",
+]
+
+
+def __getattr__(name: str):
+    """PEP 562 module-level lazy attribute access.
+
+    Lets `from sessionwiki import build_site` resolve without paying for
+    the full transitive import graph at `import sessionwiki` time.
+    """
+    if name == "main":
+        from sessionwiki.cli import main
+        return main
+    if name == "convert_all":
+        from sessionwiki.convert import convert_all
+        return convert_all
+    if name == "build_site":
+        from sessionwiki.build import build_site
+        return build_site
+    if name == "serve_site":
+        from sessionwiki.serve import serve_site
+        return serve_site
+    if name == "build_and_report":
+        from sessionwiki.graph import build_and_report
+        return build_and_report
+    if name == "export_all":
+        from sessionwiki.exporters import export_all
+        return export_all
+    if name == "REGISTRY":
+        from sessionwiki.adapters import REGISTRY
+        return REGISTRY
+    raise AttributeError(f"module 'sessionwiki' has no attribute {name!r}")

sessionwiki/__main__.py

@@ -0,0 +1,6 @@
+"""Allow `python3 -m sessionwiki` to invoke the CLI."""
+from sessionwiki.cli import main
+import sys
+
+if __name__ == "__main__":
+    sys.exit(main())

sessionwiki/_frontmatter.py

@@ -0,0 +1,118 @@
+"""Canonical frontmatter parser (#273).
+
+Historically 8 copies of this function lived scattered across the
+codebase with slightly different return shapes — dict vs
+``(dict, body)`` tuple vs ``(str | None, body)``.  Consolidating in
+one hit is risky (every caller makes specific assumptions about the
+return shape), so this module ships the canonical implementation plus
+thin wrappers that match the three existing signatures.  New call
+sites should use :func:`parse_frontmatter` or
+:func:`parse_frontmatter_dict`; legacy sites can migrate over time.
+
+Stdlib-only.  No YAML dependency — we parse the minimal subset of
+YAML we use in practice (scalars, inline lists, inline dicts, block
+lists with `- ` bullets).
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Optional
+
+# Accept LF, CRLF, or CR after each fence so Windows-authored (CRLF) and
+# old-Mac (CR) files parse identically to LF input. The optional newline
+# slots match the historical regex (`\n?(.*?)\n?---\n?`) so empty
+# frontmatter (`---\n---\nbody`) still parses. BOM is handled separately
+# in `_strip_bom()` before the regex runs. See #409, #423.
+_FRONTMATTER_RE = re.compile(
+    r"^---[ \t]*(?:\r\n|\r|\n)?(.*?)(?:\r\n|\r|\n)?---[ \t]*(?:\r\n|\r|\n)?(.*)$",
+    re.DOTALL,
+)
+
+
+def _strip_bom(text: str) -> str:
+    """Strip leading UTF-8 BOM if present (#423)."""
+    if text and text[0] == "\ufeff":
+        return text[1:]
+    return text
+
+
+def parse_frontmatter(text: str) -> tuple[dict[str, Any], str]:
+    """Return ``(meta, body)`` — the canonical shape.
+
+    Empty or malformed input returns ``({}, text)`` so callers can
+    treat every file uniformly. Handles UTF-8 BOM and CR/LF/CRLF
+    line endings transparently.
+    """
+    text = _strip_bom(text)
+    m = _FRONTMATTER_RE.match(text)
+    if not m:
+        return {}, text
+    meta_text = m.group(1)
+    body = m.group(2)
+    meta: dict[str, Any] = {}
+    for line in meta_text.splitlines():
+        mm = re.match(r"^([a-zA-Z_][\w-]*):\s*(.*)$", line)
+        if not mm:
+            continue
+        key, raw = mm.group(1), mm.group(2).strip()
+        meta[key] = _parse_scalar(raw)
+    return meta, body
+
+
+def parse_frontmatter_dict(text: str) -> dict[str, Any]:
+    """Return just the metadata dict — convenience for callers that
+    don't need the body."""
+    return parse_frontmatter(text)[0]
+
+
+def parse_frontmatter_or_none(text: str) -> tuple[Optional[str], str]:
+    """Return ``(raw_frontmatter_text | None, body)`` — legacy shape
+    used by ``sessionwiki/tags.py`` which does its own line-level parsing
+    inside the frontmatter block."""
+    text = _strip_bom(text)
+    m = _FRONTMATTER_RE.match(text)
+    if not m:
+        return None, text
+    return m.group(1), m.group(2)
+
+
+def _parse_scalar(raw: str, *, coerce_bool: bool = True) -> Any:
+    """Parse a single YAML scalar value (best-effort, no external deps).
+
+    Handles: inline lists ``[a, b, c]``, quoted strings, bools, ints.
+    Everything else comes back as the stripped string.
+
+    #py-l1 (#599): pass ``coerce_bool=False`` when recursing into list
+    items so a tag list like ``[no, yes, maybe]`` doesn't become
+    ``[False, True, "maybe"]``. Top-level scalars still coerce.
+    """
+    s = raw.strip()
+    if not s:
+        return ""
+    # Quoted string
+    if (s.startswith('"') and s.endswith('"')) or (s.startswith("'") and s.endswith("'")):
+        return s[1:-1]
+    # Inline list: [a, b, c]
+    if s.startswith("[") and s.endswith("]"):
+        body = s[1:-1].strip()
+        if not body:
+            return []
+        return [_parse_scalar(x, coerce_bool=False) for x in body.split(",")]
+    # Bool
+    low = s.lower()
+    if coerce_bool and low in {"true", "yes"}:
+        return True
+    if coerce_bool and low in {"false", "no"}:
+        return False
+    # Int
+    try:
+        return int(s)
+    except ValueError:
+        pass
+    # Float
+    try:
+        return float(s)
+    except ValueError:
+        pass
+    return s

sessionwiki/_system_pages.py

@@ -0,0 +1,44 @@
+"""Canonical list of system / nav / scaffolding pages used across
+graph.py, lint/rules.py, and (potentially) future emitters.
+
+#arch-l7 (#628 sibling): graph.py and lint/rules.py shipped two
+hand-maintained lists of "pages that are exempt from the source /
+entity / concept schema." The lists overlapped but drifted —
+graph.py had `log-archive-2026`, lint missed it; lint had
+`index.md`, graph used type-checks instead.
+
+This module owns the single source of truth. Callers can request
+either form via the helpers below.
+"""
+from __future__ import annotations
+
+# Slugs (no `.md` suffix) — the form graph.py wants because it
+# operates on graph-node ids that are already stripped of extension.
+SYSTEM_PAGE_SLUGS: frozenset[str] = frozenset({
+    "CRITICAL_FACTS",
+    "MEMORY",
+    "SOUL",
+    "hints",
+    "hot",
+    "dashboard",
+    "overview",
+    "log",
+    "log-archive-2026",
+    "index",
+})
+
+# Filenames (with `.md`) — the form lint/rules.py wants because its
+# input is page paths read off disk.
+SYSTEM_PAGE_FILES: frozenset[str] = frozenset(
+    f"{slug}.md" for slug in SYSTEM_PAGE_SLUGS
+)
+
+
+def is_system_slug(slug: str) -> bool:
+    """True if ``slug`` (no extension) is a known system / nav page."""
+    return slug in SYSTEM_PAGE_SLUGS
+
+
+def is_system_file(basename: str) -> bool:
+    """True if ``basename`` ends with ``.md`` and names a system page."""
+    return basename in SYSTEM_PAGE_FILES

sessionwiki/adapter_config.py

@@ -0,0 +1,124 @@
+"""Adapter configuration validation (v1.0 · #177).
+
+Consolidates the adapter enable/configure surface so users have a single
+place to check what opt-in adapters can be configured and which are active.
+
+Supported adapters:
+  - meeting      (file-based, source_dirs + extensions)
+  - jira         (network, server/email/api_token/jql)
+  - web_clipper  (file-based intake, watch_dir + auto_queue)
+
+The PDF adapter that used to live here was removed in the simplification
+sweep — its dispatch path in ``convert.py`` was a phantom (no concrete
+implementation; every adapter raised ``AttributeError`` on ``convert_pdf``).
+
+All disabled by default — users must set ``<adapter>.enabled: true`` in
+``sessions_config.json`` to activate.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+# ─── Schemas ───────────────────────────────────────────────────────────
+
+ADAPTER_SCHEMAS: dict[str, dict[str, Any]] = {
+    "web_clipper": {
+        "required_if_enabled": ["watch_dir"],
+        "defaults": {"extensions": [".md"], "auto_queue": True},
+        "types": {
+            "watch_dir": str,
+            "extensions": list,
+            "auto_queue": bool,
+        },
+    },
+}
+
+
+def validate_adapter_config(
+    config: dict[str, Any],
+    adapter_name: str,
+) -> list[str]:
+    """Validate a single adapter's config section. Returns list of errors.
+
+    Empty list = valid. Disabled adapters (or missing sections) are
+    always valid — the check is about the *shape* of the config when
+    enabled.
+    """
+    schema = ADAPTER_SCHEMAS.get(adapter_name)
+    if schema is None:
+        return [f"unknown adapter {adapter_name!r}"]
+
+    section = config.get(adapter_name, {})
+    if not isinstance(section, dict):
+        return [f"{adapter_name!r} config must be a JSON object"]
+
+    # If not enabled, skip further checks
+    if not section.get("enabled"):
+        return []
+
+    errors: list[str] = []
+
+    # Required fields
+    for field in schema["required_if_enabled"]:
+        if field not in section:
+            errors.append(
+                f"{adapter_name!r} is enabled but missing required field: {field!r}"
+            )
+        elif not section[field]:
+            errors.append(
+                f"{adapter_name!r} is enabled but {field!r} is empty"
+            )
+
+    # Type checks
+    for field, expected_type in schema["types"].items():
+        if field in section:
+            value = section[field]
+            if not isinstance(value, expected_type):
+                errors.append(
+                    f"{adapter_name!r} field {field!r} must be "
+                    f"{expected_type.__name__} (got {type(value).__name__})"
+                )
+
+    return errors
+
+
+def validate_all_adapters(config: dict[str, Any]) -> dict[str, list[str]]:
+    """Validate every known adapter's config section. Returns ``{name: errors}``.
+
+    Adapters with no errors map to an empty list. Use to display a full
+    status report.
+    """
+    return {
+        name: validate_adapter_config(config, name)
+        for name in ADAPTER_SCHEMAS
+    }
+
+
+def is_adapter_enabled(config: dict[str, Any], adapter_name: str) -> bool:
+    """Return True if the adapter is explicitly enabled in config."""
+    section = config.get(adapter_name, {})
+    if not isinstance(section, dict):
+        return False
+    return bool(section.get("enabled", False))
+
+
+def enabled_adapters(config: dict[str, Any]) -> list[str]:
+    """List adapter names that are enabled in config."""
+    return [name for name in ADAPTER_SCHEMAS if is_adapter_enabled(config, name)]
+
+
+def apply_defaults(
+    config: dict[str, Any],
+    adapter_name: str,
+) -> dict[str, Any]:
+    """Return the config section merged with schema defaults."""
+    schema = ADAPTER_SCHEMAS.get(adapter_name)
+    if schema is None:
+        return config.get(adapter_name, {})
+    section = dict(config.get(adapter_name, {}))
+    for key, default in schema["defaults"].items():
+        if key not in section:
+            section[key] = default
+    return section

sessionwiki/adapters/__init__.py

@@ -0,0 +1,134 @@
+"""Adapter registry.
+
+Each adapter knows how to find .jsonl session files for one coding agent and
+parse them into a stream of records. Adapters register themselves on import.
+
+    from sessionwiki.adapters import REGISTRY, discover_adapters
+    discover_adapters()
+    adapter_cls = REGISTRY["claude_code"]
+    adapter = adapter_cls(config)
+    for path in adapter.discover_sessions():
+        ...
+
+Core adapters (always loaded):
+    claude_code, codex_cli, opencode, zcode
+
+Contrib adapters (loaded on demand via --adapter flag):
+    chatgpt, copilot_chat, copilot_cli, cursor, gemini_cli, obsidian
+"""
+
+from __future__ import annotations
+
+from sessionwiki.adapters.base import BaseAdapter
+
+REGISTRY: dict[str, type[BaseAdapter]] = {}
+
+# #v1378-review: aliases tracked separately so REGISTRY stays
+# canonical-only. `cmd_adapters` and any other consumer that walks
+# every adapter exactly once can iterate REGISTRY directly without
+# de-duping. Lookup-by-alias still works via `resolve_adapter_name`.
+REGISTRY_ALIASES: dict[str, str] = {}
+
+# Contrib adapters that can be loaded on demand.
+CONTRIB_ADAPTERS = {
+    "chatgpt", "copilot_chat", "copilot_cli",
+    "cursor", "gemini_cli", "obsidian",
+}
+
+
+def register(name: str, aliases: list[str] | None = None):
+    """Decorator used by adapter modules to register themselves.
+
+    ``aliases`` (#arch-l5 / #626): historical lookup-only names that
+    resolve to the same class. Used to keep kebab-case names like
+    ``copilot-chat`` working after the canonical name moves to
+    snake_case (``copilot_chat``). ``cls.name`` always reflects the
+    canonical name.
+
+    #v1378-review: aliases live in a SEPARATE ``REGISTRY_ALIASES`` map
+    so iterating ``REGISTRY`` walks each adapter exactly once. The
+    previous version inserted aliases into ``REGISTRY`` directly,
+    which made ``cmd_adapters`` print duplicate rows (one for the
+    canonical name, one for the alias) and made ``adapter_status``
+    look up the wrong config key on the alias row.
+
+    A collision guard prevents an alias from shadowing an existing
+    canonical adapter — e.g. ``register("copilot_chat",
+    aliases=["claude_code"])`` would raise ValueError, not silently
+    replace the real ``claude_code`` entry.
+    """
+    def decorator(cls):
+        REGISTRY[name] = cls
+        cls.name = name
+        for alias in aliases or ():
+            if alias in REGISTRY:
+                raise ValueError(
+                    f"adapter alias {alias!r} would shadow existing "
+                    f"canonical adapter {REGISTRY[alias].name!r}"
+                )
+            existing = REGISTRY_ALIASES.get(alias)
+            if existing is not None and existing != name:
+                raise ValueError(
+                    f"adapter alias {alias!r} already mapped to "
+                    f"{existing!r}; cannot remap to {name!r}"
+                )
+            REGISTRY_ALIASES[alias] = name
+        return cls
+    return decorator
+
+
+def resolve_adapter_name(name: str) -> str | None:
+    """Return the canonical adapter name for ``name``, or None.
+
+    ``name`` may be the canonical name (returned as-is) or a registered
+    alias (returned as the canonical it maps to). Anything else returns
+    None, letting callers raise their own user-facing error.
+    """
+    if name in REGISTRY:
+        return name
+    canonical = REGISTRY_ALIASES.get(name)
+    if canonical and canonical in REGISTRY:
+        return canonical
+    return None
+
+
+def discover_adapters() -> None:
+    """Import core adapters so they register themselves."""
+    from sessionwiki.adapters import (
+        claude_code,  # noqa: F401
+        codex_cli,  # noqa: F401
+        opencode,  # noqa: F401
+        zcode,  # noqa: F401
+    )
+
+
+def discover_contrib(names: list[str] | None = None) -> None:
+    """Import contrib adapters on demand.
+
+    Parameters
+    ----------
+    names : list[str] | None
+        Specific adapter names to load. If None, loads all contrib adapters.
+    """
+    targets = names if names else CONTRIB_ADAPTERS
+    for name in targets:
+        if name not in CONTRIB_ADAPTERS:
+            continue
+        try:
+            __import__(f"sessionwiki.adapters.contrib.{name}")
+        except ImportError as e:
+            import sys
+            print(f"  warning: contrib adapter {name!r} failed to load: {e}",
+                  file=sys.stderr)
+
+
+def discover_all() -> None:
+    """Import all adapters (core + contrib)."""
+    discover_adapters()
+    discover_contrib()
+
+
+def get_available() -> dict[str, type[BaseAdapter]]:
+    """Return only adapters whose session store exists on this machine."""
+    discover_adapters()
+    return {name: cls for name, cls in REGISTRY.items() if cls.is_available()}

sessionwiki/adapters/base.py

@@ -0,0 +1,191 @@
+"""Base class for session-store adapters.
+
+An adapter knows two things about one coding agent:
+  1. WHERE its .jsonl session transcripts live on disk
+  2. HOW to discover them (walking the directory tree)
+
+Everything else — record filtering, markdown rendering, redaction, state
+tracking — is shared in `sessionwiki.convert` and operates on the iterator this
+class returns.
+"""
+
+from __future__ import annotations
+
+import re as _re
+from pathlib import Path
+from typing import Any, Iterator
+
+# #sec-7 (#551): project slugs flow into raw/ + site/ paths. The same
+# sanitiser regex is used by build.py for project_slug rendering — keep
+# them aligned. Anything outside [A-Za-z0-9._-] gets replaced with `_`,
+# leading dots are stripped so the slug can't form a hidden directory.
+_PROJECT_SLUG_RE = _re.compile(r"[^A-Za-z0-9._-]")
+
+
+def _safe_project_slug(raw: str) -> str:
+    """Drop path traversal + non-portable characters from a project slug."""
+    s = _PROJECT_SLUG_RE.sub("_", raw)
+    s = s.lstrip(".")
+    return s or "unnamed"
+
+
+class BaseAdapter:
+    """Adapter interface.
+
+    Subclasses must set `session_store_path` (a Path or list of Paths) and
+    implement `is_available()`. The default `discover_sessions()` does a
+    recursive glob for `*.jsonl`; override only if your agent uses a different
+    extension or layout.
+    """
+
+    #: Unique adapter name (set by @register decorator).
+    name: str = "base"
+
+    #: Path or list of paths where this agent writes session transcripts.
+    #: Subclasses MUST override.
+    session_store_path: Path | list[Path] = Path("/dev/null")
+
+    #: True if this adapter wraps an **AI coding-agent session store**
+    #: (Claude Code, Codex CLI, Copilot, Cursor, Gemini, etc.).  False
+    #: for adapters over user content (Obsidian vaults, Jira tickets,
+    #: meeting transcripts, PDFs) — those are opt-in only so
+    #: ``sessionwiki sync`` never silently ingests non-session content.
+    #: See #326.
+    is_ai_session: bool = True
+
+    #: #arch-m9 (#621): canonical declaration on BaseAdapter so subclasses
+    #: don't redeclare with format drift (`["v1"]` vs `["v1.0"]` vs
+    #: `["1.x"]`). Default is ``["v1"]`` — the schema version the
+    #: built-in adapters target. Subclasses that consume a different
+    #: agent-native format override (or extend) this list.
+    SUPPORTED_SCHEMA_VERSIONS: list[str] = ["v1"]
+
+    def __init__(self, config: dict[str, Any] | None = None):
+        self.config = config or {}
+
+    # ─── classmethods used by the registry + UI ────────────────────────
+
+    # #py-l3 (#601): subclasses can override _DESCRIPTION_OVERRIDE so
+    # `python3 -OO` (which strips __doc__) doesn't degrade the adapter
+    # listing to bare class names. The default reads __doc__ where
+    # available and falls back to a stable explicit string when not.
+    _DESCRIPTION_OVERRIDE: str = ""
+
+    @classmethod
+    def description(cls) -> str:
+        """One-line description shown in `sessionwiki adapters`."""
+        if cls._DESCRIPTION_OVERRIDE:
+            return cls._DESCRIPTION_OVERRIDE
+        if cls.__doc__:
+            return cls.__doc__.split("\n")[0]
+        return cls.__name__
+
+    @classmethod
+    def is_available(cls) -> bool:
+        """True if the session store exists on this machine.
+
+        #496: previously read ``cls.session_store_path`` directly. That
+        worked for ``ClaudeCodeAdapter`` (class attribute) but returned
+        the *property descriptor object* for the 8 contrib adapters
+        which override ``session_store_path`` as a ``@property`` — so
+        every contrib adapter had to re-implement its own
+        ``is_available()`` classmethod reading ``cls.DEFAULT_ROOTS``.
+
+        Fix: instantiate a config-less temp instance and read
+        ``self.session_store_path`` through the same code path
+        ``discover_sessions()`` uses. Both class-attribute and
+        ``@property``-overriding patterns now flow through this single
+        method; the 8 duplicate contrib overrides go away.
+
+        Adapters with expensive ``__init__()`` should override this
+        method directly, but no current adapter needs to.
+        """
+        try:
+            inst = cls()
+        except Exception:
+            # Defensive: an adapter whose __init__ raises (e.g.
+            # missing imports surfaced eagerly) is "unavailable" by
+            # definition rather than crashing the whole `adapters`
+            # listing.
+            return False
+        paths = inst.session_store_path
+        if isinstance(paths, Path):
+            paths = [paths]
+        return any(Path(p).expanduser().exists() for p in paths)
+
+    # ─── discovery ─────────────────────────────────────────────────────
+
+    def discover_sessions(self) -> list[Path]:
+        """Return a sorted list of all .jsonl files under the session store."""
+        paths: list[Path] = []
+        stores = self.session_store_path
+        if isinstance(stores, Path):
+            stores = [stores]
+        for store in stores:
+            store = Path(store).expanduser()
+            if store.exists():
+                paths.extend(sorted(store.rglob("*.jsonl")))
+        return paths
+
+    # ─── per-agent helpers ─────────────────────────────────────────────
+
+    def derive_project_slug(self, jsonl_path: Path) -> str:
+        """Derive a friendly project slug from a .jsonl file path.
+
+        Default: the immediate parent directory name under the store.
+        Override for agents that use flat or encoded directory names.
+
+        #sec-7 (#551): the returned slug is used downstream as a path
+        component (`raw/sessions/<slug>-...md`, `site/projects/<slug>.html`).
+        A user whose session store contains a directory named `..` or
+        `foo/bar` could traverse out of `raw/` or smuggle a sub-path.
+        Sanitise via the same regex rule the rest of the build uses.
+        """
+        stores = self.session_store_path
+        if isinstance(stores, Path):
+            stores = [stores]
+        raw = None
+        for store in stores:
+            store = Path(store).expanduser()
+            try:
+                rel = jsonl_path.relative_to(store)
+                raw = rel.parts[0] if rel.parts else jsonl_path.parent.name
+                break
+            except ValueError:
+                continue
+        if raw is None:
+            raw = jsonl_path.parent.name
+        return _safe_project_slug(raw)
+
+    def is_subagent(self, jsonl_path: Path) -> bool:
+        """Default: no adapter has a sub-agent concept — only Claude Code does
+        (#406). Subclasses that DO have sub-agents (currently only the
+        Claude Code adapter) override this method.
+
+        Why the default returned True for any path containing the substring
+        "subagent": that was a holdover from a Claude-specific assumption
+        when the adapter abstraction was introduced. It mis-tagged every
+        session in any user project named e.g. ``subagent-runner``,
+        demoting them on the project page and excluding them from session
+        counts. Subclassing fixes the bug at the source.
+        """
+        return False
+
+    def normalize_records(self, records: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        """Normalize agent-specific JSONL records into the shared Claude-style
+        format that ``sessionwiki.convert`` expects.
+
+        The shared renderer expects records shaped as:
+        - ``{"type": "user", "message": {"role": "user", "content": "..."}}``
+        - ``{"type": "assistant", "message": {"role": "assistant", "content": [...]}}``
+
+        The default implementation is a no-op (pass-through) — Claude Code
+        sessions already use this format. Adapters for agents with a different
+        schema (e.g. Codex CLI, Copilot) override this method to translate
+        their native records into the shared shape.
+
+        Called by ``convert.py`` after ``parse_jsonl()`` and before the
+        renderer, so the normalization is transparent to the rest of the
+        pipeline.
+        """
+        return records