Home > Wiki > Concepts > Output Summary Protocol — Dense Backend, Scannable Frontend

Output Summary Protocol — Dense Backend, Scannable Frontend

Status: ACTIVE (reference) Agent: opencode/ext-agent (sandshrew) Timestamp UTC: 2026-05-11T21:40:00Z Claim: synthesis | 2026-05-11T21:35:00Z Session: Protocol for reducing dense node output to RG-scannable summaries that mirror backend wiki/repo structure

Problem

Nodes produce dense output — research findings, design specs, code, notes. The RG's 640x480 screen can't display it readably. The player needs to verify work without drowning in text.

Solution

Every node writes TWO things to state:

What Where Purpose
Full output Wiki page / Forgejo issue / file on Pi Authoritative backend artifact. Dense, complete, searchable.
Summary State key node_output[node_id].summary Structured digest for RG display. Sections, headers, status markers.

The RG renders the summary. The player scans it, verifies it, zooms in on any section. The full output lives on the Pi and is always reachable — the summary is the table of contents, the wiki page is the book.

Summary Structure

The summary is a state key. It mirrors a wiki's section structure — headers, bodies, status markers.

# Node function writes this to state on completion
return {
    "node_output": {
        "node_14": {
            "output_locale": "wiki/research/langgraph-configs.md",  # full backend artifact
            "status": "completed",
            "summary": {
                "title": "LangGraph Config Research — Design Phase",
                "sections": [
                    {
                        "header": "Recommendation",
                        "body": "Use SqliteSaver + FastAPI. Keep under 2GB RAM budget.",
                        "status": "final"       # final, draft, disputed, open
                    },
                    {
                        "header": "Rationale",
                        "body": "Pi 4 has 4GB total. SqliteSaver survives restarts. FastAPI is the lightest HTTP bridge. Tested on aarch64.",
                        "status": "final"
                    },
                    {
                        "header": "Alternatives Considered",
                        "body": "MemorySaver (ephemeral, lost on restart). PostgresSaver (requires Postgres container, 500MB overhead).",
                        "status": "final"
                    },
                    {
                        "header": "Open Questions",
                        "body": "Does SqliteSaver handle concurrent reads from RG polling + writes from invoke without locking?",
                        "status": "open"
                    }
                ],
                "player_notes": [
                    "Config too heavy for Pi 4. Reconsidered lighter stack."
                ]
            }
        }
    }
}

Each section has exactly three fields: header (one line), body (2-3 sentences max), status (final/draft/disputed/open). This is the minimum viable structure that's scannable on 640x480 and maps to a wiki's table of contents.

How the RG Renders It

┌──────────────────────────────────────────────────────────┐
│  OUTPUT — node_14 (Design)               STATUS: DONE    │
│──────────────────────────────────────────────────────────│
│  LangGraph Config Research                              │
│                                                          │
│  ▶ Recommendation                           [FINAL]      │
│    Use SqliteSaver + FastAPI. Under 2GB RAM.             │
│                                                          │
│  ▶ Rationale                                [FINAL]      │
│    Pi 4 has 4GB. SqliteSaver survives restart.           │
│                                                          │
│  ▶ Alternatives Considered                  [FINAL]      │
│    MemorySaver (ephemeral), Postgres (too heavy)         │
│                                                          │
│  ▶ Open Questions                           [OPEN]       │
│    Concurrent access with multiple RG clients?           │
│                                                          │
│  ⚠ Notes (1): "Reconsidered lighter stack"              │
│──────────────────────────────────────────────────────────│
│  [A] Zoom in  [Y] Full wiki page  [B] Back  [X] Notes   │
└──────────────────────────────────────────────────────────┘

D-pad scrolls through sections. A on a section expands it inline (full body). Y fetches the full wiki page — opens on RG if readable, or sends a link to Mac browser. X opens the notes panel.

"Zoom In" Protocol

When the player selects a section and presses A:

