Architecture Overview¶

Houmao orchestrates CLI-based agents (Codex, Claude, Gemini) as real tmux-backed processes with isolated runtime homes. The lifecycle still has two phases. The reusable source model is recipe + setup + auth, and reusable birth-time launch configuration lives separately as launch profiles that compose with recipe defaults during build. In project overlays, auth selection is user-facing by display name while the catalog owns the stable underlying auth identity. Managed launches also prepend one short Houmao-owned prompt header by default after any prompt-overlay resolution and before backend-specific prompt injection. For the shared conceptual model that ties project profiles and native launch dossiers together, see Launch Profiles.

Two-Phase Lifecycle¶

flowchart TD
    Op["Operator"] --> SRC["Source Tree<br/>(roles + recipes + launch-profiles +<br/>tools + skills)"]
    SRC --> CAT["Canonical Parsed Catalog"]
    CAT --> RLS["Resolved Launch Spec<br/>(tool, role, setup, skills, auth,<br/>launch-profile defaults)"]
    RLS --> BB["BrainBuilder"]
    BB --> BM["Brain Manifest<br/>(schema_version=4,<br/>launch-profile provenance)"]
    BM --> LP["LaunchPlanRequest<br/>(manifest + role)"]
    LP --> RT["Runtime Session<br/>Controller"]

Build Phase¶

src/houmao/agents/brain_builder.py materializes a disposable runtime home from explicit inputs or one resolved preset.

Key Types¶

BuildRequest captures what to build:

Field	Description
`agent_def_dir`	Agent definition root
`tool`	CLI tool name
`skills`	Selected skill names
`setup`	Selected checked-in setup bundle
`auth`	Effective auth bundle
`preset_path`	Optional resolved preset path for provenance
`runtime_root`	Where to create the runtime home
`mailbox`	Optional mailbox binding
`agent_name` / `agent_id` / `home_id`	Launch-time identity metadata

BuildResult captures what was built:

Field	Description
`home_id`	Unique runtime-home id
`home_path`	Materialized runtime home
`manifest_path`	Emitted brain manifest path
`launch_helper_path`	Generated launch helper
`launch_preview`	Human-readable launch command
`manifest`	Full manifest payload

AgentPreset is the parsed declarative preset stored at presets/<name>.yaml.

ToolAdapter is the per-tool projection and launch contract stored at tools/<tool>/adapter.yaml.

Run Phase¶

src/houmao/agents/realm_controller/ reads the built manifest, pairs it with a role package, and resolves a backend-specific LaunchPlan.

When a managed agent's registry record claims active but the underlying tmux session is broken, selected-agent agents single ... stop and agents single ... relaunch route through dedicated recovery helpers rather than failing with a generic error. The runtime probes tmux authority, classifies the session as healthy, degraded, or stale, and dispatches to the appropriate recovery path. See Degraded and Stale Active Recovery.

Key Types¶

LaunchPlanRequest

Field	Description
`brain_manifest`	Built manifest from the build phase
`role_package`	Role name and system prompt
`backend`	Target backend kind
`working_directory`	Session working directory

LaunchPlan

Field	Description
`backend`	Target backend kind
`tool`	CLI tool name
`executable`	Tool executable
`args`	Final launch args
`working_directory`	Session working directory
`home_env_var` / `home_path`	Runtime-home selector
`env`	Final environment map
`role_injection`	Backend-specific prompt injection plan
`mailbox`	Optional resolved mailbox config

Source Layout¶

Path	Responsibility
`src/houmao/agents/definition_parser.py`	Parse `agents/` source tree inputs into the canonical in-memory catalog used by non-project build flows
`src/houmao/agents/native_launch_resolver.py`	Resolve `--agents` selectors onto presets
`src/houmao/agents/brain_builder.py`	Build phase: resolved inputs -> runtime home + manifest
`src/houmao/agents/realm_controller/launch_plan.py`	Manifest + role -> backend launch plan
`src/houmao/agents/realm_controller/backends/`	Backend implementations
`src/houmao/srv_ctrl/commands/agents/core.py`	Scoped `houmao-mgr agents global\|single\|self\|external` command registration

Project CLI Views¶

The repo-local operator surface is intentionally split into one low-level view and two user-facing convenience views:

houmao-mgr project
├── init | status
├── agents
│   ├── roles ...
│   ├── recipes ...                # canonical low-level source recipes
│   ├── presets ...                # compatibility alias for `recipes`
│   ├── launch-profiles ...        # explicit recipe-backed birth-time launch profiles
│   └── tools <tool> ...
├── easy
│   ├── specialist ...
│   ├── profile ...                # specialist-backed easy birth-time profiles
│   └── instance ...
└── mailbox
    ├── init | status | register | unregister | repair | cleanup
    ├── accounts list|get
    └── messages list|get

project agents ... is the low-level compatibility-projection surface for .houmao/agents/. Project-local semantic truth lives in .houmao/catalog.sqlite plus .houmao/content/, while .houmao/agents/ remains the generated file-tree view consumed by current builders and runtime.
project ... lets users author reusable specialists, optional specialist-backed project profiles, and view running instances without hand-editing the tree.
project mailbox ... mirrors the generic houmao-mgr mailbox ... operations, but automatically targets <project-root>/.houmao/mailbox.

Project-aware commands select that overlay root through one shared contract:

HOUMAO_PROJECT_OVERLAY_DIR selects an overlay root directly and wins over ambient discovery.
Otherwise Houmao uses HOUMAO_PROJECT_OVERLAY_DISCOVERY_MODE=ancestor by default, which searches for the nearest ancestor .houmao/houmao-config.toml within the current Git boundary.
Set HOUMAO_PROJECT_OVERLAY_DISCOVERY_MODE=cwd_only to restrict ambient lookup to <cwd>/.houmao/houmao-config.toml.