org-agent-contrib/org-skill-emacs-bridge.org

SKILL: Emacs Bridge Agent (Universal Literate Note)

• Overview
• Phase A: Demand (PRD)
  • 1. Purpose
  • 2. User Needs
  • 3. Success Criteria
    • Socket Listener Initialization
    • Multi-client Connection Handling
    • Harness Communication Message Framing Verification
• Phase B: Blueprint (PROTOCOL)
  • 1. Architectural Intent
  • 2. Semantic Interfaces
• Phase D: Build (Implementation)
  • TCP Sensory Layer
  • Outbound Actuation
• Registration

Overview

The Emacs Bridge Agent is the primary sensory and motor interface to Emacs. It abstracts TCP socket management, allowing the core kernel to interact with buffers as native data structures.

Phase A: Demand (PRD)

1. Purpose

Define the transport layer for Org-Agent Communication Protocol (Harness Communication).

2. User Needs

• Isolation: Kernel remains transport-agnostic.
• Persistence: Multi-client server support for simultaneous sessions.
• Dispatch: Reliable routing of actions to actuators and sensors to the kernel.

3. Success Criteria

TODO Socket Listener Initialization

TODO Multi-client Connection Handling

TODO Harness Communication Message Framing Verification

Phase B: Blueprint (PROTOCOL)

1. Architectural Intent

Interfaces for TCP I/O and protocol framing. Source of truth is the Harness Communication specification.

2. Semantic Interfaces

(defun start-emacs-server (&key (port 9105))
  "Starts the Harness Communication listener.")

(defun broadcast-to-emacs (action-plist)
  "Sends a framed message to all connected clients.")

Phase D: Build (Implementation)

TCP Sensory Layer

(defun handle-emacs-client (stream)
  ;; Logic for parsing length-prefixed Harness Communication messages
  (format nil "Handling client on stream: ~a" stream))

Outbound Actuation

(defun stream-to-emacs (stream action-plist)
  "Streams a chunk of data to a specific Emacs client over Harness Communication using framing."
  (let* ((type (or (getf action-plist :type) :request))
         (payload (getf action-plist :payload))
         ;; Ensure Emacs always receives a :payload drawer
         (envelope (if (and (getf action-plist :type) payload)
                       action-plist
                       (let ((clean-payload (copy-list action-plist)))
                         (remf clean-payload :type)
                         (remf clean-payload :id)
                         (list :type type
                               :id (or (getf action-plist :id) (get-universal-time))
                               :payload clean-payload))))
         (msg (prin1-to-string envelope))
         (len (length msg))
         (framed (format nil "~6,'0x~a" len msg)))
    (handler-case 
        (progn
          (write-string framed stream)
          (finish-output stream))
      (error (c) 
        (kernel-log "BRIDGE - Lost client: ~a" stream)
        (org-agent:unregister-emacs-client stream)))))

(defun broadcast-to-emacs (action-plist context)
  "Sends a framed message back to the client that sent the stimulus, or all clients if async."
  (let ((stream (getf context :reply-stream)))
    (if stream
        (stream-to-emacs stream action-plist)
        (progn
          (kernel-log "BRIDGE - Async broadcast to all clients...")
          (bt:with-lock-held (org-agent:*clients-lock*)
            (dolist (s org-agent:*emacs-clients*)
              (stream-to-emacs s action-plist)))))))

Registration

(org-agent:register-actuator :emacs #'broadcast-to-emacs)

(defskill :skill-emacs-bridge
  :priority 100
  :trigger (lambda (context) nil)
  :neuro (lambda (context) nil)
  :symbolic (lambda (action context) action))