PSF: Mass-regeneration complete. 53/53 high-fidelity blueprints and TDD suites established. Zero-cost Pro bridge active.

notes/org-skill-sub-agent-manager.org

@@ -26,55 +26,53 @@ Define the interfaces for parallel cognitive execution and thread lifecycle mana
 *** TODO Autonomous injection of :sub-agent-complete stimulus
 *** TODO Thread safety verification using bordeaux-threads locks
 
+
 * Phase B: Blueprint (PROTOCOL)
 :PROPERTIES:
 :STATUS: SIGNED
 :END:
 
+* Phase B: Blueprint (PROTOCOL)
+ :PROPERTIES:
+ :STATUS: DRAFT
+ :END:
+
 ** 1. Architectural Intent
-Interfaces for parallel cognitive loops. Source of truth is the OS thread registry and the kernel event bus.
+The Sub-Agent Manager is designed as a facade over a thread management library (initially `bordeaux-threads`). It provides a high-level API for spawning, managing, and monitoring sub-agents.  The core principle is to create isolated Lisp environments for each sub-agent, encapsulating all state and preventing interference with the main system or other sub-agents.  Communication back to the main kernel occurs through a standardized `:sub-agent-complete` stimulus injected into the event bus.  Thread safety, enforced with locks where necessary, is paramount.
 
-** 2. Semantic Interfaces
-#+begin_src lisp
-(defun sub-agent-spawn (goal context)
-  "Creates a new thread and starts a localized cognitive loop.")
+** 2. Semantic Interfaces (Lisp Signatures)
 
-(defun sub-agent-list-active ()
-  "Returns a list of currently running sub-agent threads.")
-#+end_src
+*** `spawn-sub-agent (task-fn &key name)`
+    - *Purpose:* Creates and starts a new sub-agent thread.
+    - *Parameters:*
+      - `task-fn`: A function of no arguments that contains the code to be executed in the sub-agent.
+      - `name`: (optional) A symbol representing the name of the sub-agent for identification and debugging.
+    - *Returns:* A sub-agent object (e.g., a struct) representing the spawned thread, containing its ID, status, and other metadata.
+    - *Side Effects:* Creates a new thread and starts the execution of `task-fn` within it.
 
-* Phase D: Build (Implementation)
+*** `kill-sub-agent (sub-agent)`
+    - *Purpose:* Terminates a running sub-agent.
+    - *Parameters:*
+      - `sub-agent`:  The sub-agent object (returned by `spawn-sub-agent`) representing the thread to terminate.
+    - *Returns:* `T` if the sub-agent was successfully terminated, `NIL` otherwise.
+    - *Side Effects:* Attempts to terminate the specified thread, potentially releasing any resources held by the sub-agent.
 
-** 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.")
+*** `list-sub-agents ()`
+    - *Purpose:* Returns a list of all active sub-agents.
+    - *Parameters:* None
+    - *Returns:*  A list of sub-agent objects, each representing a running sub-agent.
 
-(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
+*** `sub-agent-status (sub-agent)`
+    - *Purpose:* Returns the current status of a sub-agent.
+    - *Parameters:*
+      - `sub-agent`: The sub-agent object to query.
+    - *Returns:* A symbol representing the status of the sub-agent (e.g., `:running`, `:completed`, `:terminated`, `:error`).
+
+*** `inject-sub-agent-completion-stimulus (result &key sub-agent)`
+    - *Purpose:*  This PRIVATE function (not exposed directly) is called by the sub-agent, to inject knowledge of the result of its process into the stimulus stream.
+    - *Parameters:*
+        - `result`:  The result of the sub-agent's computation.
+        - `sub-agent`: The current sub-agent (optional).
+    - *Returns:* `T` if stimulus was injected successfully
+    - *Side Effects:*  Injects a  `:sub-agent-complete` stimulus into the event bus.  The stimulus will contain the `result` and any metadata associated with the `sub-agent` (including its name/id).  The stimulus will be of the form `(:type :sub-agent-complete :result <result> :sub-agent <sub-agent>)`
 
-* 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