claude-dev-env 8.14.0 → 8.15.0

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

package/scripts/dev_env_scripts_constants/claude_account_worker_constants.py

@@ -0,0 +1,139 @@
+"""Named values for the second-account Claude worker."""
+
+from __future__ import annotations
+
+from dev_env_scripts_constants.claude_account_constants import (
+    CHOICE_MAIN,
+    CHOICE_SECOND,
+    CHOICE_WAIT,
+    CREDENTIALS_FILE_NAME,
+    JSON_ACCOUNT_KEY,
+    JSON_CONFIG_DIRECTORY_KEY,
+    JSON_REASON_KEY,
+    MAIN_CLAUDE_HOME_DIRECTORY_NAME,
+)
+from dev_env_scripts_constants.shared_tree_constants import CLAUDE_CONFIG_DIR_ENV_VAR
+
+CLAUDE_BINARY_NAME: str = "claude"
+
+DEFAULT_PERMISSION_MODE: str = "auto"
+
+DEFAULT_TIMEOUT_MINUTES: int = 60
+
+MINIMUM_TIMEOUT_MINUTES: int = 1
+
+WAIT_EXIT_CODE: int = 3
+
+TIMEOUT_EXIT_CODE: int = 124
+
+MISSING_BINARY_EXIT_CODE: int = 127
+
+LAUNCH_FAILURE_EXIT_CODE: int = 1
+
+WAIT_DURATION_SECONDS: float = 0.0
+
+STDOUT_TAIL_CHARACTER_LIMIT: int = 4000
+
+DRAIN_GRACE_TIMEOUT_SECONDS: int = 10
+
+DRAIN_ATTEMPT_LIMIT: int = 2
+
+DURATION_DECIMAL_PLACES: int = 3
+
+REPORT_INDENT: int = 2
+
+UTF8_ENCODING: str = "utf-8"
+
+UTF8_DECODE_ERRORS: str = "replace"
+
+CLI_DESCRIPTION: str = "Run one Claude worker using the account picker."
+
+PROMPT_FILE_FLAG: str = "--prompt-file"
+
+CWD_FLAG: str = "--cwd"
+
+REPORT_FILE_FLAG: str = "--report-file"
+
+MODEL_FLAG: str = "--model"
+
+PERMISSION_MODE_FLAG: str = "--permission-mode"
+
+TIMEOUT_MINUTES_FLAG: str = "--timeout-minutes"
+
+OUTPUT_FORMAT_FLAG: str = "--output-format"
+
+OUTPUT_FORMAT_JSON: str = "json"
+
+SINGLE_PROMPT_FLAG: str = "-p"
+
+SECONDS_PER_MINUTE: int = 60
+
+JSON_RESULT_KEY: str = "result"
+
+JSON_IS_ERROR_KEY: str = "is_error"
+
+REPORT_ACCOUNT_KEY: str = JSON_ACCOUNT_KEY
+
+REPORT_REASON_KEY: str = JSON_REASON_KEY
+
+REPORT_EXIT_CODE_KEY: str = "exit_code"
+
+REPORT_DURATION_SECONDS_KEY: str = "duration_seconds"
+
+REPORT_RESULT_KEY: str = JSON_RESULT_KEY
+
+REPORT_IS_ERROR_KEY: str = JSON_IS_ERROR_KEY
+
+SUMMARY_LINE_TEMPLATE: str = "account={account} exit_code={exit_code} report={report_file}"
+
+INVALID_TIMEOUT_MESSAGE: str = "--timeout-minutes must be at least 1"
+
+
+__all__ = [
+    "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",
+    "DRAIN_ATTEMPT_LIMIT",
+    "DRAIN_GRACE_TIMEOUT_SECONDS",
+    "DURATION_DECIMAL_PLACES",
+    "INVALID_TIMEOUT_MESSAGE",
+    "JSON_ACCOUNT_KEY",
+    "JSON_CONFIG_DIRECTORY_KEY",
+    "JSON_IS_ERROR_KEY",
+    "JSON_REASON_KEY",
+    "JSON_RESULT_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_ACCOUNT_KEY",
+    "REPORT_DURATION_SECONDS_KEY",
+    "REPORT_EXIT_CODE_KEY",
+    "REPORT_FILE_FLAG",
+    "REPORT_INDENT",
+    "REPORT_IS_ERROR_KEY",
+    "REPORT_REASON_KEY",
+    "REPORT_RESULT_KEY",
+    "SECONDS_PER_MINUTE",
+    "SINGLE_PROMPT_FLAG",
+    "STDOUT_TAIL_CHARACTER_LIMIT",
+    "SUMMARY_LINE_TEMPLATE",
+    "TIMEOUT_EXIT_CODE",
+    "TIMEOUT_MINUTES_FLAG",
+    "UTF8_DECODE_ERRORS",
+    "UTF8_ENCODING",
+    "WAIT_DURATION_SECONDS",
+    "WAIT_EXIT_CODE",
+]

package/scripts/grok_headless_runner.py

@@ -73,6 +73,7 @@ from dev_env_scripts_constants.grok_worker_constants import (
 )
 from shared_tree_paths import resolve_shared_process_tree_scripts_directory
 from grok_worker_preflight import poteto_mode_skill_path
+from subprocess_stream_text import decode_stream_text
 
 _shared_process_tree_scripts_directory = resolve_shared_process_tree_scripts_directory(
     __file__,
@@ -200,11 +201,7 @@ def _classify_completion(
 
 
 def _normalize_stream(stream_payload: str | bytes | None) -> str:
-    if stream_payload is None:
-        return ""
-    if isinstance(stream_payload, bytes):
-        return stream_payload.decode(UTF8_ENCODING, errors=UTF8_DECODE_ERRORS)
-    return stream_payload
+    return decode_stream_text(stream_payload, encoding=UTF8_ENCODING, errors=UTF8_DECODE_ERRORS)
 
 
 def _resolve_returncode(process: subprocess.Popen[str]) -> int:

package/scripts/subprocess_stream_text.py

@@ -0,0 +1,28 @@
+"""Decode a subprocess stream text payload captured in text or bytes mode."""
+
+from __future__ import annotations
+
+
+def decode_stream_text(
+    stream_payload: str | bytes | None,
+    *,
+    encoding: str,
+    errors: str,
+) -> str:
+    """Decode a captured subprocess stream text payload, whichever mode captured it.
+
+    Args:
+        stream_payload: The captured stream content, or None when nothing
+            was captured.
+        encoding: The text encoding to use when the payload is bytes.
+        errors: The decode error handler to use when the payload is bytes.
+
+    Returns:
+        The decoded text, an empty string when stream_payload is None, or
+        stream_payload unchanged when it is already text.
+    """
+    if stream_payload is None:
+        return ""
+    if isinstance(stream_payload, bytes):
+        return stream_payload.decode(encoding, errors=errors)
+    return stream_payload