agent-cli 0.95.0__tar.gz → 0.95.2__tar.gz

{agent_cli-0.95.0 → agent_cli-0.95.2}/.github/workflows/pytest.yml

@@ -28,6 +28,9 @@ jobs:
         run: sudo apt-get update && sudo apt-get install -y portaudio19-dev
       - name: Install uv
         uses: astral-sh/setup-uv@v8.1.0
+      - name: Run macOS app Swift tests
+        if: matrix.os == 'macos-latest' && matrix.python-version == '3.13'
+        run: swift test --package-path macos/AgentCLI --enable-xctest
       - name: Run pytest (macOS - all extras)
         if: matrix.os == 'macos-latest'
         run: uv run --all-extras pytest -vvv

{agent_cli-0.95.0 → agent_cli-0.95.2}/.github/workflows/release.yml

@@ -1,4 +1,4 @@
-name: Upload Python Package
+name: Publish Release
 
 on:
   release:
@@ -6,6 +6,7 @@ on:
 
 jobs:
   deploy:
+    name: Publish Python package
     runs-on: ubuntu-latest
     environment:
       name: pypi
@@ -22,7 +23,9 @@ jobs:
         uses: pypa/gh-action-pypi-publish@release/v1
 
   build_macos_app:
+    name: Build and publish macOS app
     runs-on: macos-latest
+    timeout-minutes: 45
     permissions:
       contents: write
     steps:

