e55b8826fb
# Conflicts: # bin/agent_cycle/interrupt.py # bin/agent_cycle/run.py # bin/agent_cycle/states.py # docs/reading-cost.md # todo.md
151 lines
8.5 KiB
Python
151 lines
8.5 KiB
Python
import dataclasses
|
|
import datetime
|
|
import sys
|
|
import typing
|
|
import uuid
|
|
|
|
from claude_code.entries import AssistantTurn, Entry
|
|
from agent_cycle.hand_over import claude_args, ClaudeCommand, hand_over
|
|
from loop_effects.effects import Effects, say
|
|
from failure import Failure
|
|
from claude_code.transcript import human_turns, read_transcript
|
|
from claude_code.reply import Limited
|
|
from agent_cycle.stop import needs_human, needs_terminal, Stop
|
|
from agent_cycle.worker import run_claude
|
|
from model_routing.ladder import Rung
|
|
from agent_cycle.direct_message import tell
|
|
from agent_cycle import tmux
|
|
from claude_code.tokens import tokens_of
|
|
|
|
ANSWER_QUESTION = "answer the question above"
|
|
# TALK, what the human types at the entry point's terminal to open claude for the question, and ASK_ANSWER were picked on 2026-10-17 by a bench of three readers seated as the README's audience, as ~/.claude/CLAUDE.md → "Working loop" → "Bench a syntax with the people who write it." has it.
|
|
TALK = "/talk"
|
|
ASK_ANSWER = f"Answer ({TALK} opens claude, Enter stops the loop): "
|
|
# While the human hasn't answered, the worker's session is compacted CACHE_MARGIN seconds before its hour-long prompt cache expires: compacting reads the context from the cache, while resuming after it expired writes the whole context again. Below COMPACT_FLOOR tokens of context, that write costs less than compacting. A five-minute cache expires within the margin, so a session that last wrote one isn't compacted. lilleman chose this on 2026-11-11.
|
|
HOUR_CACHE = 3600
|
|
CACHE_MARGIN = 600
|
|
COMPACT_FLOOR = 60_000
|
|
|
|
|
|
@dataclasses.dataclass(frozen=True)
|
|
class WorkerSession:
|
|
"""The worker's claude session, which /talk opens on the entry point's terminal."""
|
|
root: str
|
|
id: uuid.UUID
|
|
rung: Rung
|
|
# The rung the worker last ran on: below rung where the ruling that interrupts stepped the worker up.
|
|
ran_on: Rung
|
|
transcript_path: str
|
|
# Added to the environment of the worker's claude, and of the claude /talk opens.
|
|
env: dict[str, str]
|
|
|
|
def claude_command(self) -> ClaudeCommand:
|
|
return ClaudeCommand(claude_args(self.rung, ["--resume", str(self.id)]), self.root, self.env)
|
|
|
|
|
|
@dataclasses.dataclass(frozen=True)
|
|
class Talked:
|
|
"""The human typed in the worker's claude session."""
|
|
|
|
|
|
def interrupt(question: str, answer_here: bool, session: WorkerSession, window: tmux.Window, driver: str, effects: Effects) -> str | Talked | Stop:
|
|
"""Prints question for the human, in window, and returns their answer. While it waits, the window's name ends in tmux.WAITS, and the bell it rings shows in tmux's status bar. The answer: where answer_here, the first line typed at the terminal of driver, the entry point, stripped, or Talked once they typed in the worker's claude session, which TALK opens; else Talked once they typed in that session, which opens at once on the terminal. A Stop where interrupt runs off a terminal, or they type no answer, or the input ends."""
|
|
# The bell ends the question's line, so it rings once the question can be read.
|
|
say(f"\n{question}{tmux.BELL}", effects)
|
|
on_terminal = effects.on_terminal()
|
|
if on_terminal:
|
|
# Keys typed while the worker ran wait on the terminal, and would answer a question no one has read, here or in claude's session, which reads them too. Of a pasted answer, the first line answers; the rest wait, and the next question drops them. A longer answer goes through TALK.
|
|
effects.discard_typed()
|
|
tmux.mark(window, True, effects.tmux)
|
|
# After the discard, so an answer typed while the DM sends counts; before the terminal check, so a loop that cannot ask still tells the human what it would have asked.
|
|
tell(f"{driver} in {session.root} asks, in the tmux window {window.target}:\n\n{question}", effects)
|
|
answer = needs_terminal(ANSWER_QUESTION, on_terminal, driver) or answered(answer_here, session, effects)
|
|
# A loop that stops unanswered leaves the mark on its window.
|
|
if not isinstance(answer, Stop):
|
|
tmux.mark(window, False, effects.tmux)
|
|
return answer
|
|
|
|
|
|
def answered(answer_here: bool, session: WorkerSession, effects: Effects) -> str | Talked | Stop:
|
|
"""The human's answer, as interrupt returns it."""
|
|
answer = waited_answer(session, effects) if answer_here else TALK
|
|
if answer != TALK:
|
|
return answer
|
|
return human_typed(session.transcript_path, lambda: claude_open(session, effects)) or Talked()
|
|
|
|
|
|
def waited_answer(session: WorkerSession, effects: Effects) -> str | Stop:
|
|
"""typed_answer, compacting the worker's session where no answer has come by CACHE_MARGIN seconds before its prompt cache expires. /talk needs no compaction: the claude it opens compacts an idle session itself."""
|
|
entries = read_transcript(session.transcript_path)
|
|
now = effects.now()
|
|
delay = None if isinstance(entries, Failure) else compaction_delay(entries, now)
|
|
if delay is None:
|
|
return typed_answer(effects)
|
|
stop_timer = effects.timer(delay, lambda: compact(session, now + delay + CACHE_MARGIN, effects))
|
|
try:
|
|
return typed_answer(effects)
|
|
finally:
|
|
# Waits for a compaction under way, so the worker doesn't resume the session while it is compacted.
|
|
stop_timer()
|
|
|
|
|
|
def compaction_delay(entries: list[Entry], now: float) -> float | None:
|
|
"""Seconds from now until CACHE_MARGIN before the session's prompt cache expires. None where its context is under COMPACT_FLOOR tokens, its cache lasts five minutes, or the margin has begun."""
|
|
turns = [entry for entry in entries if isinstance(entry, AssistantTurn) and entry.usage]
|
|
if not turns or tokens_of(turns[-1].usage).context() < COMPACT_FLOOR:
|
|
return None
|
|
# A read refreshes the cache for the lifetime it was written with.
|
|
written = next((tokens for turn in reversed(turns) if (tokens := tokens_of(turn.usage)).write_5m or tokens.write_1h), None)
|
|
if written is None or not written.write_1h:
|
|
return None
|
|
try:
|
|
last_read = datetime.datetime.fromisoformat(turns[-1].timestamp).timestamp()
|
|
except ValueError:
|
|
return None
|
|
delay = last_read + HOUR_CACHE - CACHE_MARGIN - now
|
|
return delay if delay > 0 else None
|
|
|
|
|
|
def compact(session: WorkerSession, expires: float, effects: Effects) -> None:
|
|
"""Compacts the worker's session with `claude -p /compact`, saying that it starts and how it went. Each line opens on a line of its own, below the open ASK_ANSWER. From expires on, when the prompt cache has expired, it doesn't do anything: a timer fires late where the machine was suspended."""
|
|
if effects.now() >= expires:
|
|
return
|
|
say("\ncompacting the worker's claude session before its prompt cache expires; an answer typed meanwhile is read once that ends", effects)
|
|
# On the rung the worker ran on, not the one a ruling stepped it up to: the prompt cache is kept per model, and another effort may miss it too, so another rung would read the whole context at full price. Without run_worker's wait for memory, which could outlast the cache.
|
|
outcome = run_claude(session.root, claude_args(session.ran_on, ["-p", "/compact", "--resume", str(session.id), "--output-format", "stream-json", "--verbose"]), session.env, effects)
|
|
if outcome is None:
|
|
say("\ncompacted the worker's claude session", effects)
|
|
else:
|
|
say(f"\ncould not compact the worker's claude session: {outcome.said if isinstance(outcome, Limited) else outcome.reason}", effects)
|
|
|
|
|
|
def typed_answer(effects: Effects) -> str | Stop:
|
|
"""The line typed at the entry point's terminal, stripped. A Stop where they type no answer, or the input ends."""
|
|
try:
|
|
text = effects.input(ASK_ANSWER).strip()
|
|
except EOFError:
|
|
print(file=sys.stderr) # Ends the prompt's line. It isn't a message, so it gets no time.
|
|
return needs_human(ANSWER_QUESTION, "the input ended")
|
|
return text or needs_human(ANSWER_QUESTION, "nothing was typed")
|
|
|
|
|
|
def claude_open(session: WorkerSession, effects: Effects) -> Stop | None:
|
|
"""Opens the worker's claude session on the terminal, and returns once it has ended."""
|
|
if unstarted := hand_over(session.claude_command(), effects):
|
|
return Stop(1, f"could not start claude for the interrupt: {unstarted.reason}")
|
|
return None
|
|
|
|
|
|
def human_typed(transcript_path: str, held_open: typing.Callable[[], Stop | None]) -> Stop | None:
|
|
"""Runs held_open, which returns once the claude the human answers in has ended, then checks that the human typed something there."""
|
|
entries = read_transcript(transcript_path)
|
|
if isinstance(entries, Failure):
|
|
return Stop(1, entries.reason)
|
|
before = human_turns(entries)
|
|
if stop := held_open():
|
|
return stop
|
|
entries = read_transcript(transcript_path)
|
|
if isinstance(entries, Failure):
|
|
return Stop(1, f"could not tell whether you typed anything: {entries.reason}")
|
|
return None if human_turns(entries) > before else needs_human(ANSWER_QUESTION, "the interrupt ended without anything typed")
|