:PROPERTIES:
:ID:       ce3bef2a-ff93-49a5-ae5e-acde1de19000
:CREATED:  [2026-03-30 Mon 21:16]
:EDITED:   [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Web Dashboard Agent (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :web:dashboard:telemetry:psf:

* Overview
The *Web Dashboard Agent* provides a lightweight telemetry window into the Neurosymbolic Kernel. It exposes the active skill graph and system logs via a local HTML dashboard.

* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:

** 1. Purpose
Define the interfaces for system observability and telemetry serving.

** 2. User Needs
- *Transparency:* Overview of skill performance (executions, time, failures).
- *Accessibility:* Served over a local HTTP port.
- *Observability:* Tail of system logs for debugging.
- *Low Overhead:* Background execution.

** 3. Success Criteria
*** TODO Server Bootstrap Verification
*** TODO Telemetry Data Rendering
*** TODO Log Tail Exposure


* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:

* Phase B: Blueprint (PROTOCOL)

** 1. Architectural Intent

The Web Dashboard Agent will function as a lightweight HTTP server exposing key aspects of the Neurosymbolic Kernel's state and logs.  It will leverage a simple, efficient rendering mechanism (likely string-based initially) to minimize overhead. Key components include:

- *Telemetry Collection:*  A mechanism to passively receive skill execution telemetry data from the kernel.  This could involve a message queue, shared memory, or direct function calls.
- *Data Model:* An in-memory representation of the collected telemetry data, optimized for fast rendering.
- *HTTP Server:* A lightweight HTTP server (e.g., Hunchentoot, embeddable Jetty)  to serve the dashboard.
- *Rendering Engine:* A template-based renderer to generate HTML from the data model.  Consider a simple string-based solution for initial implementation.
- *Log Tail Reader:* A mechanism to efficiently read and expose the tail of the system log file(s).

** 2. Semantic Interfaces (Lisp Signatures)

*** `telemetry-collector (skill-name start-time end-time success-p)`

    - *Purpose:*  Receives telemetry data from the Neurosymbolic Kernel.
    - *Args:*
       - `skill-name`:  Symbol representing the skill (e.g., `'parse-address`).
       - `start-time`:  Timestamp (integer or float) of skill execution start.
       - `end-time`:  Timestamp (integer or float) of skill execution end.
       - `success-p`:  Boolean indicating successful execution (`T` or `NIL`).
    - *Returns:* `T` (acknowledgment).
    - *Side Effects:* Updates the in-memory data model.

*** `current-telemetry-data ()`

    - *Purpose:* Returns the current telemetry data for rendering.
    - *Args:* None.
    - *Returns:* A data structure, likely an alist or plist,  containing aggregated telemetry information suitable for rendering. Example:
      ```lisp
      (list :total-executions 1234 :successful-executions 1200 :failure-rate 0.027 :last-execution-times (list 1678886400 1678886460 1678886520))
      ```

*** `system-log-tail (n)`

    - *Purpose:* Returns the last `n` lines of the system log.
    - *Args:*
       - `n`: Integer representing the number of lines to return.
    - *Returns:* A list of strings, each string representing a line from the log file.

*** `start-web-dashboard (port)`

    - *Purpose:* Starts the HTTP server on the given port.
    - *Args:*
       - `port`: Integer representing the port number.
    - *Returns:* `T` on success, `NIL` on failure.
    - *Side Effects:* Starts the HTTP server in its own thread.

*** `stop-web-dashboard ()`

    - *Purpose:* Stops the HTTP server.
    - *Args:* None.
    - *Returns:* `T` on success, `NIL` on failure.
    - *Side Effects:* Stops the HTTP server.