Restructure bin/ so the project reads at the comprehension floor

This commit is contained in:
2026-10-09 14:12:16 +02:00
parent 2157f5927d
commit b1913ed65d
46 changed files with 484 additions and 400 deletions
+7
View File
@@ -17,9 +17,12 @@
!agents/
!agents/*.md
!bin/
!bin/claude_code/
!bin/claude_code/*.py
!bin/comprehension_history.py
!bin/failure.py
!bin/file_writes.py
!bin/host_env.py
!bin/larv-review
!bin/larv_review/
!bin/larv_review/*.py
@@ -35,8 +38,12 @@
!bin/reading-cost
!bin/reading_cost/
!bin/reading_cost/*.py
!bin/repo_checks/
!bin/repo_checks/*.py
!bin/statusline.py
!bin/test_*.py
!bin/transcript_archive/
!bin/transcript_archive/*.py
!docs/
!docs/*.md
!principles/
+2
View File
@@ -74,6 +74,8 @@ Install puts only `loop-claude` on `PATH`; call the others by their path, such a
- `reading-cost [--reset] [record]` appends a figure for each chunk `loop-claude` finished to a project's `docs/reading-cost.md`, and says whether the figures rise; `reading-cost --help` states the measure.
- `statusline.py` renders Claude Code's status line; `settings.json` → `statusLine` runs it.
`bin/` is the import root: each launcher puts it on `sys.path`, so a module imports another by its path under `bin/`, such as `from claude_code.entries import parse_entry`. Each tool's package holds its tests. `claude_code/` reads Claude Code's files and output, and `transcript_archive/` writes and reads `loop-claude`'s archive; both serve more than one tool. `repo_checks/` tests the repo itself.
Test on the host, with `uv` on `PATH` to fetch mypy and the Python version Install names (`docs/decisions.md` → `bin/`): `python3 -m unittest discover -s bin -p 'test_*.py'`
## Tracking a new file
@@ -6,7 +6,6 @@ import shutil
import uuid
from failure import Failure
from loop_claude.paths import Paths
NAMESPACE = uuid.UUID("64fb586b-d926-4bb3-a44c-c903e86d3eec")
@@ -19,10 +18,8 @@ class Session:
name: str
def session_for(project_key: str, paths: Paths) -> Session:
# "A " is the human's cue in the session picker that the session is the loop's.
name = f"A {project_key} loop-claude"
return Session(id=uuid.uuid5(NAMESPACE, name), claude_code_transcripts=paths.claude_code_transcripts, name=name)
def session_named(name: str, claude_code_transcripts: pathlib.Path) -> Session:
return Session(id=uuid.uuid5(NAMESPACE, name), claude_code_transcripts=claude_code_transcripts, name=name)
# <claude_code_transcripts>/-home-me-code-log/<session id>.jsonl
+93
View File
@@ -0,0 +1,93 @@
import json
import pathlib
import sys
import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from claude_code import entries, transcript, trust
def assistant(*parts):
return {"type": "assistant", "message": {"content": list(parts)}}
def human(content):
return {"type": "user", "message": {"content": content}}
def queued(prompt, kind):
return {"type": "attachment", "attachment": {"type": "queued_command", "commandMode": "prompt", "origin": {"kind": kind}, "prompt": prompt}}
class Render(unittest.TestCase):
def test_joins_assistant_text_tool_calls_human_turns_and_loop_prompts_and_skips_the_rest(self):
said = transcript.render([
human("do it"),
assistant({"type": "text", "text": "Starting."}, {"type": "tool_use", "name": "Bash", "input": {"command": "ls"}}),
assistant({"type": "text", "text": " "}),
human([{"type": "tool_result", "content": "not typed"}]),
human("<command-name>/exit</command-name>"),
human([{"type": "text", "text": "yes, "}, {"type": "text", "text": "merge it"}]),
queued("B, while you work", "human"),
queued("origin/main moved", "coordinator"),
{**human("Continue the task; the previous run stopped before it was finished."), "promptSource": "sdk"},
])
self.assertEqual(said, '[human] do it\n\nStarting.\n\n[tool Bash] {"command": "ls"}\n\n[human] yes, merge it\n\n[human] B, while you work\n\n[loop] Continue the task; the previous run stopped before it was finished.')
class FirstTimestampedLine(unittest.TestCase):
def test_skips_the_lines_every_chunk_shares_and_else_takes_the_first(self):
self.assertEqual(transcript.first_timestamped_line(b'{"type": "custom-title"}\nnot JSON\n{"timestamp": "t"}\n{"timestamp": "u"}\n'), b'{"timestamp": "t"}')
self.assertEqual(transcript.first_timestamped_line(b'{"type": "custom-title"}\n[1]\n'), b'{"type": "custom-title"}')
self.assertEqual(transcript.first_timestamped_line(b""), b"")
class HumanTurns(unittest.TestCase):
def test_counts_typed_turns_and_not_tool_results(self):
self.assertEqual(transcript.human_turns([
human("typed"),
human([{"type": "text", "text": "typed as a block"}]),
human([{"type": "tool_result", "content": "not typed"}]),
human("<command-name>/model</command-name>"),
{**human("<3 merge it"), "promptSource": "typed"},
{**human("<task-notification>done</task-notification>"), "promptSource": "system"},
{**human([{"type": "text", "text": "<task-notification>done</task-notification>"}]), "promptSource": "system"},
{**human("peer message"), "isMeta": True},
{**human("the loop's own prompt"), "promptSource": "sdk"},
human([{"type": "text", "text": "[Request interrupted by user]"}]),
human([]),
queued("typed while claude worked", "human"),
queued("<task-notification>done</task-notification>", "task-notification"),
{"type": "attachment", "attachment": {"type": "queued_command", "commandMode": "task-notification", "prompt": "<task-notification>done</task-notification>"}},
assistant({"type": "text", "text": "said"}),
]), 4)
class PartLine(unittest.TestCase):
def test_renders_text_and_tool_calls_and_nothing_else(self):
self.assertEqual(transcript.part_line({"type": "text", "text": "hi"}, 20), "hi")
self.assertEqual(transcript.part_line({"type": "text", "text": " \n"}, 20), "")
self.assertEqual(transcript.part_line({"type": "tool_use", "name": "Bash", "input": {"command": "x" * 500}}, 20), '[tool Bash] {"command": "xxxxxxx')
self.assertEqual(transcript.part_line("not a part", 20), "")
self.assertEqual(transcript.part_line({"type": "tool_use", "name": "Write", "input": {"content": "Hälsa på"}}, 40), '[tool Write] {"content": "Hälsa på"}')
class Parse(unittest.TestCase):
def test_yields_only_json_objects(self):
self.assertEqual(entries.parse_entry('{"type": "user"}'), {"type": "user"})
self.assertIsNone(entries.parse_entry("not json"))
self.assertIsNone(entries.parse_entry("[1, 2]"))
class MarkTrusted(unittest.TestCase):
def test_returns_the_updated_config_and_leaves_the_one_it_was_handed(self):
config = {"other": 1, "projects": {"/a": {"hasTrustDialogAccepted": True}, "/b": {"kept": True}}}
handed = json.dumps(config)
self.assertEqual(trust.mark_trusted(config, ["/a", "/b", "/c"]), ({"other": 1, "projects": {"/a": {"hasTrustDialogAccepted": True}, "/b": {"hasTrustDialogAccepted": True, "kept": True}, "/c": {"hasTrustDialogAccepted": True}}}, ["/b", "/c"]))
self.assertEqual(json.dumps(config), handed)
self.assertEqual(trust.mark_trusted({}, ["/a"]), ({"projects": {"/a": {"hasTrustDialogAccepted": True}}}, ["/a"]))
if __name__ == "__main__":
unittest.main()
@@ -1,6 +1,6 @@
import json
from loop_claude.claude_code.entries import assistant_parts, human_text, loop_text, parse_entry, part_text, tool_call
from claude_code.entries import assistant_parts, human_text, loop_text, parse_entry, part_text, tool_call
from failure import Failure
JUDGED_TOOL_INPUT = 400
+6
View File
@@ -0,0 +1,6 @@
import os
# A git hook's GIT_DIR, the host's LOOP_CLAUDE_* or PYTHONPATH would point the program under test at the host's own state.
def host_env() -> dict[str, str]:
return {name: value for name, value in os.environ.items() if not name.startswith(("GIT_", "LOOP_CLAUDE_", "PYTHON"))}
@@ -7,19 +7,19 @@ import tempfile
import textwrap
import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from comprehension_history import appended, entries, Place, recorded, ruling_entry, Scoring, Seat
from larv_review.base import base, first_ruling, HistoryChange, measured_commit
from larv_review.ruling import counted, fallen, ruling, votes
from failure import Failure
from larv_review.scoring import fall_ruling, fall_step, means, plan_items, scoring_run_due, under_floor
from test_loop_claude_black_box import host_env
from host_env import host_env
from rank_todo import Item
from larv_review.rounds import round_counts
from larv_review.seats import score_line, scores, seats_file
TOOL = pathlib.Path(__file__).resolve().parent / "larv-review"
TOOL = pathlib.Path(__file__).resolve().parents[1] / "larv-review"
SCORING = "## 2026-10-08T12:00:00Z, PR #1 at aaaaaaa\n\n| Seat | Overall |\n|---|---|\n| Mean | 7.00 |\n"
+1 -1
View File
@@ -9,4 +9,4 @@ sys.path.insert(0, str(LAUNCHER.parent))
from loop_claude import effects, paths
from loop_claude.loop import main
sys.exit(main.main(sys.argv[1:], os.environ, paths.paths_from(pathlib.Path.home(), os.environ), LAUNCHER, pathlib.Path.cwd(), effects.system_effects()))
sys.exit(main.main(sys.argv[1:], os.environ, paths.paths_from(pathlib.Path.home()), LAUNCHER, pathlib.Path.cwd(), effects.system_effects()))
+2 -2
View File
@@ -3,10 +3,10 @@ import uuid
from loop_claude.effects import Effects
from failure import Failure
from loop_claude.claude_code.transcript import human_turns, read_transcript
from claude_code.transcript import human_turns, read_transcript
from loop_claude.stop import needs_human, needs_terminal, Stop
from loop_claude.paths import Paths
from loop_claude.claude_code.trust import trust
from claude_code.trust import trust
from loop_claude.project.checkout import worktrees
ANSWER_QUESTION = "answer the question above"
+97 -2
View File
@@ -1,15 +1,110 @@
import dataclasses
import json
import re
import typing
from loop_claude.project.records import ANSWER_DESTINATIONS, ANSWERS_RECORDED, HUMAN_RULES
from loop_claude.effects import Effects
from failure import Failure
from loop_claude.claude_code.entries import hit_limit, limit_said, parse_entry, structured_output
from loop_claude.cycle.judge_reply import Interrupt, JUDGE_RULES, JUDGE_SCHEMA, QuotedAnswer, Verdict, verdict_from
from claude_code.entries import hit_limit, limit_said, parse_entry, structured_output
from loop_claude.cycle.retry import Limited, retried
from loop_claude.stop import Stop
# At 3 to 4 characters a token, 100,000 to 133,000 tokens, which leaves a 200,000-token context room for the reply; the largest session rendered here was 364,000 characters on 2026-10-03.
JUDGE_PROMPT_CHARS = 400000
JUDGE_RULES = (
"Decide whether the human must now be interrupted. interrupt=true when any of these appear:\n"
"- the agent asks the human anything, seeks approval, or says a decision is the human's, and neither "
"README.md nor the records settle the matter\n"
"- it asks again a question a [loop] line already answered\n"
"- it carried on under an assumption that decides the deliverable, that the human could "
"reasonably reject and that neither README.md nor the records settle; a caveat about "
"transient state it then handled is not one\n"
"- it is blocked on something only the human can supply: a credential, a version bump, a choice "
"outside the repo, or a release ready to cut, which only the human may publish\n"
"- it flags that the goals, the plan in todo.md or the task itself is unclear, missing or in need of change\n"
"- it chose between alternatives that neither README.md nor the records discriminate "
"between - neither rules the rejected one out - and the choice materially changes the deliverable\n"
"interrupt=false otherwise. Bookkeeping the agent settled silently - what to document, wording, "
"where a note goes - is not on its own a reason to interrupt. The human may have replied inside the transcript, on a [human] line: judge only what "
"is still open, never a question they already answered there. A [loop] line is what loop-claude told "
"the agent, such as an answer quoted from README.md or the records.\n"
"Where the agent asked or flagged something itself, the question is that one, in the agent's own "
"wording; never construct another from facts it stated.\n"
"Where README.md or the records answer the agent's own question and no [loop] line has "
"quoted that answer yet, set interrupt=false and quote the passage that answers it; the agent is "
"then given that passage in place of the human's reply. An interrupt outranks a quoted answer, and either "
"outranks finished.\n"
"The chunk is the piece of work the agent is on, shipped as one pull request. "
"finished=true when the chunk is complete: merged, or nothing remains that the agent could do on "
f"its own. Even then, it is finished only once {ANSWERS_RECORDED}. An answer counts as recorded "
f"where README.md or the records above hold it, {HUMAN_RULES} included. It also counts where "
f"the transcript shows the agent writing it into {ANSWER_DESTINATIONS}; writing it into "
f"{HUMAN_RULES} does not count. finished=false when work remains that a further run can "
"continue: an open PR, a review not yet run, CI not yet reported, an answer not yet recorded."
)
@dataclasses.dataclass(frozen=True)
class Reply:
answer: str = dataclasses.field(metadata={"description": "With interrupt false, the passage of README.md or the records that answers the agent's question, quoted verbatim, without elisions. Empty otherwise."})
evidence: str = dataclasses.field(metadata={"description": "A verbatim quote of the one transcript passage the verdict rests on, without elisions: what triggers the interrupt; for a quoted answer, the agent's question; else what shows the chunk finished or the work remaining."})
finished: bool = dataclasses.field(metadata={"description": "Whether the chunk is finished."})
interrupt: bool = dataclasses.field(metadata={"description": "Whether the human must now be interrupted."})
question: str = dataclasses.field(metadata={"description": "With interrupt true, the single question to put to the human. With a quoted answer, the agent's question that the answer field answers. Empty otherwise."})
REPLY_TYPES = typing.get_type_hints(Reply)
JSON_TYPES = {bool: "boolean", str: "string"}
JUDGE_SCHEMA = {
"properties": {field.name: {**field.metadata, "type": JSON_TYPES[REPLY_TYPES[field.name]]} for field in dataclasses.fields(Reply)},
"required": list(REPLY_TYPES),
"type": "object",
}
@dataclasses.dataclass(frozen=True)
class Interrupt:
evidence: str
question: str
@dataclasses.dataclass(frozen=True)
class QuotedAnswer:
"""The agent asked a question that README.md or the records answer. The answer field quotes the passage."""
evidence: str
question: str
answer: str
@dataclasses.dataclass(frozen=True)
class Finished:
evidence: str
@dataclasses.dataclass(frozen=True)
class Unfinished:
evidence: str
Verdict = Interrupt | QuotedAnswer | Finished | Unfinished
def verdict_from(output: object) -> Verdict | Failure:
if not isinstance(output, dict):
return Failure("the judge returned no reply")
for name, kind in REPLY_TYPES.items():
if not isinstance(output.get(name), kind):
return Failure(f"the judge's reply has no {name} of type {JSON_TYPES[kind]}")
if output["interrupt"]:
if not output["question"].strip():
return Failure("the judge interrupted without a question")
return Interrupt(output["evidence"], output["question"])
if output["answer"].strip():
if not output["question"].strip():
return Failure("the judge quoted an answer without a question")
return QuotedAnswer(output["evidence"], output["question"], output["answer"])
return Finished(output["evidence"]) if output["finished"] else Unfinished(output["evidence"])
def judge(root: str, task: str, premises: str, records: str, rendered_transcript: str, model: str, effects: Effects) -> Verdict | Stop:
-104
View File
@@ -1,104 +0,0 @@
import dataclasses
import typing
from failure import Failure
from loop_claude.project.records import HUMAN_RULES, RECORD_FILES
# Where the judge may quote an answer from, named as the human and the worker see them; of README.md the judge sees only the premises.
QUOTE_SOURCES = "README.md's Goals and Audience, " + ", ".join(RECORD_FILES) + " or " + HUMAN_RULES
# Where the worker may write an answer the human typed, so it counts as recorded.
ANSWER_DESTINATIONS = "README.md's Goals or Audience, " + ", ".join(RECORD_FILES) + ", todo.md or a comment"
ANSWERS_RECORDED = f"every answer the human typed in it that a later chunk could need is recorded in {ANSWER_DESTINATIONS} at the one place it governs"
JUDGE_RULES = (
"Decide whether the human must now be interrupted. interrupt=true when any of these appear:\n"
"- the agent asks the human anything, seeks approval, or says a decision is the human's, and neither "
"README.md nor the records settle the matter\n"
"- it asks again a question a [loop] line already answered\n"
"- it carried on under an assumption that decides the deliverable, that the human could "
"reasonably reject and that neither README.md nor the records settle; a caveat about "
"transient state it then handled is not one\n"
"- it is blocked on something only the human can supply: a credential, a version bump, a choice "
"outside the repo, or a release ready to cut, which only the human may publish\n"
"- it flags that the goals, the plan in todo.md or the task itself is unclear, missing or in need of change\n"
"- it chose between alternatives that neither README.md nor the records discriminate "
"between - neither rules the rejected one out - and the choice materially changes the deliverable\n"
"interrupt=false otherwise. Bookkeeping the agent settled silently - what to document, wording, "
"where a note goes - is not on its own a reason to interrupt. The human may have replied inside the transcript, on a [human] line: judge only what "
"is still open, never a question they already answered there. A [loop] line is what loop-claude told "
"the agent, such as an answer quoted from README.md or the records.\n"
"Where the agent asked or flagged something itself, the question is that one, in the agent's own "
"wording; never construct another from facts it stated.\n"
"Where README.md or the records answer the agent's own question and no [loop] line has "
"quoted that answer yet, set interrupt=false and quote the passage that answers it; the agent is "
"then given that passage in place of the human's reply. An interrupt outranks a quoted answer, and either "
"outranks finished.\n"
"The chunk is the piece of work the agent is on, shipped as one pull request. "
"finished=true when the chunk is complete: merged, or nothing remains that the agent could do on "
f"its own. Even then, it is finished only once {ANSWERS_RECORDED}. An answer counts as recorded "
f"where README.md or the records above hold it, {HUMAN_RULES} included. It also counts where "
f"the transcript shows the agent writing it into {ANSWER_DESTINATIONS}; writing it into "
f"{HUMAN_RULES} does not count. finished=false when work remains that a further run can "
"continue: an open PR, a review not yet run, CI not yet reported, an answer not yet recorded."
)
@dataclasses.dataclass(frozen=True)
class Reply:
answer: str = dataclasses.field(metadata={"description": "With interrupt false, the passage of README.md or the records that answers the agent's question, quoted verbatim, without elisions. Empty otherwise."})
evidence: str = dataclasses.field(metadata={"description": "A verbatim quote of the one transcript passage the verdict rests on, without elisions: what triggers the interrupt; for a quoted answer, the agent's question; else what shows the chunk finished or the work remaining."})
finished: bool = dataclasses.field(metadata={"description": "Whether the chunk is finished."})
interrupt: bool = dataclasses.field(metadata={"description": "Whether the human must now be interrupted."})
question: str = dataclasses.field(metadata={"description": "With interrupt true, the single question to put to the human. With a quoted answer, the agent's question that the answer field answers. Empty otherwise."})
REPLY_TYPES = typing.get_type_hints(Reply)
JSON_TYPES = {bool: "boolean", str: "string"}
JUDGE_SCHEMA = {
"properties": {field.name: {**field.metadata, "type": JSON_TYPES[REPLY_TYPES[field.name]]} for field in dataclasses.fields(Reply)},
"required": list(REPLY_TYPES),
"type": "object",
}
@dataclasses.dataclass(frozen=True)
class Interrupt:
evidence: str
question: str
@dataclasses.dataclass(frozen=True)
class QuotedAnswer:
"""The agent asked a question that README.md or the records answer. The answer field quotes the passage."""
evidence: str
question: str
answer: str
@dataclasses.dataclass(frozen=True)
class Finished:
evidence: str
@dataclasses.dataclass(frozen=True)
class Unfinished:
evidence: str
Verdict = Interrupt | QuotedAnswer | Finished | Unfinished
def verdict_from(output: object) -> Verdict | Failure:
if not isinstance(output, dict):
return Failure("the judge returned no reply")
for name, kind in REPLY_TYPES.items():
if not isinstance(output.get(name), kind):
return Failure(f"the judge's reply has no {name} of type {JSON_TYPES[kind]}")
if output["interrupt"]:
if not output["question"].strip():
return Failure("the judge interrupted without a question")
return Interrupt(output["evidence"], output["question"])
if output["answer"].strip():
if not output["question"].strip():
return Failure("the judge quoted an answer without a question")
return QuotedAnswer(output["evidence"], output["question"], output["answer"])
return Finished(output["evidence"]) if output["finished"] else Unfinished(output["evidence"])
+15 -18
View File
@@ -1,17 +1,19 @@
import dataclasses
import pathlib
import typing
from loop_claude.cycle.states import Active, Archived, Closing, Ended, Event, HumanAnswered, Interrupting, Judging, QUOTED_ANSWERS_PER_CYCLE, Ruled, State, transition, WorkerRan, Working
from loop_claude.transcript_archive import archive, FINISHED, UNFINISHED
from loop_claude.claude_code.session import delete_session, Session, session_open, transcript_file
from transcript_archive.write import archive
from claude_code.session import delete_session, Session, session_open, transcript_file
from loop_claude.effects import Effects
from failure import Failure
from loop_claude.cycle.judge_reply import Finished, Interrupt, QUOTE_SOURCES, QuotedAnswer, Unfinished
from loop_claude.cycle.judge import Finished, Interrupt, judge, QuotedAnswer, Unfinished
from loop_claude.cycle.interrupt import interrupt
from loop_claude.cycle.judge import judge
from loop_claude.project.model_choice import Models
from transcript_archive import outcomes
from loop_claude.paths import Paths
from loop_claude.claude_code.transcript import read_transcript, render
from loop_claude.project.records import QUOTE_SOURCES
from claude_code.transcript import read_transcript, render
from loop_claude.cycle.retry import retried
from loop_claude.cycle.worker import run_worker, worker_args
from loop_claude.stop import Stop
@@ -23,13 +25,13 @@ class Cycle:
models: Models
paths: Paths
premises: str
project_key: str
project_archive: pathlib.Path
records: str
# The evidence of the previous cycle's unfinished verdict, empty after any other.
remaining: str
root: str
session: Session
task: str
# Empty when the previous cycle's verdict was not Unfinished.
unfinished_evidence: str
def run_cycle(cycle: Cycle) -> Stop | Finished | Unfinished:
@@ -47,7 +49,7 @@ def run_cycle(cycle: Cycle) -> Stop | Finished | Unfinished:
def stopped(cycle: Cycle, stop: Stop, why: str) -> Stop:
path = transcript_file(cycle.session)
failure = archive(cycle.project_key, path, cycle.task, f"Stopped: {why}", cycle.effects.now(), cycle.paths) if path else None
failure = archive(cycle.project_archive, path, cycle.task, outcomes.stopped(why), cycle.effects.now()) if path else None
# A failed archive exits 1 whatever the stop; when the stop was this archive failing, its reason is said once.
return Stop(1, f"{failure.reason}\n{stop.reason}".rstrip()) if failure and failure.reason != stop.reason else stop
@@ -72,7 +74,7 @@ def work(cycle: Cycle, answered: QuotedAnswer | None) -> WorkerRan | Stop:
if stop := keep_answer(cycle, answered):
return stop
# session_open runs inside the lambda: a failed attempt may have opened the session.
if stop := retried("worker", lambda: run_worker(cycle.root, worker_args(cycle.task, cycle.session, cycle.models.worker, session_open(cycle.session), answered, quoted(cycle.remaining)), cycle.effects), cycle.effects):
if stop := retried("worker", lambda: run_worker(cycle.root, worker_args(cycle.task, cycle.session, cycle.models.worker, session_open(cycle.session), answered, cycle.unfinished_evidence), 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}")
@@ -80,7 +82,7 @@ def work(cycle: Cycle, answered: QuotedAnswer | None) -> WorkerRan | Stop:
def keep_answer(cycle: Cycle, answered: QuotedAnswer) -> Stop | None:
path = transcript_file(cycle.session)
if path and (failure := archive(cycle.project_key, path, cycle.task, f"Verdict: quoted answer\n\n{answered.question}\n\n{QUOTE_SOURCES} says:\n{quoted(answered.answer)}\n\nEvidence:\n{quoted(answered.evidence)}", cycle.effects.now(), cycle.paths)):
if path and (failure := archive(cycle.project_archive, path, cycle.task, outcomes.answered(answered.question, QUOTE_SOURCES, answered.answer, answered.evidence), cycle.effects.now())):
return Stop(1, failure.reason)
return None
@@ -96,7 +98,7 @@ def rule(cycle: Cycle, transcript_path: str) -> Ruled | Stop:
def ask(cycle: Cycle, transcript_path: str, ruling: Interrupt | QuotedAnswer) -> HumanAnswered | Stop:
question = question_for(ruling)
# Archived now, so the transcript the question was asked on is kept with it; the human's answer then grows the transcript.
if failure := archive(cycle.project_key, transcript_path, cycle.task, f"Verdict: interrupt\n\n{question}\n\nEvidence:\n{quoted(ruling.evidence)}", cycle.effects.now(), cycle.paths):
if failure := archive(cycle.project_archive, transcript_path, cycle.task, outcomes.interrupted(question, ruling.evidence), cycle.effects.now()):
return Stop(1, failure.reason)
return interrupt(cycle.root, cycle.session.id, cycle.models.worker, transcript_path, question, cycle.paths, cycle.effects) or HumanAnswered()
@@ -109,13 +111,8 @@ def question_for(ruling: Interrupt | QuotedAnswer) -> str:
def close(cycle: Cycle, transcript_path: str, verdict: Finished | Unfinished) -> Archived | Stop:
finished = isinstance(verdict, Finished)
if failure := archive(cycle.project_key, transcript_path, cycle.task, f"{FINISHED if finished else UNFINISHED}\n\nEvidence:\n{quoted(verdict.evidence)}", cycle.effects.now(), cycle.paths):
if failure := archive(cycle.project_archive, transcript_path, cycle.task, outcomes.finished(verdict.evidence) if finished else outcomes.unfinished(verdict.evidence), cycle.effects.now()):
return Stop(1, failure.reason)
if finished and (failure := delete_session(cycle.session)):
return Stop(1, failure.reason)
return Archived()
# Blockquoted, so evidence holding blank lines still ends visibly where the text after it starts.
def quoted(passage: str) -> str:
return "\n".join(f"> {line}" for line in passage.splitlines())
+4 -2
View File
@@ -1,6 +1,6 @@
import dataclasses
from loop_claude.cycle.judge_reply import Finished, Interrupt, QuotedAnswer, Unfinished, Verdict
from loop_claude.cycle.judge import Finished, Interrupt, QuotedAnswer, Unfinished, Verdict
# A backstop for what the judge misses, such as a reworded repeat, so the worker cannot loop unattended on answers quoted from README.md or the records.
QUOTED_ANSWERS_PER_CYCLE = 3
@@ -72,7 +72,9 @@ def transition(state: State, event: Event) -> State:
return Judging(transcript_path, quoted_answers)
case Judging(_, quoted_answers), Ruled(QuotedAnswer() as answered) if quoted_answers < QUOTED_ANSWERS_PER_CYCLE:
return Working(answered, quoted_answers + 1)
case Judging(transcript_path, quoted_answers), Ruled(Interrupt() | QuotedAnswer() as ruling):
case Judging(transcript_path, quoted_answers), Ruled(QuotedAnswer() as ruling) if quoted_answers >= QUOTED_ANSWERS_PER_CYCLE:
return Interrupting(transcript_path, ruling, quoted_answers)
case Judging(transcript_path, quoted_answers), Ruled(Interrupt() as ruling):
return Interrupting(transcript_path, ruling, quoted_answers)
case Judging(transcript_path, _), Ruled(Finished() | Unfinished() as verdict):
return Closing(transcript_path, verdict)
+8 -6
View File
@@ -1,10 +1,12 @@
from loop_claude.cycle.judge_reply import ANSWERS_RECORDED, QUOTE_SOURCES, QuotedAnswer
from loop_claude.claude_code.entries import assistant_parts, ends_stream, hit_limit, limit_said, parse_entry, rejected_until
from loop_claude.project.records import ANSWERS_RECORDED, QUOTE_SOURCES
from claude_code.entries import assistant_parts, ends_stream, hit_limit, limit_said, parse_entry, rejected_until
from loop_claude.effects import Effects
from failure import Failure
from loop_claude.cycle.retry import Limited
from loop_claude.claude_code.transcript import part_line
from loop_claude.claude_code.session import Session
from claude_code.transcript import part_line
from transcript_archive.outcomes import quoted
from loop_claude.cycle.judge import QuotedAnswer
from claude_code.session import Session
PRINTED_TOOL_INPUT = 160
@@ -38,11 +40,11 @@ def worker_outcome(code: int, result: dict | None, resets: list[int]) -> Failure
return None if result is not None else Failure("claude exited 0 without a result event")
def worker_args(task: str, session: Session, model: str, resuming: bool, answered: QuotedAnswer | None = None, remaining: str = "") -> list[str]:
def worker_args(task: str, session: Session, model: str, resuming: bool, answered: QuotedAnswer | None = None, unfinished_evidence: str = "") -> list[str]:
if answered is not None:
start = ["-p", f"Your question: {answered.question}\n\n{QUOTE_SOURCES} answers it:\n\n{answered.answer}\n\nContinue the task.", "--resume", str(session.id)]
elif resuming:
ruled = f" A judge ruled the chunk unfinished, quoting this passage of your transcript as the work remaining:\n\n{remaining}\n\n" if remaining else " "
ruled = f" A judge ruled the chunk unfinished, quoting this passage of your transcript as the work remaining:\n\n{quoted(unfinished_evidence)}\n\n" if unfinished_evidence else " "
start = ["-p", f"Continue the task; the previous run ended before the chunk was finished.{ruled}The chunk is finished once it is merged, or nothing remains that you could do on your own. Even then, it is finished only once {ANSWERS_RECORDED}.", "--resume", str(session.id)]
else:
# --session-id creates the session under the id loop-claude keeps; --resume continues that session.
+11 -8
View File
@@ -77,17 +77,18 @@ import pathlib
import sys
import typing
from loop_claude.project.checkout import checkout_root, project_key
from loop_claude.project.checkout import checkout_root
from loop_claude.cycle.run import Cycle, run_cycle
from loop_claude.loop.reload import decode_handed, exec_if_edited, fingerprint, LoopRun, RELOAD_FLAG
from loop_claude.effects import Effects
from loop_claude.project.model_choice import get_or_ask_models
from loop_claude.paths import Paths
from transcript_archive.location import project_archive, project_key
from loop_claude.project.premises import read_premises
from loop_claude.project.records import read_records
from loop_claude.claude_code.session import session_for
from claude_code.session import session_named
from loop_claude.stop import Stop
from loop_claude.cycle.judge_reply import Unfinished
from loop_claude.cycle.judge import Unfinished
def main(argv: list[str], env: typing.Mapping[str, str], paths: Paths, launcher: pathlib.Path, cwd: pathlib.Path, effects: Effects) -> int:
@@ -105,8 +106,10 @@ def run_loop(argv: list[str], env: typing.Mapping[str, str], paths: Paths, launc
if isinstance(loop_run, Stop):
return loop_run
baseline = fingerprint(launcher)
key = project_key(loop_run.root, paths.code)
session = session_for(key, paths)
key = project_key(loop_run.root, paths.home)
archive = project_archive(loop_run.root, paths.home, env)
# "A " is the human's cue in the session picker that the session is the loop's.
session = session_named(f"A {key} loop-claude", paths.claude_code_transcripts)
while True:
if stop := exec_if_edited(launcher, baseline, loop_run, effects):
return stop
@@ -121,10 +124,10 @@ def run_loop(argv: list[str], env: typing.Mapping[str, str], paths: Paths, launc
if isinstance(models, Stop):
return models
print(f"\n=== cycle {loop_run.cycle_number} ===", flush=True)
verdict = run_cycle(Cycle(effects=effects, models=models, paths=paths, premises=premises, project_key=key, records=records, remaining=loop_run.remaining, root=loop_run.root, session=session, task=loop_run.task))
verdict = run_cycle(Cycle(effects=effects, models=models, paths=paths, premises=premises, project_archive=archive, records=records, root=loop_run.root, session=session, task=loop_run.task, unfinished_evidence=loop_run.unfinished_evidence))
if isinstance(verdict, Stop):
return verdict
loop_run = dataclasses.replace(loop_run, remaining=verdict.evidence if isinstance(verdict, Unfinished) else "")
loop_run = dataclasses.replace(loop_run, unfinished_evidence=verdict.evidence if isinstance(verdict, Unfinished) else "")
def loop_run_from(argv: list[str], cwd: pathlib.Path, effects: Effects) -> LoopRun | Stop:
@@ -133,7 +136,7 @@ def loop_run_from(argv: list[str], cwd: pathlib.Path, effects: Effects) -> LoopR
if task in ("", "-h", "--help"):
return Stop(0 if task else 1, __doc__.strip())
root = checkout_root(cwd, effects)
return root if isinstance(root, Stop) else LoopRun(0, "", root, task)
return root if isinstance(root, Stop) else LoopRun(0, root, task, "")
loop_run = decode_handed(argv[1], LoopRun) if len(argv) == 2 else None
if not (loop_run and loop_run.root and loop_run.task):
return Stop(1, f"the edited loop-claude cannot read the state the running one handed it, likely because the edit changed that handover; rerun loop-claude <task>. Handed: {' '.join(argv[1:])}")
+1 -1
View File
@@ -17,9 +17,9 @@ T = typing.TypeVar("T")
class LoopRun:
"""What a reload hands the edited script, as JSON on argv."""
cycle_number: int
remaining: str
root: str
task: str
unfinished_evidence: str
def decode_handed(handed: str, kind: type[T]) -> T | None:
+3 -6
View File
@@ -1,6 +1,5 @@
import dataclasses
import pathlib
import typing
@dataclasses.dataclass(frozen=True)
@@ -8,20 +7,18 @@ class Paths:
claude_code_transcripts: pathlib.Path
claude_json: pathlib.Path
claude_md: pathlib.Path
code: pathlib.Path
home: pathlib.Path
model_catalog: pathlib.Path
models_file: pathlib.Path
transcript_archive: pathlib.Path
def paths_from(home: pathlib.Path, env: typing.Mapping[str, str]) -> Paths:
def paths_from(home: pathlib.Path) -> Paths:
claude = home / ".claude"
return Paths(
claude_code_transcripts=claude / "projects",
claude_json=home / ".claude.json",
claude_md=claude / "CLAUDE.md",
code=home / "code",
home=home,
model_catalog=claude / "cache" / "model-catalog",
models_file=claude / "loop-claude-models.json",
transcript_archive=pathlib.Path(env["LOOP_CLAUDE_TRANSCRIPTS"]).expanduser() if env.get("LOOP_CLAUDE_TRANSCRIPTS") else claude / "loop-claude-transcripts",
)
-4
View File
@@ -25,10 +25,6 @@ def worktrees(root: str, effects: Effects) -> list[str]:
return sorted(set(found))
def project_key(root: str, code: pathlib.Path) -> str:
return root.removeprefix(f"{code}/").lstrip("/")
def read_utf8(folder: str, name: str, consequence: str) -> str | Stop:
try:
return pathlib.Path(folder, name).read_text(encoding="utf-8")
+1 -1
View File
@@ -4,7 +4,7 @@ import pathlib
import sys
import typing
from loop_claude.claude_code.model_catalog import catalog_models
from claude_code.model_catalog import catalog_models
from loop_claude.effects import Effects
from failure import Failure
from loop_claude.stop import needs_human, needs_terminal, Stop
+5
View File
@@ -6,6 +6,11 @@ from loop_claude.stop import Stop
# The records: these project files and HUMAN_RULES; the judge reads them beside the README's premises.
RECORD_FILES = ("AGENTS.md", "docs/decisions.md")
HUMAN_RULES = "~/.claude/CLAUDE.md"
# Where the judge may quote an answer from, named as the human and the worker see them; of README.md the judge sees only the premises.
QUOTE_SOURCES = "README.md's Goals and Audience, " + ", ".join(RECORD_FILES) + " or " + HUMAN_RULES
# Where the worker may write an answer the human typed, so it counts as recorded.
ANSWER_DESTINATIONS = "README.md's Goals or Audience, " + ", ".join(RECORD_FILES) + ", todo.md or a comment"
ANSWERS_RECORDED = f"every answer the human typed in it that a later chunk could need is recorded in {ANSWER_DESTINATIONS} at the one place it governs"
def read_records(root: str, claude_md: pathlib.Path) -> str | Stop:
@@ -15,14 +15,14 @@ import tempfile
import time
import unittest
BIN = pathlib.Path(__file__).resolve().parent
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from host_env import host_env
BIN = pathlib.Path(__file__).resolve().parents[1]
TASK = "Do the next chunk."
# A git hook's GIT_DIR, the host's LOOP_CLAUDE_* or PYTHONPATH would point the program under test at the host's own state.
def host_env() -> dict[str, str]:
return {name: value for name, value in os.environ.items() if not name.startswith(("GIT_", "LOOP_CLAUDE_", "PYTHON"))}
# Plays claude from FAKE_CLAUDE_SCENARIO, one step per call, logging each call; a step for another role,
# or none left, is Ctrl-C to loop-claude, which otherwise loops forever.
FAKE_CLAUDE = """#!{python}
@@ -687,12 +687,12 @@ class Reload(unittest.TestCase):
self.assertEqual(run.roles(), ["worker", "judge"] * 5)
self.assertIn("keeping the running script", run.stderr)
reloads = [json.loads(argv[1]) for argv in run.starts if argv[:1] == ["--reloaded"]]
self.assertEqual(reloads, [{"cycle_number": cycle, "remaining": "working", "root": str(checkout.root), "task": TASK} for cycle in (2, 3, 4)])
self.assertEqual(reloads, [{"cycle_number": cycle, "root": str(checkout.root), "task": TASK, "unfinished_evidence": "working"} for cycle in (2, 3, 4)])
self.assertIn("=== cycle 5 ===", run.stdout)
outside = checkout.temp / "outside"
outside.mkdir()
state = {"cycle_number": 3, "remaining": "", "root": str(checkout.root), "task": TASK}
state = {"cycle_number": 3, "root": str(checkout.root), "task": TASK, "unfinished_evidence": ""}
run = checkout.run([worker()], argv=["--reloaded", json.dumps(state)], cwd=outside)
self.assertEqual((run.code, run.roles()), (130, ["worker", "judge"]))
self.assertEqual(run.calls[0]["cwd"], str(checkout.root))
@@ -1,7 +1,6 @@
import ast
import contextlib
import dataclasses
import hashlib
import io
import json
import os
@@ -14,18 +13,18 @@ import time
import unittest
import uuid
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from loop_claude import transcript_archive as archive
from loop_claude.project import checkout, model_choice, records
from loop_claude.effects import Effects
from loop_claude.claude_code import entries, session, transcript, trust
from claude_code import entries, session
from failure import Failure
from loop_claude.cycle.judge_reply import Finished, Interrupt, QuotedAnswer, Unfinished, verdict_from
from loop_claude.cycle.judge import Finished, Interrupt, QuotedAnswer, Unfinished, verdict_from
from loop_claude.cycle import interrupt, judge, retry, run, states, worker
from loop_claude.cycle.retry import Limited
from loop_claude.loop import main, reload
from loop_claude import paths
from transcript_archive.location import project_archive
from loop_claude.stop import Stop
CWD = pathlib.Path("/c")
@@ -40,10 +39,6 @@ def human(content):
return {"type": "user", "message": {"content": content}}
def queued(prompt, kind):
return {"type": "attachment", "attachment": {"type": "queued_command", "commandMode": "prompt", "origin": {"kind": kind}, "prompt": prompt}}
class FakeEffects:
"""Effects that record each call and answer from a script, one answer per call."""
@@ -164,24 +159,20 @@ class QuestionFor(unittest.TestCase):
self.assertEqual(run.question_for(QuotedAnswer("e", "Which one?", "A.")), "Which one?\n\nREADME.md's Goals and Audience, AGENTS.md, docs/decisions.md or ~/.claude/CLAUDE.md says:\nA.\n\nThose files have answered 3 questions this cycle, the most allowed, so this one comes to you.")
class Quoted(unittest.TestCase):
def test_quotes_every_line_of_a_passage_blank_ones_included(self):
self.assertEqual(run.quoted("merged\n\nPR #1"), "> merged\n> \n> PR #1")
class Cycles(unittest.TestCase):
def setUp(self):
temp = tempfile.TemporaryDirectory()
self.addCleanup(temp.cleanup)
self.home = pathlib.Path(temp.name)
self.paths = paths.paths_from(self.home, {})
self.session = session.session_for("proj", self.paths)
self.paths = paths.paths_from(self.home)
self.session = session.session_named("A proj loop-claude", self.paths.claude_code_transcripts)
self.archive = project_archive(str(self.home / "code" / "proj"), self.home, {})
def cycle(self, fake, records="", remaining=""):
return run.Cycle(effects=fake.effects(), models=model_choice.Models("judge-model", "worker-model"), paths=self.paths, premises="## Goals", project_key="proj", records=records, remaining=remaining, root=str(self.home), session=self.session, task="Do it.")
def cycle(self, fake, records="", unfinished_evidence=""):
return run.Cycle(effects=fake.effects(), models=model_choice.Models("judge-model", "worker-model"), paths=self.paths, premises="## Goals", project_archive=self.archive, records=records, root=str(self.home), session=self.session, task="Do it.", unfinished_evidence=unfinished_evidence)
def archived_outcomes(self):
return sorted(path.read_text() for path in (self.paths.transcript_archive / "proj").glob("*/*.outcomes.md"))
return sorted(path.read_text() for path in self.archive.glob("*/*.outcomes.md"))
def test_a_finished_chunk_is_archived_and_its_session_deleted(self):
fake = FakeEffects(streams=[Worker(self.paths.claude_code_transcripts.parent)], claude=[judged("finished")])
@@ -193,7 +184,7 @@ class Cycles(unittest.TestCase):
fake = FakeEffects(streams=[Worker(self.paths.claude_code_transcripts.parent)] * 2, claude=[judged("unfinished")] * 2)
self.assertEqual(run.run_cycle(self.cycle(fake)), Unfinished("working"))
self.assertTrue(session.transcript_file(self.session))
self.assertEqual(run.run_cycle(self.cycle(fake, remaining="working")), Unfinished("working"))
self.assertEqual(run.run_cycle(self.cycle(fake, unfinished_evidence="working")), Unfinished("working"))
workers = fake.made("stream_claude")
self.assertIn("--session-id", workers[0])
self.assertIn("--resume", workers[1])
@@ -216,7 +207,7 @@ class Cycles(unittest.TestCase):
(folder.parent / f"{self.session.id}.orphaned-1.jsonl").write_text("o\n")
fake = FakeEffects(streams=[Worker(self.paths.claude_code_transcripts.parent)] * 3, claude=[judged("unfinished"), judged("finished"), judged("unfinished")])
self.assertEqual(run.run_cycle(self.cycle(fake)), Unfinished("working"))
[chunk] = (self.paths.transcript_archive / "proj").iterdir()
[chunk] = self.archive.iterdir()
kept = chunk / "session" / str(self.session.id)
self.assertEqual((chunk / "session" / f"{self.session.id}.orphaned-1.jsonl").read_text(), "o\n")
os.utime(kept / "subagents" / "workflows" / "journal.jsonl", (0, 0))
@@ -232,7 +223,7 @@ class Cycles(unittest.TestCase):
folder.mkdir()
(folder / "custom-title.json").write_text("third")
self.assertEqual(run.run_cycle(self.cycle(fake)), Unfinished("working"))
[next_chunk] = set((self.paths.transcript_archive / "proj").iterdir()) - {chunk}
[next_chunk] = set(self.archive.iterdir()) - {chunk}
self.assertEqual(sorted(path.read_text() for path in (next_chunk / "session" / str(self.session.id)).glob("custom-title.json*")), ["third"])
@unittest.skipIf(os.geteuid() == 0, "root reads an unreadable folder")
@@ -272,11 +263,12 @@ class Cycles(unittest.TestCase):
self.assertEqual(self.archived_outcomes(), [f"Task: Do it.\n\n2026-09-21T14:13:20Z Verdict: interrupt\n\nWhich one?\n\nREADME.md's Goals and Audience, AGENTS.md, docs/decisions.md or ~/.claude/CLAUDE.md says:\nUse *A*.\n\nThose files have answered 3 questions this cycle, the most allowed, so this one comes to you.\n\nEvidence:\n> working\n\n2026-09-21T14:13:20Z Stopped: the human is needed to answer the question above, but the interrupt ended with nothing typed\n", *[f"Task: Do it.\n\n{quoted}"] * 3])
def test_stops_when_a_quoted_answer_cannot_be_archived(self):
self.paths.transcript_archive.parent.mkdir(parents=True)
self.paths.transcript_archive.write_text("")
self.archive.parent.mkdir(parents=True)
self.archive.write_text("")
fake = FakeEffects(streams=[Worker(self.paths.claude_code_transcripts.parent)], claude=[judged("quoted", answer="Use A.")])
with contextlib.redirect_stdout(io.StringIO()):
self.assertEqual(run.run_cycle(self.cycle(fake, records="From AGENTS.md:\nUse A.")), Stop(1, f"could not archive the transcript: {self.paths.transcript_archive / 'proj'}: Not a directory"))
stop = run.run_cycle(self.cycle(fake, records="From AGENTS.md:\nUse A."))
self.assertRegex(stop.reason, f"^could not archive the transcript: {self.archive}/[0-9a-f]{{64}}: Not a directory$")
self.assertEqual(len(fake.made("stream_claude")), 1)
def test_an_answer_the_records_do_not_hold_is_dropped_and_the_question_goes_to_the_human(self):
@@ -357,7 +349,7 @@ class Limits(unittest.TestCase):
class Interrupts(unittest.TestCase):
def test_stops_off_a_terminal_before_starting_claude(self):
fake = FakeEffects(on_terminal=False)
stop = interrupt.interrupt("/r", uuid7(), "m", "/t", "Which one?", paths.paths_from(pathlib.Path("/h"), {}), fake.effects())
stop = interrupt.interrupt("/r", uuid7(), "m", "/t", "Which one?", paths.paths_from(pathlib.Path("/h")), fake.effects())
self.assertEqual(stop, Stop(2, "the human is needed to answer the question above, but stdin or stdout is not a terminal; rerun loop-claude on a terminal"))
self.assertEqual(fake.calls, [])
@@ -366,7 +358,7 @@ class Interrupts(unittest.TestCase):
path = pathlib.Path(home, "t.jsonl")
path.write_text(json.dumps(human("a")) + "\n")
fake = FakeEffects(on_terminal_claude=[0], git=[ran()])
stop = interrupt.interrupt(home, uuid7(), "m", str(path), "Which one?", paths.paths_from(pathlib.Path(home), {}), fake.effects())
stop = interrupt.interrupt(home, uuid7(), "m", str(path), "Which one?", paths.paths_from(pathlib.Path(home)), fake.effects())
self.assertEqual(stop, Stop(2, "the human is needed to answer the question above, but the interrupt ended with nothing typed"))
@@ -391,7 +383,7 @@ class ModelPrompt(unittest.TestCase):
class WorkerArgs(unittest.TestCase):
def test_opens_a_fresh_session_by_name_and_resumes_an_open_one(self):
opened = session.session_for("proj", paths.paths_from(pathlib.Path("/h"), {}))
opened = session.session_named("A proj loop-claude", pathlib.Path("/h/.claude/projects"))
fresh = worker.worker_args("Do it.", opened, "m", False)
self.assertEqual(fresh[fresh.index("--session-id") + 1], str(opened.id))
self.assertEqual(fresh[fresh.index("--name") + 1], "A proj loop-claude")
@@ -425,101 +417,6 @@ class Records(unittest.TestCase):
self.assertEqual(records.read_records(root, claude_md), Stop(1, f"AGENTS.md in {root} is not UTF-8 on line 2 - the judge cannot read the records."))
class Render(unittest.TestCase):
def test_joins_assistant_text_tool_calls_human_turns_and_loop_prompts_and_skips_the_rest(self):
said = transcript.render([
human("do it"),
assistant({"type": "text", "text": "Starting."}, {"type": "tool_use", "name": "Bash", "input": {"command": "ls"}}),
assistant({"type": "text", "text": " "}),
human([{"type": "tool_result", "content": "not typed"}]),
human("<command-name>/exit</command-name>"),
human([{"type": "text", "text": "yes, "}, {"type": "text", "text": "merge it"}]),
queued("B, while you work", "human"),
queued("origin/main moved", "coordinator"),
{**human("Continue the task; the previous run stopped before it was finished."), "promptSource": "sdk"},
])
self.assertEqual(said, '[human] do it\n\nStarting.\n\n[tool Bash] {"command": "ls"}\n\n[human] yes, merge it\n\n[human] B, while you work\n\n[loop] Continue the task; the previous run stopped before it was finished.')
class Archive(unittest.TestCase):
def test_writes_afresh_a_copy_whose_outcomes_file_is_missing(self):
with tempfile.TemporaryDirectory() as root:
kept = paths.paths_from(pathlib.Path(root), {})
transcript = pathlib.Path(root, "t.jsonl")
transcript.write_text('{"timestamp": "2026-10-03T00:00:00Z"}\n')
with contextlib.redirect_stderr(io.StringIO()):
self.assertIsNone(archive.archive("proj", str(transcript), "Do it.", "Verdict: unfinished", NOW, kept))
(outcomes,) = kept.transcript_archive.glob("proj/*/*.outcomes.md")
outcomes.unlink()
self.assertIsNone(archive.archive("proj", str(transcript), "Do it.", "Stopped: Ctrl-C", NOW, kept))
self.assertEqual(outcomes.read_text(), "Task: Do it.\n\n2026-09-21T14:13:20Z Stopped: Ctrl-C\n")
class CopyFor(unittest.TestCase):
def test_skips_a_version_already_kept_beside_its_copy(self):
with tempfile.TemporaryDirectory() as temp:
copy = pathlib.Path(temp, "custom-title.json")
copy.write_bytes(b"first")
beside = archive.copy_for(copy, b"second")
self.assertEqual(beside, copy.with_name(f"custom-title.json.{hashlib.sha256(b'second').hexdigest()}"))
beside.write_bytes(b"second")
self.assertIsNone(archive.copy_for(copy, b"second"))
self.assertEqual(archive.copy_for(copy, b"first, grown"), copy)
class FirstTimestampedLine(unittest.TestCase):
def test_skips_the_lines_every_chunk_shares_and_else_takes_the_first(self):
self.assertEqual(transcript.first_timestamped_line(b'{"type": "custom-title"}\nnot JSON\n{"timestamp": "t"}\n{"timestamp": "u"}\n'), b'{"timestamp": "t"}')
self.assertEqual(transcript.first_timestamped_line(b'{"type": "custom-title"}\n[1]\n'), b'{"type": "custom-title"}')
self.assertEqual(transcript.first_timestamped_line(b""), b"")
class HumanTurns(unittest.TestCase):
def test_counts_typed_turns_and_not_tool_results(self):
self.assertEqual(transcript.human_turns([
human("typed"),
human([{"type": "text", "text": "typed as a block"}]),
human([{"type": "tool_result", "content": "not typed"}]),
human("<command-name>/model</command-name>"),
{**human("<3 merge it"), "promptSource": "typed"},
{**human("<task-notification>done</task-notification>"), "promptSource": "system"},
{**human([{"type": "text", "text": "<task-notification>done</task-notification>"}]), "promptSource": "system"},
{**human("peer message"), "isMeta": True},
{**human("the loop's own prompt"), "promptSource": "sdk"},
human([{"type": "text", "text": "[Request interrupted by user]"}]),
human([]),
queued("typed while claude worked", "human"),
queued("<task-notification>done</task-notification>", "task-notification"),
{"type": "attachment", "attachment": {"type": "queued_command", "commandMode": "task-notification", "prompt": "<task-notification>done</task-notification>"}},
assistant({"type": "text", "text": "said"}),
]), 4)
class PartLine(unittest.TestCase):
def test_renders_text_and_tool_calls_and_nothing_else(self):
self.assertEqual(transcript.part_line({"type": "text", "text": "hi"}, 20), "hi")
self.assertEqual(transcript.part_line({"type": "text", "text": " \n"}, 20), "")
self.assertEqual(transcript.part_line({"type": "tool_use", "name": "Bash", "input": {"command": "x" * 500}}, 20), '[tool Bash] {"command": "xxxxxxx')
self.assertEqual(transcript.part_line("not a part", 20), "")
self.assertEqual(transcript.part_line({"type": "tool_use", "name": "Write", "input": {"content": "Hälsa på"}}, 40), '[tool Write] {"content": "Hälsa på"}')
class Parse(unittest.TestCase):
def test_yields_only_json_objects(self):
self.assertEqual(entries.parse_entry('{"type": "user"}'), {"type": "user"})
self.assertIsNone(entries.parse_entry("not json"))
self.assertIsNone(entries.parse_entry("[1, 2]"))
class MarkTrusted(unittest.TestCase):
def test_returns_the_updated_config_and_leaves_the_one_it_was_handed(self):
config = {"other": 1, "projects": {"/a": {"hasTrustDialogAccepted": True}, "/b": {"kept": True}}}
handed = json.dumps(config)
self.assertEqual(trust.mark_trusted(config, ["/a", "/b", "/c"]), ({"other": 1, "projects": {"/a": {"hasTrustDialogAccepted": True}, "/b": {"hasTrustDialogAccepted": True, "kept": True}, "/c": {"hasTrustDialogAccepted": True}}}, ["/b", "/c"]))
self.assertEqual(json.dumps(config), handed)
self.assertEqual(trust.mark_trusted({}, ["/a"]), ({"projects": {"/a": {"hasTrustDialogAccepted": True}}}, ["/a"]))
class JudgePrompt(unittest.TestCase):
def test_shows_the_transcripts_tail_and_returns_what_it_showed(self):
prompt, shown = judge.judge_prompt("Do it.", "## Goals", "", "old " + "x" * judge.JUDGE_PROMPT_CHARS + " new")
@@ -633,7 +530,7 @@ class ExitContract(unittest.TestCase):
]
root = pathlib.Path(main.__file__).parents[1]
found = []
for path in sorted(root.rglob("*.py")):
for path in sorted(path for path in root.rglob("*.py") if not path.name.startswith("test_")):
functions = [node for node in ast.walk(ast.parse(path.read_text())) if isinstance(node, ast.FunctionDef)]
stops = [(call.lineno, function.name, ast.unparse(call.args[0]), ast.unparse(call.args[1])) for function in functions for call in ast.walk(function) if isinstance(call, ast.Call) and getattr(call.func, "id", None) == "Stop" and not (isinstance(call.args[0], ast.Constant) and call.args[0].value in (0, 2, 130))]
found += [(str(path.relative_to(root)), function, code, reason) for _, function, code, reason in sorted(stops)]
@@ -650,25 +547,21 @@ class JudgeFailures(unittest.TestCase):
started, field, unasked = "claude cannot start or exits non-zero", "its reply misses or mistypes a field", "interrupts or quotes an answer without a question"
# Every Failure the judge's run returns, in source order: path, function, start of reason, its --help clause.
clauses = [
("cycle/judge.py", "run_judge", "f'could not start claude:", started),
("cycle/judge.py", "run_judge", "proc.stderr.strip() or f'the judge exited", started),
("cycle/judge.py", "run_judge", 'f"{verdict.reason}; it replied:', field),
("cycle/judge.py", "run_judge", "f'the judge quoted {verdict.evidence!r}, which is not in the transcript", "quotes a passage the transcript does not hold"),
("cycle/judge_reply.py", "verdict_from", "'the judge returned no reply'", field),
("cycle/judge_reply.py", "verdict_from", 'f"the judge\'s reply has no {name}', field),
("cycle/judge_reply.py", "verdict_from", "'the judge interrupted without a question'", unasked),
("cycle/judge_reply.py", "verdict_from", "'the judge quoted an answer without a question'", unasked),
("verdict_from", "'the judge returned no reply'", field),
("verdict_from", 'f"the judge\'s reply has no {name}', field),
("verdict_from", "'the judge interrupted without a question'", unasked),
("verdict_from", "'the judge quoted an answer without a question'", unasked),
("run_judge", "f'could not start claude:", started),
("run_judge", "proc.stderr.strip() or f'the judge exited", started),
("run_judge", 'f"{verdict.reason}; it replied:', field),
("run_judge", "f'the judge quoted {verdict.evidence!r}, which is not in the transcript", "quotes a passage the transcript does not hold"),
]
root = pathlib.Path(main.__file__).parents[1]
found = []
for path in ("cycle/judge.py", "cycle/judge_reply.py"):
functions = [node for node in ast.walk(ast.parse((root / path).read_text())) if isinstance(node, ast.FunctionDef)]
failures = sorted((call.lineno, function.name, ast.unparse(call.args[0])) for function in functions for call in ast.walk(function) if isinstance(call, ast.Call) and getattr(call.func, "id", None) == "Failure")
found += [(path, function, reason) for _, function, reason in failures]
functions = [node for node in ast.walk(ast.parse(pathlib.Path(judge.__file__).read_text())) if isinstance(node, ast.FunctionDef)]
found = sorted((call.lineno, function.name, ast.unparse(call.args[0])) for function in functions for call in ast.walk(function) if isinstance(call, ast.Call) and getattr(call.func, "id", None) == "Failure")
self.assertEqual(len(found), len(clauses), found)
for (path, function, reason), (want_path, want_function, reason_start, _) in zip(found, clauses):
self.assertEqual((path, function), (want_path, want_function))
self.assertTrue(reason.startswith(reason_start), f"{path} {function}: {reason}")
for (_, function, reason), (want_function, reason_start, _) in zip(found, clauses):
self.assertEqual(function, want_function)
self.assertTrue(reason.startswith(reason_start), f"{function}: {reason}")
judge_clause = " ".join(main.__doc__[main.__doc__.index("a judge when"):main.__doc__.index("A usage limit")].split())
self.assertEqual([clause for *_, clause in clauses if clause not in judge_clause], [])
@@ -7,16 +7,16 @@ import tempfile
import textwrap
import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from metric_bench.bench import auc, bench, co_changed, resolved, top_k
from metric_bench.python_units import cognitive, measured, python_units, Unit
from comprehension_history import entries, Place
from failure import Failure
from test_loop_claude_black_box import host_env
from host_env import host_env
from metric_bench.main import scored_runs
TOOL = pathlib.Path(__file__).resolve().parent / "metric-bench"
TOOL = pathlib.Path(__file__).resolve().parents[1] / "metric-bench"
def scored(source: str) -> int:
-20
View File
@@ -1,20 +0,0 @@
import pathlib
import typing
from failure import Failure
from loop_claude.transcript_archive import FinishedChunk
from loop_claude.paths import paths_from
from loop_claude.project.checkout import project_key
def project_archive(checkout_root: str, home: pathlib.Path, env: typing.Mapping[str, str]) -> pathlib.Path:
paths = paths_from(home, env)
return paths.transcript_archive / project_key(checkout_root, paths.code)
def read_threads(chunk: FinishedChunk) -> list[bytes] | Failure:
"""The worker's transcript, then each subagent's."""
try:
return [path.read_bytes() for path in (chunk.transcript, *chunk.subagents)]
except OSError as failure:
return Failure(f"could not read {failure.filename}: {failure.strerror}")
+2 -1
View File
@@ -3,9 +3,10 @@ import re
import statistics
from failure import Failure
from loop_claude.transcript_archive import FinishedChunk, STAMPED
from transcript_archive.read import FinishedChunk
from reading_cost.measure import Reading
from markdown_sections import sections
from transcript_archive.outcomes import STAMPED
FIGURE = re.compile(rf"^Reading cost, chunk (\w+), finished ({STAMPED})$")
PLACE = re.compile(r"^- `(.+)` (\d+)$")
+3 -2
View File
@@ -32,9 +32,10 @@ import time
from reading_cost.measure import Checkout, measure, Reading
from failure import Failure
from reading_cost.figures import figure, merged, readings_of, RESET, trend, unheld
from loop_claude.transcript_archive import finished_chunks, utc
from reading_cost.archive import project_archive, read_threads
from transcript_archive.read import finished_chunks, read_threads
from transcript_archive.location import project_archive
from file_writes import replace_file
from transcript_archive.outcomes import utc
@dataclasses.dataclass(frozen=True)
class Updated:
+1 -1
View File
@@ -2,7 +2,7 @@ import collections
import dataclasses
import re
from loop_claude.claude_code.entries import assistant_parts, parse_entry, tool_call
from claude_code.entries import assistant_parts, parse_entry, tool_call
from reading_cost.shell_reads import Reads, resolved, shell_reads
COMMIT = re.compile(r"(^|[\s;&|(])git\s+(-C\s+\S+\s+)?commit\b")
@@ -10,17 +10,19 @@ import sys
import tempfile
import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from loop_claude.transcript_archive import archive, FINISHED, FINISHED_AT, finished_chunks, FinishedChunk, UNFINISHED, utc
from transcript_archive.write import archive
from reading_cost.measure import Checkout, Reading
from failure import Failure
from reading_cost import figures, measure
from test_loop_claude_black_box import host_env
from loop_claude.paths import paths_from
from transcript_archive.read import finished_chunks, FinishedChunk
from host_env import host_env
from transcript_archive import outcomes
from transcript_archive.location import project_archive
from reading_cost.shell_reads import Reads, shell_reads
TOOL = pathlib.Path(__file__).resolve().parent / "reading-cost"
TOOL = pathlib.Path(__file__).resolve().parents[1] / "reading-cost"
def said(timestamp, message_id, command=None, tokens=0, cwd="/c/p", **call):
@@ -94,9 +96,6 @@ class Figures(unittest.TestCase):
history = "\n".join([written("a", "2026-10-01T00:00:00Z", 1), written("c", "2026-10-03T00:00:00Z", 3), "## Reading cost reset, 2026-10-02T00:00:00Z\n", written("b", "2026-10-04T00:00:00Z", 2)])
self.assertEqual(figures.readings_of(history), [Reading(3, collections.Counter()), Reading(2, collections.Counter())])
def test_the_archive_stamps_what_it_reads_back(self):
self.assertRegex(f"{utc(1790000000)} {FINISHED}", FINISHED_AT)
class ReadingCostTool(unittest.TestCase):
def setUp(self):
@@ -110,19 +109,19 @@ class ReadingCostTool(unittest.TestCase):
self.git("init", "-q")
self.git("add", "a.py")
self.git("-c", "user.name=t", "-c", "user.email=t@t", "commit", "-q", "-m", "x")
self.paths = paths_from(self.home, {})
self.archive = project_archive(str(self.checkout), self.home, {})
def git(self, *args):
subprocess.run(["git", *args], cwd=self.checkout, check=True, env=self.env)
def archive_chunk(self, at, outcome=FINISHED):
def archive_chunk(self, at, outcome=outcomes.finished):
transcript = self.home / ".claude" / "projects" / "-proj" / f"{folder_name()}.jsonl"
(transcript.with_suffix("") / "subagents").mkdir(parents=True)
worker = [said("1", "m1", tokens=10, cwd=str(self.checkout), name="Read", input={"file_path": str(self.checkout / "a.py")}), said("2", "m2", command="git commit -m x")]
transcript.write_bytes(jsonl([{"timestamp": str(at)}, *worker]))
(transcript.with_suffix("") / "subagents" / "agent-a.jsonl").write_bytes(jsonl([said("1", "s1", tokens=1)]))
with contextlib.redirect_stderr(io.StringIO()):
self.assertIsNone(archive("proj", str(transcript), "Do it.", f"{outcome}\n\nEvidence:\n> merged", at, self.paths))
self.assertIsNone(archive(self.archive, str(transcript), "Do it.", outcome("merged"), at))
def run_tool(self, cwd, *args):
return subprocess.run([sys.executable, str(TOOL), *args], capture_output=True, cwd=cwd, env=self.env, text=True)
@@ -130,8 +129,8 @@ class ReadingCostTool(unittest.TestCase):
def test_appends_each_finished_chunk_once_in_the_order_they_finished_from_a_worktree(self):
self.archive_chunk(1790000200)
self.archive_chunk(1790000100)
self.archive_chunk(1790000000, UNFINISHED)
chunks = finished_chunks(self.paths.transcript_archive / "proj")
self.archive_chunk(1790000000, outcomes.unfinished)
chunks = finished_chunks(self.archive)
self.assertEqual([chunk.finished for chunk in chunks], ["2026-09-21T14:15:00Z", "2026-09-21T14:16:40Z"])
worktree = self.home / "code" / "proj-wt"
self.git("worktree", "add", "-q", str(worktree))
View File
@@ -3,7 +3,7 @@ import re
import subprocess
import unittest
ROOT = pathlib.Path(__file__).resolve().parents[1]
ROOT = pathlib.Path(__file__).resolve().parents[2]
CITATION = re.compile(r'`?CLAUDE\.md`? → ("[^"]+"(?:,? (?:and )?"[^"]+")*)')
HEADING = re.compile(r"^#+ (.+?)(?: \(.*\))?$", re.MULTILINE)
LEAD = re.compile(r"^(?:- )?\*\*(.+?)(?:\*\*|[:.](?=\*\*| )| —)", re.MULTILINE)
@@ -1,7 +1,7 @@
import subprocess
import unittest
from test_python_floor import ROOT
from repo_checks.test_python_floor import ROOT
PRIVATE = [
".claude/settings.local.json",
@@ -2,7 +2,7 @@ import ast
import subprocess
import unittest
from test_python_floor import ROOT
from repo_checks.test_python_floor import ROOT
def bound(node: ast.Import | ast.ImportFrom) -> list[str]:
@@ -1,7 +1,7 @@
import json
import unittest
from test_python_floor import ROOT
from repo_checks.test_python_floor import ROOT
class Install(unittest.TestCase):
@@ -5,7 +5,7 @@ import subprocess
import sys
import unittest
ROOT = pathlib.Path(__file__).resolve().parents[1]
ROOT = pathlib.Path(__file__).resolve().parents[2]
FLOOR = re.compile(r"Python 3\.(\d+) or newer")
@@ -2,7 +2,7 @@ import shutil
import subprocess
import unittest
from test_python_floor import readme_floor, ROOT
from repo_checks.test_python_floor import readme_floor, ROOT
class Types(unittest.TestCase):
@@ -11,5 +11,5 @@ class Types(unittest.TestCase):
self.assertIsNotNone(floor, "README.md's Install names `Python 3.N or newer`")
if shutil.which("uv") is None:
self.fail("uv on PATH fetches mypy; see README.md's Test line")
ran = subprocess.run(["uv", "tool", "run", "--python", "%d.%d" % floor, "mypy==2.3.1", "--cache-dir=/dev/null", "--check-untyped-defs", "--disallow-untyped-defs", "-m", "comprehension_history", "-p", "larv_review", "-p", "loop_claude", "-p", "metric_bench", "-m", "rank_todo", "-p", "reading_cost", "-m", "statusline"], capture_output=True, cwd=ROOT / "bin", text=True)
ran = subprocess.run(["uv", "tool", "run", "--python", "%d.%d" % floor, "mypy==2.3.1", "--cache-dir=/dev/null", "--check-untyped-defs", "--disallow-untyped-defs", "--exclude", "/test_", "-p", "claude_code", "-m", "comprehension_history", "-m", "host_env", "-p", "larv_review", "-p", "loop_claude", "-p", "metric_bench", "-m", "rank_todo", "-p", "reading_cost", "-m", "statusline", "-p", "transcript_archive"], capture_output=True, cwd=ROOT / "bin", text=True)
self.assertEqual(ran.returncode, 0, ran.stdout + ran.stderr)
+2 -1
View File
@@ -9,7 +9,8 @@ sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
from failure import Failure
import rank_todo
from test_python_floor import ROOT
ROOT = pathlib.Path(__file__).resolve().parents[1]
README = "# P\n\n## Goals\n\n1. Fast.\n2. Correct.\n 1. Tested.\n\n## Audience\n\nMe.\n"
View File
+12
View File
@@ -0,0 +1,12 @@
import pathlib
import typing
def project_archive(checkout_root: str, home: pathlib.Path, env: typing.Mapping[str, str]) -> pathlib.Path:
archive = pathlib.Path(env["LOOP_CLAUDE_TRANSCRIPTS"]).expanduser() if env.get("LOOP_CLAUDE_TRANSCRIPTS") else home / ".claude" / "loop-claude-transcripts"
return archive / project_key(checkout_root, home)
def project_key(checkout_root: str, home: pathlib.Path) -> str:
"""The checkout's path relative to ~/code, or to / outside it."""
return checkout_root.removeprefix(f"{home / 'code'}/").lstrip("/")
+36
View File
@@ -0,0 +1,36 @@
import re
import time
FINISHED = "Verdict: finished"
STAMP = "%Y-%m-%dT%H:%M:%SZ"
STAMPED = r"\d{4}-\d\d-\d\dT\d\d:\d\d:\d\dZ"
FINISHED_AT = re.compile(rf"^({STAMPED}) {re.escape(FINISHED)}$", re.MULTILINE)
def finished(evidence: str) -> str:
return f"{FINISHED}\n\nEvidence:\n{quoted(evidence)}"
def unfinished(evidence: str) -> str:
return f"Verdict: unfinished\n\nEvidence:\n{quoted(evidence)}"
def interrupted(question: str, evidence: str) -> str:
return f"Verdict: interrupt\n\n{question}\n\nEvidence:\n{quoted(evidence)}"
def answered(question: str, sources: str, answer: str, evidence: str) -> str:
return f"Verdict: quoted answer\n\n{question}\n\n{sources} says:\n{quoted(answer)}\n\nEvidence:\n{quoted(evidence)}"
def stopped(why: str) -> str:
return f"Stopped: {why}"
# Blockquoted, so evidence holding blank lines still ends visibly where the text after it starts.
def quoted(passage: str) -> str:
return "\n".join(f"> {line}" for line in passage.splitlines())
def utc(at: float) -> str:
return time.strftime(STAMP, time.gmtime(at))
+35
View File
@@ -0,0 +1,35 @@
import dataclasses
import pathlib
from failure import Failure
from transcript_archive.outcomes import FINISHED_AT
@dataclasses.dataclass(frozen=True)
class FinishedChunk:
folder: str
finished: str
transcript: pathlib.Path
subagents: list[pathlib.Path]
# One per chunk folder, its latest finished copy, in the order they finished.
def finished_chunks(project_archive: pathlib.Path) -> list[FinishedChunk] | Failure:
found = []
try:
for folder in sorted(path for path in project_archive.glob("*") if path.is_dir()):
copies = sorted((stamps[-1], outcomes) for outcomes in folder.glob("*.outcomes.md") if (stamps := FINISHED_AT.findall(outcomes.read_text(encoding="utf-8"))))
if copies:
finished, outcomes = copies[-1]
found.append(FinishedChunk(folder.name, finished, outcomes.with_name(outcomes.name.removesuffix(".outcomes.md") + ".jsonl"), sorted(folder.glob("session/*/subagents/*.jsonl"))))
except (OSError, UnicodeDecodeError) as failure:
return Failure(f"could not read the archive {project_archive}: {failure}")
return sorted(found, key=lambda chunk: (chunk.finished, chunk.folder))
def read_threads(chunk: FinishedChunk) -> list[bytes] | Failure:
"""The worker's transcript, then each subagent's."""
try:
return [path.read_bytes() for path in (chunk.transcript, *chunk.subagents)]
except OSError as failure:
return Failure(f"could not read {failure.filename}: {failure.strerror}")
@@ -0,0 +1,62 @@
import contextlib
import hashlib
import io
import pathlib
import sys
import tempfile
import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from transcript_archive import outcomes, write
from transcript_archive.location import project_archive, project_key
NOW = 1790000000
class Archive(unittest.TestCase):
def test_writes_afresh_a_copy_whose_outcomes_file_is_missing(self):
with tempfile.TemporaryDirectory() as root:
kept = pathlib.Path(root, "archive")
transcript = pathlib.Path(root, "t.jsonl")
transcript.write_text('{"timestamp": "2026-10-03T00:00:00Z"}\n')
with contextlib.redirect_stderr(io.StringIO()):
self.assertIsNone(write.archive(kept, str(transcript), "Do it.", outcomes.unfinished("working"), NOW))
(kept_outcomes,) = kept.glob("*/*.outcomes.md")
kept_outcomes.unlink()
self.assertIsNone(write.archive(kept, str(transcript), "Do it.", outcomes.stopped("Ctrl-C"), NOW))
self.assertEqual(kept_outcomes.read_text(), "Task: Do it.\n\n2026-09-21T14:13:20Z Stopped: Ctrl-C\n")
class CopyFor(unittest.TestCase):
def test_skips_a_version_already_kept_beside_its_copy(self):
with tempfile.TemporaryDirectory() as temp:
copy = pathlib.Path(temp, "custom-title.json")
copy.write_bytes(b"first")
beside = write.copy_for(copy, b"second")
self.assertEqual(beside, copy.with_name(f"custom-title.json.{hashlib.sha256(b'second').hexdigest()}"))
beside.write_bytes(b"second")
self.assertIsNone(write.copy_for(copy, b"second"))
self.assertEqual(write.copy_for(copy, b"first, grown"), copy)
class Outcomes(unittest.TestCase):
def test_the_archive_stamps_what_it_reads_back(self):
self.assertRegex(f"{outcomes.utc(NOW)} {outcomes.finished('merged')}", outcomes.FINISHED_AT)
def test_quotes_every_line_of_a_passage_blank_ones_included(self):
self.assertEqual(outcomes.quoted("merged\n\nPR #1"), "> merged\n> \n> PR #1")
class Location(unittest.TestCase):
def test_keys_a_project_by_its_path_under_code_or_else_under_the_root(self):
home = pathlib.Path("/h")
self.assertEqual(project_key("/h/code/log", home), "log")
self.assertEqual(project_key("/h/code", home), "h/code")
self.assertEqual(project_key("/srv/log", home), "srv/log")
self.assertEqual(project_archive("/h/code/log", home, {}), pathlib.Path("/h/.claude/loop-claude-transcripts/log"))
self.assertEqual(project_archive("/h/code/log", home, {"LOOP_CLAUDE_TRANSCRIPTS": "/a"}), pathlib.Path("/a/log"))
if __name__ == "__main__":
unittest.main()
@@ -1,38 +1,22 @@
import dataclasses
import hashlib
import os
import pathlib
import re
import sys
import time
from failure import Failure
from loop_claude.claude_code.transcript import first_timestamped_line
from claude_code.transcript import first_timestamped_line
from file_writes import make_private, replace_file
from loop_claude.paths import Paths
from loop_claude.claude_code.session import session_files
FINISHED = "Verdict: finished"
UNFINISHED = "Verdict: unfinished"
STAMP = "%Y-%m-%dT%H:%M:%SZ"
STAMPED = r"\d{4}-\d\d-\d\dT\d\d:\d\d:\d\dZ"
FINISHED_AT = re.compile(rf"^({STAMPED}) {re.escape(FINISHED)}$", re.MULTILINE)
from claude_code.session import session_files
from transcript_archive.outcomes import utc
@dataclasses.dataclass(frozen=True)
class FinishedChunk:
folder: str
finished: str
transcript: pathlib.Path
subagents: list[pathlib.Path]
def archive(project_key: str, path: str, task: str, outcome: str, at: float, paths: Paths) -> Failure | None:
# <project archive>/<chunk>/<sha256 of the transcript>.jsonl, its .outcomes.md beside it, and the session's other files under <chunk>/session/
def archive(project_archive: pathlib.Path, path: str, task: str, outcome: str, at: float) -> Failure | None:
try:
with open(path, "rb") as handle:
raw = handle.read()
# Each chunk's first timestamped line is its own: a finished chunk's session is deleted, so the next chunk's transcript starts afresh.
folder = paths.transcript_archive / project_key / hashlib.sha256(first_timestamped_line(raw)).hexdigest()
folder = project_archive / hashlib.sha256(first_timestamped_line(raw)).hexdigest()
make_private(folder)
except OSError as failure:
return unarchived(failure.filename, failure.strerror)
@@ -101,21 +85,3 @@ def copy_for(copy: pathlib.Path, data: bytes) -> pathlib.Path | None:
return copy if data != kept else None
beside = copy.with_name(f"{copy.name}.{hashlib.sha256(data).hexdigest()}")
return None if beside.exists() else beside
def utc(at: float) -> str:
return time.strftime(STAMP, time.gmtime(at))
# One per chunk folder, its latest finished copy, in the order they finished.
def finished_chunks(project_archive: pathlib.Path) -> list[FinishedChunk] | Failure:
found = []
try:
for folder in sorted(path for path in project_archive.glob("*") if path.is_dir()):
copies = sorted((stamps[-1], outcomes) for outcomes in folder.glob("*.outcomes.md") if (stamps := FINISHED_AT.findall(outcomes.read_text(encoding="utf-8"))))
if copies:
finished, outcomes = copies[-1]
found.append(FinishedChunk(folder.name, finished, outcomes.with_name(outcomes.name.removesuffix(".outcomes.md") + ".jsonl"), sorted(folder.glob("session/*/subagents/*.jsonl"))))
except (OSError, UnicodeDecodeError) as failure:
return Failure(f"could not read the archive {project_archive}: {failure}")
return sorted(found, key=lambda chunk: (chunk.finished, chunk.folder))