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

docs: global terminology update from kernel/core to harness

Browse Source
This commit is contained in:
Amr Gharbeia
2026-04-12 18:28:11 -04:00
parent 475f79e79d
commit 3f8c37712c
71 changed files with 255 additions and 499 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
literate/context.org
View File

@@ -80,11 +80,11 @@ Reads the raw literate source of a specific skill. This is crucial for "System 2
#+end_src
** Kernel Logs (context-get-system-logs)
Retrieves the most recent lines from the kernel's internal log.
Retrieves the most recent lines from the harness's internal log.
#+begin_src lisp :tangle ../src/context.lisp
(defun context-get-system-logs (&optional (limit 20))
"Retrieves the most recent lines from the kernel's internal log."
"Retrieves the most recent lines from the harness's internal log."
(bt:with-lock-held (*logs-lock*)
(let ((count (min limit (length *system-logs*)))) (subseq *system-logs* 0 count))))
#+end_src

12
literate/neurosymbolic.org
View File

@@ -101,7 +101,7 @@ sequenceDiagram
(when backend-fn
(push (bt:make-thread
(lambda ()
(kernel-log "ASSOCIATIVE [Consensus]: Querying backend ~a..." backend)
(harness-log "ASSOCIATIVE [Consensus]: Querying backend ~a..." backend)
(let* ((model (when *model-selector-fn* (funcall *model-selector-fn* backend context)))
(result (ignore-errors
(if model
@@ -125,7 +125,7 @@ sequenceDiagram
(or (dolist (backend backends)
(let ((backend-fn (gethash backend *neuro-backends*)))
(when backend-fn
(kernel-log "ASSOCIATIVE: Attempting backend ~a..." backend)
(harness-log "ASSOCIATIVE: Attempting backend ~a..." backend)
(let* ((model (when *model-selector-fn* (funcall *model-selector-fn* backend context)))
(result (if model
(funcall backend-fn prompt system-prompt :model model)
@@ -149,7 +149,7 @@ Crucially, it mandates that the output be a Common Lisp property list, forcing t
(global-context (context-assemble-global-awareness)))
(if active-skill
(progn
(kernel-log "ASSOCIATIVE: Engaging skill '~a'~%" (skill-name active-skill))
(harness-log "ASSOCIATIVE: Engaging skill '~a'~%" (skill-name active-skill))
(let* ((prompt-generator (skill-neuro-prompt active-skill))
(raw-prompt (when prompt-generator (funcall prompt-generator context)))
(full-system-prompt (concatenate 'string
@@ -177,7 +177,7 @@ To call a tool, you MUST use:
(raw-thoughts (cl-ppcre:split (cl-ppcre:quote-meta-chars "|CONSENSUS-SEP|") thought))
(suggestions nil))
(dolist (raw-thought raw-thoughts)
(kernel-log "ASSOCIATIVE RAW: ~a~%" raw-thought)
(harness-log "ASSOCIATIVE RAW: ~a~%" raw-thought)
(let* ((cleaned-thought
(let ((match (cl-ppcre:scan-to-strings "(?s)```(?:lisp)?\\n?(.*?)\\n?```" raw-thought)))
(if match
@@ -191,7 +191,7 @@ To call a tool, you MUST use:
(list :sensor :syntax-error
:code cleaned-thought
:error (format nil "~a" c)))))))
(kernel-log "ASSOCIATIVE Suggestion: ~a~%" cleaned-thought)
(harness-log "ASSOCIATIVE Suggestion: ~a~%" cleaned-thought)
(when (and suggestion (listp suggestion))
(push suggestion suggestions))))
(if (and *consensus-enabled-p* suggestions)
@@ -261,7 +261,7 @@ flowchart LR
;; If any gate returns a LOG or EVENT (blocking/intercepting), stop and return it.
(when (and (listp current-action)
(member (getf current-action :type) '(:LOG :EVENT :log :event)))
(kernel-log "DELIBERATE: Intercepted by skill '~a'~%" (skill-name skill))
(harness-log "DELIBERATE: Intercepted by skill '~a'~%" (skill-name skill))
(return-from decide current-action))))
current-action))

6
literate/object-store.org
View File

@@ -126,7 +126,7 @@ Because objects are stored immutably in the `*history-store*`, a snapshot is no
(push (list :timestamp (get-universal-time) :data snapshot) *object-store-snapshots*)
(when (> (length *object-store-snapshots*) 20)
(setf *object-store-snapshots* (subseq *object-store-snapshots* 0 20)))
(kernel-log "MEMORY - CoW Object Store snapshot created.")))
(harness-log "MEMORY - CoW Object Store snapshot created.")))
#+end_src
** Memory Rollback (rollback-object-store)
@@ -138,8 +138,8 @@ Restores the state of the Memex from one of the previous snapshots.
(let ((snapshot (nth index *object-store-snapshots*)))
(if snapshot
(progn (setf *object-store* (copy-hash-table (getf snapshot :data)))
(kernel-log "MEMORY - Object Store rolled back to snapshot ~a" index))
(kernel-log "MEMORY ERROR - Snapshot ~a not found." index))))
(harness-log "MEMORY - Object Store rolled back to snapshot ~a" index))
(harness-log "MEMORY ERROR - Snapshot ~a not found." index))))
#+end_src
** Lookup Utilities

8
literate/package.org
View File

@@ -18,7 +18,7 @@ The `package.lisp` file defines the public API of the `org-agent` kernel. It exp
;; --- Daemon Lifecycle ---
#:start-daemon
#:stop-daemon
#:kernel-log
#:harness-log
#:main
;; --- Object Store (CLOSOS) ---
@@ -133,7 +133,7 @@ The `package.lisp` file defines the public API of the `org-agent` kernel. It exp
** Kernel Logging State
#+begin_src lisp :tangle ../src/package.lisp
(defvar *system-logs* nil)
(defvar *logs-lock* (bt:make-lock "kernel-logs-lock"))
(defvar *logs-lock* (bt:make-lock "harness-logs-lock"))
(defvar *max-log-history* 100)
#+end_src
@@ -171,8 +171,8 @@ The `package.lisp` file defines the public API of the `org-agent` kernel. It exp
** Kernel Logging Implementation
#+begin_src lisp :tangle ../src/package.lisp
(defun kernel-log (msg &rest args)
"Centralized logging for the kernel."
(defun harness-log (msg &rest args)
"Centralized logging for the harness."
(let ((formatted-msg (apply #'format nil msg args)))
(bt:with-lock-held (*logs-lock*)
(push formatted-msg *system-logs*)

4
literate/protocol.org
View File

@@ -7,7 +7,7 @@
** Deep Reasoning: Why Hex-Length Framing?
Streaming raw JSON over a socket is fragile. If a 5MB Org AST is fragmented by the OS network stack, a standard parser will crash or desynchronize.
- **Physical Boundary:** By prefixing every message with a 6-character hex length, we create a deterministic physical boundary.
- **Actuator-Agnosticism:** This protocol makes the kernel a "Dumb Terminal" host. Any program (Bash, Python, WebSockets) that can calculate a length and send bytes can now become an agentic interface.
- **Actuator-Agnosticism:** This protocol makes the harness a "Dumb Terminal" host. Any program (Bash, Python, WebSockets) that can calculate a length and send bytes can now become an agentic interface.
** Package Context
We begin by ensuring we are in the correct package.
@@ -98,7 +98,7 @@ Parsing is the inverse of framing. This function performs three critical safety
#+end_src
** Handshaking (make-hello-message)
Every OACP connection begins with a `HELLO` handshake. This function constructs the standard response that the kernel sends to a client to announce its capabilities and version.
Every OACP connection begins with a `HELLO` handshake. This function constructs the standard response that the harness sends to a client to announce its capabilities and version.
#+begin_src lisp :tangle ../src/protocol.lisp
(defun make-hello-message (version)

24
literate/skills.org
View File

@@ -167,7 +167,7 @@ Calculates the correct load order for a directory of skill filepaths, detecting
The core "hot-loading" mechanism. It extracts Lisp blocks from an Org file and evaluates them within a dedicated package ("Jail").
*** Phase A: Demand
- *Need:* Safely load skills from `.org` files without evaluating docstrings or kernel-level tangled blocks as logic.
- *Need:* Safely load skills from `.org` files without evaluating docstrings or harness-level tangled blocks as logic.
- *Success:* Exclude `#+begin_src lisp :tangle` blocks and ignore `:PROPERTIES:` and `:END:` drawers embedded within src blocks.
*** Phase B: Blueprint
@@ -211,7 +211,7 @@ The loader must actively scan block arguments and filter out those containing `:
(unless valid-p
(error "Syntax Error: ~a" err)))
(kernel-log "KERNEL: Jailing skill '~a' in package ~a" skill-base-name pkg-name)
(harness-log "HARNESS: Jailing skill '~a' in package ~a" skill-base-name pkg-name)
(unless (find-package pkg-name)
(let ((new-pkg (make-package pkg-name :use '(:cl))))
(do-external-symbols (sym (find-package :org-agent)) (shadowing-import sym new-pkg))))
@@ -223,7 +223,7 @@ The loader must actively scan block arguments and filter out those containing `:
t)))
(error (c)
(let ((msg (format nil "~a" c)))
(kernel-log "LOADER ERROR in skill '~a': ~a" skill-base-name msg)
(harness-log "LOADER ERROR in skill '~a': ~a" skill-base-name msg)
(setf (skill-entry-status entry) :failed)
(setf (skill-entry-error-log entry) msg)
nil)))))
@@ -248,7 +248,7 @@ Wraps the skill loader in a thread with a hard timeout to prevent a single malfo
(when (eq finished :error) (return :error))
(unless (bt:thread-alive-p thread) (return :error))
(when (> (- (get-internal-real-time) start-time) timeout-units)
(kernel-log "KERNEL: Timing out skill ~a..." (pathname-name filepath))
(harness-log "HARNESS: Timing out skill ~a..." (pathname-name filepath))
#+sbcl (sb-thread:terminate-thread thread)
#-sbcl (bt:destroy-thread thread)
(return :timeout))
@@ -256,7 +256,7 @@ Wraps the skill loader in a thread with a hard timeout to prevent a single malfo
#+end_src
** Initializing All Skills (initialize-all-skills)
The unified orchestrator for the kernel boot sequence. It scans the environment, calculates dependencies, and loads the system brain.
The unified orchestrator for the harness boot sequence. It scans the environment, calculates dependencies, and loads the system brain.
#+begin_src lisp :tangle ../src/skills.lisp
(defun initialize-all-skills ()
@@ -267,7 +267,7 @@ The unified orchestrator for the kernel boot sequence. It scans the environment,
(skills-dir (if resolved-path (uiop:ensure-directory-pathname resolved-path) nil)))
(unless (and skills-dir (uiop:directory-exists-p skills-dir))
(kernel-log "KERNEL ERROR: Skills directory not found: ~a" skills-dir-str)
(harness-log "HARNESS ERROR: Skills directory not found: ~a" skills-dir-str)
(return-from initialize-all-skills nil))
(let ((sorted-files (topological-sort-skills skills-dir)))
@@ -275,12 +275,12 @@ The unified orchestrator for the kernel boot sequence. It scans the environment,
(unless (member "org-skill-agent" sorted-files :key #'pathname-name :test #'string-equal)
(error "BOOT FAILURE: org-skill-agent.org not found in skills directory."))
(kernel-log "==================================================")
(kernel-log " LOADER: Initializing ~a skills..." (length sorted-files))
(harness-log "==================================================")
(harness-log " LOADER: Initializing ~a skills..." (length sorted-files))
(dolist (file sorted-files)
(let ((skill-name (pathname-name file)))
(kernel-log " LOADER: Loading ~a..." skill-name)
(harness-log " LOADER: Loading ~a..." skill-name)
(load-skill-with-timeout file 5)))
;; Final Summary
@@ -289,8 +289,8 @@ The unified orchestrator for the kernel boot sequence. It scans the environment,
(declare (ignore k))
(if (eq (skill-entry-status v) :ready) (incf ready) (incf failed)))
*skill-catalog*)
(kernel-log " LOADER: Boot Complete. [Ready: ~a] [Failed: ~a]" ready failed)
(kernel-log "==================================================")
(harness-log " LOADER: Boot Complete. [Ready: ~a] [Failed: ~a]" ready failed)
(harness-log "==================================================")
(values ready failed)))))
#+end_src
@@ -325,7 +325,7 @@ We register a set of standard cognitive tools that all skills can use.
*** The Eval Tool
#+begin_src lisp :tangle ../src/skills.lisp
(def-cognitive-tool :eval "Evaluates raw Common Lisp code in the kernel image. Use this for complex calculations or internal state inspection."
(def-cognitive-tool :eval "Evaluates raw Common Lisp code in the harness image. Use this for complex calculations or internal state inspection."
((:code :type :string :description "The Lisp code to evaluate"))
:guard (lambda (args context)
(declare (ignore context))

2
literate/system-definition.org
View File

@@ -31,7 +31,7 @@
(:file "src/lisp-repair")
(:file "src/bouncer")
(:file "src/verification-logic")
(:file "src/core")
(:file "src/loop")
(:file "src/gateway-telegram")
(:file "src/gateway-signal")
(:file "src/gateway-matrix")