#!/usr/bin/env python3
"""Run a task as headless claude cycles; a judge interrupts only when a decision is the human's.

usage: loop-claude <task>

Run it anywhere inside a project checkout whose README.md has ## Goals and ## Audience, the
premises; the task runs at the checkout root. Each cycle a worker runs the task; a judge then reads
the transcript against them. A question only the human can answer, or a release ready to cut, is an
interrupt: `claude --resume` on the terminal, every worktree first marked trusted in ~/.claude.json.
An unfinished chunk resumes the same session next cycle; a finished one starts a fresh session.
Cycles continue until that interrupt or Ctrl-C. Words: ~/.claude/CLAUDE.md → "Vocabulary".

Exit 1: no task, not inside a checkout, no premises, claude leaves no transcript, a reload with
unreadable state, or the worker or the judge fails three times running. A worker fails when claude
exits non-zero, is killed, or ends without a result event; a judge when its verdict misses a field
or quotes nothing in the transcript.
Exit 2: the human is needed and stdin or stdout is not a terminal, or the interrupt ended without
them typing anything. Rerunning resumes any open session.

Each project has one session, "A <path> loop-claude", <path> being the checkout relative to ~/code,
or to / outside it, deleted when the chunk finishes. Its transcript is archived under
$LOOP_CLAUDE_TRANSCRIPTS/<path>/ (default ~/.claude/loop-claude-transcripts) whenever the human is
asked and when the chunk finishes. LOOP_CLAUDE_JUDGE_MODEL and LOOP_CLAUDE_WORKER_MODEL override the
model the project's Claude Code settings pick. A change to this file takes effect at the next cycle
boundary, once the new file answers --help.

Claude Code internals this rests on, observed on 2.1.282:
- The transcript is ~/.claude/projects/*/<session-id>.jsonl, one JSON object per line. A <session-id>/
  folder and <session-id>.superseded-*/ and .orphaned-*.jsonl siblings belong to the same session.
- Claude Code writes "user" entries of its own into the transcript, and a `claude -p` prompt lands as one
  with promptSource "sdk"; typed() tells a human's from them.
- An "assistant" entry, in the transcript and in --output-format stream-json, carries message.content
  parts of type "text" (text) and "tool_use" (name, input); stream-json ends with a "result" event.
- `claude -p --output-format json --json-schema` returns the verdict under "structured_output".
- `claude -p` without --bare loads the project's and ~/.claude's CLAUDE.md, so the judge reads the words.
- ~/.claude.json holds projects.<path>.hasTrustDialogAccepted per checkout.
"""
import glob
import json
import os
import shutil
import subprocess
import sys
import time
import uuid

ARCHIVE = os.path.expanduser(os.environ.get("LOOP_CLAUDE_TRANSCRIPTS", "~/.claude/loop-claude-transcripts"))
RELOAD_BASELINE = open(__file__, encoding="utf-8").read()
RELOAD_FLAG = "--reloaded"
SESSION_NAMESPACE = uuid.UUID("64fb586b-d926-4bb3-a44c-c903e86d3eec")

JUDGE_RULES = (
	"Decide whether the human must now be interrupted. ask=true when any of these appear:\n"
	"- the agent asks the human anything, seeks approval, or says a decision is the human's\n"
	"- it carried on under an assumption that decides the deliverable and that the human could "
	"reasonably reject; 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 release "
	"ready to cut, a choice outside the repo\n"
	"- it flags that the goals, the plan or the task itself is unclear, missing or in need of change\n"
	"- it chose between alternatives the README text does not discriminate between - it does not "
	"rule the rejected one out - and the choice materially changes the deliverable\n"
	"ask=false otherwise. A sensible preference is not a derivation. 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.\n"
	"The question must be one the agent itself raised. Never construct a question from facts the agent "
	"stated. When ask=true, quote the agent's own wording where it already framed the question.\n"
	"finished=true when the chunk is complete: merged, or nothing remains that the agent could do on "
	"its own. finished=false when work remains that a further run can continue: an open PR, a review "
	"not yet run, CI not yet reported."
)

JUDGE_SCHEMA = {
	"properties": {
		"ask": {"type": "boolean"},
		"evidence": {"description": "A verbatim quote from the transcript of the line that raises the question. Empty when ask is false.", "type": "string"},
		"finished": {"type": "boolean"},
		"question": {"description": "The single question to put to the human. Empty when ask is false.", "type": "string"},
	},
	"required": ["ask", "evidence", "finished", "question"],
	"type": "object",
}


