Files
claude-config/bin/loop_claude/cycle/run.py
T

240 lines
14 KiB
Python

import dataclasses
import pathlib
import typing
from loop_claude.cycle.states import Active, Archived, Closing, Ended, Event, HumanTalked, HumanTyped, Interrupting, Judging, QUOTED_ANSWERS_PER_CYCLE, Ruled, State, to_the_human, transition, TypedAnswer, WorkerRan, Working
from transcript_archive.write import archive
from loop_claude.cycle.worker import AUTO_COMPACT_WINDOW, COMPACT_WINDOW, run_worker, worker_args
from loop_claude.cycle.judge import Brief, judge, Rejected
from loop_claude.cycle import chunk_items
from claude_code.session import delete_session, Session, session_open, transcript_file
from loop_effects.effects import Effects, say
from claude_code.entries import Entry
from failure import Failure
from loop_claude.verdicts import Finished, Interrupt, Judged, QuotedAnswer, Unfinished, Verdict
from loop_claude.cycle.interrupt import interrupt, Talked, WorkerSession
from transcript_archive.judge_run import JudgeRun
from transcript_archive.read import last_spent
from loop_claude.routing import next_route, step_up, StepUp
from transcript_archive import outcomes
from plan_store.plans import Plan
from model_routing.ladder import ProjectRung, Rung
from loop_claude.cycle import prompts
from claude_code.transcript import read_transcript
from loop_claude.cycle.retry import retried
from model_routing.route import Route
from loop_claude.cycle import spend
from loop_claude.stop import Stop
from loop_claude.tmux import Window
from model_routing import worker_rungs
@dataclasses.dataclass(frozen=True)
class Cycle:
"""What a cycle runs on. run_cycle replaces the route on a ruling's step-up; nothing changes the other fields.
Each step reads the few fields it needs by name, so the fields stay at one level. docs/decisions.md → `principles: about seven things per level, …` allows more than seven where a reader finds them by name.
"""
# The claude-config release and commit the cycle runs under, such as `v0.8.0 (<sha>)`, or why they are unknown: loop/main.py's setup_version.
config: str
effects: Effects
# What chunk-preflight found, or why it could not run, for a fresh worker's prompt; empty when the session was open as the cycle began.
facts: str
# The rung routing.judge_rung picks for the project's judge model.
judge: Rung
premises: str
# The project's rung on the ladder that model_routing/ladder_file.py read as the cycle started; None for a model off the ladder.
project: ProjectRung | None
project_archive: pathlib.Path
records: str
root: str
route: Route
session: Session
task: str
# The plan on the default branch as the cycle starts, which scores the items the worker names.
plan: Plan | Failure
# Empty when the previous cycle's verdict was not Unfinished.
unfinished_evidence: str
# The tmux window the loop runs in, which an interrupt marks.
window: Window
@dataclasses.dataclass(frozen=True)
class Concluded:
"""How a cycle ended: its verdict, and the route it ended on, which an interrupt's or a quoted answer's escalation may have stepped up from the route it began on."""
verdict: Finished | Unfinished
route: Route
def run_cycle(cycle: Cycle) -> Stop | Concluded:
state: State = Working()
try:
while not isinstance(state, Ended):
event = step(cycle, state)
if isinstance(event, Stop):
return stopped(cycle, event, event.reason)
# Only a ruling's step-up changes the route within a cycle, here, once rule has archived the ruling on the route before it. No transition reads the current route, so Cycle holds it, not the states.
if isinstance(event, Ruled) and event.stepped_to:
cycle = dataclasses.replace(cycle, route=event.stepped_to)
state = transition(state, event)
except KeyboardInterrupt:
return stopped(cycle, Stop(130, ""), "Ctrl-C")
return Concluded(state.verdict, cycle.route)
def ruling_step_up(cycle: Cycle, verdict: Verdict) -> StepUp | None:
"""The step-up an interrupt's or a quoted answer's escalation makes, so the work after the answer runs on the stepped route; None where the route holds. A finished or unfinished verdict steps the route only as the loop starts the next cycle."""
return step_up(cycle.route, next_route(cycle.project, cycle.route, verdict)) if isinstance(verdict, Interrupt | QuotedAnswer) else None
def stopped(cycle: Cycle, stop: Stop, why: str) -> Stop:
return archived_stop(cycle.project_archive, cycle.session, cycle.task, cycle.route, stop, why, cycle.effects)
def archived_stop(project_archive: pathlib.Path, session: Session, task: str, route: Route, stop: Stop, why: str, effects: Effects) -> Stop:
"""stop, once archived with the route the worker holds. A failed archive exits 1 whatever the stop; when the stop was this archive failing, its reason is said once."""
path = transcript_file(session)
failure = archived(project_archive, path, task, outcomes.stopped(route.worker_line(), why), effects) if path else None
return Stop(1, f"{failure.reason}\n{stop.reason}".rstrip()) if failure and failure.reason != stop.reason else stop
def archived(project_archive: pathlib.Path, transcript_path: str, task: str, outcome: str, effects: Effects, judge_run: JudgeRun | None = None) -> Failure | None:
"""transcript_archive.write.archive, stamped now and saying its notes through effects. A cycle and close.py, which has no Cycle, both archive through it."""
return archive(project_archive, transcript_path, task, outcome, effects.now(), lambda text: say(text, effects), judge_run)
def step(cycle: Cycle, state: Active) -> Event | Stop:
match state:
case Working(answered, _, stepped):
return work(cycle, answered, stepped)
case Judging(transcript_path, quoted_answers):
return rule(cycle, transcript_path, quoted_answers)
case Interrupting(transcript_path, ruling, _, _):
return ask(cycle, transcript_path, ruling)
case Closing(transcript_path, verdict):
return close(cycle, transcript_path, verdict)
case _:
typing.assert_never(state)
def work(cycle: Cycle, answered: QuotedAnswer | TypedAnswer | None, stepped: bool) -> WorkerRan | Stop:
if isinstance(answered, QuotedAnswer):
say(f"\n=== {prompts.QUOTE_SOURCES} answered: {answered.question} ===\n{answered.answer}", cycle.effects, stdout=True)
# worker_start runs inside the lambda: a failed attempt may have opened the session.
if stop := retried("worker", lambda: run_worker(cycle.root, worker_start(cycle, answered, stepped), worker_environment(cycle), cycle.effects), cycle.effects):
return stop
path = transcript_file(cycle.session)
return WorkerRan(path) if path is not None else Stop(1, f"claude left no transcript for session {cycle.session.id}")
def worker_environment(cycle: Cycle) -> dict[str, str]:
"""The rungs the worker's claude is handed, which rule-hook holds its review launches to, and the auto-compact window of its context."""
return {**worker_rungs.environment(cycle.project, cycle.route), AUTO_COMPACT_WINDOW: str(COMPACT_WINDOW)}
def worker_session(cycle: Cycle, transcript_path: str) -> WorkerSession:
return WorkerSession(cycle.root, cycle.session.id, cycle.route.rung, transcript_path, worker_environment(cycle))
def worker_start(cycle: Cycle, answered: QuotedAnswer | TypedAnswer | None, stepped: bool) -> list[str]:
if isinstance(answered, QuotedAnswer):
return worker_args(cycle.session, cycle.route.rung, prompts.answered(answered.question, answered.answer, cycle.route, cycle.project, stepped), resume=True)
if isinstance(answered, TypedAnswer):
return worker_args(cycle.session, cycle.route.rung, prompts.typed(answered.question, answered.answer, cycle.route, cycle.project, stepped), resume=True)
if session_open(cycle.session):
return worker_args(cycle.session, cycle.route.rung, prompts.resumed(cycle.unfinished_evidence, cycle.route, cycle.project), resume=True)
return worker_args(cycle.session, cycle.route.rung, prompts.fresh(cycle.task, cycle.premises, cycle.route, cycle.project, cycle.facts), resume=False)
def rule(cycle: Cycle, transcript_path: str, quoted_answers: int) -> Ruled | Stop:
"""The judge's ruling. Unless it is Finished, code stamps it with the items the worker names on its latest `Chunk items:` line. An interrupt or a quoted answer is archived as it is ruled, on the route the worker ran on until then, and then any step-up it makes, so the figures charge each stretch of work to its own rung."""
entries = read_transcript(transcript_path)
if isinstance(entries, Failure):
return Stop(1, entries.reason)
verdict = judge(cycle.root, Brief(cycle.task, cycle.premises, cycle.records, entries, cycle.route.escalated_at), cycle.judge, cycle.effects, lambda rejected: keep_rejection(cycle, transcript_path, rejected))
if isinstance(verdict, Stop):
return verdict
if not isinstance(verdict, Finished):
verdict = dataclasses.replace(verdict, taken_in=chunk_items.taken_in(entries, cycle.plan))
if not isinstance(verdict, Interrupt | QuotedAnswer):
return Ruled(verdict)
annotation = annotation_of(cycle, transcript_path, entries, verdict.judged)
if isinstance(annotation, Failure):
return Stop(1, annotation.reason)
stepped = ruling_step_up(cycle, verdict)
if failure := archive_stepped(cycle, transcript_path, ruling_outcome(cycle, verdict, quoted_answers, annotation), stepped, verdict.judged.run):
return Stop(1, failure.reason)
return Ruled(verdict, stepped.after if stepped else None)
def annotation_of(cycle: Cycle, transcript_path: str, entries: list[Entry], judged: Judged) -> outcomes.Annotation | Failure:
"""What a verdict, an interrupt or a quoted answer records beside its judge lines: the setup, the stretch's spend as spend.py counts it, and the reversal the judge found."""
since = last_spent(cycle.project_archive, transcript_path)
if isinstance(since, Failure):
return since
subagents = spend.subagents(transcript_path)
if isinstance(subagents, Failure):
return subagents
spent = spend.spent(since, entries, subagents, cycle.judge.model, judged.tokens)
return outcomes.Annotation(cycle.config, outcomes.spent_block(since, spent), judged.reversed)
def ruling_outcome(cycle: Cycle, ruling: Interrupt | QuotedAnswer, quoted_answers: int, annotation: outcomes.Annotation) -> str:
"""The archive's outcome for a ruling: interrupted where it goes to the human, with the question put to them, and else answered from the premises or the records."""
if isinstance(ruling, QuotedAnswer) and not to_the_human(ruling, quoted_answers):
return outcomes.answered(question=ruling.question, sources=prompts.QUOTE_SOURCES, answer=ruling.answer, evidence=ruling.evidence, escalation=ruling.escalation, judge=str(cycle.judge), worker=cycle.route.worker_line(), judge_cost=ruling.judged.cost, annotation=annotation, judge_run=ruling.judged.run)
return outcomes.interrupted(question_for(ruling), ruling.evidence, str(cycle.judge), ruling.escalation, cycle.route.worker_line(), judge_cost=ruling.judged.cost, annotation=annotation, judge_run=ruling.judged.run)
def keep_rejection(cycle: Cycle, transcript_path: str, rejected: Rejected) -> Stop | None:
"""Archives a judge reply loop-claude rejected, so the archive shows what the judge returned before a retry or an exit 1."""
if unkept := archived(cycle.project_archive, transcript_path, cycle.task, outcomes.rejected(rejected.reason, rejected.reply, str(cycle.judge), judge_cost=rejected.cost, judge_run=rejected.run), cycle.effects, rejected.run):
return Stop(1, unkept.reason)
return None
def ask(cycle: Cycle, transcript_path: str, ruling: Interrupt | QuotedAnswer) -> HumanTyped | HumanTalked | Stop:
"""The human's answer to a ruling that rule archived as it ruled; the human's answer then grows the transcript."""
# Only the human may cut a release, so a release ready to cut opens claude's session at once.
answer = interrupt(question_for(ruling), not (isinstance(ruling, Interrupt) and ruling.release_ready), worker_session(cycle, transcript_path), cycle.window, cycle.effects)
match answer:
case Stop():
return answer
case Talked():
return HumanTalked()
# The worker gets the question it asked, not the one put to the human past the cap.
return HumanTyped(TypedAnswer(ruling.question, answer))
def archive_stepped(cycle: Cycle, transcript_path: str, outcome: str, step_up: StepUp | None, judge_run: JudgeRun | None) -> Failure | None:
"""Archives the outcome of a ruling and the judge run that gave it, then the step-up it made, if it made one. The first failure is returned."""
if failure := archived(cycle.project_archive, transcript_path, cycle.task, outcome, cycle.effects, judge_run):
return failure
return archived_step(cycle.project_archive, transcript_path, cycle.task, step_up, cycle.effects)
def archived_step(project_archive: pathlib.Path, transcript_path: str, task: str, step_up: StepUp | None, effects: Effects) -> Failure | None:
"""Archives a step-up, if there is one, as the worker line it steps to. The outcome archived before it names the route the worker ran on until then, so the figures charge each stretch of work to its own rung. Both a ruling within a cycle and an unfinished verdict between cycles archive their step-up here."""
if step_up is None:
return None
return archived(project_archive, transcript_path, task, outcomes.stepped_up(step_up.after.worker_line()), effects)
def question_for(ruling: Interrupt | QuotedAnswer) -> str:
if isinstance(ruling, Interrupt):
return ruling.question
return prompts.past_the_cap(ruling.question, ruling.answer, QUOTED_ANSWERS_PER_CYCLE)
def close(cycle: Cycle, transcript_path: str, verdict: Finished | Unfinished) -> Archived | Stop:
entries = read_transcript(transcript_path)
annotation = entries if isinstance(entries, Failure) else annotation_of(cycle, transcript_path, entries, verdict.judged)
if isinstance(annotation, Failure):
return Stop(1, annotation.reason)
outcome = outcomes.finished(cycle.route.worker_line(), verdict.evidence, str(cycle.judge), judge_cost=verdict.judged.cost, annotation=annotation, judge_run=verdict.judged.run) if isinstance(verdict, Finished) else outcomes.unfinished(cycle.route.worker_line(), verdict.evidence, str(cycle.judge), verdict.escalation, judge_cost=verdict.judged.cost, annotation=annotation, judge_run=verdict.judged.run)
if failure := archived(cycle.project_archive, transcript_path, cycle.task, outcome, cycle.effects, verdict.judged.run):
return Stop(1, failure.reason)
if isinstance(verdict, Finished) and (failure := delete_session(cycle.session)):
return Stop(1, failure.reason)
return Archived()