bingshuo/hololake-system-architecture
Watch
1
0
Fork
You've already forked hololake-system-architecture
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
hololake-system-architecture/product-source/hololake-platform/docs/adr/0157-local-hldp-heartbeat-and-browser-observation-tree.md

2.3 KiB
Raw Blame History

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.