nightshift-cli 0.1.0__py3-none-any.whl

nightshift/adapters/codex.py

@@ -0,0 +1,360 @@
+"""The Codex adapter.
+
+Read-only is enforced by Codex's own sandbox — Seatbelt on macOS, Landlock plus
+seccomp on Linux, restricted tokens on Windows. That is a stronger guarantee
+than the tool allowlist the Claude Code adapter relies on: an allowlist works
+because the agent honours its own tool gating, whereas here the kernel refuses
+the write. A bug in the model cannot touch the disk.
+
+The flags below were read off the published `codex exec` reference rather than
+assumed, and two of them are load-bearing in ways worth stating:
+
+- ``--sandbox read-only`` is passed explicitly even though a fresh install
+  already defaults to it, because the reference is explicit that ``--sandbox``
+  "defaults to configuration settings". A user's ``~/.codex/config.toml``
+  setting ``workspace-write`` would otherwise silently become nightshift's
+  default too. "It defaults to read-only" is a fact about a fresh machine, not
+  a guarantee, and this product's whole claim rests on the difference.
+
+- ``--ignore-user-config`` is belt-and-braces of the same kind as the Claude
+  adapter's denylist — the explicit flags above should already settle it. It
+  earns its place on a second count: MCP servers are configured in that same
+  ``config.toml``, and an MCP tool is not a shell command, so it is not obvious
+  that the filesystem sandbox constrains one at all. Refusing to load the file
+  means there are no MCP servers to find out about. Authentication is
+  unaffected — the reference states auth still resolves via ``CODEX_HOME``.
+
+The cost of that second flag is real and worth knowing: a user's configured
+model choice is ignored too, so runs use Codex's default model.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from datetime import datetime
+from pathlib import Path
+
+from nightshift import sessions
+from nightshift.adapters._process import (
+    clip,
+    emit,
+    stream_ndjson,
+    summarize,
+)
+from nightshift.adapters.base import Availability, Event, OnEvent, RunResult
+
+#: The only sandbox nightshift will ever ask for. Not a default — an assertion.
+SANDBOX = "read-only"
+
+#: Never pause for a human: there isn't one, and a run that could ask for
+#: approval is a run that could be granted an escalation out of the sandbox.
+APPROVAL = "never"
+
+#: Where Codex records its sessions. ``CODEX_HOME`` relocates the whole tree.
+CODEX_HOME = "~/.codex"
+
+_READ_ONLY_PREAMBLE = (
+    "You are running unattended as part of an automated read-only review.\n"
+    "You are in a read-only sandbox: you cannot write, edit, or delete files, "
+    "and nothing you do can change this repository. Do not attempt it, and do "
+    "not ask questions. Inspect the repository and report findings only.\n\n"
+)
+
+
+def _first_token(command: str) -> tuple[str, str]:
+    """Split a shell command into (program, rest) for display.
+
+    ``rg -n foo src/`` reads better as ``rg(-n foo src/)`` than as
+    ``Shell(rg -n foo src/)``, and lines up with how the Claude adapter names
+    the tool it is running.
+    """
+    command = " ".join(str(command or "").split())
+    if not command:
+        return "shell", ""
+    head, _, rest = command.partition(" ")
+    return head, rest
+
+
+class _Collector:
+    """Turns Codex's NDJSON event stream into findings, events, and alarms.
+
+    One of these per run. It is the ``on_line`` sink for ``stream_ndjson``, and
+    it is deliberately the only place that knows Codex's event schema.
+    """
+
+    def __init__(self, project_dir: Path, on_event: OnEvent | None = None):
+        self.project_dir = project_dir
+        self.on_event = on_event
+        #: Every ``agent_message`` seen, in order.
+        self.messages: list[str] = []
+        #: Paths Codex reported it *changed*. Must stay empty; see :meth:`_item`.
+        self.wrote: list[str] = []
+        #: A turn- or stream-level error message, preferred over raw stderr.
+        self.error = ""
+        self._claimed = False
+
+    @property
+    def findings(self) -> str:
+        """The final assistant message.
+
+        Codex's own ``--output-last-message`` treats the last one as *the*
+        answer, so we do too. Joining every message instead would file the
+        model's running narration into the digest alongside the findings.
+        """
+        return self.messages[-1] if self.messages else ""
+
+    def _emit(self, event: Event) -> None:
+        if self.on_event is not None:
+            emit(self.on_event, event)
+
+    def __call__(self, payload: dict) -> None:
+        kind = payload.get("type")
+
+        if kind == "thread.started":
+            thread_id = str(payload.get("thread_id") or "")
+            if thread_id and not self._claimed:
+                # Claim on sight, not at the end: a run killed at the deadline
+                # still left a session file behind, and an unclaimed session is
+                # one last_human_use later mistakes for a human's.
+                sessions.record(thread_id)
+                self._claimed = True
+            self._emit(Event("start", text=str(self.project_dir)))
+
+        elif kind == "turn.failed":
+            error = payload.get("error")
+            message = error.get("message") if isinstance(error, dict) else None
+            self.error = str(message or "the turn failed")
+            self._emit(Event("error", text=self.error))
+
+        elif kind == "error":
+            self.error = str(payload.get("message") or "the run reported an error")
+            self._emit(Event("error", text=self.error))
+
+        elif kind in ("item.started", "item.completed"):
+            item = payload.get("item")
+            if isinstance(item, dict):
+                self._item(kind, item)
+
+    def _item(self, kind: str, item: dict) -> None:
+        item_type = item.get("type")
+        done = kind == "item.completed"
+
+        if item_type == "agent_message" and done:
+            text = str(item.get("text") or "").strip()
+            if text:
+                self.messages.append(text)
+                self._emit(Event("text", text=text))
+
+        elif item_type == "reasoning" and done:
+            self._emit(Event("thinking"))
+
+        elif item_type == "command_execution":
+            if done:
+                self._emit(Event("tool_result", text=summarize(item.get("aggregated_output"))))
+            else:
+                program, rest = _first_token(str(item.get("command") or ""))
+                self._emit(Event("tool", tool=program, detail=clip(rest, 60)))
+
+        elif item_type == "file_change" and done:
+            # The tripwire. A read-only sandbox cannot let this happen, so if it
+            # does, either the sandbox did not apply or it did not hold — and
+            # every claim nightshift makes about this provider is void for this
+            # run. `status` matters: a *failed* file_change is the sandbox doing
+            # its job and refusing a write, which is not an alarm.
+            if str(item.get("status") or "") != "completed":
+                return
+            changes = item.get("changes")
+            paths = [
+                str(c.get("path"))
+                for c in (changes if isinstance(changes, list) else [])
+                if isinstance(c, dict) and c.get("path")
+            ]
+            self.wrote.extend(paths or ["<unnamed file>"])
+            self._emit(Event("error", text=f"file changed: {', '.join(self.wrote)}"))
+
+        elif item_type == "mcp_tool_call" and not done:
+            # --ignore-user-config means no MCP servers are configured, so this
+            # should never arrive. Render it rather than drop it: a tool we did
+            # not expect is worth seeing in the live view.
+            server = str(item.get("server") or "?")
+            self._emit(Event("tool", tool=f"{server}:{item.get('tool') or '?'}"))
+
+        elif item_type == "web_search" and done:
+            self._emit(Event("tool", tool="web_search", detail=clip(item.get("query"), 60)))
+
+        elif item_type == "error" and done:
+            self._emit(Event("error", text=str(item.get("message") or "")))
+
+
+class CodexAdapter:
+    name = "codex"
+
+    def __init__(self, binary: str = "codex"):
+        self.binary = binary
+
+    # ---- availability -------------------------------------------------
+
+    def _which(self) -> str | None:
+        return shutil.which(self.binary)
+
+    def availability(self) -> Availability:
+        path = self._which()
+        if path is None:
+            return Availability(
+                ok=False,
+                reason=f"`{self.binary}` is not on PATH — install Codex, see "
+                f"https://developers.openai.com/codex",
+            )
+        try:
+            proc = subprocess.run(
+                [self.binary, "--version"],
+                capture_output=True,
+                text=True,
+                timeout=20,
+                check=False,
+            )
+        except (OSError, subprocess.SubprocessError) as exc:
+            return Availability(ok=False, reason=f"`{self.binary} --version` failed: {exc}")
+        if proc.returncode != 0:
+            detail = (proc.stderr or proc.stdout or "").strip().splitlines()
+            first = detail[0] if detail else f"exit {proc.returncode}"
+            return Availability(ok=False, reason=f"`{self.binary} --version` failed: {first}")
+        return Availability(ok=True, reason=(proc.stdout or "").strip())
+
+    def available(self) -> bool:
+        return self.availability().ok
+
+    # ---- idle detection -----------------------------------------------
+
+    def _sessions_dir(self) -> Path:
+        home = os.environ.get("CODEX_HOME") or CODEX_HOME
+        return Path(os.path.expanduser(home)) / "sessions"
+
+    def last_human_use(self) -> datetime | None:
+        """Newest mtime under ``$CODEX_HOME/sessions`` that was not ours.
+
+        ``None`` when the directory is absent: a Codex that has never run reads
+        as idle, not as busy.
+
+        Our own runs write session files here too, so they are skipped — count
+        them and every run would gate the next one, and nightshift would put
+        itself to sleep. Codex names these ``rollout-<timestamp>-<thread_id>``
+        rather than after the id alone, so this matches on *containment* where
+        the Claude adapter can compare the stem outright.
+
+        Only files count. A directory's mtime bumps when anything inside it is
+        written, including our own session, so it cannot be attributed to a
+        human once nightshift shares the tree.
+        """
+        root = self._sessions_dir()
+        if not root.is_dir():
+            return None
+        mine = sessions.ours()
+        newest: float | None = None
+        try:
+            for path in root.rglob("*"):
+                try:
+                    if not path.is_file():
+                        continue
+                    if any(sid and sid in path.name for sid in mine):
+                        continue
+                    mtime = path.stat().st_mtime
+                except OSError:
+                    continue
+                if newest is None or mtime > newest:
+                    newest = mtime
+        except OSError:
+            return None
+        if newest is None:
+            return None
+        return datetime.fromtimestamp(newest)
+
+    # ---- running ------------------------------------------------------
+
+    def command(self, prompt: str) -> list[str]:
+        return [
+            self.binary,
+            "exec",
+            "--sandbox",
+            SANDBOX,
+            "--ask-for-approval",
+            APPROVAL,
+            # nightshift registers directories, not repositories; codex exec
+            # refuses to run outside a git repo without this. The check exists
+            # to protect uncommitted work from edits, which is not a risk we
+            # have.
+            "--skip-git-repo-check",
+            "--ignore-user-config",
+            # Project-local execpolicy rules cannot widen an OS sandbox, but
+            # they can make one project behave unlike another. A review that
+            # depends on a file in the repo being reviewed is not one we want.
+            "--ignore-rules",
+            "--json",
+            _READ_ONLY_PREAMBLE + prompt,
+        ]
+
+    def run(
+        self,
+        prompt: str,
+        project_dir: Path,
+        timeout_s: int,
+        on_event: OnEvent | None = None,
+    ) -> RunResult:
+        """One read-only review.
+
+        Unlike the Claude adapter there is no separate buffered path: NDJSON is
+        the only output format worth parsing, and ``stream_ndjson`` is the only
+        implementation that reliably kills the process tree at the deadline.
+        An unattended run is the same run with nobody listening.
+        """
+        started = datetime.now()
+
+        def finish(status: str, findings_md: str, detail: str = "") -> RunResult:
+            return RunResult(
+                provider=self.name,
+                project=project_dir.name,
+                task="",
+                status=status,  # type: ignore[arg-type]
+                findings_md=findings_md,
+                started_at=started,
+                duration_s=(datetime.now() - started).total_seconds(),
+                detail=detail,
+            )
+
+        if not project_dir.is_dir():
+            return finish("failed", "", f"project path does not exist: {project_dir}")
+
+        collector = _Collector(project_dir, on_event)
+        try:
+            outcome = stream_ndjson(self.command(prompt), project_dir, timeout_s, collector)
+        except FileNotFoundError:
+            return finish("failed", "", f"`{self.binary}` is not on PATH")
+        except OSError as exc:
+            return finish("failed", "", f"could not start `{self.binary}`: {exc}")
+
+        findings = collector.findings
+
+        if collector.wrote:
+            # Before anything else, including the exit code: a run that changed
+            # files broke the promise the provider is here to keep, and "it also
+            # exited 0" is not the headline. Fail loudly and keep the output, so
+            # the digest carries the evidence.
+            return finish(
+                "failed",
+                findings,
+                f"sandbox breach — codex reported changing {', '.join(collector.wrote)}; "
+                "refusing to treat this run as read-only",
+            )
+
+        if outcome.timed_out:
+            return finish("timeout", findings, f"no output after {timeout_s}s")
+
+        if outcome.returncode != 0:
+            return finish("failed", findings, collector.error or outcome.stderr_head)
+
+        if not findings:
+            return finish("failed", "", collector.error or "no output")
+
+        return finish("ok", findings)

nightshift/adapters/copilot.py

@@ -0,0 +1,51 @@
+"""Copilot adapter — a documented stub, and currently a blocked one.
+
+**Help wanted, but the obstacle is upstream, not effort.** The scheduler, ledger,
+queue, and digest are all provider-agnostic, so this is one class against the
+contract in ``nightshift.adapters.base`` — perhaps an afternoon. It is not
+written because Copilot CLI has no enforcement primitive that clears our bar.
+
+What was checked, as of 2026-07, so the next person need not repeat it:
+
+- ``--allow-tool`` / ``--deny-tool`` exist, and deny beats allow. That much is
+  the right shape.
+- But denials are per-tool, not per-resource: a denied ``read(x)`` does not stop
+  ``shell(cat x)``. A rule one tool honours and another ignores is not a
+  boundary, it is a suggestion.
+- https://github.com/github/copilot-cli/issues/2722 (open) reports
+  ``--deny-tool="read(...)"`` blocking *all* file reads regardless of pattern,
+  and no persistent permission profile for non-interactive use.
+- The docs do not say what happens when the model reaches for a tool that was
+  never allowed in programmatic mode. That is the whole guarantee, undocumented.
+
+So the blocker is not "nobody wrote it". It is that nightshift cannot promise
+"0 files touched" on top of that, and the promise is the product. Compare
+``codex.py``, which is implemented precisely because Codex hands us an OS-level
+sandbox to stand on.
+
+If upstream ships a real allowlist — one that binds every tool, and is
+documented for non-interactive runs — then this becomes worth writing:
+
+1. ``availability()`` — is the GitHub Copilot CLI on PATH and authenticated?
+2. ``last_human_use()`` — newest mtime of whatever Copilot writes per session,
+   so nightshift stays out of the user's way. Return ``None`` if unknowable.
+3. ``run()`` — invoke Copilot headlessly against ``project_dir`` **read-only**,
+   and map its exit into ``ok`` / ``failed`` / ``timeout``.
+
+``claude_code.py`` and ``codex.py`` are both reference shapes: the first enforces
+read-only with CLI permission flags, the second with a kernel sandbox. Either is
+acceptable. Asking the model nicely is not.
+
+https://github.com/kishormorol/nightshift/issues
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from nightshift.adapters.base import StubAdapter
+
+
+@dataclass
+class CopilotAdapter(StubAdapter):
+    name: str = "copilot"

