claudeloop 0.2.0__py3-none-any.whl

claudeloop/__init__.py

@@ -0,0 +1,4 @@
+"""claudeloop — onion-architected, autonomous Claude Code session runner and
+full Anthropic SDK CLI."""
+
+__version__ = "0.2.0"

claudeloop/application/dto.py

@@ -0,0 +1,40 @@
+"""Data transfer objects passed between application/ and infrastructure/ adapters.
+Not domain value objects — these carry the raw shape of one SDK interaction
+before domain.classify.classify() and domain.completion.evaluate() reduce them
+to CapacityState / CompletionVerdict."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+
+from claudeloop.domain.classify import TurnSignals
+from claudeloop.domain.completion import StructuredVerdict
+
+
+@dataclass(frozen=True, slots=True)
+class TurnOutcome:
+    """What one real or probe turn produced, translated from raw SDK messages
+    by infrastructure/agent/translate.py."""
+
+    signals: TurnSignals
+    verdict: StructuredVerdict | None
+    output_text: str
+    session_id: str | None
+    cost_usd: float = 0.0
+    raw_events: tuple[dict[str, object], ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class ProbeResult:
+    signals: TurnSignals
+    at: datetime
+
+
+@dataclass(frozen=True, slots=True)
+class RunResult:
+    success: bool
+    reason: str
+    session_id: str | None
+    turns_spent: int
+    dollars_spent: float

claudeloop/application/ports.py

@@ -0,0 +1,69 @@
+"""Application ports — Protocols implemented by infrastructure/, never imported
+from it. See docs/architecture/overview.md for the onion rule this enforces:
+application/ knows the SHAPE of a collaborator, never its concrete type."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Protocol
+
+from claudeloop.application.dto import TurnOutcome
+from claudeloop.domain.session import SessionRef
+
+
+class Clock(Protocol):
+    def now(self) -> datetime: ...
+
+
+class Sleeper(Protocol):
+    async def sleep_until(self, instant: datetime) -> None: ...
+
+
+class AgentGateway(Protocol):
+    """Wraps a live claude_agent_sdk.ClaudeSDKClient session. Deliberately NOT
+    query() — see docs/architecture/decisions/0002-agent-sdk-over-subprocess.md
+    for why query() cannot be used here (it raises after an error result and
+    exits the process, where ClaudeSDKClient survives to be resumed)."""
+
+    async def send_turn(self, prompt_text: str) -> TurnOutcome: ...
+    async def close(self) -> None: ...
+
+
+class CapacityProbe(Protocol):
+    async def probe(self) -> TurnOutcome: ...
+
+
+class SessionCatalog(Protocol):
+    def most_recent(self, cwd: str) -> SessionRef | None: ...
+    def list_all(self, cwd: str | None = None) -> list[SessionRef]: ...
+
+
+class ProgressReporter(Protocol):
+    def turn_sent(self, *, attempt: int) -> None: ...
+    def waiting(self, *, reason: str, until: datetime) -> None: ...
+    def finished(self, *, success: bool, reason: str) -> None: ...
+
+
+class AuditLog(Protocol):
+    def record(self, event_type: str, payload: dict[str, Any]) -> None: ...
+
+
+class Notifier(Protocol):
+    def notify(self, message: str) -> None: ...
+
+
+class RunStateStore(Protocol):
+    def save(self, run_id: str, state: dict[str, Any]) -> None: ...
+    def load(self, run_id: str) -> dict[str, Any] | None: ...
+
+
+class SessionLock(Protocol):
+    def acquire(self, session_id: str) -> bool: ...
+    def release(self, session_id: str) -> None: ...
+
+
+class ApiGateway(Protocol):
+    """Declared now; implemented in M4 alongside the generated REST surface.
+    See docs/architecture/decisions/0006-generated-rest-surface-not-hand-written.md."""
+
+    def invoke(self, method_path: str, **kwargs: Any) -> Any: ...

claudeloop/application/runner.py

