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

SKILL: Sub-Agent Manager (Concurrency & Parallelism)

• Overview
• Phase A: Demand (PRD)
  • 1. Purpose
  • 2. User Needs
  • 3. Success Criteria
    • Successful spawning of a non-blocking background thread
    • Verification of context isolation (distinct local variables)
    • Autonomous injection of :sub-agent-complete stimulus
    • Thread safety verification using bordeaux-threads locks
• Phase B: Blueprint (PROTOCOL)
  • 1. Architectural Intent
  • 2. Semantic Interfaces
• Phase D: Build (Implementation)
  • Parallel Spawning
• Registration

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)

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)

1. Architectural Intent

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

2. Semantic Interfaces

(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.")

Phase D: Build (Implementation)

Parallel Spawning

(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))))

Registration

(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))))