def main():
	argv = sys.argv[1:]
	if argv[:1] == [RELOAD_FLAG]:
		state = reloaded_state(argv[1:])
	else:
		state = {"cycle_number": 0, "failures": 0, "root": "", "task": " ".join(argv)}
		if state["task"] in ("", "-h", "--help"):
			print(__doc__.strip())
			sys.exit(0 if state["task"] else 1)
	task = state["task"]
	root = state["root"] or checkout_root()
	cycle_number, failures = state["cycle_number"], state["failures"]
	while True:
		reload_if_edited(root, task, cycle_number, failures)
		cycle_number += 1
		premises = read_premises(root)
		name = session_name(root)
		print(f"\n=== cycle {cycle_number} ===", flush=True)
		failure = run_cycle(root, task, premises, name, uuid.uuid5(SESSION_NAMESPACE, name))
		if not failure:
			failures = 0
			continue
		failures += 1
		if failures == 3:
			sys.exit(f"the worker failed three times running: {failure}")
		print(f"retrying the worker in a minute: {failure}", file=sys.stderr)
		time.sleep(60)


def run_cycle(root, task, premises, name, session_id):
	if failure := run_worker(root, worker_args(task, name, session_id, resuming=session_open(session_id))):
		return failure
	path = session_file(session_id)
	if not path:
		sys.exit(f"claude left no transcript for session {session_id}")
	verdict = judge(root, task, premises, render(entries(path)))
	while verdict["ask"]:
		archive(root, path, f"Task: {task}\n\nVerdict: needs input\n\n{verdict['question']}")
		if failure := interrupt(root, session_id, path, verdict["question"]):
			print(failure, file=sys.stderr)
			sys.exit(2)
		verdict = judge(root, task, premises, render(entries(path)))
	if verdict["finished"]:
		archive(root, path, f"Task: {task}\n\nVerdict: finished")
		delete_transcript_files(path)
	return ""


def reload_if_edited(root, task, cycle_number, failures):
	try:
		source = open(__file__, encoding="utf-8").read()
	except OSError as failure:
		print(f"keeping the running script: {failure}", file=sys.stderr)
		return
	if source == RELOAD_BASELINE:
		return
	trial = subprocess.run([sys.executable, __file__, "--help"], capture_output=True, text=True)
	if trial.returncode != 0:
		print(f"keeping the running script: {trial.stderr.strip() or f'exit {trial.returncode}'}", file=sys.stderr)
		return
	state = {"cycle_number": cycle_number, "failures": failures, "root": root, "task": task}
	os.execv(sys.executable, [sys.executable, __file__, RELOAD_FLAG, json.dumps(state)])


def reloaded_state(handed):
	state = parse(handed[0]) if len(handed) == 1 else None
	if not state or {"cycle_number", "failures", "root"} - state.keys() or not isinstance(state.get("task"), str) or not state["task"]:
		sys.exit(f"the reload cannot read the loop's state from {handed}; rerun loop-claude <task>")
	return state


def checkout_root():
	found = subprocess.run(["git", "rev-parse", "--show-toplevel"], capture_output=True, text=True)
	if found.returncode != 0:
		sys.exit(found.stderr.strip())
	return found.stdout.strip()


def read_premises(root):
	try:
		found = sections(open(os.path.join(root, "README.md"), encoding="utf-8").read())
	except OSError as failure:
		sys.exit(f"README.md in {root}: {failure.strerror} - no premises.")
	except UnicodeDecodeError as failure:
		line = failure.object.count(b"\n", 0, failure.start) + 1
		sys.exit(f"README.md is not UTF-8 on line {line} - no premises.")
	for name in ("Goals", "Audience"):
		bodies = found.get(name, [])
		if not bodies:
			sys.exit(f"README.md has no ## {name} heading - no premises.")
		if len(bodies) > 1:
			sys.exit(f"README.md has ## {name} more than once - no premises.")
		if not bodies[0]:
			sys.exit(f"README.md has nothing under ## {name} - no premises.")
	return f"## Goals\n{found['Goals'][0]}\n\n## Audience\n{found['Audience'][0]}"