@@ -0,0 +1,140 @@
+"""AutonomousRunner — executes domain.loop's pure Decisions against real ports.
+
+Contains NO capacity or completion logic of its own. Every "is this waitable",
+"how long do we wait", "is the task done" question is answered by domain/ before
+this class ever sees it; this class only performs the I/O domain/loop.py decided
+was needed and feeds the result back in."""
+
+from __future__ import annotations
+
+from claudeloop.application.dto import RunResult, TurnOutcome
+from claudeloop.application.ports import (
+    AgentGateway,
+    AuditLog,
+    CapacityProbe,
+    Clock,
+    ProgressReporter,
+    Sleeper,
+)
+from claudeloop.domain.budget import Budget, BudgetLedger
+from claudeloop.domain.capacity import CapacityState
+from claudeloop.domain.classify import classify
+from claudeloop.domain.completion import CompletionVerdict, evaluate
+from claudeloop.domain.loop import (
+    Finish,
+    Phase,
+    RunState,
+    ScheduleProbe,
+    SendTurn,
+    decide_after_probe,
+    decide_after_turn,
+    decide_preflight,
+    start,
+)
+from claudeloop.domain.waiting import DEFAULT_WAIT_POLICY_CONFIG, WaitPolicyConfig
+
+_DEFAULT_BUDGET = Budget()
+
+
+class AutonomousRunner:
+    def __init__(
+        self,
+        *,
+        agent_gateway: AgentGateway,
+        capacity_probe: CapacityProbe,
+        clock: Clock,
+        sleeper: Sleeper,
+        audit_log: AuditLog,
+        progress: ProgressReporter,
+        budget: Budget = _DEFAULT_BUDGET,
+        wait_policy: WaitPolicyConfig = DEFAULT_WAIT_POLICY_CONFIG,
+        done_marker: str | None = None,
+    ) -> None:
+        self._gateway = agent_gateway
+        self._probe = capacity_probe
+        self._clock = clock
+        self._sleeper = sleeper
+        self._audit = audit_log
+        self._progress = progress
+        self._budget = budget
+        self._wait_policy = wait_policy
+        self._done_marker = done_marker
+
+    async def run(self, *, initial_prompt: str, continue_prompt: str) -> RunResult:
+        """Drive one run to completion: send `initial_prompt` first, then
+        `continue_prompt` on every subsequent SendTurn."""
+        state = start(BudgetLedger(budget=self._budget))
+        session_id: str | None = None
+        first_turn = True
+        attempt = 0
+
+        preflight_outcome = await self._probe.probe()
+        state, decision = decide_preflight(
+            state,
+            self._verdict_capacity(preflight_outcome),
+            now=self._clock.now(),
+            config=self._wait_policy,
+        )
+        self._audit.record("preflight", {"phase": state.phase.name})
+
+        while True:
+            if isinstance(decision, SendTurn):
+                attempt += 1
+                prompt = initial_prompt if first_turn else continue_prompt
+                first_turn = False
+                self._progress.turn_sent(attempt=attempt)
+                outcome = await self._gateway.send_turn(prompt)
+                session_id = outcome.session_id or session_id
+                capacity = classify(outcome.signals)
+                verdict = self._completion_verdict(outcome)
+                self._audit.record(
+                    "turn", {"attempt": attempt, "capacity": type(capacity).__name__}
+                )
+                state, decision = decide_after_turn(
+                    state,
+                    capacity=capacity,
+                    verdict=verdict,
+                    now=self._clock.now(),
+                    config=self._wait_policy,
+                )
+            elif isinstance(decision, ScheduleProbe):
+                self._progress.waiting(reason=state.phase.name, until=decision.at)
+                self._audit.record("waiting", {"until": decision.at.isoformat()})
+                await self._sleeper.sleep_until(decision.at)
+                probe_outcome = await self._probe.probe()
+                state, decision = decide_after_probe(
+                    state,
+                    self._verdict_capacity(probe_outcome),
+                    now=self._clock.now(),
+                    config=self._wait_policy,
+                )
+            else:
+                # RunProbe is a declared member of domain.loop.Decision but no
+                # decide_* function currently produces it standalone — probing
+                # is folded into the ScheduleProbe branch above (schedule, wait,
+                # then probe). Same unreachable-by-construction pattern as
+                # domain.loop.Phase.PROBING; see that module's own exhaustiveness
+                # asserts for the precedent this follows.
+                assert isinstance(decision, Finish)  # nosec B101
+                await self._gateway.close()
+                self._progress.finished(success=decision.success, reason=decision.reason)
+                self._audit.record(
+                    "finished", {"success": decision.success, "reason": decision.reason}
+                )
+                return RunResult(
+                    success=decision.success,
+                    reason=decision.reason,
+                    session_id=session_id,
+                    turns_spent=state.ledger.turns_spent,
+                    dollars_spent=state.ledger.dollars_spent,
+                )
+
+    def _verdict_capacity(self, outcome: TurnOutcome) -> CapacityState:
+        return classify(outcome.signals)
+
+    def _completion_verdict(self, outcome: TurnOutcome) -> CompletionVerdict:
+        kwargs = {"done_marker": self._done_marker} if self._done_marker else {}
+        return evaluate(structured=outcome.verdict, output_text=outcome.output_text, **kwargs)
+
+
+__all__ = ["AutonomousRunner", "RunState", "Phase"]

