claude-dev-env 8.14.0 → 8.15.1

package/scripts/claude_account_worker.py

@@ -0,0 +1,347 @@
+"""Run a headless Claude worker on the account chosen by the usage picker."""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import os
+import shutil
+import subprocess
+import sys
+import time
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+
+from claude_account_choice import choose_account, decision_payload, read_account_meters
+from claude_account_profile import default_profile_home
+from claude_account_worker_process import WorkerProcess, invoke_worker
+from claude_account_worker_report import (
+    WorkerReport,
+    finalize_report,
+    make_report,
+    pre_launch_failure_report,
+    wait_report,
+)
+from dev_env_scripts_constants.claude_account_worker_constants import (
+    CHOICE_MAIN,
+    CHOICE_SECOND,
+    CHOICE_WAIT,
+    CLAUDE_BINARY_NAME,
+    CLAUDE_CONFIG_DIR_ENV_VAR,
+    CLI_DESCRIPTION,
+    CREDENTIALS_FILE_NAME,
+    CWD_FLAG,
+    DEFAULT_PERMISSION_MODE,
+    DEFAULT_TIMEOUT_MINUTES,
+    INVALID_TIMEOUT_MESSAGE,
+    JSON_ACCOUNT_KEY,
+    JSON_CONFIG_DIRECTORY_KEY,
+    JSON_REASON_KEY,
+    LAUNCH_FAILURE_EXIT_CODE,
+    MAIN_CLAUDE_HOME_DIRECTORY_NAME,
+    MISSING_BINARY_EXIT_CODE,
+    MINIMUM_TIMEOUT_MINUTES,
+    MODEL_FLAG,
+    OUTPUT_FORMAT_FLAG,
+    OUTPUT_FORMAT_JSON,
+    PERMISSION_MODE_FLAG,
+    PROMPT_FILE_FLAG,
+    REPORT_FILE_FLAG,
+    SINGLE_PROMPT_FLAG,
+    TIMEOUT_MINUTES_FLAG,
+    UTF8_ENCODING,
+)
+from shared_tree_paths import resolve_shared_process_tree_scripts_directory
+
+_process_tree_scripts_directory = resolve_shared_process_tree_scripts_directory(
+    __file__, all_environment=os.environ
+)
+if str(_process_tree_scripts_directory) not in sys.path:
+    sys.path.insert(0, str(_process_tree_scripts_directory))
+
+_process_tree_kill = importlib.import_module("process_tree_kill")
+_terminate_process_tree = _process_tree_kill.terminate_process_tree
+
+
+@dataclass(frozen=True)
+class AccountSelection:
+    account: str
+    config_dir: Path | None
+    reason: str
+
+
+@dataclass(frozen=True)
+class WorkerDependencies:
+    process_factory: Callable[..., WorkerProcess]
+    all_parent_environment_variables: Mapping[str, str]
+    binary_resolver: Callable[[str], str | None]
+    process_terminator: Callable[[WorkerProcess], None]
+    monotonic_clock: Callable[[], float]
+
+
+def _default_dependencies() -> WorkerDependencies:
+    return WorkerDependencies(
+        process_factory=subprocess.Popen,
+        all_parent_environment_variables=os.environ,
+        binary_resolver=shutil.which,
+        process_terminator=_terminate_process_tree,
+        monotonic_clock=time.monotonic,
+    )
+
+
+def _selection_from_payload(all_selection_payload: Mapping[str, str | None]) -> AccountSelection:
+    account = all_selection_payload[JSON_ACCOUNT_KEY]
+    reason = all_selection_payload[JSON_REASON_KEY]
+    config_dir_text = all_selection_payload[JSON_CONFIG_DIRECTORY_KEY]
+    if account is None or reason is None:
+        raise ValueError("account picker returned an incomplete decision")
+    return AccountSelection(
+        account=account,
+        config_dir=Path(config_dir_text) if config_dir_text is not None else None,
+        reason=reason,
+    )
+
+
+def select_account() -> AccountSelection:
+    """Pick the account this worker runs on and its Claude home directory.
+
+    Returns:
+        The chosen account, its Claude config directory, and the reason.
+
+    Raises:
+        ValueError: When the account picker returns an incomplete decision.
+    """
+    main_config_dir = Path.home() / MAIN_CLAUDE_HOME_DIRECTORY_NAME
+    second_config_dir = default_profile_home()
+    config_directory_by_account = {
+        CHOICE_MAIN: main_config_dir,
+        CHOICE_SECOND: second_config_dir,
+    }
+    main_meters = read_account_meters(main_config_dir / CREDENTIALS_FILE_NAME)
+    second_meters = read_account_meters(second_config_dir / CREDENTIALS_FILE_NAME)
+    decision = choose_account(
+        main_meters=main_meters, second_meters=second_meters, now=datetime.now().astimezone()
+    )
+    selected_config_dir = config_directory_by_account.get(decision.account)
+    payload = decision_payload(decision, config_directory=selected_config_dir)
+    return _selection_from_payload(payload)
+
+
+def _positive_timeout_minutes(candidate_text: str) -> int:
+    timeout_minutes = int(candidate_text)
+    if timeout_minutes < MINIMUM_TIMEOUT_MINUTES:
+        raise argparse.ArgumentTypeError(INVALID_TIMEOUT_MESSAGE)
+    return timeout_minutes
+
+
+def build_argument_parser() -> argparse.ArgumentParser:
+    """Build the CLI parser for one headless worker invocation.
+
+    Returns:
+        The configured argument parser.
+    """
+    parser = argparse.ArgumentParser(description=CLI_DESCRIPTION)
+    parser.add_argument(PROMPT_FILE_FLAG, type=Path, required=True)
+    parser.add_argument(CWD_FLAG, type=Path, default=Path.cwd())
+    parser.add_argument(REPORT_FILE_FLAG, type=Path, required=True)
+    parser.add_argument(MODEL_FLAG)
+    parser.add_argument(
+        PERMISSION_MODE_FLAG,
+        default=DEFAULT_PERMISSION_MODE,
+    )
+    parser.add_argument(
+        TIMEOUT_MINUTES_FLAG,
+        type=_positive_timeout_minutes,
+        default=DEFAULT_TIMEOUT_MINUTES,
+    )
+    return parser
+
+
+def _child_environment(
+    selection: AccountSelection,
+    all_environment_variables: Mapping[str, str],
+) -> dict[str, str]:
+    if selection.account not in (CHOICE_MAIN, CHOICE_SECOND):
+        raise ValueError(f"unsupported account selection: {selection.account}")
+    all_child_environment_variables = dict(all_environment_variables)
+    if selection.account == CHOICE_MAIN:
+        all_child_environment_variables.pop(CLAUDE_CONFIG_DIR_ENV_VAR, None)
+        return all_child_environment_variables
+    if selection.config_dir is None:
+        raise ValueError("second account selection needs a config directory")
+    all_child_environment_variables[CLAUDE_CONFIG_DIR_ENV_VAR] = str(selection.config_dir)
+    return all_child_environment_variables
+
+
+def _invocation(
+    executable: str,
+    *,
+    model: str | None,
+    permission_mode: str,
+) -> list[str]:
+    all_arguments = [
+        executable,
+        SINGLE_PROMPT_FLAG,
+        OUTPUT_FORMAT_FLAG,
+        OUTPUT_FORMAT_JSON,
+        PERMISSION_MODE_FLAG,
+        permission_mode,
+    ]
+    if model is not None:
+        all_arguments.extend([MODEL_FLAG, model])
+    return all_arguments
+
+
+def _prepared_launch(
+    selection: AccountSelection,
+    prompt_file: Path,
+    dependencies: WorkerDependencies,
+) -> tuple[dict[str, str], str, str] | WorkerReport:
+    try:
+        all_child_environment_variables = _child_environment(
+            selection, dependencies.all_parent_environment_variables
+        )
+        prompt_text = prompt_file.read_text(encoding=UTF8_ENCODING)
+    except (OSError, ValueError):
+        return pre_launch_failure_report(
+            selection.account, selection.reason, LAUNCH_FAILURE_EXIT_CODE
+        )
+    claude_binary = dependencies.binary_resolver(CLAUDE_BINARY_NAME)
+    if claude_binary is None:
+        return pre_launch_failure_report(
+            selection.account, selection.reason, MISSING_BINARY_EXIT_CODE
+        )
+    return all_child_environment_variables, prompt_text, claude_binary
+
+
+def _invoked_report(
+    selection: AccountSelection,
+    *,
+    all_arguments: list[str],
+    cwd: Path,
+    all_child_environment_variables: dict[str, str],
+    prompt_text: str,
+    timeout_minutes: int,
+    dependencies: WorkerDependencies,
+) -> WorkerReport:
+    exit_code, duration_seconds, stdout_text = invoke_worker(
+        all_arguments=all_arguments,
+        cwd=cwd,
+        all_child_environment_variables=all_child_environment_variables,
+        prompt_text=prompt_text,
+        timeout_minutes=timeout_minutes,
+        controls=dependencies,
+    )
+    return make_report(
+        selection.account,
+        selection.reason,
+        exit_code=exit_code,
+        duration_seconds=duration_seconds,
+        stdout_text=stdout_text,
+    )
+
+
+def _worker_report(
+    selection: AccountSelection,
+    *,
+    prompt_file: Path,
+    cwd: Path,
+    model: str | None,
+    permission_mode: str,
+    timeout_minutes: int,
+    dependencies: WorkerDependencies,
+) -> WorkerReport:
+    prepared = _prepared_launch(selection, prompt_file, dependencies)
+    if isinstance(prepared, WorkerReport):
+        return prepared
+    all_child_environment_variables, prompt_text, claude_binary = prepared
+    all_arguments = _invocation(claude_binary, model=model, permission_mode=permission_mode)
+    return _invoked_report(
+        selection,
+        all_arguments=all_arguments,
+        cwd=cwd,
+        all_child_environment_variables=all_child_environment_variables,
+        prompt_text=prompt_text,
+        timeout_minutes=timeout_minutes,
+        dependencies=dependencies,
+    )
+
+
+def _report_for_selection(
+    selection: AccountSelection,
+    *,
+    prompt_file: Path,
+    cwd: Path,
+    model: str | None,
+    permission_mode: str,
+    timeout_minutes: int,
+    dependencies: WorkerDependencies,
+) -> WorkerReport:
+    if selection.account == CHOICE_WAIT:
+        return wait_report(selection.account, selection.reason)
+    return _worker_report(
+        selection,
+        prompt_file=prompt_file,
+        cwd=cwd,
+        model=model,
+        permission_mode=permission_mode,
+        timeout_minutes=timeout_minutes,
+        dependencies=dependencies,
+    )
+
+
+def run_worker(
+    *,
+    prompt_file: Path,
+    cwd: Path,
+    report_file: Path,
+    model: str | None,
+    permission_mode: str,
+    timeout_minutes: int,
+    decision_selector: Callable[[], AccountSelection],
+    dependencies: WorkerDependencies,
+) -> int:
+    """Pick an account and run one headless Claude worker on it.
+
+    Args:
+        prompt_file, report_file: The prompt and report file paths.
+        decision_selector, dependencies: The picker and process controls.
+    Returns:
+        The exit code: 3 on wait, 124 on timeout, 127 on a missing binary,
+        or the child's own exit code.
+    """
+    report = _report_for_selection(
+        decision_selector(),
+        prompt_file=prompt_file,
+        cwd=cwd,
+        model=model,
+        permission_mode=permission_mode,
+        timeout_minutes=timeout_minutes,
+        dependencies=dependencies,
+    )
+    return finalize_report(report_file, report)
+
+
+def main() -> int:
+    """Parse CLI arguments and run one headless worker.
+
+    Returns:
+        The worker's exit code.
+    """
+    arguments = build_argument_parser().parse_args()
+    return run_worker(
+        prompt_file=arguments.prompt_file,
+        cwd=arguments.cwd,
+        report_file=arguments.report_file,
+        model=arguments.model,
+        permission_mode=arguments.permission_mode,
+        timeout_minutes=arguments.timeout_minutes,
+        decision_selector=select_account,
+        dependencies=_default_dependencies(),
+    )
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/claude_account_worker_process.py

