session_log.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_chat/core/session_log.py
 
"""
Session log writer — records completed ``/goal`` turns.
 
Purpose
-------
:func:`append_session_log` appends a record of a completed goal to the
workspace ``SESSION_LOG.md``: an H2 section listing scope, the session
reference, and the files the agent modified, with file bullets grouped
under a Keep-a-Changelog ``### Changed`` subsection.
 
**Why this is not the changelog (2026-07-14).** This writer previously
targeted the root ``CHANGELOG.md``. That file is now a **registry-GENERATED
view** — it is produced by ``roadmap render`` from ``roadmap/source/**`` and
is guarded by ``render --check``. Hand-writing into it corrupted a generated
artifact on every ``/goal`` turn and drifted the check. The entry format is
unchanged; only the target moved. **The changelog is the registry's; the
session log is this module's.**
 
This lives in its own module (not next to the per-turn ReAct loop) because
it runs *after* turns, not *during* them — sub-agents that don't run goals
can construct an :class:`Agent` without ever importing it.
 
Responsibilities
----------------
- :data:`SESSION_LOG_PATH` — the ``oc_chat`` subproject's ``SESSION_LOG.md``
  (resolved at import time by a BOUNDED adjacent-marker check, always absolute).
- :func:`append_session_log` — prepend a new H2 + ``### Changed`` section
  after the metadata block and refresh the ``Last Session:`` line.
- :func:`_session_log_path` — internal path resolver.
- :func:`_project_version` — best-effort live version for the fresh-create
  metadata block; never raises.
 
Diagnostics
-----------
Domain: OC_CHAT.MAIN
Levels:
    L2 — lifecycle events
    L3 — semantic details
    L4 — deep tracing
 
Contracts
---------
- **NEVER writes to ``CHANGELOG.md``** — that file is registry-generated
  (``roadmap render``) and ``render --check``-gated. A test pins this.
- Path resolution is a BOUNDED check (no upward walk): if ``pyproject.toml`` sits
  DIRECTLY BESIDE the package (``oc_chat/pyproject.toml`` — source/editable), write
  there; else (wheel, no adjacent marker) write ``~/.oc_chat/SESSION_LOG.md``. Never
  walks upward — an upward walk adopts an unrelated host project above ``site-packages``
  (review R18 SOL18-02). Always an ABSOLUTE path, never a CWD-relative name and never
  inside a foreign project.
- A goal with no recorded file changes is a no-op (no section written).
- Section shape: ``## YYYY-MM-DD:HH:MM:SS — <scope>`` header, ``**Scope:**``
  and ``**Session:**`` metadata, blank line, ``### Changed`` H3, blank line,
  ``- `path``` bullets. Session links use the directory style
  ``oc_chat/sessions/<name>/`` (trailing slash), never ``.json``.
- The metadata block (``**Version:** ...``, ``**Last Session:** ...``) is
  preserved when the file exists; the new section is inserted between the
  metadata and the rest of the body.
- Never raises out of the fresh-create path.
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
  (no ``oc_chat.core._paths`` dependency — the bounded check uses only ``__file__``.)
- oc_chat.core._version (lazy; the single live-version entry point)
- oc_chat.core.commands (lazy; Context type hint for append_session_log)
"""
from __future__ import annotations
 
import os
from datetime import datetime
from pathlib import Path
from typing import TYPE_CHECKING
 
from oc_diagnostics import _dbg
 
if TYPE_CHECKING:
    from oc_chat.core.commands import Context
 
 
_dbg("OC_CHAT.MAIN", "module", "loaded", 4)
 
 
# Project description matching pyproject.toml — used when first creating
# a fresh SESSION_LOG.md.
_PROJECT_DESCRIPTION = "Interactive Option C chat client with ReAct agentic loop"
 
 
def _project_version() -> str:
    """Return the live project version, or ``"0.0.0"`` as a last resort.
 
    Historically this read the static ``[project].version`` key from
    ``oc_chat/pyproject.toml``. Both pyprojects are now scm-``dynamic``
    (Plan 143g-code S1) — there is no static ``version`` key to read — so
    this routes through :func:`oc_chat.core._version.resolve_version`, the
    single live-version entry point (which itself falls back through dist
    metadata → the generated version file → ``"unknown"`` and never
    raises). The ``"0.0.0"`` guard remains only for the impossible case of
    the import itself failing; the fresh-create path must never raise.
    """
    func = "_project_version"
    try:
        from oc_chat.core._version import resolve_version
        return resolve_version()
    except Exception as exc:  # pragma: no cover — resolve_version never raises
        _dbg("OC_CHAT.MAIN", func, f"VALIDATION_ERROR: {type(exc).__name__}: {exc}", 3)
        return "0.0.0"
 
 
