#+TITLE: SKILL: Sub-Agent Manager (Concurrency & Parallelism)
#+ID: skill-sub-agent-manager
#+STARTUP: content
#+FILETAGS: :concurrency:parallelism:threads:psf:

* Overview
The *Sub-Agent Manager* enables the Neurosymbolic Lisp Machine to handle multiple concurrent thoughts. It allows the primary kernel to "spawn" lightweight, isolated Lisp threads (sub-agents) to perform long-running or background tasks (research, massive refactors, etc.) without blocking the main event bus.

* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:

** 1. Purpose
Define the interfaces for parallel cognitive execution and thread lifecycle management.

** 2. User Needs
- *Non-Blocking Execution:* Spawn background threads for long-running tasks.
- *Context Isolation:* Sub-agents must have their own execution context to prevent parent context poisoning.
- *Communication Loop:* Sub-agents must inject a "Return Stimulus" upon completion.
- *Observability:* Ability to list and terminate active sub-agents.

** 3. Success Criteria
*** TODO Successful spawning of a non-blocking background thread
*** TODO Verification of context isolation (distinct local variables)
*** TODO Autonomous injection of :sub-agent-complete stimulus
*** TODO Thread safety verification using bordeaux-threads locks

* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:

** 1. Architectural Intent
Interfaces for parallel cognitive loops. Source of truth is the OS thread registry and the kernel event bus.

** 2. Semantic Interfaces
#+begin_src lisp
(defun sub-agent-spawn (goal context)
  "Creates a new thread and starts a localized cognitive loop.")

(defun sub-agent-list-active ()
  "Returns a list of currently running sub-agent threads.")
#+end_src

* Phase D: Build (Implementation)

** Parallel Spawning
#+begin_src lisp :tangle projects/org-skill-sub-agent-manager/src/concurrency-logic.lisp
(defvar *active-sub-agents* '() "Registry of active sub-agent thread objects.")

(defun sub-agent-spawn (goal parent-context)
  (let ((thread-name (format nil "sub-agent-~a" (get-universal-time))))
    (kernel-log "CONCURRENCY - Spawning sub-agent for goal: ~a" goal)
    (let ((new-thread 
           (bt:make-thread 
            (lambda ()
              (handler-case
                  (let* ((context `(:type :SUB-GOAL :payload (:goal ,goal :parent ,parent-context)))
                         (result (org-agent:think context))) ; Execute sub-goal thinking
                    ;; Inject the result back into the main kernel bus
                    (org-agent:inject-stimulus 
                     `(:type :EVENT :payload (:sensor :sub-agent-complete :result ,result :goal ,goal))))
                (error (c)
                  (kernel-log "SUB-AGENT ERROR (~a): ~a" thread-name c))))
            :name thread-name)))
      (push new-thread *active-sub-agents*)
      (format nil "SUCCESS - Sub-agent '~a' is now thinking in the background." thread-name))))
#+end_src

* Registration
#+begin_src lisp
(defskill :skill-sub-agent-manager
  :priority 90
  :trigger (lambda (context) (eq (getf (getf context :payload) :action) :spawn))
  :neuro (lambda (context) nil)
  :symbolic (lambda (action context) 
              (let ((goal (getf (getf action :payload) :goal)))
                (sub-agent-spawn goal context))))
#+end_src