PSF: Mass-regeneration complete. 53/53 high-fidelity blueprints and TDD suites established. Zero-cost Pro bridge active.

notes/org-skill-web-interface.org

@@ -25,36 +25,64 @@ Define the interfaces for system observability and telemetry serving.
 *** TODO Telemetry Data Rendering
 *** TODO Log Tail Exposure
 
+
 * Phase B: Blueprint (PROTOCOL)
 :PROPERTIES:
 :STATUS: SIGNED
 :END:
 
+* Phase B: Blueprint (PROTOCOL)
+
 ** 1. Architectural Intent
-Interfaces for HTTP serving and skill introspection. Source of truth is the kernel telemetry bus and skill registry.
 
-** 2. Semantic Interfaces
-#+begin_src lisp
-(defun start-dashboard (&optional (port 8080))
-  "Starts the telemetry web server.")
+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:
 
-(defun dashboard-home ()
-  "Renders the primary HTML dashboard.")
-#+end_src
+- *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).
 
-* Phase D: Build (Implementation)
+** 2. Semantic Interfaces (Lisp Signatures)
 
-** Server Initialization
-#+begin_src lisp :tangle projects/org-skill-web-interface/src/web-logic.lisp
-(defun start-dashboard (&optional (port 8080))
-  (format nil "Starting dashboard on port ~a" port))
-#+end_src
+*** `telemetry-collector (skill-name start-time end-time success-p)`
 
-* Registration
-#+begin_src lisp
-(defskill :skill-web-interface
-  :priority 10
-  :trigger (lambda (context) nil)
-  :neuro (lambda (context) nil)
-  :symbolic (lambda (action context) action))
-#+end_src
+    - *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.