48 lines
2.3 KiB
Markdown
48 lines
2.3 KiB
Markdown
|
# ADR 0157: Local HLDP heartbeat and browser observation tree
|
||
|
|
|
||
|
|
## Status
|
||
|
|
|
||
|
|
Accepted
|
||
|
|
|
||
|
|
## Context
|
||
|
|
|
||
|
|
Language personas need continuity and tool feedback without receiving an
|
||
|
|
ever-growing transcript or a complete web page in model context. Truncating a
|
||
|
|
large result can silently remove the important section. Persisting every
|
||
|
|
heartbeat to Git would instead turn collaboration state into repository noise
|
||
|
|
and make a remote service part of the live runtime.
|
||
|
|
|
||
|
|
The visual browser also has a different failure profile from the conversation:
|
||
|
|
a remote page can be slow, blocked, or script-heavy. It must not share the
|
||
|
|
conversation's rendering or completion path.
|
||
|
|
|
||
|
|
## Decision
|
||
|
|
|
||
|
|
- Auto-load one built-in HLDP heartbeat skill for every app-managed persona.
|
||
|
|
- Append bounded, structured events to an installation-local JSONL journal.
|
||
|
|
Events record decisions, corrections, receipts, constraints, and unfinished
|
||
|
|
branches, not tokens, paint events, hidden reasoning, or secrets.
|
||
|
|
- Finalization writes one immutable local checkpoint. Only a finalized
|
||
|
|
checkpoint is eligible for a separately authorized Git publication.
|
||
|
|
- Keep the active journal until finalization and any required publication
|
||
|
|
receipt; pruning an unfinished journal is rejected.
|
||
|
|
- Store readable web content as bounded local HLDP nodes. The first tool return
|
||
|
|
contains document metadata and short node previews. A persona requests
|
||
|
|
selected node ranges when it needs more detail.
|
||
|
|
- Show the structured receipt in a text-only observation board. A visual page
|
||
|
|
opens only after explicit user action in a single isolated native WebView.
|
||
|
|
Reopening replaces the prior visual verifier so remote pages do not
|
||
|
|
accumulate or block the AI workspace.
|
||
|
|
- Limit a fetched page to 5 MB and continue to enforce public HTTP(S), DNS, and
|
||
|
|
redirect safety checks.
|
||
|
|
|
||
|
|
## Consequences
|
||
|
|
|
||
|
|
- Large pages are no longer cut at an arbitrary model-context boundary.
|
||
|
|
- Personas retain a small global map and can drill into relevant branches.
|
||
|
|
- High-frequency collaboration state stays local and append-only; Git receives
|
||
|
|
deliberate checkpoints instead of runtime churn.
|
||
|
|
- The text map is the authoritative persona observation. The native browser is
|
||
|
|
optional human-visible evidence and can fail independently.
|
||
|
|
- This slice does not automatically publish checkpoints, run a general-purpose
|
||
|
|
browser automation engine, or grant shell access.
|