lha 1.0.2

Long-Horizon Agent command-line package that installs the lha binary.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72

# LHA Config Loader

This private `lha` module is the canonical place to load and describe LHA
configuration layers (user config, CLI/session overrides, managed config, and
MDM-managed preferences) and to produce:

- An effective merged TOML config.
- Per-key origins metadata (which layer wins for a given key).
- Per-layer versions (stable fingerprints) used for optimistic concurrency and
  conflict detection.

## Internal Surface

Exported from `crate::product::agent::config_loader`:

- `load_config_layers_state(lha_home, cwd_opt, cli_overrides, overrides, cloud_requirements) -> ConfigLayerStack`
- `ConfigLayerStack`
  - `effective_config() -> toml::Value`
  - `origins() -> HashMap<String, ConfigLayerMetadata>`
  - `layers_high_to_low() -> Vec<ConfigLayer>`
  - `with_user_config(user_config) -> ConfigLayerStack`
- `ConfigLayerEntry` (one layer's `{name, config, version, disabled_reason}`; `name` carries source metadata)
- `LoaderOverrides` (test/override hooks for managed config sources)
- `merge_toml_values(base, overlay)` (helper used elsewhere)

## Layering Model

Precedence is top overrides bottom:

1. MDM managed preferences (macOS only)
2. System managed config (for example, `managed_config.toml`)
3. Session flags (CLI overrides, applied as dotted-path TOML writes)
4. User config (`config.toml`)

Layers with a `disabled_reason` are still surfaced for UI, but are ignored when
computing the effective config and origins metadata. This is what
`ConfigLayerStack::effective_config()` implements.

## Typical Usage

Most callers want the effective config plus metadata:

```rust
use crate::product::agent::config_loader::{load_config_layers_state, LoaderOverrides};
use crate::product::utils_absolute_path::AbsolutePathBuf;
use toml::Value as TomlValue;

let cli_overrides: Vec<(String, TomlValue)> = Vec::new();
let cwd = AbsolutePathBuf::current_dir()?;
let layers = load_config_layers_state(
    &lha_home,
    Some(cwd),
    &cli_overrides,
    LoaderOverrides::default(),
    None,
).await?;

let effective = layers.effective_config();
let origins = layers.origins();
let layers_for_ui = layers.layers_high_to_low();
```

## Internal Layout

Implementation is split by concern:

- `state.rs`: public types (`ConfigLayerEntry`, `ConfigLayerStack`) plus merge/origins convenience methods.
- `layer_io.rs`: reading `config.toml`, managed config, and managed preferences inputs.
- `overrides.rs`: CLI dotted-path overrides into a TOML session-flags layer.
- `merge.rs`: recursive TOML merge.
- `fingerprint.rs`: stable per-layer hashing and per-key origins traversal.
- `macos.rs`: managed preferences integration (macOS only).