codex-coach 0.1.0

package/src/codex_coach/parser.py

@@ -0,0 +1,395 @@
+from __future__ import annotations
+
+import json
+from collections import Counter, defaultdict
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Iterable
+
+from .prompts import score_prompt
+from .redaction import stable_hash
+from .timeutil import parse_timestamp
+
+VERIFY_RE = (
+    "test",
+    "pytest",
+    "vitest",
+    "jest",
+    "playwright",
+    "lint",
+    "typecheck",
+    "tsc",
+    "mypy",
+    "ruff",
+    "build",
+    "cargo test",
+    "go test",
+    "gradle test",
+)
+ERROR_RE = (
+    "error",
+    "exception",
+    "traceback",
+    "failed",
+    "failure",
+    "timeout",
+    "panic",
+    "context_length_exceeded",
+    "usage_limit_reached",
+    "upstream_unavailable",
+)
+
+
+@dataclass
+class ScanAccumulator:
+    since: str | None = None
+    files_scanned: int = 0
+    malformed_lines: int = 0
+    sessions: dict[str, dict[str, Any]] = field(default_factory=dict)
+    projects: dict[str, Counter] = field(default_factory=lambda: defaultdict(Counter))
+    project_sessions: dict[str, set[str]] = field(default_factory=lambda: defaultdict(set))
+    totals: Counter = field(default_factory=Counter)
+    tool_counts: Counter = field(default_factory=Counter)
+    model_counts: Counter = field(default_factory=Counter)
+    effort_counts: Counter = field(default_factory=Counter)
+    source_counts: Counter = field(default_factory=Counter)
+    originator_counts: Counter = field(default_factory=Counter)
+    project_tools: dict[str, Counter] = field(default_factory=lambda: defaultdict(Counter))
+    project_efforts: dict[str, Counter] = field(default_factory=lambda: defaultdict(Counter))
+    project_verification_tools: dict[str, Counter] = field(default_factory=lambda: defaultdict(Counter))
+    project_prompt_scores: dict[str, list[int]] = field(default_factory=lambda: defaultdict(list))
+    prompt_scores: list[dict[str, Any]] = field(default_factory=list)
+    error_counts: Counter = field(default_factory=Counter)
+    verification_tools: Counter = field(default_factory=Counter)
+    compacted_sessions: set[str] = field(default_factory=set)
+    current_file_session: dict[str, str] = field(default_factory=dict)
+
+    def to_facts(self) -> dict[str, Any]:
+        projects = []
+        project_capsules = []
+        for cwd, counts in self.projects.items():
+            project_counts = counts.copy()
+            project_counts["sessions"] = len(self.project_sessions[cwd])
+            verification_tool_calls = sum(self.project_verification_tools[cwd].values())
+            projects.append(
+                {
+                    "cwd": cwd,
+                    "sessions": project_counts["sessions"],
+                    "turns": counts["turns"],
+                    "user_messages": counts["user_messages"],
+                    "tool_calls": counts["tool_calls"],
+                    "verification_tool_calls": verification_tool_calls,
+                    "compactions": counts["compactions"],
+                }
+            )
+            project_capsules.append(
+                _project_capsule(
+                    cwd,
+                    project_counts,
+                    self.project_tools[cwd],
+                    self.project_efforts[cwd],
+                    self.project_prompt_scores[cwd],
+                    verification_tool_calls,
+                )
+            )
+        projects.sort(key=lambda item: (item["user_messages"], item["tool_calls"], item["turns"]), reverse=True)
+        project_capsules.sort(key=lambda item: (item["user_messages"], item["tool_calls"], item["turns"]), reverse=True)
+
+        prompt_categories = Counter(item["category"] for item in self.prompt_scores)
+        avg_prompt = 0.0
+        if self.prompt_scores:
+            avg_prompt = round(sum(int(item["score"]) for item in self.prompt_scores) / len(self.prompt_scores), 2)
+
+        return {
+            "schema_version": 1,
+            "since": self.since,
+            "totals": {
+                "files_scanned": self.files_scanned,
+                "malformed_lines": self.malformed_lines,
+                "sessions": len(self.sessions),
+                "turns": self.totals["turns"],
+                "user_messages": self.totals["user_messages"],
+                "assistant_messages": self.totals["assistant_messages"],
+                "tool_calls": self.totals["tool_calls"],
+                "web_searches": self.totals["web_searches"],
+                "reasoning_items": self.totals["reasoning_items"],
+                "compactions": self.totals["compactions"],
+                "errors": sum(self.error_counts.values()),
+                "verification_tool_calls": sum(self.verification_tools.values()),
+            },
+            "projects": projects,
+            "project_capsules": project_capsules,
+            "models": dict(self.model_counts.most_common()),
+            "efforts": dict(self.effort_counts.most_common()),
+            "sources": dict(self.source_counts.most_common()),
+            "originators": dict(self.originator_counts.most_common()),
+            "tools": dict(self.tool_counts.most_common()),
+            "verification_tools": dict(self.verification_tools.most_common()),
+            "errors": dict(self.error_counts.most_common()),
+            "prompt_quality": {
+                "average_score": avg_prompt,
+                "categories": dict(prompt_categories),
+                "examples_needing_work": [item for item in self.prompt_scores if item["category"] == "needs_work"][:10],
+                "rewrite_examples": [item for item in self.prompt_scores if item["category"] == "needs_work"][:5],
+            },
+            "compacted_session_ids": sorted(self.compacted_sessions),
+        }
+
+
+def iter_log_paths(codex_home: Path) -> list[Path]:
+    paths: list[Path] = []
+    sessions_dir = codex_home / "sessions"
+    archived_dir = codex_home / "archived_sessions"
+    if sessions_dir.exists():
+        paths.extend(sessions_dir.glob("**/*.jsonl"))
+    if archived_dir.exists():
+        paths.extend(archived_dir.glob("*.jsonl"))
+    return sorted(path for path in paths if path.is_file())
+
+
+def scan_logs(codex_home: Path, *, since_dt=None, since_label: str | None = None) -> dict[str, Any]:
+    acc = ScanAccumulator(since=since_label)
+    for path in iter_log_paths(codex_home):
+        if since_dt is not None:
+            try:
+                if path.stat().st_mtime < since_dt.timestamp():
+                    continue
+            except OSError:
+                acc.malformed_lines += 1
+                continue
+        _scan_file(path, acc, since_dt=since_dt)
+    return acc.to_facts()
+
+
+def _scan_file(path: Path, acc: ScanAccumulator, *, since_dt) -> None:
+    acc.files_scanned += 1
+    fallback_session_id = path.stem
+    current_session_id = fallback_session_id
+    current_cwd = "<unknown>"
+    file_had_session = False
+
+    try:
+        lines = path.read_text(encoding="utf-8", errors="replace").splitlines()
+    except OSError:
+        acc.malformed_lines += 1
+        return
+
+    for line in lines:
+        if not line.strip():
+            continue
+        try:
+            event = json.loads(line)
+        except json.JSONDecodeError:
+            acc.malformed_lines += 1
+            continue
+
+        timestamp = parse_timestamp(event.get("timestamp"))
+        if since_dt is not None and timestamp is not None and timestamp < since_dt:
+            continue
+
+        event_type = event.get("type")
+        payload = event.get("payload") or {}
+        if event_type == "session_meta":
+            current_session_id, current_cwd = _handle_session(payload, acc, fallback_session_id)
+            if not file_had_session:
+                file_had_session = True
+            continue
+        if event_type == "turn_context":
+            current_cwd = _project_label(str(payload.get("cwd") or current_cwd or "<unknown>"))
+            acc.project_sessions[current_cwd].add(current_session_id)
+            _handle_turn(payload, acc, current_cwd)
+            continue
+        if event_type == "response_item":
+            _handle_response_item(payload, acc, current_cwd)
+            continue
+        if event_type == "event_msg":
+            _handle_event_msg(payload, acc)
+            continue
+        if event_type == "compacted":
+            acc.totals["compactions"] += 1
+            acc.projects[current_cwd]["compactions"] += 1
+            acc.compacted_sessions.add(current_session_id)
+
+
+def _handle_session(payload: dict[str, Any], acc: ScanAccumulator, fallback_session_id: str) -> tuple[str, str]:
+    session_id = str(payload.get("id") or fallback_session_id)
+    cwd = _project_label(str(payload.get("cwd") or "<unknown>"))
+    acc.sessions.setdefault(
+        session_id,
+        {
+            "cwd": cwd,
+            "timestamp": payload.get("timestamp"),
+            "source": payload.get("source"),
+            "originator": payload.get("originator"),
+            "cli_version": payload.get("cli_version"),
+        },
+    )
+    if payload.get("source"):
+        acc.source_counts[str(payload["source"])] += 1
+    if payload.get("originator"):
+        acc.originator_counts[str(payload["originator"])] += 1
+    acc.project_sessions[cwd].add(session_id)
+    return session_id, cwd
+
+
+def _project_label(cwd: str) -> str:
+    if not cwd or cwd == "<unknown>":
+        return "<unknown>"
+    path = Path(cwd)
+    name = path.name or "project"
+    return f"{name} [{stable_hash(cwd)}]"
+
+
+def _handle_turn(payload: dict[str, Any], acc: ScanAccumulator, cwd: str) -> None:
+    acc.totals["turns"] += 1
+    acc.projects[cwd]["turns"] += 1
+    model = payload.get("model")
+    effort = payload.get("effort")
+    if model:
+        acc.model_counts[str(model)] += 1
+    if effort:
+        acc.effort_counts[str(effort)] += 1
+        acc.project_efforts[cwd][str(effort)] += 1
+
+
+def _handle_response_item(payload: dict[str, Any], acc: ScanAccumulator, cwd: str) -> None:
+    item = payload.get("item") if isinstance(payload.get("item"), dict) else payload
+    item_type = item.get("type")
+    if item_type == "message":
+        role = item.get("role")
+        text = _content_text(item.get("content"))
+        if role == "user":
+            acc.totals["user_messages"] += 1
+            acc.projects[cwd]["user_messages"] += 1
+            score = score_prompt(text)
+            acc.prompt_scores.append(
+                {
+                    "score": score.score,
+                    "category": score.category,
+                    "reason": score.reason,
+                    "preview": score.preview,
+                    "missing": list(score.missing),
+                    "rewrite": score.rewrite,
+                    **score.stats,
+                }
+            )
+            acc.project_prompt_scores[cwd].append(score.score)
+        elif role == "assistant":
+            acc.totals["assistant_messages"] += 1
+        _count_errors(text, acc)
+        return
+
+    if item_type == "function_call":
+        name = str(item.get("name") or "<unknown>")
+        acc.totals["tool_calls"] += 1
+        acc.projects[cwd]["tool_calls"] += 1
+        acc.tool_counts[name] += 1
+        acc.project_tools[cwd][name] += 1
+        arguments = item.get("arguments")
+        arg_text = arguments if isinstance(arguments, str) else json.dumps(arguments, default=str)
+        if _looks_like_verification(name, arg_text):
+            acc.verification_tools[name] += 1
+            acc.project_verification_tools[cwd][name] += 1
+        return
+
+    if item_type == "function_call_output":
+        text = _content_text(item.get("output") or item.get("content"))
+        _count_errors(text, acc)
+        return
+
+    if item_type == "web_search_call":
+        acc.totals["web_searches"] += 1
+        return
+
+    if item_type == "reasoning":
+        acc.totals["reasoning_items"] += 1
+
+
+def _handle_event_msg(payload: dict[str, Any], acc: ScanAccumulator) -> None:
+    message = _content_text(payload.get("message") or payload.get("text") or payload)
+    _count_errors(message, acc)
+
+
+def _project_capsule(
+    cwd: str,
+    counts: Counter,
+    tools: Counter,
+    efforts: Counter,
+    prompt_scores: list[int],
+    verification_tool_calls: int,
+) -> dict[str, Any]:
+    prompt_average = round(sum(prompt_scores) / len(prompt_scores), 2) if prompt_scores else 0.0
+    workflow = _infer_workflow(tools, counts)
+    instruction = _project_instruction(counts, prompt_average, verification_tool_calls)
+    return {
+        "project": cwd,
+        "sessions": counts["sessions"],
+        "turns": counts["turns"],
+        "user_messages": counts["user_messages"],
+        "tool_calls": counts["tool_calls"],
+        "verification_tool_calls": verification_tool_calls,
+        "compactions": counts["compactions"],
+        "prompt_quality_average": prompt_average,
+        "top_tools": dict(tools.most_common(5)),
+        "effort_mix": dict(efforts.most_common()),
+        "likely_workflow": workflow,
+        "recommended_instruction": instruction,
+        "skill_candidate": counts["turns"] >= 3 or counts["tool_calls"] >= 10,
+    }
+
+
+def _infer_workflow(tools: Counter, counts: Counter) -> str:
+    names = set(tools)
+    if any(name.startswith("browser_") or name in {"screenshot", "view_image"} for name in names):
+        return "UI or browser verification"
+    if tools.get("web.run", 0) or "web_search" in names:
+        return "research and current-information checks"
+    if tools.get("exec_command", 0) >= max(2, counts["tool_calls"] // 2):
+        return "terminal-heavy implementation or diagnosis"
+    if tools.get("update_plan", 0) >= 2:
+        return "multi-step planning and execution"
+    if counts["tool_calls"] == 0:
+        return "conversation and planning"
+    return "mixed Codex workflow"
+
+
+def _project_instruction(counts: Counter, prompt_average: float, verification_tool_calls: int) -> str:
+    tool_calls = max(1, counts["tool_calls"])
+    if counts["compactions"] > 0:
+        return "For long tasks in this project, keep a short durable checklist and validate files before resuming after compaction."
+    if counts["tool_calls"] >= 6 and verification_tool_calls / tool_calls < 0.15:
+        return "Before final status in this project, run the smallest meaningful test, build, lint, browser check, or runtime probe."
+    if prompt_average and prompt_average < 5:
+        return "Start prompts for this project with action, target file or subsystem, symptom or goal, and success state."
+    return "Keep the project context compact: state the active subsystem, constraints, and the verification expected for user-facing changes."
+
+
+def _content_text(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, str):
+        return value
+    if isinstance(value, list):
+        chunks: list[str] = []
+        for item in value:
+            if isinstance(item, str):
+                chunks.append(item)
+            elif isinstance(item, dict):
+                chunks.append(str(item.get("text") or item.get("content") or ""))
+        return "\n".join(part for part in chunks if part)
+    if isinstance(value, dict):
+        return str(value.get("text") or value.get("content") or value.get("message") or "")
+    return str(value)
+
+
+def _looks_like_verification(tool_name: str, arguments: str) -> bool:
+    text = f"{tool_name} {arguments}".lower()
+    return any(marker in text for marker in VERIFY_RE)
+
+
+def _count_errors(text: str, acc: ScanAccumulator) -> None:
+    lower = text.lower()
+    for marker in ERROR_RE:
+        if marker in lower:
+            acc.error_counts[marker] += 1
+            return

package/src/codex_coach/paths.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class CoachPaths:
+    home: Path
+    codex_home: Path
+    coach_home: Path
+
+    @property
+    def reports_dir(self) -> Path:
+        return self.coach_home / "reports"
+
+    @property
+    def facts_dir(self) -> Path:
+        return self.coach_home / "facts"
+
+    @property
+    def suggestions_dir(self) -> Path:
+        return self.coach_home / "suggestions"
+
+    @property
+    def config_file(self) -> Path:
+        return self.coach_home / "config.toml"
+
+    @property
+    def app_dir(self) -> Path:
+        return self.coach_home / "app"
+
+    def ensure_output_dirs(self) -> None:
+        self.reports_dir.mkdir(parents=True, exist_ok=True)
+        self.facts_dir.mkdir(parents=True, exist_ok=True)
+        self.suggestions_dir.mkdir(parents=True, exist_ok=True)
+
+
+def default_paths(
+    *,
+    home: str | Path | None = None,
+    codex_home: str | Path | None = None,
+    coach_home: str | Path | None = None,
+) -> CoachPaths:
+    home_path = Path(home or os.environ.get("HOME") or Path.home()).expanduser()
+    codex_path = Path(codex_home or os.environ.get("CODEX_HOME") or home_path / ".codex").expanduser()
+    coach_path = Path(coach_home or os.environ.get("CODEX_COACH_HOME") or home_path / ".codex-coach").expanduser()
+    return CoachPaths(home=home_path, codex_home=codex_path, coach_home=coach_path)

package/src/codex_coach/prompts.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from .redaction import redact_text, text_stats
+
+PATH_HINT_RE = re.compile(r"(?:^|\s)(?:\.{0,2}/|~?/|[A-Za-z]:\\|[\w.-]+\.(?:py|ts|tsx|js|jsx|md|json|toml|yaml|yml|go|rs|java|cs|rb|php))")
+URL_HINT_RE = re.compile(r"https?://")
+ERROR_HINT_RE = re.compile(r"\b(error|exception|traceback|failed|failing|crash|stuck|timeout|panic|bug|regression|broken)\b", re.IGNORECASE)
+SUCCESS_HINT_RE = re.compile(r"\b(success|done|verify|should|expected|acceptance|criteria|when|until|so that)\b", re.IGNORECASE)
+COMMAND_HINT_RE = re.compile(r"`[^`]+`|\b(npm|pnpm|bun|uv|python|pytest|git|cargo|go test|make|docker|codex)\b", re.IGNORECASE)
+ACTION_HINT_RE = re.compile(r"\b(run|implement|build|fix|debug|analyze|review|refactor|test|install|deploy|create|update|remove|delete|generate|explain)\b", re.IGNORECASE)
+VAGUE_RE = re.compile(r"^(fix|run|update|delete|improve|optimi[sz]e|make better|where|why|ok|nice|worked|continue|proceed|do it|go)$", re.IGNORECASE)
+VALID_CONTEXT_REPLY_RE = re.compile(r"^(yes|y|no|n|ok|okay|proceed|continue|go ahead|do it|run tests|commit|push|retry|try again|1|2|3|4|5|a|b|c|d)$", re.IGNORECASE)
+
+
+@dataclass(frozen=True)
+class PromptScore:
+    score: int
+    category: str
+    reason: str
+    preview: str
+    missing: tuple[str, ...]
+    rewrite: str
+    stats: dict[str, int | str]
+
+
+def score_prompt(text: str) -> PromptScore:
+    stripped = text.strip()
+    lower = stripped.lower()
+    words = [part for part in re.split(r"\s+", stripped) if part]
+    score = 4
+    reasons: list[str] = []
+
+    if not stripped:
+        return PromptScore(0, "needs_work", "empty prompt", "", ("action", "target", "success state"), _rewrite_prompt(()), text_stats(text))
+
+    if stripped.startswith("<environment_context>") or stripped.startswith("# AGENTS.md instructions"):
+        return PromptScore(
+            7,
+            "good",
+            "machine-provided context block",
+            redact_text(text),
+            (),
+            "No rewrite needed for machine-provided context blocks.",
+            text_stats(text),
+        )
+
+    if VALID_CONTEXT_REPLY_RE.match(stripped):
+        return PromptScore(
+            7,
+            "good",
+            "brief response that is usually valid with conversation context",
+            redact_text(text),
+            (),
+            "No rewrite needed when the previous Codex turn made the choice explicit.",
+            text_stats(text),
+        )
+
+    if stripped.startswith("[$") and "](" in stripped:
+        return PromptScore(
+            7,
+            "good",
+            "Codex skill or plugin invocation",
+            redact_text(text),
+            (),
+            "No rewrite needed when the invocation intentionally activates a Codex skill or plugin.",
+            text_stats(text),
+        )
+
+    if len(words) <= 2 and VAGUE_RE.match(stripped):
+        missing = ("target", "success state")
+        return PromptScore(
+            3,
+            "needs_work",
+            "very short prompt with ambiguous target or action",
+            redact_text(text),
+            missing,
+            _rewrite_prompt(missing),
+            text_stats(text),
+        )
+
+    has_action = bool(ACTION_HINT_RE.search(stripped))
+    has_target = bool(PATH_HINT_RE.search(stripped) or URL_HINT_RE.search(stripped))
+    has_failure = bool(ERROR_HINT_RE.search(stripped))
+    has_success = bool(SUCCESS_HINT_RE.search(stripped))
+    has_command = bool(COMMAND_HINT_RE.search(stripped))
+
+    if len(words) >= 8:
+        score += 1
+        reasons.append("clear length")
+    if has_action:
+        score += 1
+        reasons.append("action stated")
+    if has_target:
+        score += 1
+        reasons.append("file or path context")
+    if has_failure:
+        score += 1
+        reasons.append("failure context")
+    if has_success:
+        score += 1
+        reasons.append("success context")
+    if has_command:
+        score += 1
+        reasons.append("command context")
+
+    if len(words) < 4:
+        score -= 1
+        reasons.append("short")
+    if re.search(r"\b(fix|update|delete|improve|optimi[sz]e|make)\b", lower) and not (
+        has_target or has_failure or has_success
+    ):
+        score -= 2
+        reasons.append("missing target detail")
+
+    missing: list[str] = []
+    if not has_action:
+        missing.append("action")
+    if not has_target and not has_failure and len(words) >= 3:
+        missing.append("target")
+    if (has_action or has_failure) and not has_success:
+        missing.append("success state")
+    if has_action and not has_command and any(verb in lower for verb in ("fix", "debug", "implement", "build", "refactor", "deploy")):
+        missing.append("verification")
+
+    score = max(0, min(10, score))
+    if score >= 8:
+        category = "excellent"
+    elif score >= 5:
+        category = "good"
+    else:
+        category = "needs_work"
+    reason = ", ".join(reasons[:4]) or "basic request"
+    missing_tuple = tuple(dict.fromkeys(missing))
+    return PromptScore(score, category, reason, redact_text(text), missing_tuple, _rewrite_prompt(missing_tuple), text_stats(text))
+
+
+def _rewrite_prompt(missing: tuple[str, ...]) -> str:
+    if not missing:
+        return "Keep the prompt shape. Add a success check only if the task touches code, config, deploys, or user-visible behavior."
+    parts = [
+        "[Action] in [project/file]",
+        "because [symptom or goal]",
+        "using [relevant command, link, or constraint]",
+        "Success means [observable verification result].",
+    ]
+    if "verification" in missing and "success state" not in missing:
+        parts[-1] = "Verify with [smallest meaningful test/build/runtime check]."
+    return " ".join(parts)

package/src/codex_coach/redaction.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import hashlib
+import re
+
+PATH_RE = re.compile(r"(?<!\w)(?:~|/Users/[^ \n\t]+|/home/[^ \n\t]+|/[A-Za-z0-9_.-]+(?:/[A-Za-z0-9_.-]+){2,})")
+URL_RE = re.compile(r"https?://[^\s)>\]]+")
+EMAIL_RE = re.compile(r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b")
+SECRET_RE = re.compile(r"\b(?:sk|pk|ghp|github_pat|xox[baprs])-?[A-Za-z0-9_\-]{12,}\b", re.IGNORECASE)
+LONG_TOKEN_RE = re.compile(r"\b[A-Za-z0-9_\-]{32,}\b")
+WHITESPACE_RE = re.compile(r"\s+")
+
+
+def stable_hash(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8", "ignore")).hexdigest()[:12]
+
+
+def redact_text(text: str, *, max_chars: int = 96) -> str:
+    text = URL_RE.sub("[url]", text)
+    text = EMAIL_RE.sub("[email]", text)
+    text = SECRET_RE.sub("[secret]", text)
+    text = PATH_RE.sub("[path]", text)
+    text = LONG_TOKEN_RE.sub("[token]", text)
+    text = WHITESPACE_RE.sub(" ", text).strip()
+    if len(text) > max_chars:
+        return text[: max_chars - 1].rstrip() + "..."
+    return text
+
+
+def text_stats(text: str) -> dict[str, int | str]:
+    return {
+        "chars": len(text),
+        "words": len([part for part in WHITESPACE_RE.split(text.strip()) if part]),
+        "hash": stable_hash(text),
+    }