@@ -0,0 +1,169 @@
+"""Launch a headless Claude worker process and wait for it to finish."""
+
+from __future__ import annotations
+
+import importlib
+import os
+import subprocess
+import sys
+from collections.abc import Callable
+from pathlib import Path
+from typing import Protocol
+
+from dev_env_scripts_constants.claude_account_worker_constants import (
+    DRAIN_ATTEMPT_LIMIT,
+    DRAIN_GRACE_TIMEOUT_SECONDS,
+    LAUNCH_FAILURE_EXIT_CODE,
+    SECONDS_PER_MINUTE,
+    TIMEOUT_EXIT_CODE,
+    UTF8_DECODE_ERRORS,
+    UTF8_ENCODING,
+)
+from shared_tree_paths import resolve_shared_process_tree_scripts_directory
+from subprocess_stream_text import decode_stream_text
+from subprocess_window_access import hidden_window_creation_flags
+
+_process_tree_scripts_directory = resolve_shared_process_tree_scripts_directory(
+    __file__, all_environment=os.environ
+)
+if str(_process_tree_scripts_directory) not in sys.path:
+    sys.path.insert(0, str(_process_tree_scripts_directory))
+
+_process_tree_kill = importlib.import_module("process_tree_kill")
+_should_start_new_session = _process_tree_kill.should_start_new_session
+
+
+class WorkerProcess(Protocol):
+    returncode: int | None
+
+    pid: int
+
+    def communicate(
+        self,
+        input: str | None = None,
+        timeout: float | None = None,
+    ) -> tuple[str | bytes | None, str | bytes | None]: ...
+
+    def poll(self) -> int | None: ...
+
+    def kill(self) -> None: ...
+
+
+def _decoded_text(stream_payload: str | bytes | None) -> str:
+    return decode_stream_text(
+        stream_payload, encoding=UTF8_ENCODING, errors=UTF8_DECODE_ERRORS
+    )
+
+
+def _launch_process(
+    process_factory: Callable[..., WorkerProcess],
+    all_arguments: list[str],
+    cwd: Path,
+    all_child_environment_variables: dict[str, str],
+) -> WorkerProcess | None:
+    try:
+        return process_factory(
+            all_arguments,
+            cwd=str(cwd),
+            env=all_child_environment_variables,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            encoding=UTF8_ENCODING,
+            errors=UTF8_DECODE_ERRORS,
+            start_new_session=_should_start_new_session(),
+            creationflags=hidden_window_creation_flags(),
+        )
+    except OSError:
+        return None
+
+
+def _drain_attempt_outcome(process: WorkerProcess) -> tuple[bool, str]:
+    try:
+        captured_stdout, _ = process.communicate(timeout=DRAIN_GRACE_TIMEOUT_SECONDS)
+    except subprocess.TimeoutExpired as timeout_error:
+        return False, _decoded_text(timeout_error.output)
+    return True, _decoded_text(captured_stdout)
+
+
+def _drain_after_termination(
+    process: WorkerProcess,
+    process_terminator: Callable[[WorkerProcess], None],
+    initial_stdout_text: str,
+) -> str:
+    latest_stdout_text = initial_stdout_text
+    for _ in range(DRAIN_ATTEMPT_LIMIT):
+        process_terminator(process)
+        did_drain, attempt_stdout_text = _drain_attempt_outcome(process)
+        if attempt_stdout_text:
+            latest_stdout_text = attempt_stdout_text
+        if did_drain:
+            return latest_stdout_text
+    return latest_stdout_text
+
+
+class ProcessControls(Protocol):
+    """The process factory, terminator, and clock a worker run uses."""
+
+    process_factory: Callable[..., WorkerProcess]
+    process_terminator: Callable[[WorkerProcess], None]
+    monotonic_clock: Callable[[], float]
+
+
+def _await_completion(
+    process: WorkerProcess | None,
+    prompt_text: str,
+    timeout_minutes: int,
+    process_terminator: Callable[[WorkerProcess], None],
+) -> tuple[int, str]:
+    if process is None:
+        return LAUNCH_FAILURE_EXIT_CODE, ""
+    try:
+        captured_stdout, _ = process.communicate(
+            input=prompt_text,
+            timeout=timeout_minutes * SECONDS_PER_MINUTE,
+        )
+    except subprocess.TimeoutExpired as timeout_error:
+        stdout_text = _drain_after_termination(
+            process, process_terminator, _decoded_text(timeout_error.output)
+        )
+        return TIMEOUT_EXIT_CODE, stdout_text
+    process_exit_code = (
+        process.returncode
+        if process.returncode is not None
+        else LAUNCH_FAILURE_EXIT_CODE
+    )
+    return process_exit_code, _decoded_text(captured_stdout)
+
+
+def invoke_worker(
+    *,
+    all_arguments: list[str],
+    cwd: Path,
+    all_child_environment_variables: dict[str, str],
+    prompt_text: str,
+    timeout_minutes: int,
+    controls: ProcessControls,
+) -> tuple[int, float, str]:
+    """Launch the worker process and return its exit code, duration, and stdout.
+
+    Args:
+        all_arguments: The full command line, executable first.
+        cwd: Working directory the child process runs in.
+        all_child_environment_variables: Environment passed to the child.
+        prompt_text: The prompt piped to the child on stdin.
+        timeout_minutes: Minutes to wait before the child is timed out.
+        controls: The process factory, terminator, and clock.
+
+    Returns:
+        The exit code, the duration in seconds, and the decoded stdout.
+    """
+    process_start = controls.monotonic_clock()
+    process = _launch_process(
+        controls.process_factory, all_arguments, cwd, all_child_environment_variables
+    )
+    exit_code, stdout_text = _await_completion(
+        process, prompt_text, timeout_minutes, controls.process_terminator
+    )
+    return exit_code, controls.monotonic_clock() - process_start, stdout_text

