nightfall-cli 0.1.0__py3-none-any.whl

nightfall/permissions.py

@@ -0,0 +1,120 @@
+"""Which tool calls need a human.
+
+The sandbox decides what is *possible*. These rules only decide what is worth
+interrupting you for - so read-only commands run silently, and the risky ones
+still stop and ask.
+"""
+
+from fnmatch import fnmatch
+from pathlib import Path
+
+PROJECT = Path.cwd().resolve()
+
+# Last matching rule wins, so put the catch-all first.
+BASH_RULES = {
+    "*": "ask",
+    # read-only: let them through
+    "ls*": "allow",
+    "pwd": "allow",
+    "cd *": "allow",
+    "echo *": "allow",
+    "sort*": "allow",
+    "uniq*": "allow",
+    "cut *": "allow",
+    "basename *": "allow",
+    "dirname *": "allow",
+    "date*": "allow",
+    "env": "allow",
+    "cat *": "allow",
+    "head *": "allow",
+    "tail *": "allow",
+    "wc *": "allow",
+    "file *": "allow",
+    "which *": "allow",
+    "grep *": "allow",
+    "rg *": "allow",
+    "find *": "allow",
+    "tree*": "allow",
+    "git status*": "allow",
+    "git diff*": "allow",
+    "git log*": "allow",
+    "git show*": "allow",
+    "git ls-files*": "allow",
+    "pytest*": "allow",
+    "python -m pytest*": "allow",
+    # risky: never, even if the user says yes
+    "rm *": "deny",
+    "sudo *": "deny",
+    "chmod *": "deny",
+    "chown *": "deny",
+    "curl *": "deny",
+    "wget *": "deny",
+    "git push*": "deny",
+    "git reset*": "deny",
+    "git clean*": "deny",
+}
+
+def split_command(command):
+    """Split a compound command on the separators that actually separate.
+
+    A naive split on | and ; also cuts inside quotes, so `rg "cap|max"` breaks
+    into fragments that match no rule and fall through to "ask". Anything
+    quoted or backslash-escaped is an argument, not a separator.
+    """
+    parts, current, quote = [], [], None
+    index = 0
+    while index < len(command):
+        char = command[index]
+        if quote:
+            current.append(char)
+            quote = None if char == quote else quote
+        elif char == "\\":
+            current.append(char)
+            index += 1
+            if index < len(command):
+                current.append(command[index])
+        elif char in "\"'":
+            quote = char
+            current.append(char)
+        elif char in "&|;":
+            parts.append("".join(current))
+            current = []
+            while index + 1 < len(command) and command[index + 1] in "&|":
+                index += 1
+        else:
+            current.append(char)
+        index += 1
+
+    parts.append("".join(current))
+    return [part.strip() for part in parts if part.strip()]
+
+
+def decide(command):
+    """Rate every part of a compound command; the strictest verdict wins."""
+    verdicts = []
+    for part in split_command(command):
+        action = "ask"
+        for pattern, rule in BASH_RULES.items():
+            if fnmatch(part, pattern):
+                action = rule
+        verdicts.append(action)
+
+    for strictest in ("deny", "ask"):
+        if strictest in verdicts:
+            return strictest
+    return "allow"
+
+
+def inside_project(path):
+    return PROJECT in Path(path).resolve().parents
+
+
+def check(name, args):
+    """Return (action, reason). Action is allow, ask or deny."""
+    if name == "bash":
+        return decide(args["command"]), f"run: {args['command']}"
+
+    if name in ("write_file", "str_replace") and not inside_project(args["path"]):
+        return "ask", f"{name} outside {PROJECT}: {args['path']}"
+
+    return "allow", None

nightfall/prompt.py