claudeloop/application/usecases/doctor.py

@@ -0,0 +1,98 @@
+"""Use case: pre-flight checks before starting a long unattended run.
+
+Deliberately checks BEFORE a run starts, not during — an MCP OAuth prompt or a
+missing `claude` binary discovered three hours into an unattended run is much
+worse than the same failure at `claudeloop doctor` time. See
+docs/architecture/decisions/0007-ask-user-question-denied-with-guidance.md for
+why MCP OAuth specifically can never be mitigated mid-run."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+
+
+@dataclass(frozen=True, slots=True)
+class DoctorCheck:
+    name: str
+    passed: bool
+    detail: str
+
+
+class DoctorEnvironment(Protocol):
+    """What doctor needs from the outside world — kept separate from the
+    larger AgentGateway/SessionCatalog ports so `doctor` stays cheap to run
+    and doesn't require a live SDK connection."""
+
+    def find_claude_cli(self) -> str | None: ...
+    def claude_cli_version(self, path: str) -> str | None: ...
+    def is_authenticated(self) -> bool: ...
+    def configured_mcp_servers(self) -> list[str]: ...
+
+
+def run_doctor(env: DoctorEnvironment, *, cwd: Path) -> list[DoctorCheck]:
+    checks: list[DoctorCheck] = []
+
+    cli_path = env.find_claude_cli()
+    if cli_path is None:
+        checks.append(
+            DoctorCheck(
+                name="claude-cli",
+                passed=False,
+                detail="`claude` not found on PATH. Install Claude Code first.",
+            )
+        )
+    else:
+        version = env.claude_cli_version(cli_path)
+        checks.append(
+            DoctorCheck(
+                name="claude-cli",
+                passed=version is not None,
+                detail=f"found at {cli_path} ({version or 'version unknown'})",
+            )
+        )
+
+    authed = env.is_authenticated()
+    checks.append(
+        DoctorCheck(
+            name="authentication",
+            passed=authed,
+            detail="credentials present" if authed else "no credentials found",
+        )
+    )
+
+    mcp_servers = env.configured_mcp_servers()
+    if mcp_servers:
+        checks.append(
+            DoctorCheck(
+                name="mcp-servers",
+                passed=False,
+                detail=(
+                    f"{len(mcp_servers)} MCP server(s) configured ({', '.join(mcp_servers)}) — "
+                    "MCP OAuth cannot complete unattended; verify these are already "
+                    "authorized before starting a long run."
+                ),
+            )
+        )
+    else:
+        checks.append(DoctorCheck(name="mcp-servers", passed=True, detail="none configured"))
+
+    is_git_repo = (cwd / ".git").is_dir()
+    checks.append(
+        DoctorCheck(
+            name="working-directory",
+            passed=is_git_repo,
+            detail=(
+                f"{cwd} is a git repository"
+                if is_git_repo
+                else f"{cwd} is NOT a git repository — bypassing permissions here is riskier"
+            ),
+        )
+    )
+
+    return checks
+
+
+def all_passed(checks: list[DoctorCheck]) -> bool:
+    return all(c.passed for c in checks)