package/scripts/claude_account_worker_report.py

@@ -0,0 +1,170 @@
+"""Build and write a headless Claude worker's JSON report."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+from dev_env_scripts_constants.claude_account_worker_constants import (
+    DURATION_DECIMAL_PLACES,
+    JSON_IS_ERROR_KEY,
+    JSON_RESULT_KEY,
+    REPORT_ACCOUNT_KEY,
+    REPORT_DURATION_SECONDS_KEY,
+    REPORT_EXIT_CODE_KEY,
+    REPORT_INDENT,
+    REPORT_IS_ERROR_KEY,
+    REPORT_REASON_KEY,
+    REPORT_RESULT_KEY,
+    STDOUT_TAIL_CHARACTER_LIMIT,
+    SUMMARY_LINE_TEMPLATE,
+    UTF8_ENCODING,
+    WAIT_DURATION_SECONDS,
+    WAIT_EXIT_CODE,
+)
+
+
+@dataclass(frozen=True)
+class WorkerReport:
+    account: str
+    reason: str
+    exit_code: int
+    duration_seconds: float
+    payload: object
+    is_error: bool
+
+
+def _bounded_stdout_tail(stdout_text: str) -> str:
+    return stdout_text[-STDOUT_TAIL_CHARACTER_LIMIT:]
+
+
+def _extract_payload(stdout_text: str) -> tuple[object, bool]:
+    try:
+        parsed_stdout = json.loads(stdout_text)
+    except json.JSONDecodeError:
+        return _bounded_stdout_tail(stdout_text), True
+    if not isinstance(parsed_stdout, dict) or JSON_RESULT_KEY not in parsed_stdout:
+        return None, True
+    return parsed_stdout[JSON_RESULT_KEY], parsed_stdout.get(JSON_IS_ERROR_KEY) is True
+
+
+def wait_report(account: str, reason: str) -> WorkerReport:
+    """Build the report for an account decision that says to wait.
+
+    Args:
+        account: The chosen account slot.
+        reason: Why the picker chose to wait.
+
+    Returns:
+        A report carrying the wait exit code and no payload.
+    """
+    return WorkerReport(
+        account=account,
+        reason=reason,
+        exit_code=WAIT_EXIT_CODE,
+        duration_seconds=WAIT_DURATION_SECONDS,
+        payload=None,
+        is_error=True,
+    )
+
+
+def make_report(
+    account: str,
+    reason: str,
+    *,
+    exit_code: int,
+    duration_seconds: float,
+    stdout_text: str,
+) -> WorkerReport:
+    """Build the report for a worker that ran, from its captured stdout.
+
+    Args:
+        account: The chosen account slot.
+        reason: Why the picker chose that account.
+        exit_code: The worker process's exit code.
+        duration_seconds: How long the worker ran.
+        stdout_text: The worker's captured stdout text.
+
+    Returns:
+        A report carrying the parsed payload, or the stdout tail when the
+        payload does not parse as the expected JSON shape.
+    """
+    payload, has_payload_error = _extract_payload(stdout_text)
+    return WorkerReport(
+        account=account,
+        reason=reason,
+        exit_code=exit_code,
+        duration_seconds=round(duration_seconds, DURATION_DECIMAL_PLACES),
+        payload=payload,
+        is_error=(exit_code != 0 or has_payload_error),
+    )
+
+
+def pre_launch_failure_report(
+    account: str, reason: str, exit_code: int
+) -> WorkerReport:
+    """Build the report for a failure that happened before the worker launched.
+
+    Args:
+        account: The chosen account slot.
+        reason: Why the picker chose that account.
+        exit_code: The failure's exit code.
+
+    Returns:
+        A report with no payload and a zero duration.
+    """
+    return make_report(
+        account,
+        reason,
+        exit_code=exit_code,
+        duration_seconds=WAIT_DURATION_SECONDS,
+        stdout_text="",
+    )
+
+
+def write_report(report_file: Path, report: WorkerReport) -> None:
+    """Write a worker report to disk as indented JSON.
+
+    Args:
+        report_file: Where the JSON report is written.
+        report: The report to serialize.
+    """
+    report_file.parent.mkdir(parents=True, exist_ok=True)
+    report_payload = {
+        REPORT_ACCOUNT_KEY: report.account,
+        REPORT_REASON_KEY: report.reason,
+        REPORT_EXIT_CODE_KEY: report.exit_code,
+        REPORT_DURATION_SECONDS_KEY: report.duration_seconds,
+        REPORT_RESULT_KEY: report.payload,
+        REPORT_IS_ERROR_KEY: report.is_error,
+    }
+    report_file.write_text(
+        json.dumps(report_payload, ensure_ascii=False, indent=REPORT_INDENT) + "\n",
+        encoding=UTF8_ENCODING,
+    )
+
+
+def _print_summary(report: WorkerReport, report_file: Path) -> None:
+    print(
+        SUMMARY_LINE_TEMPLATE.format(
+            account=report.account,
+            exit_code=report.exit_code,
+            report_file=report_file,
+        )
+    )
+
+
+def finalize_report(report_file: Path, report: WorkerReport) -> int:
+    """Write a worker report to disk and print its one-line summary.
+
+    Args:
+        report_file: Where the JSON report is written.
+        report: The report to write and summarize.
+
+    Returns:
+        The report's exit code.
+    """
+    write_report(report_file, report)
+    _print_summary(report, report_file)
+    return report.exit_code