passepartout/literate/package.org

System Interface (package.lisp)

• System Interface (package.lisp)
  • Architectural Intent: The Package Membrane
  • Public API Export
  • Package Implementation
  • Harness Logging State
  • Skills Registry
  • Skill Telemetry State
  • Cognitive Tool Registry
  • Harness Logging Implementation

System Interface (package.lisp)

The package.lisp file defines the public API of the org-agent harness. It serves as the primary membrane between the deterministic core modules and the dynamic world of skills and actuators.

Architectural Intent: The Package Membrane

By strictly defining the public interface, we ensure that skills remain decoupled from the harness implementation details. This allows for sovereign replacement of any component (e.g., swapping the Object Store or the Probabilistic Engine) without breaking existing skills.

flowchart TD
    External[Actuators / Clients] -- Harness Communication --> Package[Package Membrane: API]
    Skills[Dynamic Skills] -- API Calls --> Package
    Package --> Internal[Harness Internal Modules]
    style Package fill:#f9f,stroke:#333,stroke-width:4px

Public API Export

(defpackage :org-agent
  (:use :cl)
  (:export 
   ;; --- Harness Communication ---
   #:frame-message
   #:parse-message
   #:make-hello-message
   #:validate-harness-protocol-schema
   
   ;; --- Daemon Lifecycle ---
   #:start-daemon
   #:stop-daemon
   #:harness-log
   #:main
   
   ;; --- Object Store (CLOSOS) ---
   #:ingest-ast
   #:lookup-object
   #:list-objects-by-type
   #:*object-store*
   #:*history-store*
   #:org-object
   #:org-object-id
   #:org-object-type
   #:org-object-attributes
   #:org-object-parent-id
   #:org-object-children
   #:org-object-version
   #:org-object-last-sync
   #:org-object-vector
   #:org-object-content
   #:org-object-hash
   #:snapshot-object-store
   #:rollback-object-store
   
   ;; --- Context API (Peripheral Vision) ---
   #:context-query-store
   #:context-get-active-projects
   #:context-get-recent-completed-tasks
   #:context-list-all-skills
   #:context-get-skill-source
   #:context-get-system-logs
   #:context-resolve-path
   #:context-get-skill-telemetry
   #:context-assemble-global-awareness
   
   ;; --- Reactive Signal Pipeline ---
   #:process-signal
   #:perceive-gate
   #:probabilistic-gate
   #:consensus-gate
   #:decide-gate
   #:dispatch-gate
   #:inject-stimulus
   #:dispatch-action
   #:register-actuator
   
   ;; --- Skill Engine ---
   #:load-skill-from-org
   #:initialize-all-skills
   #:load-skill-with-timeout
   #:topological-sort-skills
   #:validate-lisp-syntax
   #:lisp-validator-validate
   #:defskill
   #:*skills-registry*
   #:skill
   #:skill-name
   #:skill-priority
   #:skill-dependencies
   #:skill-trigger-fn
   #:skill-probabilistic-prompt
   #:skill-deterministic-fn

   ;; --- Tool Registry ---
   #:def-cognitive-tool
   #:*cognitive-tools*
   #:cognitive-tool
   #:cognitive-tool-name
   #:cognitive-tool-description
   #:cognitive-tool-parameters
   #:cognitive-tool-guard
   #:cognitive-tool-body

   ;; --- Emacs Client Registry ---
   #:*emacs-clients*
   #:*clients-lock*
   #:register-emacs-client
   #:unregister-emacs-client

   ;; --- Probabilistic Engine ---
   #:ask-probabilistic
   #:register-probabilistic-backend
   #:distill-prompt
   #:*provider-cascade*
   
   ;; --- Deterministic Logic ---
   #:list-objects-with-attribute
   #:decide
   
   ;; --- AST Helpers ---
   #:find-headline-missing-id))

Package Implementation

(in-package :org-agent)

Harness Logging State

The harness maintains a thread-safe circular log buffer to provide context for debugging and neural reasoning.

(defvar *system-logs* nil)
(defvar *logs-lock* (bt:make-lock "harness-logs-lock"))
(defvar *max-log-history* 100)

Skills Registry

(defvar *skills-registry* (make-hash-table :test 'equal)
  "Global registry of all loaded skills.")

Skill Telemetry State

(defvar *skill-telemetry* (make-hash-table :test 'equal))
(defvar *telemetry-lock* (bt:make-lock "harness-telemetry-lock"))

Cognitive Tool Registry

The Tool Registry allows the agent to interact with the physical world. Every tool must define a guard (for security) and a body (for execution).

(defvar *cognitive-tools* (make-hash-table :test 'equal))

(defstruct cognitive-tool
  name
  description
  parameters
  guard
  body)

(defmacro def-cognitive-tool (name description parameters &key guard body)
  "Registers a new cognitive tool into the global registry. Parameters must be a list of property lists."
  `(setf (gethash (string-downcase (string ',name)) *cognitive-tools*)
         (make-cognitive-tool :name (string-downcase (string ',name))
                              :description ,description
                              :parameters ',parameters
                              :guard ,guard
                              :body ,body)))

Harness Logging Implementation

Centralized logging function. It simultaneously writes to standard output and the in-memory circular buffer.

(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*)
      (when (> (length *system-logs*) *max-log-history*)
        (setq *system-logs* (subseq *system-logs* 0 *max-log-history*))))
    (format t "~a~%" formatted-msg)
    (finish-output)))