def _session_log_path() -> Path:
    """Resolve SESSION_LOG.md — always ABSOLUTE, always in a directory THIS app owns.
 
    **BOUNDED, deliberately not an upward walk (2026-07-15, three review rounds).**
    The rule is one comparison, no walking:
 
    - ``pkg_dir = Path(__file__).parent.parent`` is the ``oc_chat`` package dir.
    - **Source / editable checkout** — the subproject's own ``pyproject.toml`` sits
      *directly beside* the package (``oc_chat/pyproject.toml``). Write
      ``pkg_dir / "SESSION_LOG.md"``. Correct today AND post-migration (the moved
      subtree keeps its own ``pyproject.toml``).
    - **Wheel install** — no ``pyproject.toml`` beside the package. Write to a
      user-owned state dir (``~/.oc_chat/SESSION_LOG.md``), NEVER inside the
      installed package tree.
 
    **Why NOT ``find_package_root`` / any upward walk (R16→R17→R18).** Each prior
    fix walked upward for the nearest ``pyproject.toml`` and was wrong a new way:
    R16 — ``find_workspace_root`` escaped to the monorepo root post-move; R17 —
    the relative-path fallback rewrote an ambient CWD file; R18 (SOL18-02) — in the
    common ``<host>/.venv/Lib/site-packages/oc_chat/…`` layout an upward walk exits
    site-packages and adopts the **host project's** ``pyproject.toml``, so ``/goal``
    would rewrite the *host's* ``SESSION_LOG.md`` (verified). **An upward walk can
    never tell "the oc_chat subproject" from "an unrelated project above
    site-packages" — so it is not used.** The bounded check above cannot escape the
    package: it looks only *beside* the package, never above it.
 
    *(Ideal, tracked as follow-up: resolve from an explicit workspace root supplied
    by the active ``Context`` when one exists, rather than a module-import-time
    global — SOL18-02 rec 1. The bounded rule here closes the corruption path; the
    Context-based resolver is a larger change filed separately.)*
    """
    func = "_session_log_path"
    pkg_dir = Path(__file__).resolve().parent.parent  # .../oc_chat
    if (pkg_dir / "pyproject.toml").is_file():
        # Source/editable: the subproject's own pyproject is right here. No walk.
        return pkg_dir / "SESSION_LOG.md"
    # Wheel install: user-owned state dir, never inside the package, never a foreign project.
    _dbg("OC_CHAT.MAIN", func, "no pyproject beside package (wheel); using ~/.oc_chat", 3)
    return Path.home() / ".oc_chat" / "SESSION_LOG.md"
 
 