@@ -0,0 +1,61 @@
+"""The input line.
+
+`input()` cannot edit a line that has wrapped past the screen width - the
+terminal owns the wrapping and readline cannot see it. prompt_toolkit redraws
+the line itself, so deleting, word jumps and history all keep working once the
+text is longer than the screen.
+"""
+
+from pathlib import Path
+
+from prompt_toolkit import PromptSession
+from prompt_toolkit.formatted_text import HTML
+from prompt_toolkit.history import FileHistory
+from prompt_toolkit.key_binding import KeyBindings
+from prompt_toolkit.styles import Style
+
+HISTORY = Path.home() / ".agents" / "history"
+
+STYLE = Style.from_dict({"prompt": "bold #9ece6a"})
+
+bindings = KeyBindings()
+
+
+# macOS sends option-arrow as escape then arrow. Terminals configured to send
+# option as meta emit alt-b / alt-f instead, which prompt_toolkit binds itself.
+@bindings.add("escape", "left")
+def _word_left(event):
+    document = event.current_buffer.document
+    event.current_buffer.cursor_position += (
+        document.find_previous_word_beginning(count=1) or 0
+    )
+
+
+@bindings.add("escape", "right")
+def _word_right(event):
+    document = event.current_buffer.document
+    event.current_buffer.cursor_position += (
+        document.find_next_word_ending(count=1) or 0
+    )
+
+
+@bindings.add("escape", "enter")
+def _newline(event):
+    """Option-enter starts a new line instead of sending the message."""
+    event.current_buffer.insert_text("\n")
+
+
+SESSION = None
+
+
+def read(prompt="> "):
+    """Read one message. Raises EOFError on ctrl-d, like input() does."""
+    global SESSION
+    if SESSION is None:
+        HISTORY.parent.mkdir(parents=True, exist_ok=True)
+        SESSION = PromptSession(
+            history=FileHistory(str(HISTORY)),
+            key_bindings=bindings,
+            style=STYLE,
+        )
+    return SESSION.prompt(HTML(f"<prompt>{prompt}</prompt>"))

nightfall/sandbox.py

