fix: serialization crash in parallel waves + add openai devDep

- validateValue: handle undefined (JSON.stringify(undefined) returns undefined
  not a string, causing .length to throw as 'circular reference')
- executeSingleTask: propagate adapter failure instead of returning success
  with undefined result
- executeParallel: wrap cache write in try-catch so cache failures don't
  abort the entire wave
- package.json: add openai as devDependency (used in examples/04-live-swarm)
- .gitignore: exclude examples/04-live-swarm.ts (contains API key)
- swarm-blackboard.md: updated with live demo run state

Author: jovanSAPFIONEER

.gitignore

@@ -18,6 +18,9 @@ Thumbs.db
 # Python
 __pycache__/
 *.pyc
+
+# Live demo (contains API key - never commit)
+examples/04-live-swarm.ts
 *.pyo
 .env
 .venv/

index.ts

@@ -407,8 +407,15 @@ class SharedBlackboard {
    * Prevents DoS via oversized writes and circular data.
    */
   private validateValue(value: unknown): { valid: boolean; reason?: string } {
+    if (value === undefined) {
+      return { valid: false, reason: 'Value is undefined and cannot be stored' };
+    }
     try {
       const serialized = JSON.stringify(value);
+      if (serialized === undefined) {
+        // JSON.stringify returns undefined for unsupported root types (functions, symbols, etc.)
+        return { valid: false, reason: 'Value cannot be serialized (unsupported type)' };
+      }
       if (serialized.length > CONFIG.maxBlackboardValueSize) {
         return { valid: false, reason: `Value exceeds max size (${serialized.length} > ${CONFIG.maxBlackboardValueSize} bytes)` };
       }
@@ -1201,10 +1208,14 @@ class TaskDecomposer {
 
         individualResults.push(result);
 
-        // Cache successful results
-        if (result.success) {
-          const cacheKey = `task:${task.agentType}:${this.hashPayload(task.taskPayload)}`;
-          this.blackboard.write(cacheKey, result.result, context.agentId, 3600, 'system-orchestrator-token'); // 1 hour TTL
+        // Cache successful results (non-fatal if caching fails)
+        if (result.success && result.result !== undefined) {
+          try {
+            const cacheKey = `task:${task.agentType}:${this.hashPayload(task.taskPayload)}`;
+            this.blackboard.write(cacheKey, result.result, context.agentId, 3600, 'system-orchestrator-token'); // 1 hour TTL
+          } catch {
+            // Caching failure should not abort the entire wave
+          }
         }
       }
     }
@@ -1282,6 +1293,19 @@ class TaskDecomposer {
 
       const result = await this.adapterRegistry.executeAgent(task.agentType, agentPayload, agentContext);
 
+      // If the adapter returned a failure, propagate it
+      if (!result.success) {
+        return {
+          agentType: task.agentType,
+          success: false,
+          result: {
+            error: result.error?.message ?? 'Agent execution failed',
+            recoverable: result.error?.recoverable ?? true,
+          },
+          executionTime: Date.now() - taskStart,
+        };
+      }
+
       // Sanitize adapter output before returning/caching
       let sanitizedData = result.data;
       try {

package-lock.json

@@ -70,6 +70,7 @@
   },
   "devDependencies": {
     "@types/node": "^25.2.3",
+    "openai": "^6.22.0",
     "ts-node": "^10.9.2",
     "typescript": "^5.9.3"
   },