SESSION_LOG_PATH = _session_log_path()
 
 
def append_session_log(ctx: "Context") -> None:
    """Append a record of the completed goal to ``SESSION_LOG.md``.
 
    **NEVER touches ``CHANGELOG.md``** — that file is registry-generated
    (``roadmap render``) and ``render --check``-gated. A test pins this.
 
    Follows the formatting rules defined in
    ``oc_chat/docs/CHANGELOG-format.md`` (Rule 4 H2 timestamp, Rule 9
    directory-style session link) and adopts the Keep-a-Changelog
    ``### Changed`` H3 vocabulary used by ``oct git changelog`` so a
    file edited by both tools stays structurally consistent (Phase
    F.2c). A new section is prepended after the metadata block:
 
        ## YYYY-MM-DD:HH:MM:SS — <scope>
        **Scope:** <scope>
        **Session:** [`<name>`](oc_chat/sessions/<name>/)
 
        ### Changed
 
        - `path/one`
        - `path/two`
    """
    func = "append_session_log"
    if not ctx.goal_files_changed:
        return
 
    now = datetime.now()
    timestamp    = now.strftime("%Y-%m-%d:%H:%M:%S")
    session_name = ctx.session.name
    session_link = f"oc_chat/sessions/{session_name}/"
 
    # Build the new section. CHANGELOG-format Rule 4 puts the timestamp
    # in the H2; the Keep-a-Changelog ``### Changed`` H3 matches
    # ``oct.git.changelog._SECTION_ORDER`` so the two tools produce
    # interleavable output.
    scope_line = ctx.goal_description
    lines: list[str] = []
    lines.append(f"## {timestamp} — {scope_line}")
    lines.append(f"**Scope:** {scope_line}")
    lines.append(f"**Session:** [`{session_name}`]({session_link})")
    lines.append("")
    lines.append("### Changed")
    lines.append("")
    for f in sorted(ctx.goal_files_changed):
        lines.append(f"- `{f}`")
    lines.append("")
 
    new_section = "\n".join(lines)
 
    # Read existing changelog (or create one)
    try:
        with open(SESSION_LOG_PATH, "r", encoding="utf-8") as fh:
            existing = fh.read()
    except FileNotFoundError:
        existing = (
            f"# OC Chat — {_PROJECT_DESCRIPTION} — SESSION LOG\n\n"
            f"**Version:** [{_project_version()}] - {timestamp}**\n"
            f"**Last Session:** [`{session_name}`]({session_link})\n\n"
        )
 
    # Normalise line-endings to \n for processing
    existing_norm = existing.replace("\r\n", "\n")
    lines_existing = existing_norm.split("\n")
 
    # Find where the metadata block ends: after the Last Session line
    meta_end = 0
    for i, line in enumerate(lines_existing):
        if line.startswith("**Last Session:**"):
            meta_end = i + 1
            break
        if line.startswith("**Version:**"):
            meta_end = i + 1  # fallback if no Last Session line
 
    if meta_end == 0:
        meta_end = min(3, len(lines_existing))
 
    # Rebuild: metadata + updated Last Session + new section + rest of body
    metadata_lines = lines_existing[:meta_end]
 
    # Update the Last Session line
    new_last_session = f"**Last Session:** [`{session_name}`]({session_link})"
    updated_meta: list[str] = []
    last_session_replaced = False
    for line in metadata_lines:
        if line.startswith("**Last Session:**"):
            updated_meta.append(new_last_session)
            last_session_replaced = True
        elif line.startswith("**Version:**"):
            updated_meta.append(line)
        else:
            updated_meta.append(line)
 
    if not last_session_replaced:
        inserted = False
        final_meta: list[str] = []
        for line in updated_meta:
            final_meta.append(line)
            if not inserted and line.startswith("**Version:**"):
                final_meta.append(new_last_session)
                inserted = True
        updated_meta = final_meta
 
    # Body: everything after metadata
    body_lines = lines_existing[meta_end:]
 
    # Assemble: metadata, 2 blank lines, new section, existing body
    result_lines = updated_meta + [""] + [new_section]
    body_has_content = any(line.strip() for line in body_lines)
    if body_has_content:
        result_lines.append("")
        first_nonblank = 0
        while first_nonblank < len(body_lines) and not body_lines[first_nonblank].strip():
            first_nonblank += 1
        result_lines.extend(body_lines[first_nonblank:])
 
    result = "\n".join(result_lines)
 
    # Atomic write (SOL18-03): a plain "w" truncates in place, so a crash mid-write
    # destroys every prior entry. Write a temp file in the same dir, then os.replace
    # (atomic on both POSIX and Windows). Does not add a cross-process lock — a
    # concurrent-writer lock is a tracked follow-up; this closes the truncation path.
    SESSION_LOG_PATH.parent.mkdir(parents=True, exist_ok=True)
    tmp = SESSION_LOG_PATH.with_name(SESSION_LOG_PATH.name + f".tmp.{os.getpid()}")
    try:
        with open(tmp, "w", encoding="utf-8") as fh:
            fh.write(result)
            fh.flush()
            os.fsync(fh.fileno())
        os.replace(tmp, SESSION_LOG_PATH)
    finally:
        if tmp.exists():
            tmp.unlink()
 
    _dbg("OC_CHAT.MAIN", func,
         f"updated {len(ctx.goal_files_changed)} file(s) for goal: {scope_line!r}", 2)
    ctx.presenter.show_info(
        f"SESSION_LOG.md updated — {len(ctx.goal_files_changed)} file(s) changed."
    )