claudeloop/application/usecases/list_sessions.py

@@ -0,0 +1,11 @@
+"""Use case: list known Claude Code sessions for the current (or a given)
+working directory."""
+
+from __future__ import annotations
+
+from claudeloop.application.ports import SessionCatalog
+from claudeloop.domain.session import SessionRef
+
+
+def list_sessions(catalog: SessionCatalog, cwd: str | None = None) -> list[SessionRef]:
+    return catalog.list_all(cwd)

claudeloop/application/usecases/resume_session.py

@@ -0,0 +1,34 @@
+"""Use cases: resume a specific session, or auto-select the most recently
+modified one for a working directory."""
+
+from __future__ import annotations
+
+from claudeloop.application.dto import RunResult
+from claudeloop.application.ports import SessionCatalog
+from claudeloop.application.runner import AutonomousRunner
+from claudeloop.application.usecases.run_plan import with_done_marker_instruction
+from claudeloop.domain.errors import InvalidSessionSelectorError
+from claudeloop.domain.session import SessionRef
+
+
+async def resume_explicit(
+    runner: AutonomousRunner,
+    *,
+    continue_prompt: str = "Continue exactly where you left off.",
+) -> RunResult:
+    """Resume via a session_id the AgentGateway was already constructed with
+    (see infrastructure/agent/gateway.py — resume/continuation is an option
+    passed at ClaudeAgentOptions construction time, not per-call)."""
+    prompt = with_done_marker_instruction(continue_prompt)
+    return await runner.run(initial_prompt=prompt, continue_prompt=prompt)
+
+
+def resolve_most_recent(catalog: SessionCatalog, cwd: str) -> SessionRef:
+    ref = catalog.most_recent(cwd)
+    if ref is None:
+        raise InvalidSessionSelectorError(
+            f"No prior Claude Code sessions found for this directory ({cwd}). "
+            "Pass a plan file to start fresh, or --session-id to target a specific "
+            "session."
+        )
+    return ref

claudeloop/application/usecases/run_plan.py

