houmao-mgr internals¶

Internal Houmao utility commands for agents and maintainers.

houmao-mgr internals exposes utility command families for maintainers and agent tooling. graph provides NetworkX-backed helpers for loop plan authoring, structural analysis, and low-level graph manipulation. native-agent exposes direct provider-aligned file-tree maintenance that is intentionally not ordinary project UX.

When to use these commands¶

graph high is designed for loop plan authoring and validation. The public $houmao-agent-loop-pro ... skill reaches it under its default admin frame or a verified as-agent frame. These commands give the loop deterministic structural facts such as root reachability, packet expectations, validation errors, and Mermaid scaffolding. Older mode names such as pairwise-v2 can still appear as graph-helper compatibility values; they are helper modes, not current skill names.

graph low is for generic graph construction and NetworkX algorithm access. Use it when you need to build or transform a graph from scratch, extract subgraphs, or run standard graph algorithms not covered by the high-level surface.

All graph commands accept a node-link JSON file via --input (or --graph where noted) and use - to read from stdin. Commands that produce a graph output emit NetworkX node-link JSON with nodes, edges, and graph keys.

native-agent¶

Direct native-agent commands operate on a selected native-agent root. Pass --native-agent-root <dir> on the leaf command or set HOUMAO_NATIVE_AGENT_ROOT to an absolute path. These commands do not discover or mutate a Houmao project catalog.

credentials¶

Manage direct native-agent credentials under tools/<tool>/auth/<name>/.

houmao-mgr internals native-agent credentials <tool> list|get|add|set|login|rename|remove --native-agent-root <dir>

brain build¶

Build one brain home directly from native-agent material.

houmao-mgr internals native-agent brain build --native-agent-root <dir> --preset <name>

The internal build command accepts the retained direct build inputs: --preset, --tool, repeatable --skill, --setup, --auth, --runtime-root, --home-id, --reuse-home, --launch-overrides, --agent-name, and --agent-id. The maintained flag names are --preset, --setup, and --auth; retired top-level brain-build examples using --recipe, --config-profile, --cred-profile, or --agent-def-dir are not current. Ordinary project launches build brain homes internally through houmao-mgr project agents launch.

config-drafts¶

Generate concise YAML configuration drafts from sparse JSON intent without mutating project or native-agent state.

houmao-mgr internals config-drafts list
houmao-mgr internals config-drafts generate --id <draft-id> --intent '<json>'

Supported draft ids are project.specialist, project.profile, and internals.native-agent.launch-dossier. The --intent value accepts an inline JSON object, - for stdin, or a path to a JSON file. Intent JSON must be an object with a top-level fields mapping.

Examples:

houmao-mgr internals config-drafts generate --id project.specialist --intent '{"fields":{"name":"general-kimi","tool":"kimi","credential":"kimi-coding"}}'
houmao-mgr internals config-drafts generate --id project.profile --intent '{"fields":{"name":"reviewer-fast","specialist":"reviewer","credential":"reviewer-creds"}}'
houmao-mgr internals config-drafts generate --id internals.native-agent.launch-dossier --intent '{"fields":{"name":"reviewer-native","recipe":"reviewer-codex","credential":"reviewer-creds"}}'

When intent JSON is invalid or has the wrong shape, the command prints a fix guide with the selected draft id, --intent source, JSON Schema-style expected shape, required fields.* paths, and a valid example.

graph high¶

Houmao-aware loop graph helpers.

analyze¶

Analyze Houmao loop graph structure. Reports root reachability, leaves, non-leaf (delegating) participants, immediate children, cycle or DAG posture, component summaries, branch points, and mode-specific shape warnings.

Synopsis:

houmao-mgr [--print-json] internals graph high analyze [OPTIONS]

Option	Required	Default	Description
`--input PATH`	yes	—	NetworkX node-link JSON graph file; use `-` for stdin.
`--root TEXT`	no	`graph.root`	Root node override.
`--mode TEXT`	no	`graph.mode`	Mode override (e.g. `pairwise-v2`, `generic`).
`--cycle-limit INT`	no	`20`	Maximum cycle examples to include in the result.

Examples:

houmao-mgr --print-json internals graph high analyze --input graph.json
houmao-mgr internals graph high analyze --input graph.json --root master --mode pairwise-v2

packet-expectations¶

