loopcaptain 0.3.1__py3-none-any.whl

loopcaptain/board/steer.py

@@ -0,0 +1,207 @@
+"""Steering a loop from the board: the inbox, and starting the one command a loop declares.
+
+The board runs nothing a browser typed. `start` runs `commands.start` from the loop's own
+`loop.json`, split into arguments and run without a shell, in the repository root, with a
+minimal environment: the board's own variables (keys, tokens) do not travel to a command a
+watched repository wrote. The first start of a given command in a given repository needs the
+person's tick; the hash of what they confirmed is kept in the state folder.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import os
+import shlex
+import signal
+import subprocess
+import time
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+
+from loopcaptain.board.discover import Repo
+from loopcaptain.protocol.models import Manifest, now
+from loopcaptain.protocol.store import StoreError
+
+log = logging.getLogger("loopcaptain.steer")
+
+STATE_ENV = "LOOPCAPTAIN_STATE"
+MAX_PID = 2**31
+LOG_TAIL_LINES = 30
+LOG_TAIL_BYTES = 20_000
+#: The only variables a started loop inherits from the board.
+PASSED_ENV = ("PATH", "HOME", "LANG", "TERM", "LOOPCAPTAIN_INBOX_KEY")
+CONFIRMED_FILE = "confirmed.json"
+PRIVATE_MODE = 0o600
+#: How far two readings of the boot time may differ and still be the same boot.
+BOOT_TOLERANCE_S = 120.0
+
+
+def boot_time() -> float:
+    """When this machine started, in epoch seconds, from the clock that counts since boot.
+
+    A pid recorded before a reboot can belong to another process now; comparing boot times
+    tells the two apart without running anything (the board runs nothing but `commands.start`).
+    """
+    clock = getattr(time, "CLOCK_BOOTTIME", time.CLOCK_MONOTONIC)
+    return time.time() - time.clock_gettime(clock)
+
+
+def minimal_env() -> dict[str, str]:
+    """The environment a started loop gets: enough to find programs and its home, nothing else."""
+    return {name: os.environ[name] for name in PASSED_ENV if name in os.environ}
+
+
+def command_hash(repo: Repo, command: str) -> str:
+    return hashlib.sha256(f"{repo.path.resolve()}\0{command}".encode()).hexdigest()
+
+
+def write_private(path: Path, text: str) -> None:
+    """Write a file only this user can read: the board's state names repositories and commands."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    descriptor = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, PRIVATE_MODE)
+    with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+        handle.write(text)
+
+
+@dataclass(frozen=True)
+class Process:
+    pid: int
+    command: str
+    started: datetime
+    alive: bool
+
+
+class Runner:
+    """Starts loops and remembers them: in memory while the board runs, in a small file across restarts."""
+
+    def __init__(self, state_dir: Path | None = None) -> None:
+        self.state_dir = state_dir or Path(os.environ.get(STATE_ENV, ".state"))
+        self.children: dict[str, subprocess.Popen[bytes]] = {}
+
+    def name(self, repo: Repo, loop_id: str) -> str:
+        return f"{repo.key}~{loop_id}"
+
+    def record_path(self, repo: Repo, loop_id: str) -> Path:
+        return self.state_dir / f"{self.name(repo, loop_id)}.json"
+
+    def log_path(self, repo: Repo, loop_id: str) -> Path:
+        return self.state_dir / f"{self.name(repo, loop_id)}.log"
+
+    def confirmed_hashes(self) -> frozenset[str]:
+        try:
+            listed = json.loads((self.state_dir / CONFIRMED_FILE).read_text(encoding="utf-8"))
+        except FileNotFoundError:
+            return frozenset()
+        except (OSError, ValueError) as error:
+            log.warning("unreadable %s, every command needs a tick again: %s", CONFIRMED_FILE, error)
+            return frozenset()
+        return frozenset(str(item) for item in listed) if isinstance(listed, list) else frozenset()
+
+    def is_confirmed(self, repo: Repo, command: str) -> bool:
+        """Whether the person has started this exact command in this repository before."""
+        return command_hash(repo, command) in self.confirmed_hashes()
+
+    def confirm(self, repo: Repo, command: str) -> None:
+        hashes = sorted(self.confirmed_hashes() | {command_hash(repo, command)})
+        write_private(self.state_dir / CONFIRMED_FILE, json.dumps(hashes) + "\n")
+
+    def process(self, repo: Repo, loop_id: str) -> Process | None:
+        """The process the board last started for this loop, and whether it still runs."""
+        try:
+            record = json.loads(self.record_path(repo, loop_id).read_text(encoding="utf-8"))
+            pid, command = int(record["pid"]), str(record["command"])
+            started = datetime.fromisoformat(str(record["started"]))
+            if not 1 < pid < MAX_PID:
+                # 0 and negative numbers name process groups, the board's own among them.
+                raise ValueError(f"pid {pid} is not a process the board could have started")
+            boot = record.get("boot")
+            same_boot = boot is None or abs(float(boot) - boot_time()) < BOOT_TOLERANCE_S
+        except FileNotFoundError:
+            return None
+        except (OSError, ValueError, KeyError, TypeError) as error:
+            log.warning("unreadable process record for %s: %s", self.name(repo, loop_id), error)
+            return None
+        return Process(pid, command, started, same_boot and self.is_alive(self.name(repo, loop_id), pid))
+
+    def is_alive(self, name: str, pid: int) -> bool:
+        child = self.children.get(name)
+        if child is not None and child.pid == pid:
+            return child.poll() is None
+        try:
+            os.kill(pid, 0)  # after a board restart: asks only whether the pid exists
+        except ProcessLookupError:
+            return False
+        except PermissionError:
+            return False  # the pid now belongs to someone else's process
+        return True
+
+    def start(self, repo: Repo, manifest: Manifest) -> Process:
+        command = manifest.commands.get("start", "").strip()
+        if not command:
+            raise StoreError("this loop declares no start command in loop.json")
+        current = self.process(repo, manifest.id)
+        if current and current.alive:
+            raise StoreError(f"already running (pid {current.pid})")
+        try:
+            argv = shlex.split(command)
+        except ValueError as error:
+            raise StoreError(f"start command cannot be read: {error}") from error
+        if not argv:
+            raise StoreError("start command is empty")
+        self.state_dir.mkdir(parents=True, exist_ok=True)
+        started = now()
+        descriptor = os.open(
+            self.log_path(repo, manifest.id), os.O_WRONLY | os.O_CREAT | os.O_APPEND, PRIVATE_MODE
+        )
+        with os.fdopen(descriptor, "ab") as out:
+            out.write(f"\n$ {command}   ({started:%Y-%m-%d %H:%M} UTC)\n".encode())
+            out.flush()
+            try:
+                child = subprocess.Popen(
+                    argv,
+                    cwd=repo.path,
+                    env=minimal_env(),
+                    stdin=subprocess.DEVNULL,
+                    stdout=out,
+                    stderr=subprocess.STDOUT,
+                    start_new_session=True,  # its own group: closing the board does not kill the loop
+                )
+            except OSError as error:
+                raise StoreError(f"could not start {argv[0]!r}: {error.strerror or error}") from error
+        name = self.name(repo, manifest.id)
+        self.children[name] = child
+        record = {"pid": child.pid, "command": command, "started": started.isoformat(), "boot": boot_time()}
+        write_private(self.record_path(repo, manifest.id), json.dumps(record) + "\n")
+        log.info("started %s: %s (pid %d)", name, command, child.pid)
+        return Process(child.pid, command, started, True)
+
+    def kill(self, repo: Repo, loop_id: str) -> None:
+        """End the process the board started, and its children, now. The polite way is an inbox `stop`."""
+        current = self.process(repo, loop_id)
+        if not current or not current.alive:
+            raise StoreError("nothing the board started is running")
+        try:
+            os.killpg(current.pid, signal.SIGTERM)
+        except ProcessLookupError:
+            return
+        except PermissionError as error:
+            raise StoreError(f"may not end pid {current.pid}") from error
+        log.info("ended %s (pid %d)", self.name(repo, loop_id), current.pid)
+
+    def log_tail(self, repo: Repo, loop_id: str) -> str:
+        path = self.log_path(repo, loop_id)
+        try:
+            with path.open("rb") as handle:
+                handle.seek(0, os.SEEK_END)
+                size = handle.tell()
+                handle.seek(max(0, size - LOG_TAIL_BYTES))
+                text = handle.read().decode("utf-8", errors="replace")
+        except FileNotFoundError:
+            return ""
+        except OSError as error:
+            log.warning("cannot read %s: %s", path.name, error)
+            return ""
+        return "\n".join(text.splitlines()[-LOG_TAIL_LINES:])

