cigar-break 0.1.0__py3-none-any.whl

cigar/__init__.py

@@ -0,0 +1,3 @@
+"""Cigar: notices when a coding agent's session is slipping, and hands off across a reset."""
+
+__version__ = "0.1.0"

cigar/auto.py

@@ -0,0 +1,70 @@
+"""Auto mode markers (D-007, D-021, D-026).
+
+In `auto` mode, once a handoff is saved for the session, the hook writes
+<CIGAR_HOME>/auto/<session id>.json with state "ready" and the handoff's path.
+The mod in mods/auto.ts reads it at the end of the turn, marks it "fired" and
+runs /clear. With no marker, or one without a handoff path, it never clears.
+Only these markers cross between the two.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+
+MAX_AGE_SECONDS = 24 * 3600
+FIRED_MAX_AGE_SECONDS = 600  # a clear that fired longer ago than this is not "just now"
+
+
+def marker_path(home: Path, session_id: str) -> Path:
+    safe = "".join(c for c in session_id if c.isalnum() or c in "-_")
+    return home / "auto" / f"{safe}.json"
+
+
+def mark_ready(home: Path, session_id: str, handoff: str) -> Path:
+    path = marker_path(home, session_id)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(".tmp")
+    marker = {"state": "ready", "session": session_id, "handoff": handoff, "ts": time.time()}
+    tmp.write_text(json.dumps(marker), encoding="utf-8")
+    tmp.replace(path)
+    return path
+
+
+def take_fired(home: Path, max_age: float = FIRED_MAX_AGE_SECONDS) -> str | None:
+    """The handoff path of a clear the mod just fired, removing its marker."""
+    folder = home / "auto"
+    if not folder.is_dir():
+        return None
+    found: tuple[float, str] | None = None
+    cutoff = time.time() - max_age
+    for path in folder.glob("*.json"):
+        try:
+            marker = json.loads(path.read_text(encoding="utf-8"))
+            if marker.get("state") != "fired" or path.stat().st_mtime < cutoff:
+                continue
+            handoff = marker.get("handoff")
+            if isinstance(handoff, str) and handoff:
+                stamp = path.stat().st_mtime
+                if found is None or stamp > found[0]:
+                    found = (stamp, handoff)
+            path.unlink()
+        except (OSError, ValueError, AttributeError):
+            continue
+    return found[1] if found else None
+
+
+def prune(home: Path, max_age: float = MAX_AGE_SECONDS) -> None:
+    """Remove fired markers and any older than max_age."""
+    folder = home / "auto"
+    if not folder.is_dir():
+        return
+    cutoff = time.time() - max_age
+    for path in folder.glob("*.json"):
+        try:
+            fired = json.loads(path.read_text(encoding="utf-8")).get("state") == "fired"
+            if fired or path.stat().st_mtime < cutoff:
+                path.unlink()
+        except (OSError, ValueError, AttributeError):
+            path.unlink(missing_ok=True)

cigar/cli.py

@@ -0,0 +1,128 @@
+"""`cigar` command line: status, report, share and mode (FR-C6)."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+from cigar import __version__, config, status
+from cigar.store import Store, project_hash
+
+MODE_HELP = {
+    "suggest": "Cigar nudges the agent and you when the session shows fatigue (default).",
+    "observe": "Cigar records signals only, with no nudges.",
+    "auto": (
+        "After a handoff is saved, Cigar clears the context itself at the end of the turn and "
+        "restores the handoff. Needs plugin mods (Claude Code 2.1.287 or newer); tested in the "
+        "terminal CLI only."
+    ),
+}
+
+
+def cmd_status(args: argparse.Namespace) -> int:
+    cfg = config.load()
+    project_dir = args.project or os.environ.get("CLAUDE_PROJECT_DIR") or os.getcwd()
+    project = project_hash(str(Path(project_dir)))
+    with Store.open(cfg.db_path) as store:
+        info = status.collect(store, cfg, args.session, project)
+    print(json.dumps(info, indent=2) if args.json else status.render(info))
+    return 0
+
+
+def cmd_mode(args: argparse.Namespace) -> int:
+    cfg = config.load()
+    mode = (args.mode or "").strip().lower()
+    if not mode:
+        print(f"Mode: {cfg.mode}. {MODE_HELP[cfg.mode]}")
+        return 0
+    if mode not in config.MODES:
+        print(f"Unknown mode {mode!r}. Choose one of: {', '.join(config.MODES)}.")
+        return 2
+    args.mode = mode
+    path = config.write_value(cfg.home, "mode", args.mode)
+    note = ""
+    if os.environ.get("CIGAR_MODE") and os.environ["CIGAR_MODE"] != args.mode:
+        note = f" Note: CIGAR_MODE={os.environ['CIGAR_MODE']} is set and overrides it."
+    print(f"Mode set to {args.mode} in {path}. {MODE_HELP[args.mode]}{note}")
+    return 0
+
+
+def cmd_report(args: argparse.Namespace) -> int:
+    from cigar import report, track
+
+    cfg = config.load()
+    with Store.open(cfg.db_path) as store:
+        fits = track.refresh_knees(store, force=True) or []
+        compactions = store.compaction_tokens()
+    print(report.render_text(fits, compactions))
+    if args.html or args.open:
+        path = report.write_html(cfg.home, report.render_html(fits, compactions))
+        print(f"\nHTML report: {path}")
+        if args.open:
+            import webbrowser
+
+            webbrowser.open(path.as_uri())
+    return 0
+
+
+def cmd_share(args: argparse.Namespace) -> int:
+    from cigar import share, track
+
+    cfg = config.load()
+    with Store.open(cfg.db_path) as store:
+        fits = track.refresh_knees(store, force=True) or []
+        harnesses = track.harnesses(store)
+    return share.run(
+        cfg,
+        fits,
+        harnesses,
+        model=args.model,
+        window=args.window,
+        dry_run=args.dry_run,
+        yes=args.yes,
+        skill=args.skill,
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="cigar", description="Cigar: take a break before the context rots."
+    )
+    parser.add_argument("--version", action="version", version=f"cigar {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_status = sub.add_parser("status", help="score, context size, knee, recent signals and mode")
+    p_status.add_argument("--session", help="session ID (default: the latest in this project)")
+    p_status.add_argument("--project", help="project directory (default: current directory)")
+    p_status.add_argument("--json", action="store_true", help="print JSON")
+    p_status.set_defaults(func=cmd_status)
+
+    p_report = sub.add_parser("report", help="your signal rate by context size, per model")
+    p_report.add_argument("--html", action="store_true", help="also write the HTML report")
+    p_report.add_argument("--open", action="store_true", help="write the HTML and open it")
+    p_report.set_defaults(func=cmd_report)
+
+    p_share = sub.add_parser("share", help="share your anonymous curve (opt-in, shows it first)")
+    p_share.add_argument("--dry-run", action="store_true", help="print the payload only")
+    p_share.add_argument("--yes", action="store_true", help="skip the confirmation question")
+    p_share.add_argument("--model", help="which model's curve (default: the most data)")
+    p_share.add_argument("--window", choices=["200k", "1m"], help="which context window")
+    p_share.add_argument("--skill", help=argparse.SUPPRESS)  # /cigar:share passes its argument
+    p_share.set_defaults(func=cmd_share)
+
+    p_mode = sub.add_parser("mode", help="show or set the mode")
+    p_mode.add_argument("mode", nargs="?", help="suggest, observe or auto")
+    p_mode.set_defaults(func=cmd_mode)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    return int(args.func(args))
+
+
+if __name__ == "__main__":
+    sys.exit(main())

cigar/config.py

@@ -0,0 +1,120 @@
+"""Configuration: ~/.cigar/config.toml, overridden by environment variables.
+
+Precedence (highest first): environment, config.toml, defaults.py.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field, replace
+from pathlib import Path
+from typing import Any
+
+from cigar import defaults
+
+MODES = ("suggest", "observe", "auto")
+
+
+def cigar_home() -> Path:
+    return Path(os.environ.get("CIGAR_HOME") or "~/.cigar").expanduser()
+
+
+@dataclass(frozen=True)
+class Config:
+    home: Path
+    mode: str = "suggest"
+    min_tokens: int = defaults.MIN_TOKENS
+    knee_tokens: int | None = None
+    cooldown_events: int = defaults.COOLDOWN_EVENTS
+    max_nudges: int = defaults.MAX_NUDGES
+    check_patterns: tuple[str, ...] = field(default=defaults.CHECK_PATTERNS)
+    context_window: str | None = None  # "200k" or "1m"; None means detect (D-026)
+
+    @property
+    def db_path(self) -> Path:
+        return self.home / "cigar.db"
+
+    @property
+    def config_path(self) -> Path:
+        return self.home / "config.toml"
+
+    @property
+    def log_dir(self) -> Path:
+        return self.home / "logs"
+
+
+def _read_toml(path: Path) -> dict[str, Any]:
+    if not path.is_file():
+        return {}
+    import tomllib
+
+    with path.open("rb") as f:
+        return tomllib.load(f)
+
+
+def _window(*values: Any) -> str | None:
+    """The first value that names a known window ("200k" or "1m")."""
+    for value in values:
+        label = str(value).strip().lower() if value is not None else ""
+        if label in defaults.WINDOWS:
+            return label
+    return None
+
+
+def _int(*values: Any) -> int | None:
+    """The first value that is set, as an int."""
+    for value in values:
+        if value is not None and value != "":
+            return int(value)
+    return None
+
+
+def load(env: dict[str, str] | None = None) -> Config:
+    env = dict(os.environ) if env is None else env
+    home = Path(env.get("CIGAR_HOME") or "~/.cigar").expanduser()
+    cfg = Config(home=home)
+    data = _read_toml(cfg.config_path)
+
+    mode = env.get("CIGAR_MODE") or data.get("mode") or cfg.mode
+    if mode not in MODES:
+        mode = "suggest"
+    min_tokens = _int(env.get("CIGAR_MIN_TOKENS"), data.get("min_tokens"))
+    knee = _int(env.get("CIGAR_KNEE_TOKENS"), data.get("knee_tokens"))
+    cooldown = _int(data.get("cooldown_events"))
+    max_nudges = _int(data.get("max_nudges"))
+    patterns = data.get("check_patterns")
+
+    return replace(
+        cfg,
+        mode=mode,
+        min_tokens=min_tokens if min_tokens is not None else cfg.min_tokens,
+        knee_tokens=knee,
+        cooldown_events=cooldown if cooldown is not None else cfg.cooldown_events,
+        max_nudges=max_nudges if max_nudges is not None else cfg.max_nudges,
+        check_patterns=tuple(patterns) if isinstance(patterns, list) else cfg.check_patterns,
+        context_window=_window(env.get("CIGAR_CONTEXT_WINDOW"), data.get("context_window")),
+    )
+
+
+def _toml_value(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, int | float):
+        return str(value)
+    if isinstance(value, list | tuple):
+        return "[" + ", ".join(_toml_value(v) for v in value) + "]"
+    s = str(value).replace("\\", "\\\\").replace('"', '\\"')
+    return f'"{s}"'
+
+
+def write_value(home: Path, key: str, value: Any) -> Path:
+    """Set one top-level key in config.toml, keeping the other keys."""
+    path = home / "config.toml"
+    data = _read_toml(path)
+    data[key] = value
+    home.mkdir(parents=True, exist_ok=True)
+    lines = [f"{k} = {_toml_value(v)}" for k, v in data.items() if not isinstance(v, dict)]
+    tmp = path.with_suffix(".toml.tmp")
+    tmp.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    tmp.replace(path)
+    return path

cigar/defaults.py

@@ -0,0 +1,100 @@
+"""Tuning constants. This is the only module where tuning numbers live.
+
+Every value here is a starting point. The learned knee (Session 2) replaces
+the default knees, and config.toml or environment variables can override the
+rest (architecture §12). The reasoning for the default knees is in D-017.
+"""
+
+from __future__ import annotations
+
+import re
+
+# --- Signals (architecture §6) ---------------------------------------------
+WINDOW_EVENTS = 20
+# Rules (a) and (c) judge behavior only over at least this many events (D-020).
+MIN_WINDOW_EVENTS = 10
+UNDO_LOOKBACK_EVENTS = 50
+
+WEIGHTS: dict[str, float] = {
+    "failure": 1.0,
+    "repeat": 0.8,
+    "reread": 0.5,
+    "undo": 1.0,
+    "check_fail": 0.7,
+}
+
+READ_TOOLS = frozenset({"Read", "NotebookRead"})
+EDIT_TOOLS = frozenset({"Edit", "MultiEdit", "Write", "NotebookEdit"})
+SHELL_TOOLS = frozenset({"Bash", "PowerShell"})
+
+# Shell commands that count as a test, build, lint or type check.
+CHECK_PATTERNS: tuple[str, ...] = (
+    r"\b(pytest|py\.test|tox|nox|unittest)\b",
+    r"\b(npm|pnpm|yarn|bun)\s+(run\s+)?(test|build|lint|typecheck|type-check|check)\b",
+    r"\b(jest|vitest|mocha|playwright\s+test|cypress\s+run)\b",
+    r"\b(tsc|eslint|biome|prettier\s+--check)\b",
+    r"\b(ruff|flake8|pylint|mypy|pyright|black\s+--check)\b",
+    r"\bcargo\s+(test|build|check|clippy)\b",
+    r"\bgo\s+(test|build|vet)\b|\bgolangci-lint\b",
+    r"\b(make|ninja|cmake\s+--build|bazel\s+(build|test)|gradle\w*|mvn)\b",
+    r"\b(rspec|rubocop|phpunit|swift\s+(build|test)|dotnet\s+(build|test))\b",
+)
+
+# --- Score and nudge policy (architecture §6) -------------------------------
+DEFAULT_BASELINE = 0.08
+BASELINE_MIN_EVENTS = 200
+BASELINE_KNEE_FRACTION = 0.4
+BASELINE_CACHE_SECONDS = 3600
+
+BEHAVIOR_MARGIN = 0.10  # rule (a): behavior >= baseline + margin, past the knee
+PRESSURE_KNEE = 1.0  # rule (a)
+PRESSURE_HARD = 1.3  # rule (b): well past the knee, whatever the behavior
+DISTRESS_BEHAVIOR = 0.45  # rule (c)
+DISTRESS_PRESSURE = 0.6  # rule (c)
+FATIGUE_PRESSURE_CAP = 1.5
+
+MIN_TOKENS = 40_000
+COOLDOWN_EVENTS = 25
+MAX_NUDGES = 3
+
+# --- Handoffs ---------------------------------------------------------------
+HANDOFF_INJECT_MAX_CHARS = 8_000
+HANDOFF_MAX_AGE_SECONDS = 24 * 3600
+
+# --- Transcript tail reading --------------------------------------------------
+TAIL_BLOCK_BYTES = 64 * 1024
+TAIL_MAX_BYTES = 4 * 1024 * 1024
+
+# --- Knees (D-017) -------------------------------------------------------------
+STANDARD_WINDOW = 200_000
+EXTENDED_WINDOW = 1_000_000
+# Window labels stored per session and used in shared curves (D-026).
+WINDOWS: dict[str, int] = {"200k": STANDARD_WINDOW, "1m": EXTENDED_WINDOW}
+
+# (pattern on the model ID, knee for a 200k window, knee for a 1M window)
+KNEES: tuple[tuple[str, int, int], ...] = (
+    (r"opus", 120_000, 160_000),
+    (r"sonnet", 100_000, 140_000),
+    (r"haiku", 70_000, 70_000),
+)
+FALLBACK_KNEE_CAP = 120_000
+FALLBACK_KNEE_FRACTION = 0.5
+
+# A model ID marked like this runs with a 1M window. Claude Code does not mark
+# transcript model IDs (D-014), so seeing more tokens than the standard window
+# also counts as evidence of an extended window.
+EXTENDED_MARKERS = re.compile(r"\[1m\]|-1m\b|context-1m", re.IGNORECASE)
+
+# --- Knee learning (architecture §9, D-029) -------------------------------------
+KNEE_BUCKET_TOKENS = 10_000
+KNEE_MIN_BUCKET_EVENTS = 50  # a bucket counts with this many events...
+KNEE_MIN_BUCKET_SESSIONS = 3  # ...from at least this many sessions
+KNEE_LOW_FRACTION = 0.4  # baseline: buckets holding the lowest 40% of events
+KNEE_BASELINE_FLOOR = 0.02  # so a near-zero baseline doesn't make any blip a knee
+KNEE_RISE = 1.5  # knee: the 3-bucket mean reaches 1.5 x baseline...
+KNEE_RUN_BUCKETS = 3
+KNEE_MEDIUM = (5, 6)  # (sessions, counting buckets) for medium confidence
+KNEE_HIGH = (15, 10)  # ...and for high
+KNEE_REFRESH_SECONDS = 3600  # SessionStart refits at most this often
+
+LOG_RETENTION_DAYS = 7

cigar/handoff.py

@@ -0,0 +1,176 @@
+"""Handoffs: validate, render, truncate for injection, save and load (FR-H1 to FR-H5).
+
+`validate`, `render` and `for_injection` are pure. `save` and `load` do I/O.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from cigar import defaults
+
+HANDOFF_DIR = Path(".cigar") / "handoffs"
+INJECTION_PREAMBLE = (
+    "This session continues earlier work. The handoff written before the context reset follows."
+)
+LIST_FIELDS = ("done", "decisions", "next_steps", "open_questions", "gotchas")
+
+
+class HandoffError(ValueError):
+    pass
+
+
+@dataclass(frozen=True)
+class Handoff:
+    goal: str
+    status: str
+    done: tuple[str, ...] = ()
+    decisions: tuple[str, ...] = ()
+    files: tuple[tuple[str, str], ...] = ()
+    next_steps: tuple[str, ...] = ()
+    open_questions: tuple[str, ...] = ()
+    gotchas: tuple[str, ...] = ()
+
+
+def _text(data: dict[str, Any], key: str) -> str:
+    value = data.get(key)
+    if not isinstance(value, str) or not value.strip():
+        raise HandoffError(f"`{key}` is required and must be a non-empty string")
+    return value.strip()
+
+
+def _items(data: dict[str, Any], key: str) -> tuple[str, ...]:
+    value = data.get(key)
+    if value is None:
+        return ()
+    if isinstance(value, str):
+        value = [value]
+    if not isinstance(value, list) or not all(isinstance(v, str) for v in value):
+        raise HandoffError(f"`{key}` must be a list of strings")
+    return tuple(v.strip() for v in value if v.strip())
+
+
+def _split_note(path: str, note: str) -> tuple[str, str]:
+    """Agents often write "path — note" in one string; keep the two apart."""
+    if not note and " — " in path:
+        path, note = (part.strip() for part in path.split(" — ", 1))
+    return path, note
+
+
+def _files(data: dict[str, Any]) -> tuple[tuple[str, str], ...]:
+    value = data.get("files")
+    if value is None:
+        return ()
+    if not isinstance(value, list):
+        raise HandoffError("`files` must be a list of {path, note}")
+    out = []
+    for item in value:
+        if isinstance(item, str) and item.strip():
+            out.append(_split_note(item.strip(), ""))
+        elif isinstance(item, dict) and isinstance(item.get("path"), str) and item["path"].strip():
+            note = item.get("note")
+            out.append(
+                _split_note(item["path"].strip(), note.strip() if isinstance(note, str) else "")
+            )
+        else:
+            raise HandoffError("each entry of `files` needs a `path` string")
+    return tuple(out)
+
+
+def validate(data: Any) -> Handoff:
+    if not isinstance(data, dict):
+        raise HandoffError("the handoff must be an object")
+    fields = {key: _items(data, key) for key in LIST_FIELDS}
+    handoff = Handoff(
+        goal=_text(data, "goal"), status=_text(data, "status"), files=_files(data), **fields
+    )
+    if not handoff.next_steps:
+        raise HandoffError("`next_steps` needs at least one step (the immediate action first)")
+    return handoff
+
+
+def _bullets(items: tuple[str, ...]) -> str:
+    return "\n".join(f"- {item}" for item in items) if items else "- (none)"
+
+
+def render(handoff: Handoff, project_name: str, when: dt.datetime) -> str:
+    files = (
+        "\n".join(f"- `{path}` — {note}" if note else f"- `{path}`" for path, note in handoff.files)
+        if handoff.files
+        else "- (none)"
+    )
+    steps = "\n".join(f"{i}. {step}" for i, step in enumerate(handoff.next_steps, 1))
+    return (
+        f"# Cigar handoff · {project_name} · {when.isoformat(timespec='minutes')}\n"
+        f"**Goal:** {handoff.goal}\n"
+        f"**Status:** {handoff.status}\n\n"
+        f"## Done\n{_bullets(handoff.done)}\n\n"
+        f"## Decisions\n{_bullets(handoff.decisions)}\n\n"
+        f"## Files (path — note)\n{files}\n\n"
+        f"## Next steps\n{steps}\n\n"
+        f"## Open questions\n{_bullets(handoff.open_questions)}\n\n"
+        f"## Gotchas\n{_bullets(handoff.gotchas)}\n"
+    )
+
+
+def for_injection(
+    markdown: str, rel_path: str, limit: int = defaults.HANDOFF_INJECT_MAX_CHARS
+) -> str:
+    """The text injected after a reset: under `limit` chars (FR-H5).
+
+    A long handoff is cut to its goal, status and next steps, followed by the
+    path to the full version.
+    """
+    full = f"{INJECTION_PREAMBLE}\n\n{markdown.strip()}"
+    if len(full) <= limit:
+        return full
+    sections = markdown.strip().split("\n## ")
+    head = sections[0]
+    steps = next((s for s in sections[1:] if s.startswith("Next steps")), "")
+    tail = f"\n\n(Cut to fit. The full handoff is at {rel_path}.)"
+    body = f"{INJECTION_PREAMBLE}\n\n{head}\n\n## {steps}".rstrip()
+    room = limit - len(tail)
+    if len(body) > room:
+        body = body[: max(0, room - 1)].rstrip() + "…"
+    return body + tail
+
+
+def _ensure_dir(project_dir: Path) -> Path:
+    root = project_dir / ".cigar"
+    target = project_dir / HANDOFF_DIR
+    target.mkdir(parents=True, exist_ok=True)
+    ignore = root / ".gitignore"
+    if not ignore.exists():
+        ignore.write_text("*\n", encoding="utf-8")
+    return target
+
+
+def save(
+    project_dir: Path, markdown: str, session_id: str | None, when: dt.datetime
+) -> tuple[Path, str]:
+    """Write the handoff file. Returns (absolute path, path relative to the project)."""
+    target = _ensure_dir(project_dir)
+    stem = f"{when:%Y-%m-%dT%H%M}-{(session_id or 'nosession')[:4]}"
+    path = target / f"{stem}.md"
+    n = 2
+    while path.exists():
+        path = target / f"{stem}-{n}.md"
+        n += 1
+    tmp = path.with_suffix(".md.tmp")
+    tmp.write_text(markdown, encoding="utf-8")
+    tmp.replace(path)
+    return path, path.relative_to(project_dir).as_posix()
+
+
+def load(project_dir: Path, rel_path: str) -> str | None:
+    path = (project_dir / rel_path).resolve()
+    handoffs = (project_dir / HANDOFF_DIR).resolve()
+    if handoffs not in path.parents:
+        return None
+    try:
+        return path.read_text(encoding="utf-8")
+    except OSError:
+        return None