251 lines
15 KiB
Python
251 lines
15 KiB
Python
import dataclasses
|
|
import pathlib
|
|
import typing
|
|
|
|
from agent_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 agent_cycle.worker import AUTO_COMPACT_WINDOW, COMPACT_WINDOW, run_worker, worker_args
|
|
from claude_code.output_limits import BASH_CEILING, BASH_CEILING_CHARACTERS
|
|
from agent_cycle.judge import Brief, judge, Rejected
|
|
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 agent_cycle.verdicts import Finished, Interrupt, Judged, QuotedAnswer, TakenIn, Unfinished, Verdict
|
|
from agent_cycle.interrupt import interrupt, Talked, WorkerSession
|
|
from transcript_archive.judge_run import JudgeRun
|
|
from transcript_archive.read import last_spent
|
|
from agent_cycle.routing import next_route, step_up, StepUp
|
|
from transcript_archive import outcomes
|
|
from model_routing.ladder import ProjectRung, Rung
|
|
from claude_code.transcript import read_transcript
|
|
from agent_cycle.retry import retried
|
|
from model_routing.route import Route
|
|
from agent_cycle import spend
|
|
from agent_cycle.stop import Stop
|
|
from agent_cycle.tmux import Window
|
|
from model_routing import worker_rungs
|
|
from agent_cycle.worker_prompts import WorkerPrompts
|
|
|
|
|
|
@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: chunk_driver/cycle_start.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 prompts and the file names of the entry point that drives the cycle.
|
|
prompts: WorkerPrompts
|
|
# 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 items a transcript's worker has taken into its chunk, as the entry point reads and scores them.
|
|
taken_in: typing.Callable[[list[Entry]], TakenIn]
|
|
# 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:
|
|
cycle = dataclasses.replace(cycle, route=event.stepped.after)
|
|
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, replace=effects.replace_file)
|
|
|
|
|
|
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, _, stepped_from):
|
|
return ask(cycle, transcript_path, ruling, stepped_from)
|
|
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=== {cycle.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.project_archive, cycle.project.rung if cycle.project else cycle.route.rung, 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, the auto-compact window of its context, and the length past which it saves a Bash result to a file."""
|
|
return {**worker_rungs.environment(cycle.project, cycle.route), AUTO_COMPACT_WINDOW: str(COMPACT_WINDOW), BASH_CEILING: str(BASH_CEILING_CHARACTERS)}
|
|
|
|
|
|
def worker_session(cycle: Cycle, transcript_path: str, stepped_from: Rung | None) -> WorkerSession:
|
|
return WorkerSession(cycle.root, cycle.session.id, cycle.route.rung, stepped_from or 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, cycle.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, cycle.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, cycle.prompts.resumed(cycle.unfinished_evidence, cycle.route, cycle.project), resume=True)
|
|
return worker_args(cycle.session, cycle.route.rung, cycle.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 took in, as cycle.taken_in reads them. 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)
|
|
brief = Brief(
|
|
task=cycle.task,
|
|
premises=cycle.premises,
|
|
records=cycle.records,
|
|
records_named=cycle.prompts.records_named,
|
|
answer_destinations=cycle.prompts.answer_destinations,
|
|
entries=entries,
|
|
escalated_at=cycle.route.escalated_at,
|
|
driver=cycle.prompts.driver,
|
|
)
|
|
verdict = judge(cycle.root, brief, 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=cycle.taken_in(entries))
|
|
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)
|
|
|
|
|
|
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=cycle.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(cycle, 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, stepped_from: Rung | None) -> HumanTyped | HumanTalked | Stop:
|
|
"""The human's answer to a ruling that rule archived as it ruled; the human's answer then grows the transcript. stepped_from is the rung the worker ran on, where the ruling stepped it up."""
|
|
# Only the human may cut a release, so a release ready to cut opens claude's session at once.
|
|
answer = interrupt(question_for(cycle, ruling), not (isinstance(ruling, Interrupt) and ruling.release_ready), worker_session(cycle, transcript_path, stepped_from), cycle.window, cycle.prompts.driver, 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(cycle: Cycle, ruling: Interrupt | QuotedAnswer) -> str:
|
|
if isinstance(ruling, Interrupt):
|
|
return ruling.question
|
|
return cycle.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()
|