nightfall-cli 0.1.0__py3-none-any.whl

nightfall/todos.py

@@ -0,0 +1,66 @@
+"""The plan. Lives here, not in the transcript, and is re-injected every turn."""
+
+MARKS = {"pending": "[ ]", "in_progress": "[~]", "done": "[x]"}
+
+TODOS = []  # [{"content": ..., "activeForm": ..., "status": ...}]
+
+
+def write_todos(todos):
+    """Replace the whole list. Exactly one task may be in_progress."""
+    active = [t for t in todos if t["status"] == "in_progress"]
+    if len(active) > 1:
+        return f"Error: {len(active)} tasks are in_progress. Only one may be."
+
+    TODOS[:] = todos
+    return todos_prompt() or "Todo list cleared."
+
+
+def todos_prompt():
+    return "\n".join(f"{MARKS[t['status']]} {t['content']}" for t in TODOS)
+
+
+def active_form():
+    """What the agent is doing right now, for the spinner."""
+    for todo in TODOS:
+        if todo["status"] == "in_progress":
+            return todo["activeForm"]
+    return "thinking"
+
+
+TODO_SCHEMA = {
+    "type": "function",
+    "function": {
+        "name": "write_todos",
+        "description": (
+            "Record the plan for a multi-step task. Send the whole list every "
+            "time. Keep exactly one task in_progress and update it as you go."
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "todos": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "content": {
+                                "type": "string",
+                                "description": "The task, imperative: 'Fix the parser'",
+                            },
+                            "activeForm": {
+                                "type": "string",
+                                "description": "Present continuous: 'Fixing the parser'",
+                            },
+                            "status": {
+                                "type": "string",
+                                "enum": ["pending", "in_progress", "done"],
+                            },
+                        },
+                        "required": ["content", "activeForm", "status"],
+                    },
+                }
+            },
+            "required": ["todos"],
+        },
+    },
+}

nightfall/tools.py