@@ -0,0 +1,41 @@
+"""Use case: seed a fresh session from a plan file and run it to completion."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from claudeloop.application.dto import RunResult
+from claudeloop.application.runner import AutonomousRunner
+from claudeloop.domain.completion import DEFAULT_DONE_MARKER
+from claudeloop.domain.plan import WorkPlan
+
+_DONE_INSTRUCTION_TEMPLATE = (
+    "{prompt}\n\n"
+    "---\n"
+    "Process note (from the automation running you, not the user): this session "
+    "may be resumed automatically across multiple turns if you get cut off. "
+    "If, and only if, the ENTIRE task above is now fully complete with nothing "
+    "left to do, end your final message with this exact line on its own: "
+    "{marker}\n"
+    "If any work remains -- including work you were mid-way through -- do NOT "
+    "include that line, so the automation knows to resume you."
+)
+
+
+def with_done_marker_instruction(prompt_text: str, done_marker: str = DEFAULT_DONE_MARKER) -> str:
+    """Ported from legacy/claude_autoresume.py's with_done_marker_instruction()
+    (lines 232-248) as the fallback path for models without structured output."""
+    return _DONE_INSTRUCTION_TEMPLATE.format(prompt=prompt_text, marker=done_marker)
+
+
+async def run_from_plan_file(
+    runner: AutonomousRunner,
+    plan_path: Path,
+    *,
+    continue_prompt: str = "Continue exactly where you left off.",
+) -> RunResult:
+    raw_text = plan_path.read_text(encoding="utf-8")
+    plan = WorkPlan.parse(raw_text)
+    initial_prompt = with_done_marker_instruction(plan.raw_text)
+    continue_with_marker = with_done_marker_instruction(continue_prompt)
+    return await runner.run(initial_prompt=initial_prompt, continue_prompt=continue_with_marker)

claudeloop/bootstrap.py

@@ -0,0 +1,93 @@
+"""Composition root — the only module permitted to know about every layer at
+once. Wires concrete infrastructure adapters into application ports and hands
+the assembled AutonomousRunner (or a lighter-weight use-case dependency) to
+cli/. Nothing outside this file should import both a port name from
+application/ports.py and its concrete infrastructure implementation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import timedelta
+from pathlib import Path
+
+from claudeloop.application.runner import AutonomousRunner
+from claudeloop.application.usecases.doctor import DoctorEnvironment
+from claudeloop.domain.budget import Budget
+from claudeloop.domain.waiting import WaitPolicyConfig
+from claudeloop.infrastructure.agent.catalog import SdkSessionCatalog
+from claudeloop.infrastructure.agent.gateway import ClaudeAgentGateway, ClaudeCapacityProbe
+from claudeloop.infrastructure.audit import JsonlAuditLog
+from claudeloop.infrastructure.clock import AnyioSleeper, SystemClock
+from claudeloop.infrastructure.config import RunnerConfig
+from claudeloop.infrastructure.doctor_env import RealDoctorEnvironment
+from claudeloop.infrastructure.progress import ConsoleProgressReporter
+
+
+@dataclass(frozen=True, slots=True)
+class RunnerContext:
+    runner: AutonomousRunner
+    gateway: ClaudeAgentGateway
+
+
+def build_runner(
+    *,
+    cwd: Path,
+    config: RunnerConfig,
+    session_id: str | None = None,
+    resume: str | None = None,
+    continue_conversation: bool = False,
+    log_file: Path | None = None,
+) -> RunnerContext:
+    gateway = ClaudeAgentGateway(
+        cwd=str(cwd),
+        session_id=session_id,
+        resume=resume,
+        continue_conversation=continue_conversation,
+        max_turns=config.max_turns,
+        max_budget_usd=config.max_dollars,
+        retry_watchdog=config.retry_watchdog,
+        model=config.model,
+    )
+    probe = ClaudeCapacityProbe(cwd=str(cwd))
+    clock = SystemClock()
+    sleeper = AnyioSleeper(clock)
+    audit_path = Path(log_file) if log_file else cwd / "claudeloop.log.jsonl"
+    audit_log = JsonlAuditLog(audit_path)
+    progress = ConsoleProgressReporter()
+    budget = Budget(
+        max_turns=config.max_turns,
+        max_dollars=config.max_dollars,
+        max_attempts=config.max_attempts,
+    )
+    wait_policy = WaitPolicyConfig(
+        credits_probe_interval=timedelta(seconds=config.credits_probe_interval_seconds),
+        credits_probe_ceiling=timedelta(seconds=config.credits_probe_ceiling_seconds),
+        window_probe_interval=timedelta(seconds=config.window_probe_interval_seconds),
+        reset_grace=timedelta(seconds=config.reset_grace_seconds),
+        max_wait=(
+            timedelta(seconds=config.max_wait_seconds)
+            if config.max_wait_seconds is not None
+            else None
+        ),
+    )
+
+    runner = AutonomousRunner(
+        agent_gateway=gateway,
+        capacity_probe=probe,
+        clock=clock,
+        sleeper=sleeper,
+        audit_log=audit_log,
+        progress=progress,
+        budget=budget,
+        wait_policy=wait_policy,
+        done_marker=config.done_marker,
+    )
+    return RunnerContext(runner=runner, gateway=gateway)
+
+
+def build_session_catalog() -> SdkSessionCatalog:
+    return SdkSessionCatalog()
+
+
+def build_doctor_environment() -> DoctorEnvironment:
+    return RealDoctorEnvironment()

claudeloop/cli/app.py