┌──────────────────────────────────────────────────────────┐
│  ▶ Rationale                                [FINAL]      │
│──────────────────────────────────────────────────────────│
│  Pi 4 has 4GB total RAM across all containers.           │
│  SqliteSaver is a single file — no server process.       │
│  Survives container restart without data loss.           │
│  FastAPI adds ~50MB overhead. Total stack: ~300MB.       │
│                                                          │
│  Source: wiki/research/langgraph-configs.md#rationale     │
│──────────────────────────────────────────────────────────│
│  [B] Back to summary                                     │
└──────────────────────────────────────────────────────────┘

The expanded view shows the full body text. The footer shows the source pointer. The player always knows where the full artifact lives.

"Full Wiki Page" — Cross-Device

If the full wiki page is too dense for the RG screen (code blocks, tables, long prose), the RG offers to open it elsewhere:

# On Y press, RG sends the output_locale to the Pi
# Pi generates a viewable URL and returns it
# RG displays: "Full page available at: http://100.120.38.37:3001/wiki/langgraph-configs"
# Or sends a push notification to Mac browser

The RG doesn't render the full wiki page — it shows the summary. The full page is for the Mac or another device. The summary is the RG-native representation.

LangGraph Configs in Play

Config Role
Output locale (#6) Pointer to full backend artifact. Lives in state, never rendered on RG.
State schema — summary New key under node_output[node_id]. Sections array with header/body/status.
Node function (#2) Produces BOTH the full output (writes to wiki) AND the summary (writes to state).
Interrupt (#9) Player zooms in on sections, toggles views, opens full wiki page.
HTTP bridge (T-06) RG fetches full wiki content on "zoom in." Pi serves wiki pages via HTTP.

What the Node Function Does

def design_node(state, config, runtime):
    # Run the agent — produces DENSE output
    full_output = call_agent(prompt, context)

    # Write full output to wiki (backend)
    wiki_path = write_to_wiki(full_output, "wiki/research/langgraph-configs.md")

    # ALSO produce a summary — structured, scannable, RG-renderable
    summary = extract_summary(full_output)
    # summary = {
    #     "title": "...",
    #     "sections": [{"header": "...", "body": "...", "status": "..."}, ...]
    # }

    # Write both to state
    return {
        "node_output": {
            "node_14": {
                "output_locale": wiki_path,   # pointer to full artifact
                "summary": summary,            # structured digest
                "status": "completed"
            }
        }
    }

The extract_summary() function is either: - The agent itself producing a structured summary alongside the full output (prompt: "Output: 1) full research, 2) structured summary with sections") - A deterministic parser that extracts headers and first paragraphs from the full output - A second, lightweight LLM call that summarizes the full output into the structured format

Why This Mirrors a Real Wiki/Repo

The summary IS the wiki's table of contents. The sections map to headers in the wiki page. The status markers map to issue states. The output locale is the canonical URL. Nothing is duplicated — the summary points to the backend artifact. The backend artifact is the source of truth. The summary is a viewport into it.

┌───────────────────────────────────────────────────────┐
│  BACKEND (Pi)          │  FRONTEND (RG)                │
│────────────────────────┼───────────────────────────────│
│  wiki/langgraph-       │  SUMMARY                      │
│  configs.md            │  ├─ Recommendation    [FINAL] │
│  (dense, complete)     │  ├─ Rationale         [FINAL] │
│                        │  ├─ Alternatives      [FINAL] │
│  forgejo/issue/42      │  └─ Open Questions    [OPEN]  │
│  (tracking, comments)  │                               │
│                        │  [A] Zoom in on any section   │
│                        │  [Y] Open full wiki page      │
└───────────────────────────────────────────────────────┘

The RG is a remote control for the wiki. The summary tells the player what's there and whether it's verified. Zooming in shows the details. The full artifact is always one button press away — on a device that can actually display it.

Last generated: 2026-05-11 21:55 UTC | v0.2.0