def sections(text):
	found, current, fenced = {}, None, False
	for line in text.splitlines():
		fenced ^= line.startswith("```")
		if not fenced and line.startswith("## "):
			current = []
			found.setdefault(line.strip()[3:], []).append(current)
		elif not fenced and line.startswith("# "):
			current = None
		elif current is not None and line.strip():
			current.append(line)
	return {name: ["\n".join(body) for body in bodies] for name, bodies in found.items()}


def session_name(root):
	# "A " is the human's cue in the session picker that the session is the loop's.
	return f"A {project(root)} loop-claude"


def archive(root, path, note):
	folder = os.path.join(ARCHIVE, project(root))
	try:
		stamp = time.strftime("%Y-%m-%dT%H-%M-%SZ", time.gmtime(os.path.getmtime(path)))
		make_private(folder)
		dest = os.path.join(folder, f"{stamp}.md")
		if not os.path.exists(dest):
			with open(os.open(dest, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600), "w", encoding="utf-8") as copy:
				copy.write(f"# {stamp} {project(root)}\n\n{note}\n\n{render(entries(path))}\n")
		print(f"transcript: {dest}", file=sys.stderr)
	except OSError as failure:
		print(f"could not archive the transcript: {failure}", file=sys.stderr)


def make_private(folder):
	mask = os.umask(0o077)
	try:
		os.makedirs(folder, exist_ok=True)
	finally:
		os.umask(mask)


def model(variable):
	return ["--model", os.environ[variable]] if os.environ.get(variable) else []


def project(root):
	return root.removeprefix(os.path.expanduser("~/code/")).lstrip("/")


# The transcript file


def session_open(session_id):
	return bool(session_file(session_id))


def session_file(session_id):
	hit = glob.glob(os.path.expanduser(f"~/.claude/projects/*/{session_id}.jsonl"))
	return hit[0] if hit else ""


def delete_transcript_files(path):
	for sibling in glob.glob(glob.escape(path.removesuffix(".jsonl")) + "*"):
		try:
			shutil.rmtree(sibling) if os.path.isdir(sibling) else os.remove(sibling)
		except OSError as failure:
			print(f"could not remove {sibling}: {failure}", file=sys.stderr)


def entries(path):
	for raw in open(path, encoding="utf-8"):
		if entry := parse(raw):
			yield entry


def parse(raw):
	try:
		entry = json.loads(raw)
	except ValueError:
		return None
	return entry if isinstance(entry, dict) else None


# "user" entries


def human_turns(entries):
	return sum(1 for entry in entries if typed(entry))


def typed(entry):
	"""A human turn: a "user" entry, not isMeta, not promptSource "sdk" (the loop's own prompts), whose message.content is a string not starting with "<" (<command-name> and its kind) or one or more text parts, none starting with "[Request interrupted"."""
	if entry.get("type") != "user" or entry.get("isMeta") or entry.get("promptSource") == "sdk":
		return False
	content = entry.get("message", {}).get("content")
	if isinstance(content, str):
		return not content.startswith("<")
	parts = content if isinstance(content, list) else []
	return bool(parts) and all(isinstance(part, dict) and part.get("type") == "text" and not part.get("text", "").startswith("[Request interrupted") for part in parts)


# "assistant" entries and stream-json


def run_worker(root, args):
	proc = subprocess.Popen(["claude", *args], cwd=root, stdin=subprocess.DEVNULL, stdout=subprocess.PIPE, text=True)
	done = False
	for raw in proc.stdout:
		event = parse(raw) or {}
		if event.get("type") == "result":
			done = True
		elif event.get("type") == "assistant":
			for part in event.get("message", {}).get("content", []):
				if line := said(part, 160):
					print(line, flush=True)
	code = proc.wait()
	if code < 0:
		return f"claude killed by signal {-code}"
	if code:
		return f"claude exited {code}"
	return "" if done else "claude exited 0 without a result event"


def worker_args(task, name, session_id, resuming):
	if resuming:
		start = ["-p", "Continue the task; the previous run stopped before it was finished.", "--resume", str(session_id)]
	else:
		start = ["-p", f"{task}\n\nContinue any open draft PR or worktree for the item before creating a new one.", "--name", name, "--session-id", str(session_id)]
	return [
		*start,
		"--output-format", "stream-json",
		"--permission-mode", "bypassPermissions",
		"--verbose",
		*model("LOOP_CLAUDE_WORKER_MODEL"),
	]


