Files
claude-config/bin/loop_effects/effects.py
T

193 lines
8.7 KiB
Python

"""The effects a tool reaches the world through, such as its terminal, clock, processes, git and the machine's memory.
A change here, such as to how input reads a line, changes every tool that runs on them.
"""
import dataclasses
import os
import pathlib
import select
import signal
import subprocess
import sys
import termios
import threading
import time
import typing
from notifier.notify import Backend, BACKENDS, notify
from loop_effects import child_shells
from failure import Failure
from git_cli import git_repo
from machine_load.memory import Memory, read_memory
from project_config.settings import Notifier
from text_files.file_writes import replace_file
from forge.commands import Run, runner
from machine_load.slots import slot_folder
# Seconds before a Python script loop-claude runs is stopped, so a hung one, such as chunk-preflight, cannot hold the loop.
PYTHON_TIMEOUT = 600
# Seconds a command of the forge's CLI may take, so a stalled one cannot hold the loop.
FORGE_TIMEOUT = 60
class Streaming(typing.Protocol):
"""A started claude whose stream-json lines arrive as it works."""
def lines(self, idle: float) -> typing.Iterable[str | None]:
"""Each line as it arrives, and None whenever idle seconds pass without one."""
...
def shells(self) -> list[child_shells.Shell]:
"""The shells that are children of the claude."""
...
def stop(self, shell: child_shells.Shell) -> None:
"""Ends the shell and everything below it."""
...
def wait(self) -> int: ...
@dataclasses.dataclass(frozen=True)
class Effects:
claude: typing.Callable[[list[str], str, str], subprocess.CompletedProcess[str]]
claude_on_terminal: typing.Callable[[list[str], str, dict[str, str]], int]
# Drops what was typed on the terminal and not yet read.
discard_typed: typing.Callable[[], None]
# Sends the human a direct message through the notifier the project's config names, as `notify` does, for the project whose checkout holds the given directory, else the current directory; a Failure where it could not.
dm: typing.Callable[[str, str | None], Failure | None]
execv: typing.Callable[[str, list[str]], None]
# Runs the CLI of a checkout's forge in that checkout, as forge.commands.runner does.
forge: typing.Callable[[str], Run]
git: git_repo.Git
input: typing.Callable[[str], str]
# A date and time in the machine's zone, as `2026-10-28 11:46:01`. lilleman chose this spelling and local time over UTC on 2026-10-28, since the human reads these on their own clock.
local_time: typing.Callable[[float], str]
# The machine's memory; None where it cannot be read.
memory: typing.Callable[[], Memory | None]
now: typing.Callable[[], float]
on_terminal: typing.Callable[[], bool]
# Runs a Python script in a directory, as run_python does.
python: typing.Callable[[list[str], str], subprocess.CompletedProcess[str]]
# Writes a file whole, as text_files.file_writes.replace_file does.
replace_file: typing.Callable[[pathlib.Path, bytes], Failure | None]
sleep: typing.Callable[[float], None]
stream_claude: typing.Callable[[list[str], str, dict[str, str]], Streaming]
# Starts a timer, as start_timer does.
timer: typing.Callable[[float, typing.Callable[[], None]], typing.Callable[[], None]]
# Runs tmux with these arguments, as run_tmux does.
tmux: typing.Callable[[list[str]], subprocess.CompletedProcess[str]]
# Runs tmux on the terminal, as to attach a session, and returns its exit code once the human detaches.
tmux_on_terminal: typing.Callable[[list[str]], int]
class StreamingClaude:
def __init__(self, args: list[str], cwd: str, env: dict[str, str]) -> None:
self.proc = subprocess.Popen(["claude", *args], cwd=cwd, env={**os.environ, **env}, stdin=subprocess.DEVNULL, stdout=subprocess.PIPE, bufsize=0)
def lines(self, idle: float) -> typing.Iterable[str | None]:
# Reads the pipe's file descriptor itself. select cannot see what a buffered reader holds.
# A thread blocked in a read would keep the pipe from closing when a Ctrl-C ends the loop.
pending = b""
with self.proc:
fd = self.proc.stdout.fileno() if self.proc.stdout else -1
while True:
if not select.select([fd], [], [], idle)[0]:
yield None
continue
chunk = os.read(fd, 65536)
if not chunk:
break
*complete, pending = (pending + chunk).split(b"\n")
for line in complete:
yield line.decode("utf-8", errors="replace") + "\n"
if pending:
yield pending.decode("utf-8", errors="replace")
def shells(self) -> list[child_shells.Shell]:
return child_shells.shells_of(self.proc.pid, slot_folder(os.environ, pathlib.Path.home()), child_shells.children_of)
def stop(self, shell: child_shells.Shell) -> None:
child_shells.stop(shell)
def wait(self) -> int:
return self.proc.wait()
def system_effects(home: pathlib.Path, env: typing.Mapping[str, str], backends: typing.Mapping[Notifier, Backend[typing.Any]] = BACKENDS, forge_timeout: float = FORGE_TIMEOUT) -> Effects:
"""The effects on this machine: the configs of its DM are under home, and tmux runs in env.
A test hands in `backends` that don't send anything, in place of the notifiers loop-claude's DM goes through. It hands in a short `forge_timeout`, so a command that outlasts it ends quickly.
"""
return Effects(
claude=lambda args, cwd, stdin: subprocess.run(["claude", *args], capture_output=True, cwd=cwd, input=stdin, text=True),
claude_on_terminal=claude_on_terminal,
discard_typed=lambda: termios.tcflush(sys.stdin, termios.TCIFLUSH),
dm=lambda text, directory: notify(text, directory, home, backends),
execv=os.execv,
forge=lambda cwd: runner(cwd, forge_timeout),
git=git_repo.git,
input=input,
local_time=lambda seconds: time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(seconds)),
memory=read_memory,
now=time.time,
on_terminal=lambda: sys.stdin.isatty() and sys.stdout.isatty(),
python=lambda args, cwd: run_python(args, cwd, PYTHON_TIMEOUT),
replace_file=replace_file,
sleep=time.sleep,
stream_claude=StreamingClaude,
timer=start_timer,
tmux=lambda args: run_tmux(args, env),
tmux_on_terminal=lambda args: subprocess.run(["tmux", *args], env=env).returncode,
)
def claude_on_terminal(args: list[str], cwd: str, env: dict[str, str]) -> int:
"""Runs claude on the terminal in cwd, with env added to its environment, and returns its exit code. While claude runs, Ctrl-C belongs to it: this process shares its terminal, and ignores the key."""
# A Python handler, unlike SIG_IGN, is reset to the default as claude starts, so Ctrl-C still reaches claude.
previous = signal.signal(signal.SIGINT, lambda number, frame: None)
try:
return subprocess.run(["claude", *args], cwd=cwd, env={**os.environ, **env}).returncode
finally:
signal.signal(signal.SIGINT, previous)
def run_python(args: list[str], cwd: str, timeout: float) -> subprocess.CompletedProcess[str]:
"""Runs a Python script in cwd. One that cannot start, or still runs after timeout seconds and is stopped, reads as exit 1, saying why on stderr."""
command = [sys.executable, *args]
try:
return subprocess.run(command, capture_output=True, cwd=cwd, encoding="utf-8", errors="replace", stdin=subprocess.DEVNULL, timeout=timeout)
except OSError as failure:
return subprocess.CompletedProcess(command, 1, "", f"could not start: {failure}")
except subprocess.TimeoutExpired:
return subprocess.CompletedProcess(command, 1, "", f"stopped after {timeout} s")
def start_timer(delay: float, action: typing.Callable[[], None]) -> typing.Callable[[], None]:
"""Runs action on a thread of its own once delay seconds have passed, and returns what stops the timer: it cancels an action not yet started, and waits for one that has started to end."""
timer = threading.Timer(delay, action)
# A timer still running doesn't keep the process alive once the loop exits.
timer.daemon = True
timer.start()
def stop() -> None:
timer.cancel()
timer.join()
return stop
def run_tmux(args: list[str], env: typing.Mapping[str, str] | None) -> subprocess.CompletedProcess[str]:
"""Runs tmux in env, else in this process's environment, and returns what it printed. A tmux that cannot start, as where none is installed, reads as exit 127, saying why on stderr."""
command = ["tmux", *args]
try:
return subprocess.run(command, capture_output=True, encoding="utf-8", env=env, errors="replace", stdin=subprocess.DEVNULL)
except OSError as failure:
return subprocess.CompletedProcess(command, 127, "", f"could not start: {failure}")
def say(text: str, effects: Effects, *, stdout: bool = False) -> None:
"""Prints text on stderr, or on stdout where stdout, opening the first line of words with the machine's local time. Blank lines before those words stay blank, and later lines get no time."""
body = text.lstrip("\n")
blanks = text[: len(text) - len(body)]
print(f"{blanks}{effects.local_time(effects.now())} {body}", file=sys.stdout if stdout else sys.stderr, flush=True)