Derive pairwise-v2 routing-packet expectations from graph topology. Returns the expected root packet shape, one child packet expectation per pairwise edge, non-leaf dispatch-table expectations, and freshness-marker requirements. Use the output to author or audit routing packets before a pairwise-v2 run.

Synopsis:

houmao-mgr [--print-json] internals graph high packet-expectations [OPTIONS]

Option	Required	Default	Description
`--input PATH`	yes	—	NetworkX node-link JSON graph file; use `-` for stdin.
`--root TEXT`	no	`graph.root`	Root node override.

Examples:

houmao-mgr --print-json internals graph high packet-expectations --input graph.json
houmao-mgr internals graph high packet-expectations --input graph.json --root master

validate-packets¶

Validate pairwise-v2 routing packets against graph-derived expectations. Checks for missing root packets, missing child packets, stale revisions or digests, intended-recipient mismatches, immediate-driver mismatches, missing dispatch tables, and missing exact child packet text or references. Returns a structured validation result with any errors.

Packet JSON shape: root_packet plus child_packets, where each packet includes intended_recipient, immediate_driver, freshness markers, and optional child_dispatch_table entries with packet_text or packet_ref.

Synopsis:

houmao-mgr [--print-json] internals graph high validate-packets [OPTIONS]

Option	Required	Default	Description
`--graph PATH`	yes	—	NetworkX node-link JSON graph file; use `-` for stdin.
`--packets PATH`	yes	—	Pairwise-v2 routing packet JSON document.
`--root TEXT`	no	`graph.root`	Root node override.

Examples:

houmao-mgr --print-json internals graph high validate-packets --graph graph.json --packets packets.json
houmao-mgr internals graph high validate-packets --graph graph.json --packets packets.json --root master

slice¶

Extract an authoring-time graph slice as node-link JSON. Supports four slice directions: ancestors, descendants, reachable (all nodes reachable from root), and component (a named component subgraph). Emits a node-link JSON graph preserving all node, edge, and graph metadata for the included elements.

Synopsis:

houmao-mgr [--print-json] internals graph high slice [OPTIONS]

Option	Required	Default	Description
`--input PATH`	yes	—	NetworkX node-link JSON graph file; use `-` for stdin.
`--root TEXT`	yes	—	Root node for ancestor, descendant, or reachable slices.
`--direction CHOICE`	yes	—	One of `ancestors`, `descendants`, `reachable`, `component`.
`--component-id TEXT`	no	—	Component ID required when `--direction component`.

Examples:

houmao-mgr --print-json internals graph high slice --input graph.json --root agent-a --direction descendants
houmao-mgr --print-json internals graph high slice --input graph.json --direction component --component-id c1 --root master

render-mermaid¶

Render deterministic Mermaid scaffolding from graph structure. Produces a Mermaid flowchart based on node and edge types in the graph. This is a structural scaffold — final semantic review of loop logic and edge labels belongs in the owning Houmao skill.

With --print-plain (the default), emits the Mermaid text directly. With --print-json, emits a JSON payload with a mermaid field.

Synopsis:

houmao-mgr [--print-json | --print-plain] internals graph high render-mermaid [OPTIONS]

Option	Required	Default	Description
`--input PATH`	yes	—	NetworkX node-link JSON graph file; use `-` for stdin.
`--root TEXT`	no	`graph.root`	Root node override.
`--mode TEXT`	no	`graph.mode`	Mode override.

Examples:

houmao-mgr internals graph high render-mermaid --input graph.json
houmao-mgr --print-json internals graph high render-mermaid --input graph.json --mode generic

graph low¶

Constrained NetworkX-style low-level graph primitives. These commands emit node-link JSON graphs and accept node-link JSON as input.

create¶

Create an empty supported NetworkX graph.

Option	Required	Default	Description
`--type CHOICE`	no	`multidigraph`	One of `multidigraph`, `digraph`, `multigraph`, `graph`.

houmao-mgr --print-json internals graph low create --type multidigraph

mutate¶

Apply constrained graph mutation operations. The ops JSON must have an ops array; each op must have an op field (e.g. add_node, add_edge, remove_node, remove_edge, set_node_attr, set_edge_attr, set_graph_attr).

Ops JSON shape: { "ops": [{ "op": "add_node", "node": "agent-a", "attrs": {"kind": "agent"} }] }.

Option	Required	Description
`--input PATH`	yes	NetworkX node-link JSON graph file; use `-` for stdin.
`--ops PATH`	yes	Mutation ops JSON file.

