flowly-code 1.0.0__py3-none-any.whl

flowly_code/heartbeat/service.py

@@ -0,0 +1,130 @@
+"""Heartbeat service - periodic agent wake-up to check for tasks."""
+
+import asyncio
+from pathlib import Path
+from typing import Any, Callable, Coroutine
+
+from loguru import logger
+
+# Default interval: 30 minutes
+DEFAULT_HEARTBEAT_INTERVAL_S = 30 * 60
+
+# The prompt sent to agent during heartbeat
+HEARTBEAT_PROMPT = """Read HEARTBEAT.md in your workspace (if it exists).
+Follow any instructions or tasks listed there.
+If nothing needs attention, reply with just: HEARTBEAT_OK"""
+
+# Token that indicates "nothing to do"
+HEARTBEAT_OK_TOKEN = "HEARTBEAT_OK"
+
+
+def _is_heartbeat_empty(content: str | None) -> bool:
+    """Check if HEARTBEAT.md has no actionable content."""
+    if not content:
+        return True
+    
+    # Lines to skip: empty, headers, HTML comments, empty checkboxes
+    skip_patterns = {"- [ ]", "* [ ]", "- [x]", "* [x]"}
+    
+    for line in content.split("\n"):
+        line = line.strip()
+        if not line or line.startswith("#") or line.startswith("<!--") or line in skip_patterns:
+            continue
+        return False  # Found actionable content
+    
+    return True
+
+
+class HeartbeatService:
+    """
+    Periodic heartbeat service that wakes the agent to check for tasks.
+    
+    The agent reads HEARTBEAT.md from the workspace and executes any
+    tasks listed there. If nothing needs attention, it replies HEARTBEAT_OK.
+    """
+    
+    def __init__(
+        self,
+        workspace: Path,
+        on_heartbeat: Callable[[str], Coroutine[Any, Any, str]] | None = None,
+        interval_s: int = DEFAULT_HEARTBEAT_INTERVAL_S,
+        enabled: bool = True,
+    ):
+        self.workspace = workspace
+        self.on_heartbeat = on_heartbeat
+        self.interval_s = interval_s
+        self.enabled = enabled
+        self._running = False
+        self._task: asyncio.Task | None = None
+    
+    @property
+    def heartbeat_file(self) -> Path:
+        return self.workspace / "HEARTBEAT.md"
+    
+    def _read_heartbeat_file(self) -> str | None:
+        """Read HEARTBEAT.md content."""
+        if self.heartbeat_file.exists():
+            try:
+                return self.heartbeat_file.read_text()
+            except Exception:
+                return None
+        return None
+    
+    async def start(self) -> None:
+        """Start the heartbeat service."""
+        if not self.enabled:
+            logger.info("Heartbeat disabled")
+            return
+        
+        self._running = True
+        self._task = asyncio.create_task(self._run_loop())
+        logger.info(f"Heartbeat started (every {self.interval_s}s)")
+    
+    def stop(self) -> None:
+        """Stop the heartbeat service."""
+        self._running = False
+        if self._task:
+            self._task.cancel()
+            self._task = None
+    
+    async def _run_loop(self) -> None:
+        """Main heartbeat loop."""
+        while self._running:
+            try:
+                await asyncio.sleep(self.interval_s)
+                if self._running:
+                    await self._tick()
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                logger.error(f"Heartbeat error: {e}")
+    
+    async def _tick(self) -> None:
+        """Execute a single heartbeat tick."""
+        content = self._read_heartbeat_file()
+        
+        # Skip if HEARTBEAT.md is empty or doesn't exist
+        if _is_heartbeat_empty(content):
+            logger.debug("Heartbeat: no tasks (HEARTBEAT.md empty)")
+            return
+        
+        logger.info("Heartbeat: checking for tasks...")
+        
+        if self.on_heartbeat:
+            try:
+                response = await self.on_heartbeat(HEARTBEAT_PROMPT)
+                
+                # Check if agent said "nothing to do"
+                if HEARTBEAT_OK_TOKEN in response.upper().replace("_", ""):
+                    logger.info("Heartbeat: OK (no action needed)")
+                else:
+                    logger.info(f"Heartbeat: completed task")
+                    
+            except Exception as e:
+                logger.error(f"Heartbeat execution failed: {e}")
+    
+    async def trigger_now(self) -> str | None:
+        """Manually trigger a heartbeat."""
+        if self.on_heartbeat:
+            return await self.on_heartbeat(HEARTBEAT_PROMPT)
+        return None