@@ -0,0 +1,198 @@
+import json
+import subprocess
+
+from . import history
+from . import sandbox
+from .permissions import check
+from .subagent import TASK_SCHEMA, task
+from .skills import read_skill
+from .todos import TODO_SCHEMA, write_todos
+
+
+def bash(command: str) -> str:
+    """Run a shell command and return its combined stdout and stderr."""
+    try:
+        result = sandbox.run(command)
+    except subprocess.TimeoutExpired as expired:
+        # Hand the failure back as a result. A slow command is the model's
+        # problem to work around, not a reason to take the session down.
+        return (
+            f"Timed out after {expired.timeout}s and was killed. "
+            "Narrow it down - search inside the working directory rather than /."
+        )
+    return history.cap((result.stdout + result.stderr) or "(no output)")
+
+
+def read_file(path: str) -> str:
+    """Read a file and return its contents."""
+    with open(path) as f:
+        return history.cap(f.read())
+
+
+def write_file(path: str, content: str) -> str:
+    """Create a file, or overwrite it if it already exists."""
+    with open(path, "w") as f:
+        f.write(content)
+    return f"Wrote {path}"
+
+
+def str_replace(path, old_str, new_str, allow_multi_edit=False):
+    """Swap exact text in a file. old_str must match exactly once."""
+    with open(path) as f:
+        content = f.read()
+
+    count = content.count(old_str)
+    if count == 0:
+        return f"Error: old_str was not found in {path}"
+    if count > 1 and not allow_multi_edit:
+        return (
+            f"Error: old_str matches {count} times in {path}. "
+            "Add surrounding lines to make it unique, "
+            "or set allow_multi_edit to replace them all."
+        )
+
+    with open(path, "w") as f:
+        f.write(content.replace(old_str, new_str))
+    return f"Replaced {count} match(es) in {path}"
+
+
+def execute(tool_call):
+    """Run one tool call through the permission layer.
+
+    Shared by the main loop and by subagents, so a subagent is fenced in by
+    exactly the same rules - it is not a way around them.
+
+    A tool call is text the model wrote, so all of it is untrusted: the name
+    may not exist, the arguments may not be JSON, and they may not match the
+    signature. Every one of those comes back as a result the model can read
+    and retry. None of them is allowed to end the session.
+    """
+    from .ui import ui
+
+    name = tool_call.function.name
+    try:
+        args = json.loads(tool_call.function.arguments)
+    except json.JSONDecodeError as broken:
+        return {}, f"Error: arguments were not valid JSON ({broken})."
+
+    if name not in TOOLS:
+        return args, f"Error: no tool named '{name}'. Available: {', '.join(TOOLS)}."
+
+    try:
+        action, reason = check(name, args)
+        if action == "deny":
+            return args, f"Blocked by policy: {reason}"
+        if action == "ask" and not ui.approve(reason):
+            return args, "The user denied this tool call."
+        return args, TOOLS[name](**args)
+    except TypeError as mismatch:
+        return args, f"Error: wrong arguments for {name} ({mismatch})."
+    except KeyError as missing:
+        return args, f"Error: {name} needs an argument you did not send: {missing}."
+    except Exception as failure:  # noqa: BLE001 - the model gets to see and retry
+        return args, f"Error: {name} failed - {type(failure).__name__}: {failure}"
+
+
+TOOL_SCHEMAS = [
+    {
+        "type": "function",
+        "function": {
+            "name": "bash",
+            "description": "Run a shell command and return its combined stdout and stderr.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "command": {
+                        "type": "string",
+                        "description": "The shell command to run",
+                    }
+                },
+                "required": ["command"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "read_file",
+            "description": "Read a file and return its contents.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "path": {
+                        "type": "string",
+                        "description": "Path to the file to read",
+                    }
+                },
+                "required": ["path"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "read_skill",
+            "description": "Open a skill by name and return its full instructions.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "name": {
+                        "type": "string",
+                        "description": "Name of the skill to open",
+                    }
+                },
+                "required": ["name"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "write_file",
+            "description": "Create a file, or overwrite it if it already exists.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "path": {"type": "string", "description": "File to write"},
+                    "content": {"type": "string", "description": "The full contents"},
+                },
+                "required": ["path", "content"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "str_replace",
+            "description": (
+                "Replace exact text in a file. old_str must appear exactly once, "
+                "so include surrounding lines if needed."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "path": {"type": "string", "description": "File to edit"},
+                    "old_str": {"type": "string", "description": "Exact text to find"},
+                    "new_str": {"type": "string", "description": "Text to put in its place"},
+                    "allow_multi_edit": {
+                        "type": "boolean",
+                        "description": "Replace every match instead of failing",
+                    },
+                },
+                "required": ["path", "old_str", "new_str"],
+            },
+        },
+    },
+    TODO_SCHEMA,
+    TASK_SCHEMA,
+]
+
+TOOLS = {
+    "bash": bash,
+    "read_file": read_file,
+    "write_file": write_file,
+    "str_replace": str_replace,
+    "read_skill": read_skill,
+    "write_todos": write_todos,
+    "task": task,
+}

nightfall/ui.py

