ai-comm 0.2.4__py3-none-any.whl

ai_comm/cli.py

@@ -0,0 +1,94 @@
+"""ai-comm CLI entry point."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from ai_comm import __version__
+from ai_comm.commands import response, send, window
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"ai-comm {__version__}")
+        raise typer.Exit()
+
+
+HELP_TEXT = """\
+Cross-AI CLI communication tool for Kitty terminal.
+
+Enables AI assistants (Claude, Codex, Gemini, Aider, Cursor, OpenCode)
+running in separate Kitty windows to communicate with each other.
+
+IMPORTANT: Only use parameters documented here. Hidden/internal
+parameters exist for debugging only and must never be used.
+
+Workflow:
+  1. ai-comm list-ai-windows     Find available AI windows
+  2. ai-comm send <MESSAGE> -w <ID>  Send message and get response
+
+Protocol:
+  - Request-response only. Receiver must NOT send new messages back
+    immediately after responding—this causes deadlock.
+  - If you need the sender to act, include the request in your response.
+
+Notes:
+  - AI assistants MUST use ONLY the two Workflow commands without
+    any additional parameters. Other parameters are forbidden for AI use.
+  - For long responses, ask AI to write to a file in project directory
+    (/tmp requires manual approval on target AI — avoid).
+  - Blocking is intentional: AI cannot perceive time, only acts on user
+    input. Non-blocking = lost messages. Timed-out commands auto-move
+    to background; results return when ready.
+"""
+
+app = typer.Typer(
+    name="ai-comm",
+    help=HELP_TEXT,
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+@app.callback()
+def _app_callback(
+    version: Annotated[
+        bool,
+        typer.Option("--version", "-V", callback=_version_callback, is_eager=True),
+    ] = False,
+) -> None:
+    pass
+
+
+WORKFLOW_PANEL = "Workflow Commands (for AI agents)"
+DEBUG_CMD_PANEL = "Debug Commands (HUMAN ONLY - AI agents must not use)"
+
+# Workflow commands - for AI agents
+app.command(name="send", help=send.SEND_HELP, rich_help_panel=WORKFLOW_PANEL)(send.send)
+app.command(
+    name="list-ai-windows", help=window.LIST_HELP, rich_help_panel=WORKFLOW_PANEL
+)(window.list_ai_windows)
+
+# Debug commands - for human use only
+app.command(
+    name="get-response",
+    help=response.GET_RESPONSE_HELP,
+    rich_help_panel=DEBUG_CMD_PANEL,
+)(response.get_response)
+app.command(
+    name="wait-idle", help=response.WAIT_IDLE_HELP, rich_help_panel=DEBUG_CMD_PANEL
+)(response.wait_idle)
+app.command(
+    name="get-text", help=response.GET_TEXT_HELP, rich_help_panel=DEBUG_CMD_PANEL
+)(response.get_text)
+
+
+def main() -> None:
+    """Main entry point."""
+    app()
+
+
+if __name__ == "__main__":
+    main()

ai_comm/commands/__init__.py

@@ -0,0 +1,11 @@
+"""CLI commands for ai-comm."""
+
+from __future__ import annotations
+
+import typer
+
+
+def handle_error(error: Exception, exit_code: int = 1) -> None:
+    """Handle error with consistent formatting."""
+    typer.echo(f"Error: {error}", err=True)
+    raise typer.Exit(exit_code) from None

ai_comm/commands/response.py

@@ -0,0 +1,122 @@
+"""Response and idle waiting commands."""
+
+from __future__ import annotations
+
+import json
+from typing import Annotated
+
+import typer
+
+from ai_comm.commands import handle_error
+from ai_comm.kitten_client import KittenClient, KittenError
+from ai_comm.polling import PollingTimeoutError
+from ai_comm.services import InteractionService
+
+
+def wait_idle(
+    window: Annotated[int, typer.Option("--window", "-w", help="Target window ID")],
+    timeout: Annotated[
+        int, typer.Option("--timeout", "-t", help="Timeout in seconds")
+    ] = 1800,
+    idle_time: Annotated[
+        int, typer.Option("--idle-time", help="Idle time in seconds")
+    ] = 3,
+) -> None:
+    """Wait for window content to stabilize."""
+    try:
+        client = KittenClient()
+        service = InteractionService(client)
+
+        elapsed = service.wait_for_response(window, idle_time, float(timeout))
+        typer.echo(f"Window {window} idle after {elapsed:.1f}s")
+
+    except PollingTimeoutError as e:
+        typer.echo(f"Timeout: {e}", err=True)
+        raise typer.Exit(1) from None
+    except KittenError as e:
+        handle_error(e)
+
+
+def get_text(
+    window: Annotated[int, typer.Option("--window", "-w", help="Target window ID")],
+    extent: Annotated[str, typer.Option("--extent", help="screen or all")] = "all",
+    as_json: Annotated[bool, typer.Option("--json", help="Output as JSON")] = False,
+) -> None:
+    """Get raw text content from window."""
+    try:
+        client = KittenClient()
+        text = client.get_text(window, extent)
+    except KittenError as e:
+        handle_error(e)
+        return
+
+    if as_json:
+        typer.echo(json.dumps({"text": text}))
+    else:
+        typer.echo(text)
+
+
+HUMAN_ONLY_WARNING = """\
+Debug command for human troubleshooting.
+AI agents: run 'ai-comm --help' for usage instructions.
+
+"""
+
+WAIT_IDLE_HELP = (
+    HUMAN_ONLY_WARNING
+    + """\
+Wait for window content to stabilize.
+"""
+)
+
+GET_TEXT_HELP = (
+    HUMAN_ONLY_WARNING
+    + """\
+Get raw text content from window.
+"""
+)
+
+GET_RESPONSE_HELP = (
+    HUMAN_ONLY_WARNING
+    + """\
+Get parsed response from an AI window.
+
+Examples:
+  ai-comm get-response -w 5
+  ai-comm get-response -w 8 --json
+"""
+)
+
+
+def get_response(
+    window: Annotated[
+        int,
+        typer.Option("--window", "-w", help="Target window ID (from list-ai-windows)"),
+    ],
+    parser: Annotated[
+        str,
+        typer.Option("--parser", "-p", help="Response parser (auto-detected)"),
+    ] = "auto",
+    extent: Annotated[str, typer.Option("--extent", help="screen or all")] = "all",
+    as_json: Annotated[bool, typer.Option("--json", help="Output as JSON")] = False,
+) -> None:
+    """Get parsed response from window."""
+    try:
+        client = KittenClient()
+        service = InteractionService(client)
+
+        response, effective_parser = service.get_response(
+            window, parser=parser, extent=extent
+        )
+
+        if not response:
+            typer.echo("No content", err=True)
+            raise typer.Exit(1)
+
+        if as_json:
+            typer.echo(json.dumps({"response": response, "parser": effective_parser}))
+        else:
+            typer.echo(response)
+
+    except KittenError as e:
+        handle_error(e)

ai_comm/commands/send.py

@@ -0,0 +1,120 @@
+"""Send message commands."""
+
+from __future__ import annotations
+
+import json
+from typing import Annotated
+
+import typer
+
+from ai_comm.commands import handle_error
+from ai_comm.kitten_client import KittenClient, KittenError
+from ai_comm.polling import PollingTimeoutError
+from ai_comm.services import InteractionService
+
+SEND_HELP = """\
+Send message to AI window and wait for response.
+
+The message is automatically wrapped with sender metadata. For Aider, /ask is
+prepended to prevent automatic file edits.
+
+Notes:
+  - For long responses, ask AI to write to a file in the project directory
+    (/tmp and other external paths require manual approval on target AI — avoid).
+  - Timed-out commands auto-move to background.
+
+Examples:
+  ai-comm send "review this function" -w 5
+  ai-comm send "write to out_$(date +%Y%m%d_%H%M%S).md" -w 8
+"""
+
+
+DEBUG_PANEL = "Debug Options (HUMAN ONLY - AI agents must not use)"
+
+
+def send(
+    message: Annotated[str, typer.Argument(help="Message to send to the AI")],
+    window: Annotated[
+        int,
+        typer.Option("--window", "-w", help="Target window ID (from list-ai-windows)"),
+    ],
+    timeout: Annotated[
+        int,
+        typer.Option(
+            "--timeout", "-t", help="Timeout in seconds", rich_help_panel=DEBUG_PANEL
+        ),
+    ] = 1800,
+    idle_time: Annotated[
+        int,
+        typer.Option(
+            "--idle-time", help="Idle time in seconds", rich_help_panel=DEBUG_PANEL
+        ),
+    ] = 3,
+    parser: Annotated[
+        str,
+        typer.Option(
+            "--parser",
+            "-p",
+            help="Response parser (auto, claude, codex, gemini, aider...)",
+            rich_help_panel=DEBUG_PANEL,
+        ),
+    ] = "auto",
+    raw: Annotated[
+        bool,
+        typer.Option(
+            "--raw",
+            help="Return raw terminal text instead of parsed response",
+            rich_help_panel=DEBUG_PANEL,
+        ),
+    ] = False,
+    no_wait: Annotated[
+        bool,
+        typer.Option(
+            "--no-wait",
+            help="Send without waiting for response",
+            rich_help_panel=DEBUG_PANEL,
+        ),
+    ] = False,
+    as_json: Annotated[
+        bool,
+        typer.Option("--json", help="Output as JSON", rich_help_panel=DEBUG_PANEL),
+    ] = False,
+) -> None:
+    """Send message to AI window and wait for response."""
+    try:
+        client = KittenClient()
+        service = InteractionService(client)
+
+        service.send_message(window, message)
+
+        if no_wait:
+            if as_json:
+                typer.echo(json.dumps({"status": "sent", "window": window}))
+            else:
+                typer.echo(f"Message sent to window {window}")
+            return
+
+        elapsed = service.wait_for_response(window, idle_time, float(timeout))
+
+        response, effective_parser = service.get_response(
+            window, parser=parser, raw=raw
+        )
+
+        if as_json:
+            typer.echo(
+                json.dumps(
+                    {
+                        "response": response,
+                        "elapsed": elapsed,
+                        "parser": effective_parser if not raw else None,
+                    }
+                )
+            )
+        else:
+            typer.echo(response)
+
+    except PollingTimeoutError as e:
+        typer.echo(f"Timeout: {e}", err=True)
+        raise typer.Exit(1) from None
+    except KittenError as e:
+        handle_error(e)

ai_comm/commands/window.py

@@ -0,0 +1,42 @@
+"""Window listing commands."""
+
+from __future__ import annotations
+
+import json
+from typing import Annotated
+
+import typer
+
+from ai_comm.kitten_client import KittenClient, KittenError
+
+LIST_HELP = """\
+List Kitty windows running AI CLIs.
+
+Output columns: ID (window ID for -w option), CLI (detected AI type), CWD.
+
+Examples:
+  ai-comm list-ai-windows
+  ai-comm list-ai-windows --json
+"""
+
+
+def list_ai_windows(
+    as_json: Annotated[bool, typer.Option("--json", help="Output as JSON")] = False,
+) -> None:
+    """List windows running AI CLIs."""
+    try:
+        client = KittenClient()
+        ai_windows = client.list_ai_windows()
+    except KittenError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1) from None
+
+    if as_json:
+        typer.echo(json.dumps(ai_windows, indent=2))
+    else:
+        if not ai_windows:
+            typer.echo("No AI CLI windows found")
+            return
+        typer.echo(f"{'ID':>4}  {'CLI':10s}  CWD")
+        for w in ai_windows:
+            typer.echo(f"{w['id']:4d}  {w['cli']:10s}  {w.get('cwd', '')}")

ai_comm/kitten/ai_comm_kitten.py

@@ -0,0 +1,254 @@
+#!/usr/bin/env python3
+"""
+Simplified ai-comm kitten providing atomic operations via Boss API.
+
+This kitten is called by the ai-comm CLI tool. It provides low-level
+operations that require access to kitty's Boss API.
+
+Commands:
+    get-text --window ID [--extent screen|all]
+    send-text --window ID TEXT
+    send-key --window ID KEY
+    check-idle --window ID --last-hash HASH
+    list-ai-windows
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import subprocess
+from pathlib import PurePath
+from typing import TYPE_CHECKING, Any
+
+from kittens.tui.handler import result_handler  # type: ignore[import-not-found]
+
+if TYPE_CHECKING:
+    from kitty.boss import Boss  # type: ignore[import-not-found]
+    from kitty.window import Window  # type: ignore[import-not-found]
+
+# Known AI CLI names and their canonical form
+AI_CLI_NAMES: dict[str, str] = {
+    "claude": "claude",
+    "codex": "codex",
+    "gemini": "gemini",
+    "aider": "aider",
+    "cursor": "cursor",
+    "cursor-cli": "cursor",
+    "cursor-agent": "cursor",
+    "opencode": "opencode",
+}
+
+# Keywords that indicate non-CLI processes (status lines, themes, etc.)
+EXCLUDE_KEYWORDS: list[str] = ["powerline", "statusline", "prompt", "theme"]
+
+
+def parse_args(args: list[str]) -> argparse.Namespace:
+    """Parse command line arguments."""
+    parser = argparse.ArgumentParser(prog="ai_comm_kitten")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # get-text
+    get_text = subparsers.add_parser("get-text")
+    get_text.add_argument("--window", "-w", type=int, required=True)
+    get_text.add_argument("--extent", default="all", choices=["screen", "all"])
+
+    # send-text
+    send_text = subparsers.add_parser("send-text")
+    send_text.add_argument("--window", "-w", type=int, required=True)
+    send_text.add_argument("text", nargs="+")
+
+    # send-key
+    send_key = subparsers.add_parser("send-key")
+    send_key.add_argument("--window", "-w", type=int, required=True)
+    send_key.add_argument("key")
+
+    # check-idle
+    check_idle = subparsers.add_parser("check-idle")
+    check_idle.add_argument("--window", "-w", type=int, required=True)
+    check_idle.add_argument("--last-hash", default="")
+
+    # list-ai-windows
+    subparsers.add_parser("list-ai-windows")
+
+    return parser.parse_args(args)
+
+
+def compute_hash(text: str) -> str:
+    """Compute short hash of text content."""
+    return hashlib.md5(text.encode()).hexdigest()[:16]
+
+
+def get_window(boss: Boss, window_id: int) -> Window | None:
+    """Get window by ID."""
+    return boss.window_id_map.get(window_id)
+
+
+def get_text(boss: Boss, window_id: int, extent: str) -> dict[str, Any]:
+    """Get text content from window."""
+    window = get_window(boss, window_id)
+    if window is None:
+        return {"status": "error", "message": f"Window {window_id} not found"}
+
+    result = boss.call_remote_control(
+        window, ("get-text", "-m", f"id:{window_id}", "--extent", extent)
+    )
+    text = result if isinstance(result, str) else ""
+    return {"status": "ok", "text": text, "hash": compute_hash(text)}
+
+
+def send_text(boss: Boss, window_id: int, text: str) -> dict[str, Any]:
+    """Send text to window using multiple methods."""
+    window = get_window(boss, window_id)
+    if window is None:
+        return {"status": "error", "message": f"Window {window_id} not found"}
+
+    # Try paste_text first (fastest)
+    paste = getattr(window, "paste_text", None)
+    if callable(paste):
+        paste(text)
+        return {"status": "ok", "method": "paste"}
+
+    # Try write_to_child
+    writer = getattr(window, "write_to_child", None)
+    if callable(writer):
+        try:
+            writer(text.encode())
+        except TypeError:
+            writer(text)
+        return {"status": "ok", "method": "write_to_child"}
+
+    # Fallback to subprocess
+    socket = getattr(boss, "listening_on", "") or ""
+    cmd = ["kitty", "@"]
+    if socket:
+        cmd.extend(["--to", socket])
+    cmd.extend(["send-text", "-m", f"id:{window_id}", "--", text])
+    subprocess.run(cmd, check=False, capture_output=True)
+    return {"status": "ok", "method": "subprocess"}
+
+
+def send_key(boss: Boss, window_id: int, key: str) -> dict[str, Any]:
+    """Send key press to window."""
+    window = get_window(boss, window_id)
+    if window is None:
+        return {"status": "error", "message": f"Window {window_id} not found"}
+
+    socket = getattr(boss, "listening_on", "") or ""
+    cmd = ["kitty", "@"]
+    if socket:
+        cmd.extend(["--to", socket])
+    cmd.extend(["send-key", "-m", f"id:{window_id}", key])
+    subprocess.run(cmd, check=False, capture_output=True)
+    return {"status": "ok"}
+
+
+def check_idle(boss: Boss, window_id: int, last_hash: str) -> dict[str, Any]:
+    """Check if window content has changed."""
+    result = get_text(boss, window_id, "all")
+    if result["status"] != "ok":
+        return result
+
+    current_hash = result["hash"]
+    is_idle = current_hash == last_hash if last_hash else False
+    return {"status": "ok", "idle": is_idle, "hash": current_hash}
+
+
+def detect_ai_cli(cmdline_args: list[str]) -> str | None:
+    """Detect AI CLI from cmdline arguments (for parser selection only)."""
+    # Check exclusions first
+    for arg in cmdline_args:
+        arg_lower = arg.lower()
+        for exclude in EXCLUDE_KEYWORDS:
+            if exclude in arg_lower:
+                return None
+
+    for arg in cmdline_args:
+        # Check basename (without extension)
+        path = PurePath(arg)
+        name = path.stem.lower()
+        if name in AI_CLI_NAMES:
+            return AI_CLI_NAMES[name]
+
+        # Check path components (for wrappers like /path/to/cursor-cli/index.js)
+        for part in path.parts:
+            part_name = PurePath(part).stem.lower()
+            if part_name in AI_CLI_NAMES:
+                return AI_CLI_NAMES[part_name]
+
+    return None
+
+
+def list_ai_windows(boss: Boss) -> dict[str, Any]:
+    """List windows running AI CLIs."""
+    ai_windows: list[dict[str, Any]] = []
+
+    for os_window in boss.os_window_map.values():
+        for tab in os_window.tabs:
+            for window in tab.windows:
+                child = getattr(window, "child", None)
+                if not child:
+                    continue
+
+                fg_processes = getattr(child, "foreground_processes", None)
+                if callable(fg_processes):
+                    fg_processes = fg_processes()
+                if not fg_processes:
+                    continue
+
+                detected_cli: str | None = None
+                detected_cwd: str = ""
+                for proc in fg_processes:
+                    cmdline = proc.get("cmdline", [])
+                    cli = detect_ai_cli(cmdline)
+                    if cli:
+                        detected_cli = cli
+                        detected_cwd = proc.get("cwd", "")
+                        break
+
+                if detected_cli:
+                    ai_windows.append(
+                        {"id": window.id, "cli": detected_cli, "cwd": detected_cwd}
+                    )
+
+    return {"status": "ok", "ai_windows": ai_windows}
+
+
+def main(args: list[str]) -> str:
+    """Main entry point - not used for no_ui kitten."""
+    return ""
+
+
+@result_handler(no_ui=True)
+def handle_result(
+    args: list[str], answer: str, target_window_id: int, boss: Boss
+) -> str:
+    """Handle kitten result, runs in kitty process."""
+    try:
+        parsed = parse_args(args[1:])
+    except SystemExit:
+        return json.dumps({"status": "error", "message": "Invalid arguments"})
+
+    result: dict[str, Any]
+
+    if parsed.command == "get-text":
+        result = get_text(boss, parsed.window, parsed.extent)
+
+    elif parsed.command == "send-text":
+        text = " ".join(parsed.text)
+        result = send_text(boss, parsed.window, text)
+
+    elif parsed.command == "send-key":
+        result = send_key(boss, parsed.window, parsed.key)
+
+    elif parsed.command == "check-idle":
+        result = check_idle(boss, parsed.window, parsed.last_hash)
+
+    elif parsed.command == "list-ai-windows":
+        result = list_ai_windows(boss)
+
+    else:
+        result = {"status": "error", "message": f"Unknown command: {parsed.command}"}
+
+    return json.dumps(result, ensure_ascii=False)