@@ -0,0 +1,210 @@
+"""Platform-backed command sandboxing."""
+
+from __future__ import annotations
+
+import ctypes
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+PROJECT = Path.cwd().resolve()
+
+
+class SandboxUnavailable(RuntimeError):
+    """Raised when a platform sandbox cannot be initialized."""
+
+
+class Backend:
+    label = "none"
+
+    def name(self) -> str:
+        return self.label
+
+    def run(self, command: str, timeout: int = 60) -> subprocess.CompletedProcess:
+        raise NotImplementedError
+
+
+class SeatbeltBackend(Backend):
+    label = "seatbelt"
+
+    def __init__(self, project: Path):
+        self.project = project
+
+    def wrap(self, command: str) -> list[str]:
+        profile = Path(tempfile.gettempdir()) / "nightfall.sb"
+        profile.write_text(
+            "(version 1)\n"
+            "(deny default)\n"
+            "(allow process-exec process-fork signal)\n"
+            "(allow file-read*)\n"
+            "(allow sysctl-read)\n"
+            "(deny network*)\n"
+            f'(allow file-write* (subpath "{self.project}") '
+            '(literal "/dev/null"))\n'
+            f'(deny file-write* (subpath "{self.project / ".git"}"))\n'
+        )
+        return ["sandbox-exec", "-f", str(profile), "/bin/sh", "-c", command]
+
+    def run(self, command: str, timeout: int = 60) -> subprocess.CompletedProcess:
+        return subprocess.run(
+            self.wrap(command), capture_output=True, text=True, timeout=timeout
+        )
+
+
+class BubblewrapBackend(Backend):
+    label = "bubblewrap"
+
+    def __init__(self, project: Path):
+        self.project = project
+
+    def wrap(self, command: str) -> list[str]:
+        return [
+            "bwrap", "--ro-bind", "/", "/", "--bind", str(self.project), str(self.project),
+            "--dev", "/dev", "--proc", "/proc", "--unshare-net", "--die-with-parent",
+            "/bin/sh", "-c", command,
+        ]
+
+    def run(self, command: str, timeout: int = 60) -> subprocess.CompletedProcess:
+        return subprocess.run(
+            self.wrap(command), capture_output=True, text=True, timeout=timeout
+        )
+
+
+class _BasicLimits(ctypes.Structure):
+    _fields_ = [
+        ("PerProcessUserTimeLimit", ctypes.c_longlong),
+        ("PerJobUserTimeLimit", ctypes.c_longlong),
+        ("LimitFlags", ctypes.c_uint32),
+        ("MinimumWorkingSetSize", ctypes.c_size_t),
+        ("MaximumWorkingSetSize", ctypes.c_size_t),
+        ("ActiveProcessLimit", ctypes.c_uint32),
+        ("Affinity", ctypes.c_size_t),
+        ("PriorityClass", ctypes.c_uint32),
+        ("SchedulingClass", ctypes.c_uint32),
+    ]
+
+
+class _IoCounters(ctypes.Structure):
+    _fields_ = [("value", ctypes.c_ulonglong) for _ in range(6)]
+
+
+class _ExtendedLimits(ctypes.Structure):
+    _fields_ = [
+        ("BasicLimitInformation", _BasicLimits),
+        ("IoInfo", _IoCounters),
+        ("ProcessMemoryLimit", ctypes.c_size_t),
+        ("JobMemoryLimit", ctypes.c_size_t),
+        ("PeakProcessMemoryUsed", ctypes.c_size_t),
+        ("PeakJobMemoryUsed", ctypes.c_size_t),
+    ]
+
+
+class WindowsBackend(Backend):
+    """Native Windows process containment using Job Objects."""
+
+    label = "windows-appcontainer"
+    JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE = 0x00002000
+    JOB_OBJECT_EXTENDED_LIMIT_INFORMATION = 9
+    CREATE_NEW_PROCESS_GROUP = 0x00000200
+    CREATE_NO_WINDOW = 0x08000000
+
+    def __init__(self, project: Path):
+        if sys.platform != "win32":
+            raise SandboxUnavailable("Windows sandbox requested on a non-Windows host")
+        self.project = project
+        try:
+            self.kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+            self._configure_api()
+        except (AttributeError, OSError) as error:
+            raise SandboxUnavailable(
+                "Windows native sandbox APIs are unavailable; use a supported Windows runtime."
+            ) from error
+
+    def _configure_api(self):
+        self.kernel32.CreateJobObjectW.restype = ctypes.c_void_p
+        self.kernel32.SetInformationJobObject.argtypes = [
+            ctypes.c_void_p, ctypes.c_int, ctypes.c_void_p, ctypes.c_uint32
+        ]
+        self.kernel32.AssignProcessToJobObject.argtypes = [ctypes.c_void_p, ctypes.c_void_p]
+        self.kernel32.TerminateJobObject.argtypes = [ctypes.c_void_p, ctypes.c_uint32]
+        self.kernel32.CloseHandle.argtypes = [ctypes.c_void_p]
+
+    def wrap(self, command: str) -> list[str]:
+        return ["cmd.exe", "/d", "/s", "/c", command]
+
+    def _job(self):
+        handle = self.kernel32.CreateJobObjectW(None, None)
+        if not handle:
+            raise SandboxUnavailable(f"CreateJobObjectW failed: {ctypes.get_last_error()}")
+        limits = _ExtendedLimits()
+        limits.BasicLimitInformation.LimitFlags = self.JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE
+        if not self.kernel32.SetInformationJobObject(
+            handle, self.JOB_OBJECT_EXTENDED_LIMIT_INFORMATION,
+            ctypes.byref(limits), ctypes.sizeof(limits)
+        ):
+            self.kernel32.CloseHandle(handle)
+            raise SandboxUnavailable(
+                f"SetInformationJobObject failed: {ctypes.get_last_error()}"
+            )
+        return handle
+
+    def run(self, command: str, timeout: int = 60) -> subprocess.CompletedProcess:
+        job = self._job()
+        argv = self.wrap(command)
+        try:
+            process = subprocess.Popen(
+                argv, cwd=str(self.project), stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+                text=True, creationflags=self.CREATE_NEW_PROCESS_GROUP | self.CREATE_NO_WINDOW,
+            )
+            if not self.kernel32.AssignProcessToJobObject(job, ctypes.c_void_p(process._handle)):
+                process.kill()
+                raise SandboxUnavailable(
+                    f"AssignProcessToJobObject failed: {ctypes.get_last_error()}"
+                )
+            try:
+                stdout, stderr = process.communicate(timeout=timeout)
+            except subprocess.TimeoutExpired:
+                self.kernel32.TerminateJobObject(job, 1)
+                stdout, stderr = process.communicate()
+                raise subprocess.TimeoutExpired(timeout, argv, stdout, stderr)
+            return subprocess.CompletedProcess(argv, process.returncode, stdout, stderr)
+        finally:
+            self.kernel32.CloseHandle(job)
+
+
+class UnavailableBackend(Backend):
+    label = "unavailable"
+
+    def run(self, command: str, timeout: int = 60) -> subprocess.CompletedProcess:
+        raise SandboxUnavailable(
+            "No supported OS sandbox is available. Install Bubblewrap on Linux "
+            "or use a supported macOS/Windows runtime."
+        )
+
+
+def _select_backend() -> Backend:
+    if sys.platform == "darwin":
+        return SeatbeltBackend(PROJECT)
+    if sys.platform.startswith("linux") and shutil.which("bwrap"):
+        return BubblewrapBackend(PROJECT)
+    if sys.platform == "win32":
+        return WindowsBackend(PROJECT)
+    return UnavailableBackend()
+
+
+BACKEND = _select_backend()
+
+
+def name() -> str:
+    return BACKEND.name()
+
+
+def wrap(command: str):
+    wrapper = getattr(BACKEND, "wrap", None)
+    return wrapper(command) if wrapper else None
+
+
+def run(command: str, timeout: int = 60) -> subprocess.CompletedProcess:
+    return BACKEND.run(command, timeout)