@@ -0,0 +1,290 @@
+"""Terminal presentation layer.
+
+Knows nothing about LLMs, providers or tools - it only receives plain strings
+and dicts and decides how they look.
+"""
+
+import json
+from contextlib import contextmanager
+
+from rich.console import Console, Group
+from rich.json import JSON
+from rich.markdown import Markdown
+from rich.padding import Padding
+from rich.panel import Panel
+from rich.rule import Rule
+from rich.table import Table
+from rich.text import Text
+
+from . import prompt
+from .todos import MARKS
+
+ACCENT = "#7aa2f7"
+USER = "#9ece6a"
+TOOL = "#e0af68"
+MUTED = "#565f89"
+
+MAX_TOOL_OUTPUT_LINES = 12
+
+TODO_STYLES = {
+    "done": f"{MUTED} strike",
+    "in_progress": f"bold {ACCENT}",
+    "pending": MUTED,
+}
+
+
+class UI:
+    def __init__(self):
+        self.console = Console()
+        self._totals = {}
+
+    # ---------------------------------------------------------------- input
+
+    def banner(self, sandbox_name="none"):
+        self.console.print()
+        self.console.print(
+            Rule(Text(" coding agent ", style=f"bold {ACCENT}"), style=MUTED)
+        )
+        self.console.print(
+            Padding(Text(f"sandbox: {sandbox_name}  ·  opt-enter for a newline  ·  ctrl-d to exit", style=MUTED), (0, 0, 0, 2))
+        )
+
+    def clear(self):
+        self.console.clear()
+
+    def resumed(self, messages, label="resumed"):
+        turns = sum(1 for m in messages if m["role"] == "user")
+        self.console.print(
+            Padding(
+                Text(f"{label} · {len(messages)} messages · {turns} turns", style=MUTED),
+                (0, 0, 0, 2),
+            )
+        )
+
+    def replay(self, messages):
+        """Redraw a loaded transcript so the screen matches the history."""
+        results = {m["tool_call_id"]: m["content"] for m in messages if m["role"] == "tool"}
+        for message in messages:
+            if message["role"] == "user":
+                self.user(message["content"])
+            elif message["role"] == "assistant":
+                if message.get("content"):
+                    self.agent(message["content"])
+                for call in message.get("tool_calls") or []:
+                    self.tool(
+                        call["function"]["name"],
+                        json.loads(call["function"]["arguments"]),
+                        results.get(call["id"], ""),
+                    )
+
+    def approve(self, reason):
+        self.console.print(Padding(Text(reason, style=f"bold {TOOL}"), (1, 0, 0, 2)))
+        try:
+            answer = prompt.read("  allow? (y/n)> ").strip()
+        except (EOFError, KeyboardInterrupt):
+            return False
+        return answer.lower().startswith("y")
+
+    def note(self, text):
+        self.console.print(Padding(Text(text, style=MUTED), (1, 0, 0, 2)))
+
+    def pick(self, title, rows):
+        """Numbered list; returns the chosen index or None."""
+        self.console.print(Padding(Text(title, style=f"bold {ACCENT}"), (1, 0, 0, 2)))
+        for i, row in enumerate(rows):
+            self.console.print(Padding(Text(f"{i:>3}  {row}", style=MUTED), (0, 0, 0, 2)))
+        try:
+            answer = prompt.read("\n  number> ").strip()
+        except (EOFError, KeyboardInterrupt):
+            return None
+        return int(answer) if answer.isdigit() and int(answer) < len(rows) else None
+
+    def ask(self):
+        self.console.print()
+        try:
+            return prompt.read("> ").strip()
+        except (EOFError, KeyboardInterrupt):
+            self.console.print()
+            return ""
+
+    # --------------------------------------------------------------- output
+
+    def user(self, text):
+        self.console.print(
+            Padding(Text(text.strip(), style=f"bold {USER}"), (1, 0, 0, 2))
+        )
+
+    def agent(self, text):
+        self.console.print(
+            Padding(
+                Group(
+                    Text("agent", style=f"bold {ACCENT}"),
+                    Padding(Markdown(text.strip()), (1, 0, 0, 0)),
+                ),
+                (1, 2, 0, 2),
+            )
+        )
+
+    def tool(self, name, args, result, nested=False):
+        if name == "write_todos" and args.get("todos"):
+            return self.todos(args["todos"])
+
+        header = Text.assemble(
+            (f"{name} ", f"bold {TOOL}"),
+            (self._format_args(args), MUTED),
+        )
+        self.console.print(
+            Padding(
+                Panel(
+                    Group(header, Rule(style=MUTED), self._format_result(result)),
+                    border_style=MUTED,
+                    padding=(0, 1),
+                ),
+                (1, 2, 0, 6 if nested else 2),
+            )
+        )
+
+    def subagent(self, description):
+        """Shown to you, never to the main agent - it only gets the report."""
+        self.console.print(
+            Padding(
+                Panel(
+                    Text(description.strip(), style=MUTED),
+                    title=Text("subagent · own context", style=f"bold {ACCENT}"),
+                    title_align="left",
+                    border_style=ACCENT,
+                    padding=(0, 1),
+                ),
+                (1, 2, 0, 4),
+            )
+        )
+
+    def injection(self, text):
+        self.console.print(
+            Padding(
+                Panel(
+                    Text(text.strip(), style=MUTED),
+                    title=Text("late injection", style=f"italic {MUTED}"),
+                    title_align="left",
+                    border_style=MUTED,
+                    padding=(0, 1),
+                ),
+                (1, 2, 0, 2),
+            )
+        )
+
+    def debug(self, data):
+        self.console.print(
+            Padding(
+                Panel(
+                    JSON.from_data(data),
+                    title=Text("raw response", style=f"italic {MUTED}"),
+                    title_align="left",
+                    border_style=TOOL,
+                    padding=(0, 1),
+                ),
+                (1, 2, 0, 2),
+            )
+        )
+
+    @contextmanager
+    def working(self, label="thinking"):
+        with self.console.status(
+            Text(label, style=MUTED), spinner="dots", spinner_style=ACCENT
+        ):
+            yield
+
+    # ---------------------------------------------------------------- usage
+
+    def usage(self, stats):
+        for key, value in stats.items():
+            self._totals[key] = self._totals.get(key, 0) + (value or 0)
+
+        parts = " · ".join(
+            f"{value:,} {key.replace('_tokens', '')}"
+            for key, value in stats.items()
+            if value
+        )
+        self.console.print(Padding(Text(parts, style=MUTED), (1, 0, 0, 2)))
+
+    def summary(self):
+        if not self._totals:
+            return
+
+        table = Table.grid(padding=(0, 2))
+        table.add_column(style=MUTED)
+        table.add_column(style=f"bold {ACCENT}", justify="right")
+        for key, value in self._totals.items():
+            table.add_row(key.replace("_", " "), f"{value:,}")
+
+        self.console.print(Padding(table, (1, 2)))
+        self.console.print(Rule(style=MUTED))
+        self.console.print()
+
+    def compacted(self, before, messages):
+        summary = next(
+            (m["content"] for m in messages if "<summary>" in (m.get("content") or "")),
+            "",
+        )
+        self.console.print(
+            Padding(
+                Panel(
+                    Markdown(summary.replace("<summary>", "").replace("</summary>", "")),
+                    title=Text(
+                        f"compacted · {before} → {len(messages)} messages",
+                        style=f"bold {TOOL}",
+                    ),
+                    title_align="left",
+                    border_style=TOOL,
+                    padding=(0, 1),
+                ),
+                (1, 2, 0, 2),
+            )
+        )
+
+    def todos(self, todos):
+        """The plan, as a checklist. The raw tool output is never worth showing."""
+        done = sum(1 for t in todos if t["status"] == "done")
+
+        rows = Table.grid(padding=(0, 1))
+        rows.add_column(no_wrap=True)
+        rows.add_column(overflow="fold")
+        for todo in todos:
+            status = todo["status"]
+            style = TODO_STYLES[status]
+            rows.add_row(
+                Text(MARKS[status], style=style),
+                Text(todo["content"], style=style),
+            )
+
+        self.console.print(
+            Padding(
+                Panel(
+                    rows,
+                    title=Text(f"todos {done}/{len(todos)}", style=f"bold {TOOL}"),
+                    title_align="left",
+                    border_style=MUTED,
+                    padding=(0, 1),
+                ),
+                (1, 2, 0, 2),
+            )
+        )
+
+    # -------------------------------------------------------------- helpers
+
+    def _format_args(self, args):
+        if len(args) == 1:
+            return str(next(iter(args.values())))
+        return json.dumps(args)
+
+    def _format_result(self, result):
+        lines = result.strip().splitlines() or ["(no output)"]
+        shown = lines[:MAX_TOOL_OUTPUT_LINES]
+        body = Text("\n".join(shown), style=MUTED)
+        hidden = len(lines) - len(shown)
+        if hidden > 0:
+            body.append(f"\n… {hidden} more lines", style=f"italic {TOOL}")
+        return body
+
+
+ui = UI()