def render(entries):
	lines = []
	for entry in entries:
		if entry.get("type") == "assistant":
			lines += [line for part in entry.get("message", {}).get("content", []) if (line := said(part))]
		elif typed(entry):
			content = entry["message"]["content"]
			lines.append("[human] " + (content if isinstance(content, str) else "".join(part.get("text", "") for part in content)))
	return "\n\n".join(lines)


def said(part, limit=400):
	kind = part.get("type") if isinstance(part, dict) else None
	if kind == "text" and part.get("text", "").strip():
		return part["text"]
	if kind == "tool_use":
		return f"[tool {part.get('name')}] {json.dumps(part.get('input'))[:limit]}"
	return ""


# --json-schema verdicts


def judge(root, task, premises, transcript):
	args = [
		"-p",
		"--json-schema", json.dumps(JUDGE_SCHEMA),
		*model("LOOP_CLAUDE_JUDGE_MODEL"),
		"--no-session-persistence",
		"--output-format", "json",
		"--permission-mode", "bypassPermissions",
		"--tools", "",
	]
	prompt = judge_prompt(task, premises, transcript)
	for attempt in range(3):
		proc = subprocess.run(["claude", *args], capture_output=True, cwd=root, input=prompt, text=True)
		verdict = (parse(proc.stdout) or {}).get("structured_output") if proc.returncode == 0 else None
		if not complete(verdict):
			failure = proc.stderr.strip() or "the judge returned no verdict"
		elif not grounded(verdict, transcript):
			failure = f"the judge quoted {verdict['evidence']!r}, nothing in the transcript, asking: {verdict['question']}"
		else:
			return verdict
		if attempt == 2:
			sys.exit(f"the judge failed three times running: {failure}")
		print(f"retrying the judge in a minute: {failure}", file=sys.stderr)
		time.sleep(60)


def judge_prompt(task, premises, transcript):
	return (
		f"From README.md:\n{premises}\n\n"
		f"The task an agent was given:\n{task}\n\n"
		# The tail, where an ask or a finish lands; the session's transcript grows cycle over cycle.
		f"What the agent did and said, and what the human typed on [human] lines, latest last:\n{transcript[-40000:]}\n\n"
		f"{JUDGE_RULES}"
	)


def complete(verdict):
	return isinstance(verdict, dict) and set(JUDGE_SCHEMA["required"]) <= verdict.keys()


def grounded(verdict, transcript):
	if not verdict["ask"]:
		return True
	evidence = verdict["evidence"]
	return evidence.strip() != "" and evidence in transcript


# ~/.claude.json


def interrupt(root, session_id, path, question):
	print(f"\n{question}", file=sys.stderr)
	if not (sys.stdin.isatty() and sys.stdout.isatty()):
		return "stdin or stdout is not a terminal"
	trust(checkouts(root))
	before = human_turns(entries(path))
	subprocess.run(["claude", "--permission-mode", "bypassPermissions", "--resume", str(session_id)], cwd=root)
	return "" if human_turns(entries(path)) > before else "the interrupt ended without the human typing anything"


def checkouts(root):
	found = [root]
	listing = subprocess.run(["git", "worktree", "list", "--porcelain"], capture_output=True, cwd=root, text=True)
	if listing.returncode == 0:
		found += [line.split(" ", 1)[1] for line in listing.stdout.splitlines() if line.startswith("worktree ")]
	return sorted(set(found))


def trust(paths):
	config = os.path.expanduser("~/.claude.json")
	try:
		with open(config, encoding="utf-8") as handle:
			data = json.load(handle)
	except (OSError, ValueError) as failure:
		print(f"could not read {config}: {getattr(failure, 'strerror', failure)}", file=sys.stderr)
		return
	projects = data.setdefault("projects", {})
	granted = [path for path in paths if not projects.get(path, {}).get("hasTrustDialogAccepted")]
	if not granted:
		return
	for path in granted:
		projects.setdefault(path, {})["hasTrustDialogAccepted"] = True
	staged = f"{config}.loop-claude"
	try:
		with open(staged, "w", encoding="utf-8") as handle:
			json.dump(data, handle, indent=2)
		os.replace(staged, config)
	except OSError as failure:
		print(f"could not write {config}: {failure.strerror}", file=sys.stderr)
		return
	print("trusted for the interrupt: " + ", ".join(granted), file=sys.stderr)


if __name__ == "__main__":
	try:
		main()
	except KeyboardInterrupt:
		sys.exit(130)
