prompt_layers.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_chat/core/prompt_layers.py
 
"""
Prompt-layer classification inventory.
 
Purpose
-------
Phase C5 records the authoritative classification of prompt and
request layers that affect prefix-cache stability. The runtime already
separates the immutable system prefix from variable context; this module
turns that separation into a typed inventory that tests and docs can
hold stable.
 
Plan 157 adds the session-anchors block (sandbox root + cwd + git branch)
and an in-process ``.git/HEAD`` parser that handles linked-worktree
``.git``-FILE indirection — no subprocess, no git invocation.
 
Responsibilities
----------------
- :class:`PromptLayer` describes one prompt/request layer, where it is
  assembled, and whether it is immutable or variable.
- :data:`PROMPT_LAYERS` is the canonical C5 inventory.
- :func:`prompt_layer_inventory` returns the immutable inventory tuple.
- :func:`layers_by_classification` filters the inventory for tests and
  diagnostics.
- :func:`session_anchors_block` renders the session self-location block
  (plan 157) — sandbox root, process cwd, and git branch.
- :func:`_git_branch` is the in-process ``.git/HEAD`` parser that
  handles normal repos, linked worktrees, and detached HEAD.
 
Diagnostics
-----------
Domain: OC_CHAT.MAIN
Levels:
    L2 - lifecycle events
    L3 - semantic details
    L4 - deep tracing
 
Contracts
---------
- Layer names are stable public identifiers for documentation and tests.
- Classifications are deliberately binary: ``immutable`` means the layer
  belongs in the cache-stable prefix; ``variable`` means it must remain
  outside that prefix or be treated as per-turn/per-session data.
- The inventory is descriptive. It must not mutate session messages.
- ``_git_branch`` never invokes subprocess or git; it reads ``.git/HEAD``
  (and the linked-worktree indirection file) via in-process file I/O.
 
Dependencies
------------
- oc_diagnostics (_dbg)
- oc_chat.tools.filesystem (lazy; _sandbox_root_info for the sandbox-root and source-label pair)
"""
from __future__ import annotations
 
from dataclasses import dataclass
from pathlib import Path
from typing import Literal
 
from oc_diagnostics import _dbg
 
 
PromptLayerClassification = Literal["immutable", "variable"]
 
 
@dataclass(frozen=True)
class PromptLayer:
    """One classified prompt or request layer."""
 
    name: str
    classification: PromptLayerClassification
    role_or_scope: str
    owner: str
    source: str
    cache_policy: str
    notes: str
 
 
PROMPT_LAYERS: tuple[PromptLayer, ...] = (
    PromptLayer(
        name="base_system_prompt",
        classification="immutable",
        role_or_scope="messages[0].role == system",
        owner="oc_chat.core.policy.CANONICAL_POLICY",
        source="oc_chat.core.session.ChatSession.messages",
        cache_policy="Must remain byte-stable unless the user changes /system.",
        notes="The first message anchors the cacheable prompt prefix.",
    ),
    PromptLayer(
        name="compact_tool_map",
        classification="immutable",
        role_or_scope="messages[0].content suffix",
        owner="oc_chat.core.tool_prompt.compact_tool_map",
        source="one-line-per-tool map rendered from the mode-filtered registry",
        cache_policy="Behind the compact-tool-map sentinel; changes only when the registered tools change.",
        notes="Full JSON Schema is still sent through the API tools parameter (plan 135 §3.3).",
    ),
    PromptLayer(
        name="variable_environment_context",
        classification="variable",
        role_or_scope="messages[1].content (## Environment sublayer)",
        owner="oc_chat.core.startup._inject_variable_context",
        source="date/timezone/cwd/branch/git/model/mode per the active mode env_fields",
        cache_policy="Outside messages[0]; refreshed on session load and model switch.",
        notes="Volatile facts like date + branch live here, never in messages[0] (plan 135 §3.5).",
    ),
    PromptLayer(
        name="variable_context_user_message",
        classification="variable",
        role_or_scope="messages[1].role == user",
        owner="oc_chat.core.startup._inject_variable_context",
        source="project tree plus AGENT_CONTEXT.md",
        cache_policy="Always outside messages[0]; refreshed on session load.",
        notes="Marked by VARIABLE_CONTEXT_SENTINEL.",
    ),
    PromptLayer(
        name="session_anchors",
        classification="variable",
        role_or_scope="messages[1].content suffix (after project tree)",
        owner="oc_chat.core.prompt_layers.session_anchors_block",
        source="sandbox root (_sandbox_root_info) + cwd + git branch (.git/HEAD parser)",
        cache_policy="Always outside messages[0]; refreshed on session load.",
        notes="Session self-location block for agent orientation (plan 157).",
    ),
    PromptLayer(
        name="chat_turn_user_input",
        classification="variable",
        role_or_scope="user history after the context layer",
        owner="oc_chat.core.session.ChatSession.add_user",
        source="interactive input, batch input, or API caller text",
        cache_policy="Per-turn content; never part of the immutable prefix.",
        notes="The latest user task drives the ReAct turn.",
    ),
    PromptLayer(
        name="assistant_and_tool_history",
        classification="variable",
        role_or_scope="assistant/tool history",
        owner="oc_chat.core.react_loop.run_turn",
        source="assistant replies, tool calls, and tool results",
        cache_policy="History grows during a turn and across turns.",
        notes="API shaping may truncate copies, but the session log is full.",
    ),
    PromptLayer(
        name="finalize_iteration_nudge",
        classification="variable",
        role_or_scope="API-only synthetic user message",
        owner="oc_chat.core.api_context.messages_for_api",
        source="FORCE_FINALIZE_USER_MESSAGE",
        cache_policy="Transient final-iteration nudge; never persisted.",
        notes="Injected only when inject_finalize_nudge is true.",
    ),
    PromptLayer(
        name="sub_loop_result_message",
        classification="variable",
        role_or_scope="synthetic user message",
        owner="oc_chat.core.react_loop.run_turn",
        source="[Sub-loop result] payload",
        cache_policy="Per-task result; appended after prompt prefix.",
        notes="Lets the main loop reason over delegated work output.",
    ),
    PromptLayer(
        name="provider_request_options",
        classification="variable",
        role_or_scope="request metadata outside messages",
        owner="oc_chat.core.react_loop.run_turn",
        source="model, effort, extra_body, tools, max_tokens",
        cache_policy="Provider/request dependent; not a system prompt layer.",
        notes="Tracked because it can still affect provider cache keys.",
    ),
)
 
 
def prompt_layer_inventory() -> tuple[PromptLayer, ...]:
    """Return the canonical C5 prompt-layer inventory."""
    func = "prompt_layer_inventory"
    _dbg("OC_CHAT.MAIN", func, f"layers={len(PROMPT_LAYERS)}", 4)
    return PROMPT_LAYERS
 
 