nightfall/session.py

@@ -0,0 +1,86 @@
+"""Transcripts on disk. One JSONL file per chat."""
+
+import json
+from datetime import datetime
+from pathlib import Path
+
+PROJECT = str(Path.cwd().resolve()).replace("/", "-")
+SESSION_DIR = Path.home() / ".agents" / "sessions" / PROJECT
+CURRENT = datetime.now().strftime("%Y%m%d-%H%M%S")
+WRITTEN = 0  # how many messages are already on disk
+
+
+def path_for(session_id):
+    return SESSION_DIR / f"{session_id}.jsonl"
+
+
+def save(messages):
+    """Append what is new. Never rewrite what is already on disk."""
+    global WRITTEN
+    SESSION_DIR.mkdir(parents=True, exist_ok=True)
+    with path_for(CURRENT).open("a") as f:
+        for message in messages[WRITTEN:]:
+            f.write(json.dumps(message) + "\n")
+    WRITTEN = len(messages)
+
+
+def rewind_to(count):
+    """Record a rewind as an entry, so the old messages stay in the file."""
+    global WRITTEN
+    with path_for(CURRENT).open("a") as f:
+        f.write(json.dumps({"rewind_to": count}) + "\n")
+    WRITTEN = count
+
+
+def compacted(messages):
+    """Compaction rewrites history, so record the result and start from it."""
+    global WRITTEN
+    with path_for(CURRENT).open("a") as f:
+        f.write(json.dumps({"compacted": messages}) + "\n")
+    WRITTEN = len(messages)
+
+
+def load(session_id):
+    """Replay the log: messages accumulate, rewinds cut them back."""
+    messages = []
+    for line in path_for(session_id).read_text().splitlines():
+        try:
+            entry = json.loads(line)
+        except json.JSONDecodeError:
+            # A half-written last line, usually from a kill mid-save. Skipping
+            # it costs one message; raising would break /sessions for every
+            # chat in the project, because listing them all calls load().
+            continue
+        if "rewind_to" in entry:
+            del messages[entry["rewind_to"]:]
+        elif "compacted" in entry:
+            messages = list(entry["compacted"])
+        else:
+            messages.append(entry)
+    return messages
+
+
+def open_session(session_id):
+    """Switch to a past chat and become it."""
+    global CURRENT, WRITTEN
+    CURRENT = session_id
+    messages = load(session_id)
+    WRITTEN = len(messages)
+    return messages
+
+
+def title(messages):
+    for message in messages:
+        if message["role"] == "user":
+            return " ".join(str(message.get("content") or "").split())[:60]
+    return "(empty)"
+
+
+def all_sessions():
+    """Newest first."""
+    if not SESSION_DIR.exists():
+        return []
+    files = sorted(
+        SESSION_DIR.glob("*.jsonl"), key=lambda p: p.stat().st_mtime, reverse=True
+    )
+    return [{"id": p.stem, "title": title(load(p.stem))} for p in files]