{agent_cli-0.95.0 → agent_cli-0.95.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-cli
-Version: 0.95.0
+Version: 0.95.2
 Summary: A suite of AI-powered command-line tools for text correction, audio transcription, and voice assistance.
 Project-URL: Homepage, https://github.com/basnijholt/agent-cli
 Author-email: Bas Nijholt <bas@nijho.lt>
@@ -961,9 +961,13 @@ the `[defaults]` section of your configuration file.
 │                                 [env var: GEMINI_API_KEY]                              │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 ╭─ Process Management ───────────────────────────────────────────────────────────────────╮
-│ --stop            Stop any running instance of this command.                           │
-│ --status          Check if an instance is currently running.                           │
-│ --toggle          Start if not running, stop if running. Ideal for hotkey binding.     │
+│ --start                   Start this command if it is not already running.             │
+│ --stop                    Stop any running instance of this command.                   │
+│ --status                  Check if an instance is currently running.                   │
+│ --toggle                  Start if not running, stop if running. Ideal for hotkey      │
+│                           binding.                                                     │
+│ --wait-for-start          When stopping, wait briefly for a just-launched process to   │
+│                           write its PID.                                               │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 ╭─ General Options ──────────────────────────────────────────────────────────────────────╮
 │ --clipboard              --no-clipboard                          Copy result to        │

{agent_cli-0.95.0 → agent_cli-0.95.2}/README.md

@@ -856,9 +856,13 @@ the `[defaults]` section of your configuration file.
 │                                 [env var: GEMINI_API_KEY]                              │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 ╭─ Process Management ───────────────────────────────────────────────────────────────────╮
-│ --stop            Stop any running instance of this command.                           │
-│ --status          Check if an instance is currently running.                           │
-│ --toggle          Start if not running, stop if running. Ideal for hotkey binding.     │
+│ --start                   Start this command if it is not already running.             │
+│ --stop                    Stop any running instance of this command.                   │
+│ --status                  Check if an instance is currently running.                   │
+│ --toggle                  Start if not running, stop if running. Ideal for hotkey      │
+│                           binding.                                                     │
+│ --wait-for-start          When stopping, wait briefly for a just-launched process to   │
+│                           write its PID.                                               │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
 ╭─ General Options ──────────────────────────────────────────────────────────────────────╮
 │ --clipboard              --no-clipboard                          Copy result to        │

{agent_cli-0.95.0 → agent_cli-0.95.2}/agent_cli/agents/transcribe.py

@@ -625,9 +625,11 @@ def transcribe(  # noqa: PLR0912, PLR0911, PLR0915, C901
     gemini_api_key: str | None = opts.GEMINI_API_KEY,
     llm: bool = opts.LLM,
     # --- Process Management ---
+    start: bool = opts.START,
     stop: bool = opts.STOP,
     status: bool = opts.STATUS,
     toggle: bool = opts.TOGGLE,
+    wait_for_start: bool = opts.WAIT_FOR_START,
     # --- General Options ---
     clipboard: bool = opts.CLIPBOARD,
     log_level: opts.LogLevel = opts.LOG_LEVEL,
@@ -854,6 +856,29 @@ def transcribe(  # noqa: PLR0912, PLR0911, PLR0915, C901
 
     # Normal recording mode
     process_name = "transcribe"
+    if start:
+        process_status = process.get_process_status(process_name)
+        if process_status.running:
+            if json_output:
+                print(
+                    json.dumps(
+                        {
+                            "action": "start",
+                            "process": process_name,
+                            "running": True,
+                            "status": "running",
+                            "pid": process_status.pid,
+                            "stale_cleaned": process_status.stale_cleaned,
+                        },
+                    ),
+                )
+            elif not general_cfg.quiet:
+                print_with_style(
+                    f"✅ Transcribe is already running (PID: {process_status.pid}).",
+                    style="green",
+                )
+            return
+
     if stop_or_status_or_toggle(
         process_name,
         "transcribe",
@@ -861,24 +886,26 @@ def transcribe(  # noqa: PLR0912, PLR0911, PLR0915, C901
         status,
         toggle,
         quiet=general_cfg.quiet,
+        json_output=json_output,
+        wait_for_start_seconds=300.0 if wait_for_start else 0.0,
     ):
         return
 
-    audio_in_cfg = config.AudioInput(
-        input_device_index=input_device_index,
-        input_device_name=input_device_name,
-    )
-
-    # We only use setup_devices for its input device handling
-    device_info = setup_devices(general_cfg, audio_in_cfg, None)
-    if device_info is None:
-        return
-    input_device_index, _, _ = device_info
-    audio_in_cfg.input_device_index = input_device_index
-
-    # Use context manager for PID file management
+    # Use context manager before audio setup so --stop can target startup reliably.
     try:
         with process.pid_file_context(process_name), suppress(KeyboardInterrupt):
+            audio_in_cfg = config.AudioInput(
+                input_device_index=input_device_index,
+                input_device_name=input_device_name,
+            )
+
+            # We only use setup_devices for its input device handling
+            device_info = setup_devices(general_cfg, audio_in_cfg, None)
+            if device_info is None:
+                return
+            input_device_index, _, _ = device_info
+            audio_in_cfg.input_device_index = input_device_index
+
             result = asyncio.run(
                 _async_main(
                     extra_instructions=extra_instructions,

{agent_cli-0.95.0 → agent_cli-0.95.2}/agent_cli/agents/transcribe_live.py

@@ -408,7 +408,8 @@ def transcribe_live(  # noqa: PLR0912
 
     # Handle stop/status commands
     if stop:
-        if process.kill_process(process_name):
+        result = process.stop_process(process_name)
+        if result.was_running or result.stale_cleaned:
             if not quiet:
                 print_with_style(f"✅ Stopped {process_name}", style="green")
         elif not quiet:
@@ -416,7 +417,8 @@ def transcribe_live(  # noqa: PLR0912
         return
 
     if status:
-        if process.is_process_running(process_name):
+        process_status = process.get_process_status(process_name)
+        if process_status.running:
             if not quiet:
                 print_with_style(f"✅ {process_name} is running", style="green")
         elif not quiet:

{agent_cli-0.95.0 → agent_cli-0.95.2}/agent_cli/core/deps.py

@@ -382,7 +382,7 @@ def _should_skip_extra_check_for_process_control(
 
     from agent_cli.core import process  # noqa: PLC0415
 
-    return process.is_process_running(process_name)
+    return process.get_process_status(process_name).running
 
 
 def requires_extras(

{agent_cli-0.95.0 → agent_cli-0.95.2}/agent_cli/core/process.py

@@ -24,6 +24,24 @@ class _PidInfo(NamedTuple):
     uses_lock: bool
 
 
+class ProcessStatus(NamedTuple):
+    """Current state of a managed Agent CLI process."""
+
+    process_name: str
+    running: bool
+    pid: int | None
+    stale_cleaned: bool = False
+
+
+class StopProcessResult(NamedTuple):
+    """Result of a stop request for a managed Agent CLI process."""
+
+    process_name: str
+    was_running: bool
+    status: ProcessStatus
+    stale_cleaned: bool = False
+
+
 def _default_pid_dir() -> Path:
     """Return local runtime dir for process control files."""
     if runtime_dir := os.environ.get("AGENTCLI_RUNTIME_DIR"):
@@ -116,8 +134,10 @@ def _is_pid_running(pid: int) -> bool:
     try:
         os.kill(pid, 0)
         return True
-    except (ProcessLookupError, PermissionError):
+    except ProcessLookupError:
         return False
+    except PermissionError:
+        return True
 
 
 def _supports_process_locks() -> bool:
@@ -233,58 +253,59 @@ def _cleanup_process_files(process_name: str) -> None:
     clear_stop_file(process_name)
 
 
-def _get_running_pid(process_name: str) -> int | None:
-    """Get PID if process is running, None otherwise. Cleans up stale files."""
+def get_process_status(process_name: str) -> ProcessStatus:
+    """Return process state and deterministically clean stale control files."""
     if not _get_pid_file(process_name).exists():
-        return None
+        return ProcessStatus(process_name=process_name, running=False, pid=None)
 
     pid_info = _read_pid_info(process_name)
     if pid_info is None:
         _cleanup_process_files(process_name)
-        return None
+        return ProcessStatus(
+            process_name=process_name,
+            running=False,
+            pid=None,
+            stale_cleaned=True,
+        )
 
     if pid_info.uses_lock and _supports_process_locks() and not _is_process_lock_held(process_name):
         _cleanup_process_files(process_name)
-        return None
+        return ProcessStatus(
+            process_name=process_name,
+            running=False,
+            pid=None,
+            stale_cleaned=True,
+        )
 
     if _is_pid_running(pid_info.pid):
-        return pid_info.pid
+        return ProcessStatus(process_name=process_name, running=True, pid=pid_info.pid)
 
     _cleanup_process_files(process_name)
-    return None
-
-
-def is_process_running(process_name: str) -> bool:
-    """Check if a process is currently running."""
-    return _get_running_pid(process_name) is not None
-
-
-def read_pid_file(process_name: str) -> int | None:
-    """Read PID from file if process is running."""
-    return _get_running_pid(process_name)
-
-
-def kill_process(process_name: str) -> bool:
-    """Kill a process by name.
-
-    Returns True if killed or cleaned up, False if not found.
-    On Windows, creates a stop file first to allow graceful shutdown.
-    """
-    pid_file = _get_pid_file(process_name)
-
-    # If no PID file exists at all, nothing to do
-    if not pid_file.exists():
-        clear_stop_file(process_name)
-        return False
-
-    # Check if we have a running process
-    pid = _get_running_pid(process_name)
-
-    # If _get_running_pid returned None but file existed, it cleaned up a stale file
-    if pid is None:
-        clear_stop_file(process_name)
-        return True
-
+    return ProcessStatus(
+        process_name=process_name,
+        running=False,
+        pid=None,
+        stale_cleaned=True,
+    )
+
+
+def _wait_for_process_start(
+    process_name: str,
+    *,
+    wait_for_start_seconds: float,
+    poll_interval: float,
+) -> ProcessStatus:
+    """Wait briefly for a just-launched process to write its PID file."""
+    deadline = time.monotonic() + wait_for_start_seconds
+    status = get_process_status(process_name)
+    while not status.running and time.monotonic() < deadline:
+        time.sleep(poll_interval)
+        status = get_process_status(process_name)
+    return status
+
+
+def _signal_running_process(process_name: str, pid: int) -> None:
+    """Signal a known-running process and clean control files if it exits."""
     stop_file = _get_stop_file(process_name)
     should_force_kill = sys.platform != "win32" and stop_file.exists()
 
@@ -317,7 +338,39 @@ def kill_process(process_name: str) -> bool:
     elif not should_force_kill:
         stop_file.touch()
 
-    return True
+
+def stop_process(
+    process_name: str,
+    *,
+    wait_for_start_seconds: float = 0.0,
+    poll_interval: float = 0.1,
+) -> StopProcessResult:
+    """Stop a process by name and return the resulting process state."""
+    initial_status = get_process_status(process_name)
+    if not initial_status.running and wait_for_start_seconds > 0:
+        initial_status = _wait_for_process_start(
+            process_name,
+            wait_for_start_seconds=wait_for_start_seconds,
+            poll_interval=poll_interval,
+        )
+
+    if not initial_status.running or initial_status.pid is None:
+        clear_stop_file(process_name)
+        return StopProcessResult(
+            process_name=process_name,
+            was_running=False,
+            status=initial_status,
+            stale_cleaned=initial_status.stale_cleaned,
+        )
+
+    _signal_running_process(process_name, initial_status.pid)
+    status = get_process_status(process_name)
+    return StopProcessResult(
+        process_name=process_name,
+        was_running=True,
+        status=status,
+        stale_cleaned=initial_status.stale_cleaned or status.stale_cleaned,
+    )
 
 
 @contextmanager
@@ -329,14 +382,15 @@ def pid_file_context(process_name: str) -> Generator[Path, None, None]:
     """
     lock_fd = _acquire_process_lock(process_name)
     if _supports_process_locks() and lock_fd is None:
-        existing_pid = _get_running_pid(process_name)
-        print(f"Process {process_name} is already running (PID: {existing_pid})")
+        existing_status = get_process_status(process_name)
+        print(f"Process {process_name} is already running (PID: {existing_status.pid})")
         sys.exit(1)
 
-    if not _supports_process_locks() and is_process_running(process_name):
-        existing_pid = _get_running_pid(process_name)
-        print(f"Process {process_name} is already running (PID: {existing_pid})")
-        sys.exit(1)
+    if not _supports_process_locks():
+        existing_status = get_process_status(process_name)
+        if existing_status.running:
+            print(f"Process {process_name} is already running (PID: {existing_status.pid})")
+            sys.exit(1)
 
     if _supports_process_locks():
         pid_info = _read_pid_info(process_name)

{agent_cli-0.95.0 → agent_cli-0.95.2}/agent_cli/core/utils.py

@@ -326,6 +326,94 @@ def signal_handling_context(
             signal.signal(signum, previous)
 
 
+def _process_status_payload(
+    *,
+    action: str,
+    process_name: str,
+    process_status: process.ProcessStatus,
+    was_running: bool | None = None,
+    stale_cleaned: bool | None = None,
+) -> dict[str, object]:
+    """Build machine-readable process control output."""
+    payload: dict[str, object] = {
+        "action": action,
+        "process": process_name,
+        "running": process_status.running,
+        "status": "running" if process_status.running else "stopped",
+        "pid": process_status.pid,
+        "stale_cleaned": (process_status.stale_cleaned if stale_cleaned is None else stale_cleaned),
+    }
+    if was_running is not None:
+        payload["was_running"] = was_running
+    return payload
+
+
+def _handle_process_stop(
+    process_name: str,
+    which: str,
+    *,
+    quiet: bool,
+    json_output: bool,
+    wait_for_start_seconds: float,
+) -> bool:
+    """Handle a process stop request."""
+    result = process.stop_process(
+        process_name,
+        wait_for_start_seconds=wait_for_start_seconds,
+    )
+    if json_output:
+        print(
+            json.dumps(
+                _process_status_payload(
+                    action="stop",
+                    process_name=process_name,
+                    process_status=result.status,
+                    was_running=result.was_running,
+                    stale_cleaned=result.stale_cleaned,
+                ),
+            ),
+        )
+        return True
+
+    stopped = result.was_running or result.stale_cleaned
+
+    if stopped:
+        if not quiet:
+            print_with_style(f"✅ {which.capitalize()} stopped.")
+    elif not quiet:
+        print_with_style(f"⚠️  No {which} is running.", style="yellow")
+    return True
+
+
+def _handle_process_status(
+    process_name: str,
+    which: str,
+    *,
+    quiet: bool,
+    json_output: bool,
+) -> bool:
+    """Handle a process status request."""
+    process_status = process.get_process_status(process_name)
+    if json_output:
+        print(
+            json.dumps(
+                _process_status_payload(
+                    action="status",
+                    process_name=process_name,
+                    process_status=process_status,
+                ),
+            ),
+        )
+        return True
+
+    if process_status.running:
+        if not quiet:
+            print_with_style(f"✅ {which.capitalize()} is running (PID: {process_status.pid}).")
+    elif not quiet:
+        print_with_style(f"⚠️ {which.capitalize()} is not running.", style="yellow")
+    return True
+
+
 def stop_or_status_or_toggle(
     process_name: str,
     which: str,
@@ -334,28 +422,32 @@ def stop_or_status_or_toggle(
     toggle: bool,
     *,
     quiet: bool = False,
+    json_output: bool = False,
+    wait_for_start_seconds: float = 0.0,
 ) -> bool:
     """Handle process control for a given process name."""
     if stop:
-        if process.kill_process(process_name):
-            if not quiet:
-                print_with_style(f"✅ {which.capitalize()} stopped.")
-        elif not quiet:
-            print_with_style(f"⚠️  No {which} is running.", style="yellow")
-        return True
+        return _handle_process_stop(
+            process_name,
+            which,
+            quiet=quiet,
+            json_output=json_output,
+            wait_for_start_seconds=wait_for_start_seconds,
+        )
 
     if status:
-        if process.is_process_running(process_name):
-            pid = process.read_pid_file(process_name)
-            if not quiet:
-                print_with_style(f"✅ {which.capitalize()} is running (PID: {pid}).")
-        elif not quiet:
-            print_with_style(f"⚠️ {which.capitalize()} is not running.", style="yellow")
-        return True
+        return _handle_process_status(
+            process_name,
+            which,
+            quiet=quiet,
+            json_output=json_output,
+        )
 
     if toggle:
-        if process.is_process_running(process_name):
-            if process.kill_process(process_name) and not quiet:
+        process_status = process.get_process_status(process_name)
+        if process_status.running:
+            result = process.stop_process(process_name)
+            if (result.was_running or result.stale_cleaned) and not quiet:
                 print_with_style(f"✅ {which.capitalize()} stopped.")
             return True
         if not quiet:

{agent_cli-0.95.0 → agent_cli-0.95.2}/agent_cli/opts.py

@@ -326,6 +326,12 @@ TTS_GEMINI_VOICE: str = typer.Option(
 
 
 # --- Process Management Options ---
+START: bool = typer.Option(
+    False,  # noqa: FBT003
+    "--start",
+    help="Start this command if it is not already running.",
+    rich_help_panel="Process Management",
+)
 STOP: bool = typer.Option(
     False,  # noqa: FBT003
     "--stop",
@@ -344,6 +350,12 @@ TOGGLE: bool = typer.Option(
     help="Start if not running, stop if running. Ideal for hotkey binding.",
     rich_help_panel="Process Management",
 )
+WAIT_FOR_START: bool = typer.Option(
+    False,  # noqa: FBT003
+    "--wait-for-start",
+    help="When stopping, wait briefly for a just-launched process to write its PID.",
+    rich_help_panel="Process Management",
+)
 
 # --- General Options ---
 

{agent_cli-0.95.0 → agent_cli-0.95.2}/docs/commands/transcribe.md

@@ -168,9 +168,11 @@ The `--from-file` option supports multiple audio formats:
 
 | Option | Default | Description |
 |--------|---------|-------------|
+| `--start` | `false` | Start this command if it is not already running. |
 | `--stop` | `false` | Stop any running instance of this command. |
 | `--status` | `false` | Check if an instance is currently running. |
 | `--toggle` | `false` | Start if not running, stop if running. Ideal for hotkey binding. |
+| `--wait-for-start` | `false` | When stopping, wait briefly for a just-launched process to write its PID. |
 
 ### General Options
 

{agent_cli-0.95.0 → agent_cli-0.95.2}/macos/AgentCLI/Package.swift

@@ -21,5 +21,10 @@ let package = Package(
             ],
             path: "Sources/AgentCLI"
         ),
+        .testTarget(
+            name: "AgentCLITests",
+            dependencies: ["AgentCLI"],
+            path: "Tests/AgentCLITests"
+        ),
     ]
 )