def layers_by_classification(
    classification: PromptLayerClassification,
) -> tuple[PromptLayer, ...]:
    """Return prompt layers with the requested C5 classification."""
    func = "layers_by_classification"
    layers = tuple(
        layer for layer in PROMPT_LAYERS
        if layer.classification == classification
    )
    _dbg("OC_CHAT.MAIN", func, f"{classification}={len(layers)}", 4)
    return layers
 
 
# ── Plan 157: session-anchors block ────────────────────────────────────────
 
 
def _git_branch(root: Path) -> str | None:
    """Return the current git branch name, or ``None`` when no git repo exists.
 
    In-process file reads only — no subprocess, no git invocation.
    Handles three cases:
 
    * **Normal ``.git/`` directory** — reads ``.git/HEAD`` directly.
    * **Linked-worktree ``.git`` FILE** — parses the ``gitdir: <path>``
      indirection line and reads ``HEAD`` from the real git dir.
    * **Detached HEAD** — returns the short (7-char) hash.
 
    Returns ``None`` when ``.git`` is missing or unreadable.
    """
    dot_git = root / ".git"
    if not dot_git.exists():
        return None
 
    # Linked-worktree case: .git is a FILE containing "gitdir: <path>"
    if dot_git.is_file():
        try:
            content = dot_git.read_text(encoding="utf-8").strip()
        except OSError:
            return None
        if content.startswith("gitdir: "):
            gitdir = Path(content[len("gitdir: "):].strip())
        else:
            return None
    else:
        gitdir = dot_git
 
    head = gitdir / "HEAD"
    try:
        head_content = head.read_text(encoding="utf-8").strip()
    except OSError:
        return None
    if not head_content:
        return None
 
    # Branch ref: "ref: refs/heads/<name>" → "<name>"
    if head_content.startswith("ref: refs/heads/"):
        return head_content[len("ref: refs/heads/"):]
    # Other symbolic ref (tag, etc.): "ref: refs/tags/<name>" → "refs/tags/<name>"
    if head_content.startswith("ref: "):
        return head_content[len("ref: "):]
    # Detached HEAD — bare SHA hash
    return head_content[:7]
 
 
def session_anchors_block() -> str:
    """Return the ``## Session anchors`` block for the system prompt.
 
    Composed of three lines:
 
    * **sandbox root** — effective root path and its source label,
      obtained from :func:`oc_chat.tools.filesystem._sandbox_root_info`.
    * **process cwd** — :func:`pathlib.Path.cwd`.
    * **git branch** — of the SANDBOX ROOT (the anchors' subject — in a
      worktree launch the cwd has no ``.git`` while the root does), via
      :func:`_git_branch`, rendered as the branch
      name, ``(detached: <hash>)``, or ``(no git)``.
 
    Designed to be injected into ``messages[1]`` after the project tree
    so every agent session can answer "where am I?" on the first turn.
    """
    from oc_chat.tools.filesystem import _sandbox_root_info  # noqa: PLC0415
 
    root_path, label = _sandbox_root_info()
    cwd = Path.cwd()
    branch_raw = _git_branch(root_path)
 
    if branch_raw is None:
        branch_str = "(no git)"
    elif len(branch_raw) == 7 and all(c in "0123456789abcdef" for c in branch_raw.lower()):
        branch_str = f"(detached: {branch_raw})"
    else:
        branch_str = branch_raw
 
    return (
        "## Session anchors (verify before acting)\n"
        f"- sandbox root: {root_path}  (source: {label})\n"
        f"- process cwd:  {cwd}\n"
        f"- git branch:   {branch_str}"
    )
 
 
__all__ = [
    "PROMPT_LAYERS",
    "PromptLayer",
    "PromptLayerClassification",
    "_git_branch",
    "layers_by_classification",
    "prompt_layer_inventory",
    "session_anchors_block",
]