loopcaptain/board/templates/base.html

@@ -0,0 +1,27 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta name="color-scheme" content="light dark">
+  <title>{% block title %}Loopcaptain{% endblock %}</title>
+  <link rel="icon" type="image/svg+xml" href="{{ url_for('static', path='mark.svg') }}">
+  <link rel="preload" href="{{ url_for('static', path='fonts/inter-latin-wght-normal.woff2') }}" as="font" type="font/woff2" crossorigin>
+  <link rel="stylesheet" href="{{ url_for('static', path='style.css') }}">
+  <script src="{{ url_for('static', path='board.js') }}" defer></script>
+</head>
+<body{% block body_attrs %}{% endblock %}>
+<header class="top">
+  <a class="brand" href="{{ url_for('overview') }}" aria-label="Loopcaptain, all loops"><img src="{{ url_for('static', path='mark.svg') }}" alt="" width="28" height="28">Loopcaptain</a>
+  <span class="where">{% block where %}{% endblock %}</span>
+  <nav class="strip" aria-label="Pages">
+    <a href="{{ url_for('overview') }}"{% if page == 'overview' %} aria-current="page"{% endif %}>Loops</a>
+    <a href="{{ url_for('connect') }}"{% if page == 'connect' %} aria-current="page"{% endif %}>Connect a loop</a>
+  </nav>
+</header>
+<main>
+{% block main %}{% endblock %}
+</main>
+<footer class="foot">Reads each loop's <code>.loops/</code> folder on every request. Answers only on this machine.</footer>
+</body>
+</html>

