nightfall-cli 0.1.0__tar.gz

nightfall_cli-0.1.0/.github/workflows/workflow.yml

@@ -0,0 +1,37 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+
+    steps:
+      - name: Check out source
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Build distributions
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+
+      - name: Check distributions
+        run: |
+          python -m pip install --upgrade twine
+          python -m twine check dist/*
+
+      - name: Publish distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

nightfall_cli-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*html
+*.pyc
+.venv/
+.env
+.envrc
+
+# Local planning and architecture notes
+docs/adr/
+docs/plans/

nightfall_cli-0.1.0/.python-version

@@ -0,0 +1 @@
+3.10

nightfall_cli-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,47 @@
+# 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/nightfall/agent.py

@@ -0,0 +1,88 @@
+import argparse
+
+from . import commands
+from . import compact
+from . import history
+from . import session
+from .context import reminder
+from .llm import SYSTEM_PROMPT, call_llm
+from . import sandbox
+from .todos import active_form
+from .tools import execute
+from .ui import ui
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--resume", action="store_true", help="continue the last session")
+    parser.add_argument("--debug", action="store_true", help="show the raw model response")
+    cli = parser.parse_args()
+
+    ui.banner(sandbox.name())
+
+    messages = [{"role": "system", "content": SYSTEM_PROMPT}]
+    if cli.resume:
+        saved = session.all_sessions()
+        if saved:
+            messages = session.open_session(saved[0]["id"])
+            history.strip(messages)
+            ui.resumed(messages)
+            ui.replay(messages)
+
+    while True:
+        user_input = ui.ask()
+        if not user_input:
+            break
+
+        if user_input.startswith("/"):
+            messages = commands.handle(user_input, messages)
+            session.save(messages)
+            continue
+
+        messages.append({"role": "user", "content": user_input})
+
+        while True:
+            injection = reminder()
+            ui.injection(injection["content"])
+
+            if history.fit(messages):
+                ui.note("dropped old tool output to make this request fit")
+
+            with ui.working(active_form()):
+                message, usage = call_llm(messages + [injection])
+
+            messages.append(message.model_dump(exclude_none=True))
+            session.save(messages)
+            ui.usage(usage)
+
+            if cli.debug:
+                ui.debug(message.model_dump(exclude_none=True))
+
+            if message.content:
+                ui.agent(message.content)
+
+            if not message.tool_calls:
+                break
+
+            for tool_call in message.tool_calls:
+                args, result = execute(tool_call)
+                ui.tool(tool_call.function.name, args, result)
+
+                messages.append({
+                    "role": "tool",
+                    "tool_call_id": tool_call.id,
+                    "content": result,
+                })
+                session.save(messages)
+
+        history.sweep()   # the turn is over: bin its temp files
+        history.strip(messages)  # ...and shrink the tool output it produced
+
+        if compact.needed(usage):
+            messages = commands.compact(messages)
+
+    ui.summary()
+
+
+if __name__ == "__main__":
+    main()

nightfall_cli-0.1.0/nightfall/commands.py

@@ -0,0 +1,78 @@
+"""Slash commands. Anything typed starting with / lands here."""
+
+from . import compact as compaction
+from . import sandbox
+from . import session
+from .ui import ui
+
+COMMANDS = {
+    "/rewind": "jump back to an earlier point in this chat",
+    "/sessions": "open a past chat",
+    "/compact": "summarise the history so far and free up the context window",
+}
+
+
+def preview(message):
+    if message.get("tool_calls"):
+        return "-> " + message["tool_calls"][0]["function"]["name"]
+    return " ".join(str(message.get("content") or "").split())[:70]
+
+
+def redraw(messages, label):
+    """The screen no longer matches the history, so wipe it and draw again."""
+    ui.clear()
+    ui.banner(sandbox.name())
+    ui.resumed(messages, label)
+    ui.replay(messages)
+    return messages
+
+
+def rewind(messages):
+    rows = [f"{m['role']:<9} {preview(m)}" for m in messages]
+    choice = ui.pick("rewind to", rows)
+    if choice is None:
+        return messages
+    session.rewind_to(choice + 1)
+    return redraw(messages[: choice + 1], "rewound")
+
+
+def sessions(messages):
+    saved = session.all_sessions()
+    if not saved:
+        ui.note("no saved chats yet")
+        return messages
+    rows = [f"{s['id']}  {s['title']}" for s in saved]
+    choice = ui.pick("open chat", rows)
+    if choice is None:
+        return messages
+
+    return redraw(session.open_session(saved[choice]["id"]), "opened")
+
+
+def compact(messages):
+    before = len(messages)
+    try:
+        with ui.working("compacting"):
+            compacted = compaction.compact(messages)
+    except Exception as failure:  # noqa: BLE001
+        # Compaction is one more API call, and it fires when the window is
+        # nearly full - the worst moment to lose the session over a rate limit.
+        ui.note(f"compaction failed ({type(failure).__name__}); transcript kept as is")
+        return messages
+    if len(compacted) == before:
+        ui.note("nothing old enough to compact yet")
+        return messages
+    session.compacted(compacted)
+    ui.compacted(before, compacted)
+    return compacted
+
+
+def handle(command, messages):
+    if command == "/compact":
+        return compact(messages)
+    if command == "/rewind":
+        return rewind(messages)
+    if command == "/sessions":
+        return sessions(messages)
+    ui.note("\n".join(f"{name}  -  {help}" for name, help in COMMANDS.items()))
+    return messages

nightfall_cli-0.1.0/nightfall/compact.py

@@ -0,0 +1,132 @@
+"""The compaction agent.
+
+A second agent with one job: read a transcript that has grown too big and
+write the handoff note a fresh agent would need to carry on.
+
+The result replaces the messages it summarised, so this is the only place in
+the codebase that throws information away for good. It runs rarely and cuts
+deep - trimming just enough to fit would put us back over the line next turn,
+and every trim costs the whole prompt cache.
+"""
+
+from . import config
+from .history import estimate, strip
+from .llm import client
+
+SYSTEM_PROMPT = """
+You are compacting the transcript of a coding session. The session is out of
+context window. Write the handoff note that lets a fresh agent pick the work up
+without re-reading anything.
+
+Use these sections, in this order. Skip any that would be empty.
+
+## Goal
+What the user asked for. Quote them where the exact wording matters.
+
+## What happened
+Decisions taken and the reasoning behind them. Include approaches that were
+tried and abandoned, and why - those are the expensive lessons, and an agent
+without them will try the same dead end again.
+
+## Files
+Every file touched: path, and what changed in it.
+
+## State
+What works, what is broken, what was left half-finished.
+
+## Next
+The immediate next step.
+
+Rules:
+- Be specific. Real paths, function names, error text, exact commands.
+- Keep anything the user explicitly asked for, corrected, or rejected.
+- Never invent progress. If something was not finished, say it was not.
+- No preamble and no sign-off. Start at the first heading.
+"""
+
+HANDOFF = """<summary>
+Everything before this point has been compacted out of the context window to
+free up room. This is the record of it - treat it as your own memory of the
+work so far, not as something the user told you.
+
+{summary}
+</summary>"""
+
+def needed(usage):
+    """Has the last request grown past the point where we rebuild?"""
+    return usage["prompt_tokens"] > config.CONTEXT_WINDOW * config.COMPACT_AT
+
+
+ROLES = {"user": "USER", "assistant": "ASSISTANT", "tool": "TOOL RESULT"}
+
+
+def render(messages):
+    """Flatten the transcript into something the summariser can read."""
+    lines = []
+    for message in messages:
+        if message["role"] == "system":
+            continue
+
+        content = message.get("content") or ""
+        for call in message.get("tool_calls") or []:
+            function = call["function"]
+            content += f"\n[called {function['name']}: {function['arguments']}]"
+
+        lines.append(f"{ROLES.get(message['role'], message['role'])}: {content}")
+    return "\n\n".join(lines)
+
+
+def summarize(messages):
+    """One LLM call, no tools. Returns the handoff note."""
+    response = client.chat.completions.create(
+        model=config.MODEL,
+        messages=[
+            {"role": "system", "content": SYSTEM_PROMPT},
+            {"role": "user", "content": render(messages)},
+        ],
+    )
+    return response.choices[0].message.content
+
+
+def safe_boundary(messages, start):
+    """First index at or after `start` where cutting cannot orphan a tool call.
+
+    A tool result has to keep the assistant message that asked for it, so the
+    only safe cut points are the messages that open a fresh exchange.
+    """
+    for index in range(max(start, 1), len(messages)):
+        previous = messages[index - 1]
+        if messages[index]["role"] == "tool" or previous.get("tool_calls"):
+            continue
+        return index
+    return len(messages)
+
+
+def tail_start(messages, budget):
+    """Walk back from the end, taking messages until the tail fills `budget`."""
+    total = 0
+    for index in range(len(messages) - 1, 0, -1):
+        total += estimate([messages[index]])
+        if total > budget:
+            return safe_boundary(messages, index)
+    return safe_boundary(messages, 1)
+
+
+def compact(messages):
+    """system + summary + a recent tail. The caller freezes what comes back."""
+    cut = tail_start(messages, config.CONTEXT_WINDOW * config.COMPACT_TO)
+    if cut <= 1:
+        return messages  # nothing old enough to be worth summarising
+
+    summary = summarize(messages[1:cut])
+    kept = [
+        messages[0],
+        {"role": "user", "content": HANDOFF.format(summary=summary)},
+        *messages[cut:],
+    ]
+
+    # Shrink the retained tail now, while we are already paying for a rebuilt
+    # prefix. Stripping is idempotent, so from here the frozen block is final
+    # and stays byte-identical - and cached - until the next compaction.
+    strip(kept)
+    return kept

nightfall_cli-0.1.0/nightfall/config.py

@@ -0,0 +1,21 @@
+"""Settings: real environment variables first, then ~/.agents/env."""
+
+import os
+from pathlib import Path
+
+ENV_FILE = Path.home() / ".agents" / "env"
+
+if ENV_FILE.exists():
+    for line in ENV_FILE.read_text().splitlines():
+        if "=" in line and not line.startswith("#"):
+            key, value = line.split("=", 1)
+            os.environ.setdefault(key.strip(), value.strip())
+
+BASE_URL = os.environ["BASE_URL"]
+API_KEY = os.environ["API_KEY"]
+MODEL = os.environ.get("MODEL", "deepseek/deepseek-v4-flash")
+
+# How much room the model has, and how we spend it.
+CONTEXT_WINDOW = int(os.environ.get("CONTEXT_WINDOW", 128_000))
+COMPACT_AT = 0.85  # compact once the prompt crosses this much of the window
+COMPACT_TO = 0.35  # and cut back to this much, so it does not retrigger soon

nightfall_cli-0.1.0/nightfall/context.py

@@ -0,0 +1,77 @@
+"""Late injection: a small block appended just before we send.
+
+It goes at the END of the message list so the stable prefix in front of it
+stays cached.
+"""
+
+import hashlib
+import subprocess
+from datetime import datetime
+
+from .todos import todos_prompt
+from pathlib import Path
+
+LABELS = {"M": "modified", "D": "deleted", "A": "added", "??": "new"}
+
+
+def git(command):
+    result = subprocess.run(
+        f"git {command}", shell=True, capture_output=True, text=True
+    )
+    return result.stdout
+
+
+def file_hash(path):
+    file = Path(path)
+    return hashlib.md5(file.read_bytes()).hexdigest() if file.is_file() else None
+
+
+def git_state():
+    """path -> (status, content hash) for every file git sees as changed."""
+    state = {}
+    for line in git("status --porcelain").splitlines():
+        path = line[3:]
+        state[path] = (line[:2].strip(), file_hash(path))
+    return state
+
+
+LAST_STATE = git_state()
+
+
+def file_changes():
+    """Files whose status or contents moved since the previous turn."""
+    global LAST_STATE
+    now = git_state()
+    changed = {p: v[0] for p, v in now.items() if LAST_STATE.get(p) != v}
+    LAST_STATE = now
+    return changed
+
+
+def changes_note():
+    changed = file_changes()
+    if not changed:
+        return ""
+    lines = [f"{LABELS.get(code, code)}: {path}" for path, code in changed.items()]
+    return (
+        "\n<system-reminder>\n"
+        "These files changed since your last turn. Read them again before "
+        "editing:\n" + "\n".join(lines) + "\n</system-reminder>"
+    )
+
+
+def todos_note():
+    plan = todos_prompt()
+    return f"\n<todos>\n{plan}\n</todos>" if plan else ""
+
+
+def reminder():
+    """The block we append to the messages on every turn."""
+    return {
+        "role": "user",
+        "content": (
+            "<env>\n"
+            f"time: {datetime.now():%Y-%m-%d %H:%M}\n"
+            f"git branch: {git('branch --show-current').strip() or '(detached)'}\n"
+            "</env>" + todos_note() + changes_note()
+        ),
+    }

nightfall_cli-0.1.0/nightfall/history.py

@@ -0,0 +1,127 @@
+"""Keeping the transcript small enough to send.
+
+Three mechanisms, cheapest first. Only the first two live here; the expensive
+one is compact.py.
+
+1. cap    - a fresh tool result is trimmed and the full text parked in a temp
+            file the agent can page through. Free: the decision is made once,
+            when the result is created, so it never edits the prefix.
+2. strip  - once a turn is over, its tool results shrink to a stub. The edit
+            lands at the tail, right before the next user message, so the
+            cached prefix in front of it survives.
+3. drop   - a single request is still too big. Throw tool results away whole,
+            oldest first, until it fits.
+
+Everything here refuses to touch the locked prefix - the frozen
+system + summary + head that compaction leaves behind. That block has to stay
+byte-identical to stay cached.
+"""
+
+import json
+import tempfile
+from pathlib import Path
+
+from . import config
+
+CAP = 10_000  # chars of a fresh tool result the agent sees inline
+STUB = 300  # chars kept once the turn that produced it is over
+
+TRIMMED = "[output trimmed:"  # marker, so stripping twice is a no-op
+SUMMARY = "<summary>"  # marks the handoff note compaction leaves behind
+SPILLS = []  # temp files belonging to the current turn
+
+
+# ------------------------------------------------------------------- 1. cap
+
+
+def spill(text):
+    """Park the full output on disk for the rest of this turn."""
+    handle = tempfile.NamedTemporaryFile(
+        mode="w", prefix="nightfall-", suffix=".txt", delete=False
+    )
+    handle.write(text)
+    handle.close()
+    SPILLS.append(Path(handle.name))
+    return handle.name
+
+
+def cap(text):
+    """Trim a fresh tool result, leaving a pointer to the whole thing."""
+    if len(text) <= CAP:
+        return text
+
+    try:
+        path = spill(text)
+    except OSError:
+        # No temp file (read-only /tmp, no space). Still better to trim and
+        # say so than to fail the tool call outright.
+        return text[:CAP] + f"\n\n{TRIMMED} {len(text) - CAP} chars cut and the rest could not be saved.]"
+    return (
+        text[:CAP] + f"\n\n{TRIMMED} {len(text) - CAP} of {len(text)} chars cut. "
+        f"The whole output is at {path} - page through it with "
+        "head, tail, sed -n or grep. It is deleted when this turn ends.]"
+    )
+
+
+def sweep():
+    """Delete this turn's temp files. Their paths die with the tool results."""
+    for path in SPILLS:
+        path.unlink(missing_ok=True)
+    SPILLS.clear()
+
+
+def locked(messages):
+    """Length of the frozen prefix - everything up to and including the newest
+    summary. Derived rather than remembered, so it stays correct across
+    /compact, /rewind and switching sessions."""
+    for index in range(len(messages) - 1, -1, -1):
+        if SUMMARY in (messages[index].get("content") or ""):
+            return index + 1
+    return 0
+
+
+# ----------------------------------------------------------------- 2. strip
+
+
+def strip(messages):
+    """Shrink every tool result that is no longer part of the live turn.
+
+    Called once a turn has finished, so by now "everything unlocked" and
+    "everything the model no longer needs in full" are the same set.
+    """
+    shrunk = 0
+    for message in messages[locked(messages):]:
+        content = message.get("content") or ""
+        if message["role"] != "tool" or TRIMMED in content or len(content) <= STUB:
+            continue
+
+        message["content"] = (
+            content[:STUB] + f"\n\n{TRIMMED} {len(content) - STUB} more chars. "
+            "Run the command again if you need them.]"
+        )
+        shrunk += 1
+    return shrunk
+
+
+# ------------------------------------------------------------------ 3. drop
+
+
+def estimate(messages):
+    """Rough token count. Good enough to decide whether to panic."""
+    return sum(len(json.dumps(m)) for m in messages) // 4
+
+
+def fit(messages):
+    """Last resort: discard whole tool results, oldest first, until it fits.
+
+    Returns how many went. Normally zero - cap and strip do the real work.
+    """
+    budget = config.CONTEXT_WINDOW * config.COMPACT_AT
+    dropped = 0
+    for message in messages[locked(messages):]:
+        if estimate(messages) <= budget:
+            break
+        if message["role"] == "tool" and TRIMMED not in (message.get("content") or ""):
+            message["content"] = f"{TRIMMED} dropped to fit the context window.]"
+            dropped += 1
+    return dropped