nightfall_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,58 @@
+Metadata-Version: 2.5
+Name: nightfall-cli
+Version: 0.1.0
+Summary: A minimal coding agent
+Requires-Python: >=3.10
+Requires-Dist: openai>=3.5.0
+Requires-Dist: prompt-toolkit>=3.0.53
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: rich>=15.0.0
+Description-Content-Type: text/markdown
+
+# Nightfall CLI
+
+A minimal coding agent harness in Python, built to show how the pieces of a coding agent fit together.
+
+This is the Nightfall CLI repository, a small coding-agent harness built from scratch.
+
+https://github.com/user-attachments/assets/e4aaa9e4-69ec-40e3-8f5a-e4ec8c5b7208
+
+## Getting started
+
+Install the project with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv sync
+```
+
+Configure an OpenAI-compatible endpoint and key in `~/.agents/env`:
+
+```text
+BASE_URL=https://your-endpoint/v1
+API_KEY=your-api-key
+MODEL=your-model-name
+```
+
+Start the agent from the repository root:
+
+```bash
+uv run nightfall
+```
+
+Use `uv run nightfall --resume` to resume the latest saved session or
+`uv run nightfall --debug` to display raw model responses. The sandbox backend
+is selected automatically for the host operating system.
+
+
+## Features
+
+- Interactive terminal chat 
+- Tools for running shell commands, reading and writing files, and making targeted edits.
+- Configurable model and OpenAI-compatible API endpoint.
+- Tool permissions and shell sandboxing on macOS, Linux, and Windows
+- Skills loaded from project and user `.agents/skills` directories.
+- Subagents for exploring a codebase in a separate context window.
+- Todo tracking for tasks with multiple steps.
+- Saved chat sessions, with `/sessions` to reopen them and `/rewind` to go back in the conversation.
+- Automatic context compaction, plus `/compact` to trigger it manually.
+- Git branch context and reminders when files change between turns.

nightfall_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+nightfall/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+nightfall/agent.py,sha256=Jx5tyhi9rOzC63MdUIfEIu44nu7dVVtNzOyYFisjJWQ,2543
+nightfall/commands.py,sha256=D7eoBloTck9vs79nfCTm3R6fPOvjQ4tst15aj_2O0fM,2389
+nightfall/compact.py,sha256=BQeGUoD4e7HpUtkiWZf8mFvvzz6lnLIVdvzkD6knnmI,4491
+nightfall/config.py,sha256=goO7qzg46ZYA-7O8xcv5Wgc886W426s4yH043q0Zv4w,784
+nightfall/context.py,sha256=ZMrYBpuhQP3LWIBNMCvuEegrkEvcsCJnJ3wumiLtQfA,2008
+nightfall/history.py,sha256=C6C2JRHGctb1zfLEH-zNwK87jhhwN-VRYjl1a6ZIA-g,4449
+nightfall/llm.py,sha256=T4ltsR2iS203xa7Kluy6476BhiK-VS4IKZzZJN_l1Nk,3118
+nightfall/permissions.py,sha256=9M-PztNi_hoAlREndJTvxM0Y6_Q1XzdOWA3WQQ14324,3392
+nightfall/prompt.py,sha256=6gLswlqAflBXaT8LKt3NBARD--I2mfQZSvMKwS1AW10,1848
+nightfall/sandbox.py,sha256=1sC__he9GJKAG6QqSTeBozcMM_BMgg_-P1UzInOwNhI,7272
+nightfall/session.py,sha256=qVmtDUZ9u2c3nBKyB163Oi309IMrojdgvCekwO-rhTE,2655
+nightfall/skills.py,sha256=uzmiDk-sRFUGtwDXQMnaCByiR5mamKaGiq07UHdL8xs,942
+nightfall/subagent.py,sha256=fDB5SzKOkv03LCccJuDw9-Q9K02DwkOpL0ulX4yUb_A,7134
+nightfall/todos.py,sha256=iFmYI-x6mO_I52zIJnWMK8LeoEA3OYH69M190u56uKs,2238
+nightfall/tools.py,sha256=Q_mLxDDWRlCUULaDlN7cs1UTLMQwJQES-SgwQNj1rzQ,6666
+nightfall/ui.py,sha256=-pE-ajCbcWNbembgsbM-RurmModu5fTdpjQIqbhdj5k,9313
+nightfall_cli-0.1.0.dist-info/METADATA,sha256=MF6GGIUUKal7Qn-DONKBCQnUjGh6VZEKFNdM8K5r4Vo,1790
+nightfall_cli-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+nightfall_cli-0.1.0.dist-info/entry_points.txt,sha256=RrY9rZc2OVvwiUf3BDJ4AcGkiOt6mtN2uFRd2wxvH8c,51
+nightfall_cli-0.1.0.dist-info/RECORD,,

nightfall_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

nightfall_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+nightfall = nightfall.agent:main