phalanx-cli 0.2.0__tar.gz → 0.2.2__tar.gz

{phalanx_cli-0.2.0 → phalanx_cli-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phalanx-cli
-Version: 0.2.0
+Version: 0.2.2
 Summary: Open-source, vendor-agnostic multi-agent orchestration CLI
 License-Expression: MIT
 Requires-Python: >=3.11

{phalanx_cli-0.2.0 → phalanx_cli-0.2.2}/README.md

@@ -16,12 +16,16 @@ Requires: Python 3.11+, tmux.
 
 ## Quick Start
 
+Initialize Phalanx in your workspace:
+
+```bash
+phalanx init
+```
+
 Start an agent session and talk to it:
 
 ```bash
-phalanx                          # interactive session (auto-detects backend)
-phalanx -b gemini                # use a specific backend
-phalanx run "fix the failing tests"  # with an initial prompt
+phalanx run-agent "fix the failing tests"
 ```
 
 Then just ask your agent to create teams:
@@ -79,12 +83,12 @@ phalanx models reset                       # restore defaults
 
 ## Architecture
 
-- **State**: SQLite (WAL mode) at `~/.phalanx/state.db`
-- **Process isolation**: tmux sessions per agent
-- **Artifacts**: Ephemeral JSON (deleted after 24h inactivity)
-- **File locking**: Advisory locks via SQLite
-- **Stall detection**: stream.log monitoring with exponential backoff retry
-- **GC**: Opportunistic, runs on every command
+- **State**: SQLite (WAL mode) at `.phalanx/state.db`
+- **TUI Process Isolation**: Agents run interactively inside background `tmux` sessions. Output is captured via `pipe-pane`, meaning Phalanx can screen-scrape and deterministically handle CLI prompts (like workspace trust or tool approval) without relying on fragile prompt engineering.
+- **Real-Time Communication**: Because agents are running live in `tmux`, Phalanx can send them keystrokes or interrupt them (`Ctrl+C`) to deliver messages instantly, instead of relying on slow, costly session restarts via `--resume`.
+- **Artifacts**: Ephemeral JSON storing structured outputs per agent.
+- **Stall Detection**: `stream.log` (from `tmux`) is monitored via a Heartbeat system. If an agent hangs or crashes, Phalanx detects the lack of output, interrupts, and prompts the agent to continue or fail gracefully.
+- **GC**: Opportunistic cleanup of dead teams, running on standard CLI commands.
 
 ## CLI Reference
 
@@ -92,72 +96,56 @@ phalanx models reset                       # restore defaults
 
 | Command | Description |
 |---------|-------------|
-| `phalanx` | Start interactive agent session |
-| `phalanx run "prompt"` | Single agent session with prompt |
-| `phalanx --auto-approve create-team` | Create agent team |
-| `phalanx team-status <id>` | Team status |
-| `phalanx team-result <id>` | Read team results |
-| `phalanx message <id> "msg"` | Message team lead |
-| `phalanx stop <id>` | Stop team |
-| `phalanx resume <id>` | Resume team |
-| `phalanx status` | List all teams |
-| `phalanx config show/set` | Configuration |
-| `phalanx models show/set/reset/update` | Model routing |
+| `phalanx init` | Initialize `.phalanx` in workspace, generate skill files |
+| `phalanx run-agent "task"` | Spawn a single interactive agent (no team lead) |
+| `phalanx create-team "task"` | Create a team and start its team lead |
+| `phalanx monitor <id>` | Attach a blocking DEM-style monitoring loop |
+| `phalanx team-status [id]` | View team status summary |
+| `phalanx agent-status [id]` | View specific agent status |
+| `phalanx team-result <id>` | Read team lead's final artifact |
+| `phalanx message <id> "msg"` | Message a team lead |
+| `phalanx message-agent <id> "msg"` | Message a specific agent |
+| `phalanx send-keys <id> <keys>` | Send raw keystrokes to an agent's `tmux` pane |
+| `phalanx stop <id>` | Stop a team (kills processes) |
+| `phalanx status` | List all running agents across all teams |
+| `phalanx gc` | Clean up old data and dead teams |
 
 ### Agent Tools (used by spawned agents)
 
 | Command | Description |
 |---------|-------------|
-| `phalanx write-artifact` | Write structured result |
-| `phalanx agent-status` | Check peer status |
+| `phalanx spawn-agent` | Spawn a sub-agent (used by team lead) |
+| `phalanx write-artifact` | Write structured result (success/failure/escalation) |
 | `phalanx agent-result <id>` | Read peer artifact |
-| `phalanx message <team-id> "msg"` | Message team lead |
-| `phalanx message-agent <id> "msg"` | Message a specific worker |
-| `phalanx lock/unlock <path>` | File locking |
+| `phalanx lock/unlock <path>` | Advisory file locking to prevent collisions |
 
 ## Develop Locally
 
 ```bash
 git clone https://github.com/creynir/phalanx.git
 cd phalanx
-pip install -e ".[dev]"
+uv sync
+uv pip install -e ".[dev]"
 ```
 
 Run tests:
 
 ```bash
-pytest tests/unit/          # unit tests
-pytest tests/integration/   # integration tests (requires tmux)
-pytest tests/e2e/           # end-to-end tests
-pytest tests/               # all 211 tests
-```
-
-Pre-commit hooks (ruff lint + format) are configured — install with:
-
-```bash
-pip install pre-commit
-pre-commit install
+uv run pytest tests/
 ```
 
 ## Configuration
 
-Global: `~/.phalanx/config.toml`
-Workspace override: `.phalanx/config.toml`
-
-```toml
-[defaults]
-backend = "cursor"
-
-[timeouts]
-agent_inactivity_minutes = 30
-team_gc_hours = 24
-stall_seconds = 180
+Workspace overrides can be edited at `.phalanx/config.json`:
 
-[models.cursor]
-orchestrator = "sonnet-4.6"
-coder = "sonnet-4.6"
-researcher = "gemini-3.1-pro"
-default = "gemini-3.1-pro"
+```json
+{
+  "default_backend": "cursor",
+  "idle_timeout_seconds": 1800,
+  "max_runtime_seconds": 1800,
+  "stall_check_interval": 20,
+  "auto_approve": true
+}
 ```
 
 ## License

{phalanx_cli-0.2.0 → phalanx_cli-0.2.2}/phalanx/__init__.py

@@ -1,3 +1,3 @@
 """Phalanx — Multi-Agent Orchestration System."""
 
-__version__ = "0.2.0"
+__version__ = "0.2.2"

{phalanx_cli-0.2.0 → phalanx_cli-0.2.2}/phalanx/cli.py

@@ -181,11 +181,12 @@ def run_agent(ctx, task, backend, model, auto_approve):
 
 @cli.command("create-team")
 @click.argument("task")
+@click.option("--agents", "-a", default="coder", help="Agent spec: role[:count],...")
 @click.option("--backend", "-b", default=None, help="Backend")
 @click.option("--model", "-m", default=None, help="Model")
 @click.option("--auto-approve/--no-auto-approve", default=True)
 @click.pass_context
-def create_team_cmd(ctx, task, backend, model, auto_approve):
+def create_team_cmd(ctx, task, agents, backend, model, auto_approve):
     """Create a team and start its team lead."""
     from phalanx.monitor.heartbeat import HeartbeatMonitor
     from phalanx.process.manager import ProcessManager
@@ -204,6 +205,7 @@ def create_team_cmd(ctx, task, backend, model, auto_approve):
         process_manager=pm,
         heartbeat_monitor=hb,
         task=task,
+        agents_spec=agents,
         backend_name=backend or config.default_backend,
         model=model or config.default_model,
         auto_approve=auto_approve,

{phalanx_cli-0.2.0 → phalanx_cli-0.2.2}/phalanx/team/create.py

@@ -15,12 +15,28 @@ from phalanx.team.spawn import spawn_agent
 logger = logging.getLogger(__name__)
 
 
+def parse_agents_spec(spec: str) -> list[tuple[str, int]]:
+    """Parse agent spec like 'researcher,coder:2,reviewer' into [(role, count)]."""
+    agents = []
+    if not spec:
+        return agents
+    for part in spec.split(","):
+        part = part.strip()
+        if ":" in part:
+            role, count_str = part.split(":", 1)
+            agents.append((role.strip(), int(count_str)))
+        else:
+            agents.append((part, 1))
+    return agents
+
+
 def create_team(
     phalanx_root: Path,
     db: StateDB,
     process_manager: ProcessManager,
     heartbeat_monitor: HeartbeatMonitor,
     task: str,
+    agents_spec: str = "coder",
     backend_name: str = "cursor",
     model: str | None = None,
     auto_approve: bool = True,
@@ -43,6 +59,28 @@ def create_team(
     team_dir = phalanx_root / "teams" / team_id
     team_dir.mkdir(parents=True, exist_ok=True)
 
+    # Spawn workers first
+    worker_specs = parse_agents_spec(agents_spec)
+    worker_index = 0
+    for role, count in worker_specs:
+        for _ in range(count):
+            worker_id = f"w{worker_index}-{role}"
+            spawn_agent(
+                phalanx_root=phalanx_root,
+                db=db,
+                process_manager=process_manager,
+                heartbeat_monitor=heartbeat_monitor,
+                team_id=team_id,
+                task=task,
+                role=role,
+                agent_id=worker_id,
+                backend_name=backend_name,
+                model=None,  # let router decide based on role
+                auto_approve=auto_approve,
+                config=config,
+            )
+            worker_index += 1
+
     # Spawn team lead
     spawn_agent(
         phalanx_root=phalanx_root,

{phalanx_cli-0.2.0 → phalanx_cli-0.2.2}/phalanx_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phalanx-cli
-Version: 0.2.0
+Version: 0.2.2
 Summary: Open-source, vendor-agnostic multi-agent orchestration CLI
 License-Expression: MIT
 Requires-Python: >=3.11

{phalanx_cli-0.2.0 → phalanx_cli-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "phalanx-cli"
-version = "0.2.0"
+version = "0.2.2"
 description = "Open-source, vendor-agnostic multi-agent orchestration CLI"
 requires-python = ">=3.11"
 license = "MIT"