flowly_code/multiagent/README.md

@@ -0,0 +1,248 @@
+# Multi-Agent Orchestration
+
+Flowly's multi-agent system delegates tasks to external CLI-based AI agents (Claude Code, Codex, Gemini CLI, OpenCode, Droid) and orchestrates team collaboration through chain execution and fan-out patterns.
+
+## Architecture
+
+```
+User message
+     │
+     ▼
+┌─────────────┐     @mention?     ┌──────────────┐
+│  AgentLoop  │ ───────────────── │  AgentRouter  │
+│  (main LLM) │                   │  (routing)    │
+└──────┬──────┘                   └───────┬───────┘
+       │                                  │
+       │  delegate_to()                   │  route()
+       ▼                                  ▼
+┌──────────────┐               ┌───────────────────┐
+│ DelegateTool │               │ TeamOrchestrator   │
+│ (fire&forget)│               │ (chain + fan-out)  │
+└──────┬───────┘               └─────────┬─────────┘
+       │                                 │
+       ▼                                 ▼
+┌──────────────────────────────────────────────┐
+│              invoke_agent()                   │
+│  Spawns CLI subprocess per provider:          │
+│  claude / codex / gemini / opencode / droid   │
+└──────────────────────────────────────────────┘
+```
+
+## Key Concepts
+
+### Agents vs AgentLoop
+
+These are fundamentally different:
+
+| | AgentLoop | Configured Agents |
+|---|---|---|
+| **What** | Main LLM processing engine | CLI subprocess instances |
+| **Lifetime** | Long-lived, handles all messages | Short-lived, one task per invocation |
+| **Provider** | Single LiteLLM provider | Each agent has its own provider/model |
+| **Invocation** | Runs continuously in-process | Spawned as `claude -p "..."`, `codex exec "..."`, etc. |
+| **Tools** | Full tool registry (web, file, exec, MCP, ...) | Only what the CLI tool provides |
+| **Communication** | Message bus | `[@agent_id: message]` tag format in responses |
+
+### Execution Patterns
+
+#### 1. Direct Delegation (fire-and-forget)
+
+The main AgentLoop calls `delegate_to(agent_id, message)`. The subprocess runs in the background, and the result is delivered asynchronously via the message bus.
+
+```
+User: "fix the login bug"
+  → AgentLoop calls delegate_to("coder", "fix the login bug")
+  → Returns immediately: "Task delegated to @coder..."
+  → Background: claude --model opus -p "fix the login bug"
+  → When done: result sent back through bus → AgentLoop summarizes
+```
+
+#### 2. Team Chain (sequential handoff)
+
+When routed via `@team`, the leader agent is invoked first. If its response contains a `[@teammate: message]` tag, the orchestrator detects it and invokes that teammate with the message. The chain continues until no teammate is mentioned or `MAX_CHAIN_DEPTH` (10) is reached.
+
+```
+User: "@dev fix and review the auth module"
+  → Router: @dev → team leader "coder"
+  → Step 1: invoke coder → response contains [@reviewer: check this PR]
+  → Step 2: invoke reviewer with coder's message
+  → Step 3: reviewer responds (no mention) → chain ends
+  → Final: all step responses combined
+```
+
+#### 3. Fan-out (parallel execution)
+
+If an agent's response mentions multiple teammates (via tag format), all are invoked in parallel. The chain ends after fan-out.
+
+```
+Step 1: invoke leader
+  → Response: [@coder: implement feature] [@tester: write tests]
+Step 2: invoke coder AND tester in parallel (asyncio.gather)
+  → Both responses collected
+  → Chain ends
+```
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `router.py` | `@mention` parsing, message routing, teammate validation |
+| `orchestrator.py` | Team chain execution, fan-out, depth limiting |
+| `invoke.py` | CLI subprocess spawning per provider (claude, codex, gemini, ...) |
+| `setup.py` | Agent directory initialization, `AGENTS.md` / `CLAUDE.md` generation |
+
+## Module Details
+
+### router.py — AgentRouter
+
+Parses `@agent_id` or `@team_id` prefixes from incoming messages and routes to the correct agent.
+
+**Routing priority:**
+1. `@agent_id` → direct agent match
+2. `@team_id` → team leader agent
+3. `@agent_name` → case-insensitive name match
+4. `@team_name` → case-insensitive team name match
+5. No prefix → default agent (main AgentLoop handles it)
+
+**Teammate mention extraction** from agent responses supports two formats:
+- **Tag format** (preferred): `[@agent_id: message here]` — supports multiple mentions
+- **Bare format** (fallback): `@agent_id` — first valid match only
+
+### orchestrator.py — TeamOrchestrator
+
+Executes the chain/fan-out logic:
+
+```python
+result = await orchestrator.execute(
+    message="fix the auth bug",
+    agent_id="coder",
+    team_context=TeamContext(team_id="dev", team=team_config),
+    agents=all_agents,
+    workspace=workspace_path,
+)
+# result.steps = [ChainStep("coder", "..."), ChainStep("reviewer", "...")]
+# result.final_response = combined output
+```
+
+**Chain rules:**
+- Max depth: 10 steps (configurable via `MAX_CHAIN_DEPTH`)
+- Single mention → sequential handoff (next agent gets `[Message from teammate @prev]:`)
+- Multiple mentions → parallel fan-out (all invoked via `asyncio.gather`)
+- Fan-out terminates the chain (no further handoffs)
+- Errors are caught per-agent and included in results
+
+### invoke.py — CLI Subprocess Invocation
+
+Each provider maps to a specific CLI tool:
+
+| Provider | CLI Command | Key Flags |
+|----------|-------------|-----------|
+| `anthropic` | `claude` | `--dangerously-skip-permissions`, `--model`, `-c` (continue), `--append-system-prompt`, `--add-dir` |
+| `openai` | `codex exec` | `--skip-git-repo-check`, `--dangerously-bypass-approvals-and-sandbox`, `--json` |
+| `gemini` | `gemini` | `--model`, `-p` |
+| `opencode` | `opencode run` | `--model` |
+| `droid` | `droid exec` | `--auto high`, `--model` |
+
+**Model resolution:** Short names are resolved to full IDs:
+- `sonnet` → `claude-sonnet-4-5`
+- `opus` → `claude-opus-4-6`
+- `haiku` → `claude-haiku-4-5`
+- `gpt-5.3-codex` → `gpt-5.3-codex`
+
+**Timeout:** 1800 seconds (30 minutes) per invocation.
+
+**Codex output:** Parsed from JSONL format — extracts the final `agent_message` from `item.completed` events.
+
+### setup.py — Agent Directory Setup
+
+Creates `~/.flowly/workspace/agents/{agent_id}/` with:
+
+```
+agents/{agent_id}/
+├── AGENTS.md           # Team communication instructions
+└── .claude/
+    └── CLAUDE.md       # Teammate list for Claude Code
+```
+
+**AGENTS.md** contains:
+- Instructions explaining the `[@agent_id: message]` tag system
+- List of teammates with their IDs and models
+- Rules for single/parallel/chain communication
+
+Teammate lists are updated between `<!-- TEAMMATES_START -->` / `<!-- TEAMMATES_END -->` markers, so manual edits outside those markers are preserved.
+
+## Configuration
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "model": "anthropic/claude-sonnet-4-5",
+      "workspace": "~/.flowly/workspace"
+    },
+    "agents": {
+      "coder": {
+        "name": "Code Assistant",
+        "provider": "anthropic",
+        "model": "opus",
+        "persona": ""
+      },
+      "reviewer": {
+        "name": "Code Reviewer",
+        "provider": "openai",
+        "model": "gpt-5.3-codex",
+        "workingDirectory": "~/projects"
+      }
+    },
+    "teams": {
+      "dev": {
+        "name": "Development Team",
+        "agents": ["coder", "reviewer"],
+        "leader_agent": "coder"
+      }
+    }
+  }
+}
+```
+
+### Agent Fields
+
+| Field | Description | Default |
+|-------|-------------|---------|
+| `name` | Display name | agent ID |
+| `provider` | `anthropic`, `openai`, `gemini`, `opencode`, `droid` | `anthropic` |
+| `model` | Short name or full model ID | — |
+| `working_directory` | Where the CLI runs | `$HOME` |
+| `persona` | Agent persona | — |
+
+### Team Fields
+
+| Field | Description |
+|-------|-------------|
+| `name` | Team display name |
+| `agents` | List of agent IDs in the team |
+| `leader_agent` | Agent that receives `@team` messages first |
+
+## Integration with AgentLoop
+
+The multi-agent system connects to the main AgentLoop through `DelegateTool`:
+
+```python
+# In cli/commands.py gateway() setup:
+from flowly_code.multiagent.router import AgentRouter
+from flowly_code.multiagent.orchestrator import TeamOrchestrator
+from flowly_code.agent.tools.delegate import DelegateTool
+
+router = AgentRouter(agents, teams)
+orchestrator = TeamOrchestrator(router)
+
+# Setup agent directories with AGENTS.md
+for agent_id, cfg in agents.items():
+    ensure_agent_directory(workspace / agent_id, agent_id, agents, teams)
+
+# Register delegate_to tool on main agent
+delegate_tool = DelegateTool(agents, teams, workspace, bus)
+agent.tools.register(delegate_tool)
+```
+
+When a `[DELEGATE_RESULT:agent_id]` message comes back through the bus, the routing layer temporarily removes `delegate_to` from the tool registry to prevent infinite re-delegation loops.

flowly_code/multiagent/__init__.py

@@ -0,0 +1 @@
+"""Multi-agent orchestration for flowly."""

flowly_code/multiagent/invoke.py

@@ -0,0 +1,210 @@
+"""Agent invocation via CLI subprocess delegation."""
+
+import asyncio
+import json
+from pathlib import Path
+
+from loguru import logger
+
+from flowly_code.config.schema import MultiAgentConfig
+
+
+# CLI install hints for error messages
+INSTALL_HINTS = {
+    "claude": "npm install -g @anthropic-ai/claude-code",
+    "codex": "npm install -g @openai/codex",
+    "gemini": "npm install -g @anthropic-ai/gemini-cli",
+    "opencode": "brew install opencode  OR  go install github.com/opencode-ai/opencode@latest",
+    "droid": "npm install -g @anthropic-ai/factory",
+}
+
+# Short name → full model ID mappings
+CLAUDE_MODELS = {
+    "sonnet": "claude-sonnet-4-5",
+    "opus": "claude-opus-4-6",
+    "haiku": "claude-haiku-4-5",
+}
+
+CODEX_MODELS = {
+    "gpt-5.3-codex": "gpt-5.3-codex",
+    "gpt-5.2": "gpt-5.2",
+}
+
+
+def resolve_claude_model(short_name: str) -> str:
+    """Resolve short model name to full Claude model ID."""
+    return CLAUDE_MODELS.get(short_name, short_name)
+
+
+def resolve_codex_model(short_name: str) -> str:
+    """Resolve short model name to full Codex model ID."""
+    return CODEX_MODELS.get(short_name, short_name)
+
+
+def parse_codex_jsonl(output: str) -> str:
+    """Parse Codex JSONL output and extract the final agent_message."""
+    response = ""
+    for line in output.strip().split("\n"):
+        try:
+            data = json.loads(line)
+            if data.get("type") == "item.completed" and data.get("item", {}).get("type") == "agent_message":
+                response = data["item"].get("text", "")
+        except (json.JSONDecodeError, KeyError):
+            continue
+    return response or "Sorry, I could not generate a response."
+
+
+def _build_system_context(agent_id: str, workspace_path: Path) -> str:
+    """Build system prompt context from agent's AGENTS.md file.
+
+    Reads the AGENTS.md from the agent directory and returns it as
+    system prompt context for the subprocess.
+    """
+    agents_md = workspace_path / agent_id / "AGENTS.md"
+    if agents_md.exists():
+        return agents_md.read_text()
+    return ""
+
+
+async def invoke_agent(
+    agent: MultiAgentConfig,
+    agent_id: str,
+    message: str,
+    workspace_path: Path,
+    continue_conversation: bool = True,
+    timeout: int = 1800,
+) -> str:
+    """Invoke an agent via CLI subprocess.
+
+    Args:
+        agent: Agent configuration.
+        agent_id: Agent identifier.
+        message: Message to send to the agent.
+        workspace_path: Base path for agent working directories.
+        continue_conversation: Whether to continue previous conversation.
+        timeout: Subprocess timeout in seconds.
+
+    Returns:
+        Agent response text.
+    """
+    provider = agent.provider or "anthropic"
+
+    # Working directory: explicit config path, or user's home directory.
+    # The agent dir (~/.flowly/workspace/agents/{id}/) only holds AGENTS.md
+    # and .claude/CLAUDE.md — the agent should work in the user's project.
+    if agent.working_directory:
+        working_dir = str(Path(agent.working_directory).expanduser())
+    else:
+        working_dir = str(Path.home())
+
+    # Ensure working directory exists
+    Path(working_dir).mkdir(parents=True, exist_ok=True)
+
+    # Agent config directory (holds AGENTS.md and .claude/CLAUDE.md)
+    agent_dir = str(workspace_path / agent_id)
+
+    if provider == "anthropic":
+        args = ["claude", "--dangerously-skip-permissions"]
+        model_id = resolve_claude_model(agent.model) if agent.model else None
+        if model_id:
+            args.extend(["--model", model_id])
+        if continue_conversation:
+            args.append("-c")
+
+        # Inject teammate context via --append-system-prompt
+        system_context = _build_system_context(agent_id, workspace_path)
+        if system_context:
+            args.extend(["--append-system-prompt", system_context])
+
+        # Add agent dir so Claude Code can read .claude/CLAUDE.md from there
+        args.extend(["--add-dir", agent_dir])
+
+        args.extend(["-p", message])
+
+    elif provider == "openai":
+        args = ["codex", "exec"]
+        if continue_conversation:
+            args.extend(["resume", "--last"])
+        model_id = resolve_codex_model(agent.model) if agent.model else None
+        if model_id:
+            args.extend(["--model", model_id])
+        args.extend([
+            "--skip-git-repo-check",
+            "--dangerously-bypass-approvals-and-sandbox",
+            "--json",
+            message,
+        ])
+
+    elif provider == "gemini":
+        args = ["gemini"]
+        if agent.model:
+            args.extend(["--model", agent.model])
+        args.extend(["-p", message])
+
+    elif provider == "opencode":
+        args = ["opencode", "run"]
+        if agent.model:
+            args.extend(["--model", agent.model])
+        args.append(message)
+
+    elif provider == "droid":
+        args = ["droid", "exec", "--auto", "high"]
+        if agent.model:
+            args.extend(["--model", agent.model])
+        args.append(message)
+
+    else:
+        raise ValueError(f"Unsupported provider: {provider}")
+
+    logger.info(f"Invoking agent @{agent_id} [{provider}/{agent.model}] in {working_dir}")
+    return await run_subprocess(args, cwd=working_dir, timeout=timeout, provider=provider)
+
+
+async def run_subprocess(
+    args: list[str],
+    cwd: str,
+    timeout: int = 1800,
+    provider: str = "anthropic",
+) -> str:
+    """Run a CLI command as subprocess and return stdout.
+
+    Args:
+        args: Command and arguments.
+        cwd: Working directory.
+        timeout: Timeout in seconds.
+        provider: Provider name for output parsing.
+
+    Returns:
+        Command output (parsed for codex).
+
+    Raises:
+        RuntimeError: If command fails or times out.
+    """
+    try:
+        proc = await asyncio.create_subprocess_exec(
+            *args,
+            cwd=cwd,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+    except FileNotFoundError:
+        cmd = args[0]
+        hint = INSTALL_HINTS.get(cmd, f"install '{cmd}' and make sure it's in your PATH")
+        raise RuntimeError(f"Command '{cmd}' not found. Install it first: {hint}")
+
+    try:
+        stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=timeout)
+    except asyncio.TimeoutError:
+        proc.kill()
+        raise RuntimeError(f"Agent subprocess timed out after {timeout}s")
+
+    if proc.returncode != 0:
+        error_msg = stderr.decode().strip() or f"Process exited with code {proc.returncode}"
+        raise RuntimeError(f"Agent process failed: {error_msg}")
+
+    output = stdout.decode()
+
+    if provider == "openai":
+        return parse_codex_jsonl(output)
+
+    return output.strip()