Overview

Date: 2026-05-11

Time: 15:41

Overview

This is an FTL2 AI-loop rule that ensures four Python packages (uv, ftl2-stargate, ftl2-htop, textual-serve) are installed on a host called stargate. It follows the observe-condition-action pattern used by FTL2's reconciliation loop: observe current package state, check if any are missing, and install them if needed. The rule uses --break-system-packages because the target runs Fedora 43, which enforces PEP 668 restrictions on system-wide pip installs.

Usage Patterns

This rule is not called directly — it is loaded and executed by the FTL2 AI reconciliation loop. The loop evaluates it periodically or on trigger:

1. Observe: Runs pip3 list and which commands on stargate to check installed packages.

2. Condition: Returns True (meaning "action needed") if any of the four required packages are missing from the observe output.

3. Action: Installs each package sequentially via sudo pip3 install.

# The three-part rule contract:
observe = [...]              # what to check
async def condition(state)   # should we act? (True = yes)
async def action(ftl)        # what to do

API and Configuration

• observe — list of dicts, each specifying a name, module (here shell), params, and target host.
• condition(state) — receives a dict keyed by observe step names. Each value has stdout, etc.
• action(ftl) — receives an ftl dict keyed by host name. Hosts expose module methods like .shell(cmd=...).
• Target host: stargate (must be defined in FTL2 inventory).
• Packages installed from git: ftl2-stargate and ftl2-htop are installed from GitHub repos via pip's @ git+https:// syntax.

Key Behaviors

• Sequential installs: uv is installed first because later packages may depend on it. Each await blocks before the next install.
• --break-system-packages: Required on Fedora 43+ (PEP 668) to allow system-wide pip installs without a virtualenv. This is a deliberate policy override.
• Loose grep matching: The observe step uses grep -iE (case-insensitive extended regex) and the condition checks for substring presence. The trailing space in "uv " prevents false matches against package names that merely contain "uv".
• || true in observe: Prevents the shell command from returning non-zero if textual-serve isn't found, which would cause the observe step to report failure rather than missing-package state.
• No idempotency guard in action: pip itself handles the "already installed" case, but the condition check avoids running pip at all when packages are present.

Relationships

• FTL2 AI-loop runtime: This rule is discovered and executed by the reconciliation loop engine. The module docstring metadata (created date, trigger description) is consumed by the loop for logging/audit.
• ftl host accessor: ftl["stargate"] provides a handle to the stargate host, with methods mapping to FTL2 modules (.shell(), etc.).
• Target packages: ftl2-stargate and ftl2-htop are companion tools from the same author, likely providing the stargate web UI and a TUI htop-like monitor. textual-serve is the Textual framework's web-serving component, suggesting these TUI apps are served over the web.
• Inventory: Requires a host named stargate in the FTL2 inventory with SSH access and sudo privileges.