liteharness 0.1.0__tar.gz

liteharness-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryan Devlin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

liteharness-0.1.0/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: liteharness
+Version: 0.1.0
+Summary: Portable cross-CLI agent orchestration. Hook-polled inbox, conversation discovery, task tracking.
+Author-email: Ryan Devlin <ryan@litesuite.dev>
+Maintainer-email: Ryan Devlin <ryan@litesuite.dev>
+License: MIT
+Project-URL: Homepage, https://litesuite.dev/liteharness
+Project-URL: Documentation, https://litesuite.dev/liteharness
+Project-URL: Repository, https://github.com/ahostbr/liteharness
+Project-URL: Issues, https://github.com/ahostbr/liteharness/issues
+Project-URL: Changelog, https://github.com/ahostbr/liteharness/blob/main/CHANGELOG.md
+Keywords: ai,agents,orchestration,claude,gemini,codex,mcp,multi-agent,cli,pty
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Distributed Computing
+Classifier: Topic :: Terminals
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: psutil>=5.9
+Provides-Extra: embed
+Requires-Dist: onnxruntime>=1.18.0; extra == "embed"
+Requires-Dist: numpy>=1.26.0; extra == "embed"
+Requires-Dist: huggingface_hub>=0.23.0; extra == "embed"
+Requires-Dist: tokenizers>=0.19.0; extra == "embed"
+Dynamic: license-file
+
+# LiteHarness
+
+Portable cross-CLI agent orchestration for Claude Code, Codex, Copilot, and any CLI agent. Spawn, name, message, and programmatically control agent sessions from pure Python.
+
+## Install
+
+```bash
+pip install -e packages/liteharness
+```
+
+## Quick Start
+
+```bash
+# Initialize (creates dirs, detects CLIs, installs hooks)
+liteharness init
+
+# Discover active agents
+liteharness discover
+
+# Send a message
+liteharness send <agent-id> "fix the auth bug" --from <your-id>
+
+# Spawn a new Claude session (visible terminal tab)
+liteharness spawn --model opus --name "Recon" --prompt "review the PR"
+
+# Spawn headless with full stdin/stdout control
+liteharness pty-daemon
+liteharness spawn --pty --model haiku --name "Worker"
+liteharness send-input <agent-id> "/compact"
+liteharness read-output <agent-id>
+```
+
+## Features
+
+### Agent Spawning
+
+Three modes for spawning Claude Code sessions:
+
+| Mode     | Flag         | Visible | Stdin Control | Use Case                   |
+| -------- | ------------ | ------- | ------------- | -------------------------- |
+| Terminal | (default)    | Yes     | No            | Agents you want to watch   |
+| PTY      | `--pty`      | No      | Full          | Automation, Karpathy loops |
+| Headed   | UIAutomation | Yes     | Full          | Best of both worlds        |
+
+### ConPTY Daemon
+
+Headless agent control via Windows ConPTY (pywinpty). Token-authenticated TCP daemon on port 7450.
+
+```bash
+liteharness pty-daemon              # Start daemon
+liteharness spawn --pty --model opus --name "Worker"
+liteharness send-input <id> "/compact"   # Send slash commands
+liteharness send-input <id> "fix it"     # Send prompts
+liteharness read-output <id>             # Read terminal output
+liteharness pty-list                     # List sessions
+liteharness pty-kill <id>                # Kill session
+```
+
+**Security:** Bearer token auth, executable whitelist (claude/codex/python only), shell metachar block, agent ID validation, max 20 sessions, input length caps.
+
+### UIAutomation (Headed Mode)
+
+Read and write to visible Windows Terminal panes via PowerShell UIAutomation. Uses clipboard paste for atomic input (no race conditions).
+
+```bash
+liteharness wt-list-panes                        # Find windows/panes
+liteharness send-input --headed <handle:pane> "text"  # Paste into terminal
+liteharness read-output --headed <handle:pane>        # Read terminal buffer
+```
+
+```python
+from liteharness.terminal_automation import list_panes, read_buffer, send_input
+
+panes = list_panes()
+output = read_buffer(window_handle, pane_id)
+send_input(window_handle, pane_id, "/compact")  # auto-appends Enter
+```
+
+### Agent Naming
+
+Every agent gets a deterministic two-word name derived from its UUID (e.g., SwiftRelay, IronWatch). Same UUID always produces the same name. Override with `--name`.
+
+```bash
+liteharness discover
+# [active] Sentinel (fa88c542) claude-code/opus — 0s ago
+# [active] PrimeFlint (b2db8be8) claude-code/opus — 7m ago
+```
+
+### Inter-Agent Messaging
+
+Maildir-style inbox with hook-polled delivery. Agents discover each other automatically via presence files.
+
+```bash
+liteharness send <agent-id> "message" --from <your-id>
+liteharness list                    # List inbox
+liteharness discover                # Find active agents
+```
+
+### Hook Integration
+
+Auto-installs hooks for supported CLIs:
+
+- **Claude Code** — SessionStart registration, PostToolUse inbox polling
+- **Codex CLI** — `codex_hooks.json` routes through Codex JSON adapters for SessionStart, PostToolUse, and UserPromptSubmit
+- **Copilot CLI** — Project-level .github/hooks/
+- **OpenCode / KiloCode** — Plugin-based hooks
+
+## Commands
+
+| Command                    | Description                                                |
+| -------------------------- | ---------------------------------------------------------- |
+| `init`                     | Initialize LiteHarness, detect CLIs, install hooks         |
+| `status`                   | Show root, agent ID, inbox counts, active agents           |
+| `send <to> <msg>`          | Send a message to another agent                            |
+| `list`                     | List inbox messages                                        |
+| `discover [N]`             | Discover N most recent active agents                       |
+| `spawn [opts]`             | Spawn a new Claude Code session                            |
+| `sessions <cmd>`           | Save/restore Claude, Codex, and Copilot terminal sessions  |
+| `register`                 | Update agent presence (--agent-id, --cli, --model, --name) |
+| `pty-daemon`               | Start the ConPTY daemon                                    |
+| `send-input <id> <text>`   | Send text to a PTY or headed terminal                      |
+| `read-output <id>`         | Read output from a PTY or headed terminal                  |
+| `pty-list`                 | List active PTY sessions                                   |
+| `pty-kill <id>`            | Kill a PTY session                                         |
+| `wt-list-panes`            | List Windows Terminal windows/panes                        |
+| `wt-focus <handle> <pane>` | Focus a specific WT pane                                   |
+| `query-patterns`           | Query task patterns (BM25)                                 |
+| `embed-query`              | Hybrid RAG pattern query                                   |
+| `record-pattern`           | Record a task outcome pattern                              |
+
+### Terminal Session Restore
+
+Save and restore visible terminal agents:
+
+```bash
+liteharness sessions save morning-layout
+liteharness sessions restore morning-layout
+liteharness sessions restore morning-layout --layout tabs --dry-run
+liteharness sessions status
+liteharness sessions list
+```
+
+Restore defaults to `windows`, which opens one top-level Windows Terminal window per restored agent. Use `--layout tabs` for legacy grouped tabs or `--layout panes` for one window with split panes. Snapshots and config live under `~/.liteharness/sessions/`.
+
+## Architecture
+
+```
+~/.liteharness/
+  agents/          # Presence files (heartbeat, model, CLI)
+  names/           # Name overrides (plain text, immune to clobbering)
+  inbox/
+    new/           # Unread messages
+    cur/           # In-progress messages
+    done/          # Completed messages
+    tmp/           # Atomic write staging
+  tasks/           # Task store
+  patterns/        # Pattern learning
+  pty_daemon.lock  # PTY daemon token + port
+  config.json      # Global config
+```
+
+## Requirements
+
+- Python 3.10+
+- Windows 10+ (for ConPTY and UIAutomation features)
+- `pywinpty` (included on Windows Python installations)
+- Claude Code CLI (for spawning agents)
+
+## License
+
+MIT