houmao-mgr --print-json internals graph low mutate --input graph.json --ops ops.json

relabel¶

Relabel graph nodes with a JSON object mapping old node IDs to new node IDs.

Option	Required	Description
`--input PATH`	yes	NetworkX node-link JSON graph file; use `-` for stdin.
`--mapping PATH`	yes	JSON object mapping old node IDs to new IDs.

houmao-mgr --print-json internals graph low relabel --input graph.json --mapping mapping.json

compose¶

Compose two node-link graphs (NetworkX compose semantics — nodes and edges from both graphs are merged; right-graph attributes override on conflict).

Option	Required	Description
`--left PATH`	yes	Left graph JSON.
`--right PATH`	yes	Right graph JSON.

houmao-mgr --print-json internals graph low compose --left a.json --right b.json

subgraph¶

Extract a node-induced subgraph. The nodes JSON must have a nodes array of node IDs.

Option	Required	Description
`--input PATH`	yes	NetworkX node-link JSON graph file; use `-` for stdin.
`--nodes PATH`	yes	JSON file with a `nodes` array.

houmao-mgr --print-json internals graph low subgraph --input graph.json --nodes nodes.json

reverse¶

Reverse directed graph edges.

Option	Required	Description
`--input PATH`	yes	NetworkX node-link JSON graph file; use `-` for stdin.

houmao-mgr --print-json internals graph low reverse --input graph.json

ego¶

Compute an ego graph (a subgraph centered on one node within a given radius).

Option	Required	Default	Description
`--input PATH`	yes	—	NetworkX node-link JSON graph file; use `-` for stdin.
`--node TEXT`	yes	—	Center node.
`--radius INT`	no	`1`	Ego radius (hop count).
`--undirected`	no	off	Treat graph as undirected for ego expansion.

houmao-mgr --print-json internals graph low ego --input graph.json --node agent-a --radius 2

graph low alg¶

Whitelisted low-level graph algorithm wrappers. All algorithm subcommands share the same option schema; only the options relevant to each algorithm need to be supplied.

Shared option schema¶

Option	Description
`--input PATH`	NetworkX node-link JSON graph file; use `-` for stdin. Required for all alg commands.
`--node TEXT`	Node argument for node-centered algorithms.
`--source TEXT`	Source node for path algorithms.
`--target TEXT`	Target node for path algorithms.
`--distance INT`	Exact-distance value for distance-bounded algorithms.
`--cutoff INT`	Path length cutoff for path-enumeration algorithms.
`--length-bound INT`	Cycle length bound for cycle-enumeration algorithms.
`--limit INT`	Maximum result count for expansive algorithms. Default: `50`.

Subcommand summary¶

Subcommand	Required options (beyond `--input`)	Description
`ancestors`	`--node`	Return all NetworkX ancestors of a node.
`descendants`	`--node`	Return all NetworkX descendants of a node.
`descendants-at-distance`	`--node`, `--distance`	Return descendants at an exact hop distance.
`topological-sort`	—	Return a deterministic topological ordering. Graph must be a DAG.
`is-dag`	—	Report whether the directed graph is acyclic.
`cycles`	—	Return bounded simple cycle examples. Use `--length-bound` and `--limit` to bound results.
`weak-components`	—	Return weakly connected component sets.
`strong-components`	—	Return strongly connected component sets.
`condensation`	—	Return NetworkX condensation graph summary.
`transitive-reduction`	—	Return a transitive-reduction adjacency summary. Graph must be a DAG.
`dag-longest-path`	—	Return a DAG longest path. Graph must be a DAG.
`shortest-path`	`--source`, `--target`	Return one shortest path between source and target.
`all-simple-paths`	`--source`, `--target`	Return bounded simple paths between source and target. Use `--cutoff` and `--limit` to bound results.

Examples:

houmao-mgr --print-json internals graph low alg ancestors --input graph.json --node agent-b
houmao-mgr --print-json internals graph low alg descendants-at-distance --input graph.json --node master --distance 2
houmao-mgr --print-json internals graph low alg cycles --input graph.json --length-bound 6 --limit 10
houmao-mgr --print-json internals graph low alg shortest-path --input graph.json --source master --target agent-b
houmao-mgr --print-json internals graph low alg all-simple-paths --input graph.json --source master --target agent-b --cutoff 5 --limit 20