160 lines
6.9 KiB
Org Mode
160 lines
6.9 KiB
Org Mode
#+TITLE: Skill: Diagnostics (org-skill-diagnostics.org)
|
|
#+AUTHOR: Agent
|
|
#+FILETAGS: :skill:diagnostic:health:
|
|
#+STARTUP: content
|
|
|
|
* Overview
|
|
The *Diagnostics Skill* provides the OpenCortex Agent with the capability to perform self-examinations and environment validation.
|
|
|
|
By moving this logic from the harness to a skill, we enable the Agent's **Reflection Loop** to autonomously run health checks when a tool fails, transforming the Agent into a self-healing system.
|
|
|
|
* Phase A: Demand (Thinking)
|
|
** The Self-Healing Invariant
|
|
In a standard Lisp Machine, the system should be able to reason about its own environment. The `:run-diagnostics` capability ensures the Agent can verify its own dependency chain and XDG directory structure.
|
|
|
|
** XDG Compliance
|
|
The skill strictly validates the POSIX standard paths resolved during bootstrap, ensuring no silent configuration drift occurs.
|
|
|
|
* Phase B: Protocol (Success Criteria)
|
|
|
|
** Test Suite Context
|
|
#+begin_src lisp :tangle (expand-file-name "diagnostics-tests.lisp" (concat (or (identity (getenv "INSTALL_DIR")) ".") "/tests"))
|
|
(defpackage :opencortex-diagnostics-tests
|
|
(:use :cl :fiveam :opencortex)
|
|
(:export #:diagnostics-suite))
|
|
#+end_src
|
|
|
|
#+begin_src lisp :tangle (expand-file-name "diagnostics-tests.lisp" (concat (or (identity (getenv "INSTALL_DIR")) ".") "/tests"))
|
|
(in-package :opencortex-diagnostics-tests)
|
|
#+end_src
|
|
|
|
#+begin_src lisp :tangle (expand-file-name "diagnostics-tests.lisp" (concat (or (identity (getenv "INSTALL_DIR")) ".") "/tests"))
|
|
(def-suite diagnostics-suite :description "Verification of the Diagnostics skill")
|
|
#+end_src
|
|
|
|
#+begin_src lisp :tangle (expand-file-name "diagnostics-tests.lisp" (concat (or (identity (getenv "INSTALL_DIR")) ".") "/tests"))
|
|
(in-suite diagnostics-suite)
|
|
#+end_src
|
|
|
|
** Dependency Tests
|
|
#+begin_src lisp :tangle (expand-file-name "diagnostics-tests.lisp" (concat (or (identity (getenv "INSTALL_DIR")) ".") "/tests"))
|
|
(test test-dependency-check-fail
|
|
"Verify that missing binaries are correctly identified as failures."
|
|
(let ((opencortex::*doctor-required-binaries* '("non-existent-binary-123")))
|
|
(is (null (opencortex:doctor-check-dependencies)))))
|
|
#+end_src
|
|
|
|
* Phase C: Implementation (Build)
|
|
|
|
** Package Context
|
|
#+begin_src lisp :tangle (expand-file-name "org-skill-diagnostics.lisp" (concat (or (identity (getenv "INSTALL_DIR")) ".") "/skills"))
|
|
(in-package :opencortex)
|
|
#+end_src
|
|
|
|
** Skill Metadata
|
|
#+begin_src lisp :tangle (expand-file-name "org-skill-diagnostics.lisp" (concat (or (identity (getenv "INSTALL_DIR")) ".") "/skills"))
|
|
(defparameter *skill-diagnostics*
|
|
'(:name "diagnostics"
|
|
:description "Performs system health checks and environment validation."
|
|
:capabilities (:run-diagnostics)
|
|
:type :deterministic)
|
|
"Skill metadata for the Diagnostics component.")
|
|
#+end_src
|
|
|
|
** Global Configuration
|
|
#+begin_src lisp :tangle (expand-file-name "org-skill-diagnostics.lisp" (concat (or (identity (getenv "INSTALL_DIR")) ".") "/skills"))
|
|
(defvar *doctor-required-binaries* '("sbcl" "emacs" "git" "socat" "nc")
|
|
"List of external binaries required for full system operation.")
|
|
#+end_src
|
|
|
|
** Dependency Verification
|
|
#+begin_src lisp :tangle (expand-file-name "org-skill-diagnostics.lisp" (concat (or (identity (getenv "INSTALL_DIR")) ".") "/skills"))
|
|
(defun doctor-check-dependencies ()
|
|
"Verifies that required external binaries are available in the PATH via a shell probe."
|
|
(let ((all-ok t))
|
|
(harness-log "DOCTOR: Checking system dependencies...")
|
|
(dolist (dep *doctor-required-binaries*)
|
|
(let ((path (ignore-errors
|
|
(uiop:run-program (list "which" dep)
|
|
:output :string :ignore-error-status t))))
|
|
(if (and path (> (length path) 0))
|
|
(harness-log " [OK] Found ~a" dep)
|
|
(progn
|
|
(harness-log " [FAIL] Missing binary: ~a" dep)
|
|
(setf all-ok nil)))))
|
|
all-ok))
|
|
#+end_src
|
|
|
|
** Environment & XDG Validation
|
|
#+begin_src lisp :tangle (expand-file-name "org-skill-diagnostics.lisp" (concat (or (identity (getenv "INSTALL_DIR")) ".") "/skills"))
|
|
(defun doctor-check-env ()
|
|
"Validates XDG directories and environment configuration against the POSIX standard."
|
|
(harness-log "DOCTOR: Checking XDG environment...")
|
|
(let ((all-ok t)
|
|
(config-dir (uiop:getenv "OC_CONFIG_DIR"))
|
|
(data-dir (uiop:getenv "OC_DATA_DIR"))
|
|
(state-dir (uiop:getenv "OC_STATE_DIR"))
|
|
(memex-dir (uiop:getenv "MEMEX_DIR")))
|
|
|
|
(flet ((check-dir (name path critical)
|
|
(if (and path (> (length path) 0))
|
|
(if (uiop:directory-exists-p path)
|
|
(harness-log " [OK] ~a: ~a" name path)
|
|
(progn
|
|
(harness-log " [FAIL] ~a directory missing: ~a" name path)
|
|
(when critical (setf all-ok nil))))
|
|
(progn
|
|
(harness-log " [FAIL] ~a variable not set." name)
|
|
(when critical (setf all-ok nil))))))
|
|
|
|
(check-dir "Config (OC_CONFIG_DIR)" config-dir t)
|
|
(check-dir "Data (OC_DATA_DIR)" data-dir t)
|
|
(check-dir "State (OC_STATE_DIR)" state-dir t)
|
|
(check-dir "Memex (MEMEX_DIR)" memex-dir t))
|
|
all-ok))
|
|
#+end_src
|
|
|
|
** LLM Connectivity
|
|
#+begin_src lisp :tangle (expand-file-name "org-skill-diagnostics.lisp" (concat (or (identity (getenv "INSTALL_DIR")) ".") "/skills"))
|
|
(defun doctor-check-llm ()
|
|
"Tests connectivity to primary LLM providers. Non-critical fallback allowed."
|
|
(harness-log "DOCTOR: Checking LLM connectivity...")
|
|
(let ((openrouter-key (uiop:getenv "OPENROUTER_API_KEY")))
|
|
(if (and openrouter-key (> (length openrouter-key) 0))
|
|
(progn
|
|
(harness-log " [OK] OpenRouter API Key detected.")
|
|
t)
|
|
(progn
|
|
(harness-log " [WARN] No OpenRouter API Key. Falling back to local inference only.")
|
|
t))))
|
|
#+end_src
|
|
|
|
** Orchestration
|
|
#+begin_src lisp :tangle (expand-file-name "org-skill-diagnostics.lisp" (concat (or (identity (getenv "INSTALL_DIR")) ".") "/skills"))
|
|
(defun doctor-run-all ()
|
|
"Executes the full diagnostic suite and returns T if system is healthy."
|
|
(harness-log "==================================================")
|
|
(harness-log " OPENCORTEX DOCTOR: Commencing Health Check")
|
|
(harness-log "==================================================")
|
|
(let ((dep-ok (doctor-check-dependencies))
|
|
(env-ok (doctor-check-env))
|
|
(llm-ok (doctor-check-llm)))
|
|
(harness-log "==================================================")
|
|
(if (and dep-ok env-ok)
|
|
(progn
|
|
(harness-log " ✓ SYSTEM HEALTHY: Ready for ignition.")
|
|
t)
|
|
(progn
|
|
(harness-log " ✗ SYSTEM UNHEALTHY: Fix the errors above.")
|
|
nil))))
|
|
#+end_src
|
|
|
|
** CLI Entry Point
|
|
#+begin_src lisp :tangle (expand-file-name "org-skill-diagnostics.lisp" (concat (or (identity (getenv "INSTALL_DIR")) ".") "/skills"))
|
|
(defun doctor-main ()
|
|
"Entry point for the 'doctor' CLI command."
|
|
(if (doctor-run-all)
|
|
(uiop:quit 0)
|
|
(uiop:quit 1)))
|
|
#+end_src
|