liteharness-0.1.0/README.md

@@ -0,0 +1,171 @@
+# LiteHarness
+
+Portable cross-CLI agent orchestration for Claude Code, Codex, Copilot, and any CLI agent. Spawn, name, message, and programmatically control agent sessions from pure Python.
+
+## Install
+
+```bash
+pip install -e packages/liteharness
+```
+
+## Quick Start
+
+```bash
+# Initialize (creates dirs, detects CLIs, installs hooks)
+liteharness init
+
+# Discover active agents
+liteharness discover
+
+# Send a message
+liteharness send <agent-id> "fix the auth bug" --from <your-id>
+
+# Spawn a new Claude session (visible terminal tab)
+liteharness spawn --model opus --name "Recon" --prompt "review the PR"
+
+# Spawn headless with full stdin/stdout control
+liteharness pty-daemon
+liteharness spawn --pty --model haiku --name "Worker"
+liteharness send-input <agent-id> "/compact"
+liteharness read-output <agent-id>
+```
+
+## Features
+
+### Agent Spawning
+
+Three modes for spawning Claude Code sessions:
+
+| Mode     | Flag         | Visible | Stdin Control | Use Case                   |
+| -------- | ------------ | ------- | ------------- | -------------------------- |
+| Terminal | (default)    | Yes     | No            | Agents you want to watch   |
+| PTY      | `--pty`      | No      | Full          | Automation, Karpathy loops |
+| Headed   | UIAutomation | Yes     | Full          | Best of both worlds        |
+
+### ConPTY Daemon
+
+Headless agent control via Windows ConPTY (pywinpty). Token-authenticated TCP daemon on port 7450.
+
+```bash
+liteharness pty-daemon              # Start daemon
+liteharness spawn --pty --model opus --name "Worker"
+liteharness send-input <id> "/compact"   # Send slash commands
+liteharness send-input <id> "fix it"     # Send prompts
+liteharness read-output <id>             # Read terminal output
+liteharness pty-list                     # List sessions
+liteharness pty-kill <id>                # Kill session
+```
+
+**Security:** Bearer token auth, executable whitelist (claude/codex/python only), shell metachar block, agent ID validation, max 20 sessions, input length caps.
+
+### UIAutomation (Headed Mode)
+
+Read and write to visible Windows Terminal panes via PowerShell UIAutomation. Uses clipboard paste for atomic input (no race conditions).
+
+```bash
+liteharness wt-list-panes                        # Find windows/panes
+liteharness send-input --headed <handle:pane> "text"  # Paste into terminal
+liteharness read-output --headed <handle:pane>        # Read terminal buffer
+```
+
+```python
+from liteharness.terminal_automation import list_panes, read_buffer, send_input
+
+panes = list_panes()
+output = read_buffer(window_handle, pane_id)
+send_input(window_handle, pane_id, "/compact")  # auto-appends Enter
+```
+
+### Agent Naming
+
+Every agent gets a deterministic two-word name derived from its UUID (e.g., SwiftRelay, IronWatch). Same UUID always produces the same name. Override with `--name`.
+
+```bash
+liteharness discover
+# [active] Sentinel (fa88c542) claude-code/opus — 0s ago
+# [active] PrimeFlint (b2db8be8) claude-code/opus — 7m ago
+```
+
+### Inter-Agent Messaging
+
+Maildir-style inbox with hook-polled delivery. Agents discover each other automatically via presence files.
+
+```bash
+liteharness send <agent-id> "message" --from <your-id>
+liteharness list                    # List inbox
+liteharness discover                # Find active agents
+```
+
+### Hook Integration
+
+Auto-installs hooks for supported CLIs:
+
+- **Claude Code** — SessionStart registration, PostToolUse inbox polling
+- **Codex CLI** — `codex_hooks.json` routes through Codex JSON adapters for SessionStart, PostToolUse, and UserPromptSubmit
+- **Copilot CLI** — Project-level .github/hooks/
+- **OpenCode / KiloCode** — Plugin-based hooks
+
+## Commands
+
+| Command                    | Description                                                |
+| -------------------------- | ---------------------------------------------------------- |
+| `init`                     | Initialize LiteHarness, detect CLIs, install hooks         |
+| `status`                   | Show root, agent ID, inbox counts, active agents           |
+| `send <to> <msg>`          | Send a message to another agent                            |
+| `list`                     | List inbox messages                                        |
+| `discover [N]`             | Discover N most recent active agents                       |
+| `spawn [opts]`             | Spawn a new Claude Code session                            |
+| `sessions <cmd>`           | Save/restore Claude, Codex, and Copilot terminal sessions  |
+| `register`                 | Update agent presence (--agent-id, --cli, --model, --name) |
+| `pty-daemon`               | Start the ConPTY daemon                                    |
+| `send-input <id> <text>`   | Send text to a PTY or headed terminal                      |
+| `read-output <id>`         | Read output from a PTY or headed terminal                  |
+| `pty-list`                 | List active PTY sessions                                   |
+| `pty-kill <id>`            | Kill a PTY session                                         |
+| `wt-list-panes`            | List Windows Terminal windows/panes                        |
+| `wt-focus <handle> <pane>` | Focus a specific WT pane                                   |
+| `query-patterns`           | Query task patterns (BM25)                                 |
+| `embed-query`              | Hybrid RAG pattern query                                   |
+| `record-pattern`           | Record a task outcome pattern                              |
+
+### Terminal Session Restore
+
+Save and restore visible terminal agents:
+
+```bash
+liteharness sessions save morning-layout
+liteharness sessions restore morning-layout
+liteharness sessions restore morning-layout --layout tabs --dry-run
+liteharness sessions status
+liteharness sessions list
+```
+
+Restore defaults to `windows`, which opens one top-level Windows Terminal window per restored agent. Use `--layout tabs` for legacy grouped tabs or `--layout panes` for one window with split panes. Snapshots and config live under `~/.liteharness/sessions/`.
+
+## Architecture
+
+```
+~/.liteharness/
+  agents/          # Presence files (heartbeat, model, CLI)
+  names/           # Name overrides (plain text, immune to clobbering)
+  inbox/
+    new/           # Unread messages
+    cur/           # In-progress messages
+    done/          # Completed messages
+    tmp/           # Atomic write staging
+  tasks/           # Task store
+  patterns/        # Pattern learning
+  pty_daemon.lock  # PTY daemon token + port
+  config.json      # Global config
+```
+
+## Requirements
+
+- Python 3.10+
+- Windows 10+ (for ConPTY and UIAutomation features)
+- `pywinpty` (included on Windows Python installations)
+- Claude Code CLI (for spawning agents)
+
+## License
+
+MIT

liteharness-0.1.0/liteharness/__init__.py

@@ -0,0 +1,3 @@
+"""LiteHarness — Portable cross-CLI agent orchestration."""
+
+__version__ = "0.1.0"