loopcaptain/board/templates/connect.html

@@ -0,0 +1,35 @@
+{% extends "base.html" %}
+{% set page = 'connect' %}
+{% block title %}Connect a loop · Loopcaptain{% endblock %}
+{% block main %}
+<p class="eyebrow">Connect a loop</p>
+<h1>A loop writes a few small files. That is the whole interface.</h1>
+<p class="lede">Design the loop however you like. To show it here it says what it is and what happens, in one folder. Nothing to install, no server to reach.</p>
+<section class="start-here" aria-label="Get started with your coding agent">
+  <h2>Start with your coding agent</h2>
+  <div class="prompts">
+    <div class="card"><p class="eyebrow">Build a loop</p><pre class="prompt" id="prompt-build">{{ prompts['build-a-loop'] }}</pre>
+      <p class="act"><button type="button" class="quiet" data-copy-from="prompt-build-text">Copy</button><span class="grey" data-copied hidden role="status">Copied.</span></p></div>
+    <div class="card"><p class="eyebrow">Watch the loops on this machine</p><pre class="prompt" id="prompt-watch">{{ prompts['watch-my-loops'] }}</pre>
+      <p class="act"><button type="button" class="quiet" data-copy-from="prompt-watch-text">Copy</button><span class="grey" data-copied hidden role="status">Copied.</span></p></div>
+  </div>
+</section>
+<textarea id="prompt-build-text" hidden readonly aria-hidden="true">{{ prompts['build-a-loop'] }}</textarea>
+<textarea id="prompt-watch-text" hidden readonly aria-hidden="true">{{ prompts['watch-my-loops'] }}</textarea>
+<section class="how">
+  <div class="card"><h3><b class="n">1</b>A loop with a script</h3>
+    <p>Give <a href="{{ url_for('spec_file') }}">LOOPS.md</a> to the agent that works on the loop, or paste it into the loop's repository. It holds the format and a helper of 60 lines, standard library only.</p>
+    <p class="act"><button type="button" class="quiet" data-copy-from="spec-text">Copy LOOPS.md</button><span class="grey" data-copied hidden role="status">Copied.</span></p></div>
+  <div class="card"><h3><b class="n">2</b>A loop an agent session drives</h3>
+    <p>Add the MCP server, <code>loopcaptain mcp</code> over stdio, to your agent. Its tools write the same files. Pick yours:</p>
+    <nav class="agents" aria-label="Coding agents">{% for item in agents %}<a href="{{ url_for('connect') }}?agent={{ item.key }}#mcp"{% if item.key == picked.key %} aria-current="true"{% endif %}>{{ item.name }}</a>{% endfor %}</nav>
+    <pre id="mcp">{{ picked.add }}</pre>
+    <p class="grey">Unattended, as <code>commands.start</code>: <code>{{ picked.headless }}</code></p></div>
+  <div class="card"><h3><b class="n">3</b>Show it here</h3>
+    <p>The board lists every repository it watches that has a <code>.loops/</code> folder. Add one with <code>loopcaptain watch &lt;folder&gt;</code>, and check it with:</p>
+    <pre>loopcaptain validate &lt;repository&gt;</pre></div>
+</section>
+<textarea id="spec-text" hidden readonly aria-hidden="true">{{ spec }}</textarea>
+<h2>The standard</h2>
+<article class="prose card">{{ body }}</article>
+{% endblock %}

loopcaptain/board/templates/file.html

@@ -0,0 +1,9 @@
+{% extends "base.html" %}
+{% block title %}{{ path }} · {{ view.title }}{% endblock %}
+{% block where %}{{ view.repo.key }} / {{ view.loop_id }}{% endblock %}
+{% block main %}
+<p class="crumb"><a href="{{ url_for('overview') }}">Loops</a> / <a href="{{ url_for('loop_page', repo_key=view.repo.key, loop_id=view.loop_id) }}">{{ view.title }}</a> / {{ path }}</p>
+{% if reason %}<p class="empty"><code>{{ path }}</code>: {{ reason }}.</p>
+{% elif body is not none %}<article class="prose card">{{ body }}</article>
+{% else %}<pre class="raw">{{ text }}</pre>{% endif %}
+{% endblock %}