🥮 mooncakes.io

    #moonbitlang/workflow/viz

    Turn a workflow journal into a self-contained HTML report with an attempt ledger, expandable answers, and a graph of possible data dependencies. This is an executable for native and wasm, with no importable API. It needs a journal file, not access to the engines that produced it.

    #Render a journal

    From this repository's root:

    moon run viz -- run.jsonl
moon run viz -- run.jsonl report.html

    Or run the published executable from a directory containing your journal:

    moonx moonbitlang/workflow/viz run.jsonl report.html

    ArgumentMeaning
    journalRequired input path.
    outOptional output path; default is <journal>.html.
    --watchRe-read and render every 2 seconds; generated HTML refreshes every 2 seconds.

    The tool writes or replaces the output file. Choose an output path distinct from the journal. Its parent directory must exist. Open the HTML file in a browser; the page has inline CSS and SVG and needs no server or external assets. just viz run.jsonl report.html is a repository shortcut.

    To follow a running workflow:

    moon run viz -- run.jsonl report.html --watch

    Stop the command when finished following the run. Render once without --watch to remove the page's automatic refresh before sharing a snapshot. The page contains report text, so share it with the same audience as the underlying journal.

    #What the report shows

    Each journal entry becomes a row with its label, phase, Finished or DidNotFinish status, step count, elapsed milliseconds, and token usage. Failures with an attempt contribute their usage just like successes. Elapsed time is blank when the entry lacks timestamps. Expand a row's answer panel to read its output or failure reason; the newest panel starts open. Text is HTML-escaped.

    Rows follow journal file order, normally completion order. They include historical attempts across resume generations. Replay hits do not append entries, so they do not add rows; an agent currently running has no row until its outcome is journalled. To observe launches as they happen, use hosted sidecar events or the core's event callback.

    #How the graph is derived

    flowchart TD
  Journal["Journal entries in file order"] --> Ledger["Attempt ledger and answers"]
  Journal --> Earlier["Earlier successful answer longer than 60"]
  Earlier --> Prefix["JSON-escaped prefix, up to 50 UTF-16 code units"]
  Prefix --> Match{"Prefix appears in later input?"}
  Match -->|Yes| Edge["Draw an edge"]
  Match -->|No| None["No inferred edge"]

    For a successful report, the probe text is its answer field when that field is a string; otherwise it is the whole report serialized as JSON. For each answer longer than 60 UTF-16 code units, the renderer takes a surrogate-safe prefix of up to 50, JSON-escapes it, and looks for it in each later entry's serialized input.

    An edge is a content-match heuristic, not a declared dependency or proof of causality. Repeated boilerplate can create an edge; short, summarized, or transformed answers can hide one. Entries without matching text still appear as graph nodes. There is no recorded static DAG to recover.

    #Reading a live file

    The parser accepts {"v":1,"e":...} entries and skips blank, malformed, metadata, and unsupported lines. It reads without modifying the journal; it deliberately does not use Journal::load, which can repair a torn tail. That makes it suitable for watching an append in progress, but not for auditing journal integrity.

    A missing, unreadable, or empty journal is treated as having no entries. If none can be parsed, the tool prints a message and leaves any existing HTML unchanged. In watch mode, render failures are printed and retried on the next tick. Errors are reported as text rather than a guaranteed nonzero process status; automation should check that the expected output exists.

    #Development

    main.mbt contains argument parsing, the tolerant journal reader, edge inference, and HTML rendering. From the repository root:

    moon run viz --target native -- --help
moon check viz --target native
moon check viz --target wasm

    For a report with known local data, run the keyless examples/scout example with a journal, then render that journal here.

    Source Files

    Powered by MoonBit

    Site sourceReport issueModulesSkillsCLIBuild queueStatistics

    © 2026 mooncakes.io