nightshift/budget.py

@@ -0,0 +1,150 @@
+"""Per-provider run ledger.
+
+Counts *attempts*, not successes: a failed or timed-out run still consumed the
+user's quota, so it still costs budget. The ledger is the only thing standing
+between a cron job and someone's monthly limit, so it errs toward counting.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date, datetime, timedelta
+from pathlib import Path
+
+from nightshift.config import Budget, state_dir
+from nightshift.store import read_json, write_json
+
+#: Ledger entries older than this are dropped when the file is loaded.
+RETENTION_DAYS = 30
+
+
+def day_key(d: date) -> str:
+    return d.isoformat()
+
+
+def week_key(d: date) -> str:
+    """ISO week key, e.g. ``2026-W29``. ISO weeks start on Monday."""
+    year, week, _ = d.isocalendar()
+    return f"{year}-W{week:02d}"
+
+
+def _week_start(key: str) -> date | None:
+    """The Monday of an ISO week key, or ``None`` if unparseable."""
+    try:
+        year_s, week_s = key.split("-W", 1)
+        return date.fromisocalendar(int(year_s), int(week_s), 1)
+    except (ValueError, TypeError):
+        return None
+
+
+def _day_start(key: str) -> date | None:
+    try:
+        return date.fromisoformat(key)
+    except (ValueError, TypeError):
+        return None
+
+
+def entry_date(key: str) -> date | None:
+    """The date a ledger key refers to, whichever form it takes."""
+    return _week_start(key) if "-W" in key else _day_start(key)
+
+
+@dataclass
+class Usage:
+    """What a provider has spent, against what it is allowed."""
+
+    day: int
+    week: int
+    max_day: int
+    max_week: int
+
+    @property
+    def day_exhausted(self) -> bool:
+        return self.day >= self.max_day
+
+    @property
+    def week_exhausted(self) -> bool:
+        return self.week >= self.max_week
+
+    @property
+    def exhausted(self) -> bool:
+        return self.day_exhausted or self.week_exhausted
+
+    def reason(self) -> str:
+        if self.day_exhausted:
+            return f"daily budget spent ({self.day}/{self.max_day} today)"
+        if self.week_exhausted:
+            return f"weekly budget spent ({self.week}/{self.max_week} this week)"
+        return ""
+
+
+def ledger_path() -> Path:
+    return state_dir() / "ledger.json"
+
+
+class Ledger:
+    """A JSON map of ``{provider: {day-or-week key: count}}``."""
+
+    def __init__(self, path: Path | None = None):
+        self.path = path or ledger_path()
+        self._data: dict[str, dict[str, int]] = self._load()
+
+    def _load(self) -> dict[str, dict[str, int]]:
+        raw = read_json(self.path, default={})
+        if not isinstance(raw, dict):
+            return {}
+        data: dict[str, dict[str, int]] = {}
+        for provider, entries in raw.items():
+            if not isinstance(provider, str) or not isinstance(entries, dict):
+                continue
+            clean: dict[str, int] = {}
+            for key, count in entries.items():
+                if isinstance(key, str) and isinstance(count, int) and not isinstance(count, bool):
+                    clean[key] = count
+            data[provider] = clean
+        return data
+
+    def prune(self, today: date | None = None) -> int:
+        """Drop entries older than :data:`RETENTION_DAYS`. Returns count removed."""
+        today = today or date.today()
+        cutoff = today - timedelta(days=RETENTION_DAYS)
+        removed = 0
+        for provider, entries in self._data.items():
+            for key in list(entries):
+                when = entry_date(key)
+                if when is None or when < cutoff:
+                    del entries[key]
+                    removed += 1
+        return removed
+
+    def count(self, provider: str, key: str) -> int:
+        return self._data.get(provider, {}).get(key, 0)
+
+    def usage(self, provider: str, budget: Budget, when: datetime | None = None) -> Usage:
+        when = when or datetime.now()
+        d = when.date()
+        return Usage(
+            day=self.count(provider, day_key(d)),
+            week=self.count(provider, week_key(d)),
+            max_day=budget.max_runs_per_day,
+            max_week=budget.max_runs_per_week,
+        )
+
+    def increment(self, provider: str, when: datetime | None = None, by: int = 1) -> None:
+        """Record ``by`` attempts against ``provider`` and persist immediately.
+
+        Persisting eagerly matters: if the process dies after spending quota but
+        before writing, the next run would happily spend it again.
+        """
+        when = when or datetime.now()
+        d = when.date()
+        entries = self._data.setdefault(provider, {})
+        for key in (day_key(d), week_key(d)):
+            entries[key] = entries.get(key, 0) + by
+        self.save()
+
+    def save(self) -> None:
+        write_json(self.path, self._data)
+
+    def as_dict(self) -> dict[str, dict[str, int]]:
+        return {p: dict(e) for p, e in self._data.items()}