83 lines
4.3 KiB
Org Mode
83 lines
4.3 KiB
Org Mode
:PROPERTIES:
|
|
:ID: e870d860-5db7-443a-aaf3-23cd5521b27c
|
|
:CREATED: [2026-03-31 Tue 18:28]
|
|
:EDITED: [2026-04-07 Tue 13:42]
|
|
:END:
|
|
#+TITLE: SKILL: Sub-Agent Manager (Concurrency & Parallelism)
|
|
#+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:
|
|
|
|
* Phase B: Blueprint (PROTOCOL)
|
|
:PROPERTIES:
|
|
:STATUS: DRAFT
|
|
:END:
|
|
|
|
** 1. Architectural Intent
|
|
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 (Lisp Signatures)
|
|
|
|
*** `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.
|
|
|
|
*** `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.
|
|
|
|
*** `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.
|
|
|
|
*** `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>)`
|
|
|