nightfall/skills.py

@@ -0,0 +1,34 @@
+from pathlib import Path
+
+import yaml
+
+SKILL_DIRS = [
+    Path.cwd() / ".agents" / "skills",
+    Path.home() / ".agents" / "skills",
+]
+
+
+def find_skills():
+    """Map each skill name to its description and SKILL.md path."""
+    skills = {}
+    for directory in SKILL_DIRS:
+        for path in sorted(directory.glob("*/SKILL.md")):
+            _, frontmatter, _ = path.read_text().split("---", 2)
+            meta = yaml.safe_load(frontmatter)
+            description = " ".join(meta["description"].split())
+            skills[meta["name"]] = {"description": description, "path": path}
+    return skills
+
+
+SKILLS = find_skills()
+
+
+def skills_prompt():
+    return "\n".join(f"- {name}: {s['description']}" for name, s in SKILLS.items())
+
+
+def read_skill(name: str) -> str:
+    """Open a skill and return its full instructions."""
+    if name not in SKILLS:
+        return f"No skill named '{name}'."
+    return SKILLS[name]["path"].read_text()

nightfall/subagent.py

@@ -0,0 +1,166 @@
+"""Subagents: exploration that happens somewhere else.
+
+A subagent is a whole agent loop with its own message list. That list is never
+shown to the main agent and never outlives the call - the only thing that
+crosses back is the final report.
+
+That is the entire point, and it is compact.py's idea from the other end.
+Exploring a repo burns tens of thousands of tokens of tool output to produce a
+few hundred tokens of answer. compact.py throws context away after it has been
+spent; a subagent spends it somewhere that gets thrown away by design, so the
+main transcript never pays for the difference at all.
+
+Four rules, and the code below is really just these:
+
+  1. it starts from an empty history          (no memory of anything)
+  2. it holds every tool but two              (no recursion, no touching the plan)
+  3. it runs the same loop as the main agent  (nothing special happens here)
+  4. only its last message comes back         (the rest is discarded)
+"""
+
+import os
+
+MAX_TURNS = 12  # a runaway explorer is worse than a missing answer
+
+
+# --- rule 2 -----------------------------------------------------------------
+# `task` would let a subagent spawn subagents, forever. `write_todos` writes to
+# a module global that belongs to the main agent's plan, and this one is a
+# guest in someone else's session. Everything else it gets.
+#
+# Note this is a *structural* guarantee - those tools are simply not in the
+# list it is offered, so it cannot call them. The "do not edit files" rule in
+# the prompt below is only asking nicely. To make that one structural too, add
+# write_file and str_replace to this set.
+WITHHELD = {"task", "write_todos", "str_replace", "write"}
+
+
+SYSTEM_PROMPT = f"""
+You are an exploration subagent. You were given one question by a lead agent
+and you answer it. That is the whole job.
+
+You cannot see the conversation that spawned you, and the lead agent cannot
+see anything you do here. Only your final message crosses back, so it has to
+stand on its own.
+
+You are working in {os.getcwd()}. Search inside it. Never search from / or
+from the home directory - that scans the whole machine and will time out.
+
+How to work:
+- Use bash, read_file and read_skill to find out what is actually true.
+  Prefer rg, grep and find to guess at where things live.
+- You are here to read and report, not to change anything. Do not write or
+  edit files, and do not run commands with side effects.
+- Search in batches. Several greps in one turn beats one grep per turn.
+- Stop as soon as you can answer. Do not keep looking to be thorough.
+
+Your final message is the entire report, and it is the only thing that costs
+the lead agent anything - so keep it short. Aim for under 150 words. Findings
+only: file paths with line numbers, names, values. No preamble, no restating
+the question, no long code blocks - cite the path and line and let the lead
+agent open it. Say plainly what you could not find; a gap is useful, a guess
+is not.
+"""
+
+
+def toolset():
+    """Every tool except the ones a guest should not hold."""
+    from .tools import TOOL_SCHEMAS
+
+    return [s for s in TOOL_SCHEMAS if s["function"]["name"] not in WITHHELD]
+
+
+def task(description: str) -> str:
+    """Run a fresh agent on one question and return only its final answer."""
+    # Imported inside the function, not at the top: llm imports tools, and
+    # tools imports us, so importing them up there would close the circle.
+    from .history import fit
+    from .llm import call_llm
+    from .tools import execute
+    from .ui import ui
+
+    # --- rule 1 ---
+    # Two messages. Not a copy of the caller's transcript, not a trimmed
+    # version of it, and not whatever the last subagent left behind - this
+    # list is born here and dies at the return statement.
+    messages = [
+        {"role": "system", "content": SYSTEM_PROMPT},
+        {"role": "user", "content": description},
+    ]
+    ui.subagent(description)
+
+    report = None  # newest thing it has said, kept in case we run out of turns
+
+    # --- rule 3 ---
+    # Compare this with the inner loop in agent.py: call, append, run the
+    # tools, append, repeat. A subagent is not a new kind of thing. It is the
+    # loop you already have, pointed at a different list of messages.
+    for _ in range(MAX_TURNS):
+        fit(messages)  # its context can overflow too, and nobody compacts it
+
+        with ui.working("subagent exploring"):
+            message, usage = call_llm(messages, tools=toolset())
+
+        messages.append(message.model_dump(exclude_none=True))
+        ui.usage(usage)
+        report = message.content or report
+
+        # --- rule 4 ---
+        # No tool calls means it has stopped looking and started answering.
+        # `messages` goes out of scope on this line - every tool result it
+        # gathered, every path it explored, all of it. One string comes back.
+        if not message.tool_calls:
+            return report or "(the subagent came back with nothing)"
+
+        for tool_call in message.tool_calls:
+            # The same executor the main loop uses, so the same permission
+            # rules and the same sandbox apply. A subagent is a second caller,
+            # not a privileged one - it is not a way around any of that.
+            args, result = execute(tool_call)
+            ui.tool(tool_call.function.name, args, result, nested=True)
+            messages.append({
+                "role": "tool",
+                "tool_call_id": tool_call.id,
+                "content": result,
+            })
+
+    # Out of turns. Hand back whatever it last managed to say rather than
+    # nothing at all - a partial finding still beats making the lead agent
+    # start the whole search again from scratch.
+    if report:
+        return (
+            f"(stopped after {MAX_TURNS} turns, before finishing. Partial "
+            f"findings below - narrow the question and ask again.)\n\n{report}"
+        )
+    return f"(stopped after {MAX_TURNS} turns with nothing to report.)"
+
+
+TASK_SCHEMA = {
+    "type": "function",
+    "function": {
+        "name": "task",
+        "description": (
+            "Hand a self-contained exploration question to a fresh agent that "
+            "has its own context window, and get back its findings. Use this "
+            "to learn how the codebase works - tracing behaviour, locating "
+            "where something is implemented, surveying files - so the search "
+            "costs you one answer instead of dozens of tool results. It cannot "
+            "see this conversation, so include every detail it needs. It reads "
+            "and reports; it never edits. Do your own editing."
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "description": {
+                    "type": "string",
+                    "description": (
+                        "The question, written to stand alone: what to find "
+                        "out, where to start looking, and what the answer "
+                        "should contain."
+                    ),
+                }
+            },
+            "required": ["description"],
+        },
+    },
+}