@@ -0,0 +1,60 @@
+"""The Typer root app and console-script entry point.
+
+Registered in pyproject.toml as:
+    [project.scripts]
+    claudeloop = "claudeloop.cli.app:main"
+"""
+
+from __future__ import annotations
+
+import typer
+
+from claudeloop import __version__
+from claudeloop.cli.commands.doctor import app as doctor_app
+from claudeloop.cli.commands.resume import resume
+from claudeloop.cli.commands.run import run
+from claudeloop.cli.commands.sessions import app as sessions_app
+
+app = typer.Typer(
+    name="claudeloop",
+    help=(
+        "Onion-architected, autonomous Claude Code session runner — never "
+        "blocks on a human, distinguishes rate limits from exhausted credits, "
+        "and resumes safely across usage windows."
+    ),
+    add_completion=False,
+    no_args_is_help=True,
+)
+
+app.command(name="run")(run)
+app.command(name="resume")(resume)
+app.add_typer(sessions_app, name="sessions")
+app.add_typer(doctor_app, name="doctor")
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"claudeloop {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main_callback(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show the installed claudeloop version and exit.",
+    ),
+) -> None:
+    del version  # handled entirely by the eager callback above
+
+
+def main() -> int:
+    app()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

claudeloop/cli/asyncio.py

@@ -0,0 +1,50 @@
+"""The single anyio bridge point between Typer's sync command functions and the
+async claude_agent_sdk / AutonomousRunner call chain. One bridge, not one per
+command — see docs/architecture/overview.md's async-bridge note.
+
+SIGTERM is converted to SIGINT at the OS level before anyio.run() starts, so
+both signals get the same well-understood handling: Python's default SIGINT
+handler raises KeyboardInterrupt in the main thread, which anyio propagates
+into the running task tree as a cancellation — letting in-flight `finally`
+blocks (closing the AgentGateway, flushing the audit log) run before the
+process exits, instead of dying mid-write."""
+
+from __future__ import annotations
+
+import functools
+import os
+import signal
+import sys
+from collections.abc import Awaitable, Callable
+from typing import ParamSpec, TypeVar
+
+import anyio
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+def _sigterm_as_sigint(signum: int, frame: object) -> None:
+    del signum, frame
+    os.kill(os.getpid(), signal.SIGINT)
+
+
+def async_command(func: Callable[P, Awaitable[R]]) -> Callable[P, R]:
+    """Wrap an async Typer command body so Typer (sync) can call it directly."""
+
+    @functools.wraps(func)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+        previous_handler = None
+        if hasattr(signal, "SIGTERM"):  # pragma: no cover - platform-dependent
+            previous_handler = signal.signal(signal.SIGTERM, _sigterm_as_sigint)
+        bound = functools.partial(func, *args, **kwargs)
+        try:
+            return anyio.run(bound)
+        except KeyboardInterrupt:  # pragma: no cover - real Ctrl-C/SIGTERM not exercised in tests
+            print("\nInterrupted — shutting down gracefully.", file=sys.stderr)
+            raise SystemExit(130) from None
+        finally:
+            if previous_handler is not None:  # pragma: no cover - platform-dependent
+                signal.signal(signal.SIGTERM, previous_handler)
+
+    return wrapper

claudeloop/cli/commands/doctor.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from claudeloop import bootstrap
+from claudeloop.application.usecases.doctor import all_passed, run_doctor
+from claudeloop.cli.render import render_doctor_checks
+
+app = typer.Typer(add_completion=False)
+
+
+@app.callback(invoke_without_command=True)
+def doctor(ctx: typer.Context) -> None:
+    """Pre-flight checks before starting a long unattended run: Claude Code
+    installed and authenticated, configured MCP servers, working-directory
+    safety. Run this BEFORE `run`/`resume`, not instead of them."""
+    if ctx.invoked_subcommand is not None:
+        return
+    env = bootstrap.build_doctor_environment()
+    checks = run_doctor(env, cwd=Path.cwd())
+    typer.echo(render_doctor_checks(checks))
+    if not all_passed(checks):
+        raise typer.Exit(code=1)