amr/passepartout
1
0
Fork 0
Code Issues 15 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs: rename OACP to Harness Protocol and revamp protocol.org with verbose literate text

Browse Source
This commit is contained in:
Amr Gharbeia
2026-04-12 18:54:00 -04:00
parent 5c7a925e4d
commit 117f3143d3
16 changed files with 111 additions and 82 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
src/org-agent.el
View File

@@ -12,7 +12,7 @@
;; org-agent provides a Neurosymbolic Lisp Machine interface for Emacs.
;; It acts as the sensor/actuator array, communicating with a persistent
;; Common Lisp daemon over a high-speed OACP socket.
;; Common Lisp daemon over a high-speed Harness Protocol socket.
;;; Code:
@@ -100,7 +100,7 @@ will assume you have started it manually (e.g., via SBCL)."
(message "org-agent: Killed daemon process.")))
(defun org-agent--filter (proc string)
"Handle incoming OACP messages from the daemon via PROC with STRING."
"Handle incoming Harness Protocol messages from the daemon via PROC with STRING."
(let ((buf (process-buffer proc)))
(when (buffer-live-p buf)
(with-current-buffer buf
@@ -109,7 +109,7 @@ will assume you have started it manually (e.g., via SBCL)."
(org-agent--process-buffer buf proc)))))
(defun org-agent--process-buffer (buffer &optional proc)
"Process the OACP message BUFFER, optionally using PROC."
"Process the Harness Protocol message BUFFER, optionally using PROC."
(with-current-buffer buffer
(goto-char (point-min))
(while (>= (buffer-size) 6)
@@ -127,13 +127,13 @@ will assume you have started it manually (e.g., via SBCL)."
(setq msg-len 1000000)))))) ; Break loop
(defun org-agent--plist-get (plist prop)
"Case-insensitive keyword lookup for OACP compatibility."
"Case-insensitive keyword lookup for Harness Protocol compatibility."
(or (plist-get plist prop)
(plist-get plist (intern (upcase (symbol-name prop))))
(plist-get plist (intern (downcase (symbol-name prop))))))
(defun org-agent--handle-message (proc plist)
"Route and execute incoming OACP messages from PROC using PLIST."
"Route and execute incoming Harness Protocol messages from PROC using PLIST."
(let ((type (org-agent--plist-get plist :type))
(id (org-agent--plist-get plist :id))
(payload (or (org-agent--plist-get plist :payload) plist)))
@@ -190,7 +190,7 @@ will assume you have started it manually (e.g., via SBCL)."
(message "org-agent: Connection lost.")))
(defun org-agent-send (plist)
"Send a Lisp PLIST to the daemon using OACP framing."
"Send a Lisp PLIST to the daemon using Harness Protocol framing."
(let* ((msg (prin1-to-string plist))
(len (length msg))
(framed (format "%06x%s" len msg)))

2
src/package.lisp
View File

@@ -1,7 +1,7 @@
(defpackage :org-agent
(:use :cl)
(:export
;; --- OACP Protocol ---
;; --- Harness Protocol Protocol ---
#:frame-message
#:parse-message
#:make-hello-message

22
src/protocol-validator.lisp
View File

@@ -1,39 +1,39 @@
(in-package :org-agent)
(defun validate-oacp-schema (msg)
"Strict structural validation for incoming OACP messages."
(defun validate-harness-protocol-schema (msg)
"Strict structural validation for incoming Harness Protocol messages."
(unless (listp msg)
(error "OACP Schema Error: Message must be a property list (got ~s)" (type-of msg)))
(error "Harness Protocol Schema Error: Message must be a property list (got ~s)" (type-of msg)))
(let ((type (getf msg :type)))
(unless (member type '(:REQUEST :EVENT :RESPONSE :LOG))
(error "OACP Schema Error: Invalid message type '~a'" type))
(error "Harness Protocol Schema Error: Invalid message type '~a'" type))
(case type
(:REQUEST
(unless (getf msg :target)
(error "OACP Schema Error: REQUEST missing mandatory :target"))
(error "Harness Protocol Schema Error: REQUEST missing mandatory :target"))
(unless (getf msg :payload)
(error "OACP Schema Error: REQUEST missing mandatory :payload")))
(error "Harness Protocol Schema Error: REQUEST missing mandatory :payload")))
(:EVENT
(let ((payload (getf msg :payload)))
(unless (and payload (listp payload))
(error "OACP Schema Error: EVENT missing or invalid :payload"))
(error "Harness Protocol Schema Error: EVENT missing or invalid :payload"))
(unless (or (getf payload :action) (getf payload :sensor))
(error "OACP Schema Error: EVENT payload must contain :action or :sensor"))))
(error "Harness Protocol Schema Error: EVENT payload must contain :action or :sensor"))))
(:RESPONSE
(unless (getf msg :payload)
(error "OACP Schema Error: RESPONSE missing mandatory :payload"))))
(error "Harness Protocol Schema Error: RESPONSE missing mandatory :payload"))))
t))
(defskill :skill-oacp-validator
(defskill :skill-harness-protocol-validator
:priority 95
:trigger (lambda (ctx) (member (getf (getf ctx :payload) :sensor) '(:protocol-received)))
:neuro nil
:symbolic (lambda (action ctx)
(declare (ignore ctx))
(validate-oacp-schema action)
(validate-harness-protocol-schema action)
action))

16
src/protocol.lisp
View File

@@ -9,11 +9,11 @@
(defun frame-message (msg-string)
"Prefix MSG-STRING with a 6-character hex length (lowercase).
FUTURE: Will also prefix a 64-char HMAC signature when OACP_ENFORCE_HMAC=true."
If HARNESS_PROTOCOL_ENFORCE_HMAC is true, it prefixes a 64-char HMAC signature."
(let ((len (length msg-string))
(enforce-hmac (uiop:getenv "OACP_ENFORCE_HMAC")))
(enforce-hmac (uiop:getenv "HARNESS_PROTOCOL_ENFORCE_HMAC")))
(if (and enforce-hmac (string-equal enforce-hmac "true"))
(let* ((secret (or (uiop:getenv "OACP_HMAC_SECRET") "default-insecure-secret"))
(let* ((secret (or (uiop:getenv "HARNESS_PROTOCOL_HMAC_SECRET") "default-insecure-secret"))
(key (ironclad:ascii-string-to-byte-array secret))
(hmac (ironclad:make-mac :hmac key :sha256))
(payload-bytes (ironclad:ascii-string-to-byte-array msg-string)))
@@ -26,11 +26,11 @@
"Extract and parse the S-expression from a framed string, securely preventing reader macro injection."
(when (< (length framed-string) 6)
(error "Framed string too short"))
(let* ((enforce-hmac (uiop:getenv "OACP_ENFORCE_HMAC"))
(let* ((enforce-hmac (uiop:getenv "HARNESS_PROTOCOL_ENFORCE_HMAC"))
(use-hmac (and enforce-hmac (string-equal enforce-hmac "true")))
(prefix-len (if use-hmac 70 6)))
(when (< (length framed-string) prefix-len)
(error "Framed string too short for OACP signature/length"))
(error "Framed string too short for Harness Protocol signature/length"))
(let* ((len-str (subseq framed-string 0 6))
(signature (when use-hmac (subseq framed-string 6 70)))
@@ -43,19 +43,19 @@
;; HMAC Validation Foundation
(when use-hmac
(let* ((secret (or (uiop:getenv "OACP_HMAC_SECRET") "default-insecure-secret"))
(let* ((secret (or (uiop:getenv "HARNESS_PROTOCOL_HMAC_SECRET") "default-insecure-secret"))
(key (ironclad:ascii-string-to-byte-array secret))
(hmac (ironclad:make-mac :hmac key :sha256))
(payload-bytes (ironclad:ascii-string-to-byte-array actual-msg)))
(ironclad:update-mac hmac payload-bytes)
(let ((expected-signature (ironclad:byte-array-to-hex-string (ironclad:produce-mac hmac))))
(unless (string-equal signature expected-signature)
(error "OACP Integrity Failure: HMAC signature mismatch")))))
(error "Harness Protocol Integrity Failure: HMAC signature mismatch")))))
;; SECURITY: Prevent Reader Macro Injection (e.g. #. ) during deserialization
(let ((*read-eval* nil))
(let ((msg (read-from-string actual-msg)))
(validate-oacp-schema msg)
(validate-harness-protocol-schema msg)
msg)))))
(defun make-hello-message (version)