@illuma-ai/agents 1.1.28 → 1.3.1

package/src/graphs/HandoffRegistry.ts

@@ -3,11 +3,12 @@ import type * as t from '@/types';
 
 /**
  * Tracks the lifecycle of a spawned handoff child agent.
- * Mirrors OpenClaw's SubagentRunRecord pattern.
  */
 export type HandoffRecord = {
-  /** Unique handoff ID (destination agentId) */
+  /** Agent identity (destination agentId) — stable across multiple spawns of the same agent */
   id: string;
+  /** Unique internal key for this specific spawn (agentId + monotonic counter) */
+  spawnKey: string;
   /** Display name of the child agent */
   name: string;
   /** Task description / instructions passed to child */
@@ -31,7 +32,7 @@ export type HandoffRecord = {
 /**
  * Registry for async handoff execution.
  *
- * Enables the OpenClaw-style autonomous orchestration pattern:
+ * Enables the autonomous orchestration pattern:
  * 1. Orchestrator spawns children (non-blocking)
  * 2. Orchestrator stays alive to reason, spawn more, or check status
  * 3. Orchestrator collects results when ready
@@ -40,10 +41,14 @@ export type HandoffRecord = {
  */
 export class HandoffRegistry {
   private records: Map<string, HandoffRecord> = new Map();
+  /** Monotonically increasing counter for unique spawn IDs */
+  private spawnCounter = 0;
 
   /**
    * Register a spawned handoff child.
    * The promise runs in the background — not awaited here.
+   * Uses a unique key per spawn so the same agent can be spawned multiple times
+   * across rounds without overwriting prior records.
    */
   spawn(params: {
     id: string;
@@ -56,8 +61,13 @@ export class HandoffRegistry {
     /** Callback when child completes (for SSE events) */
     onComplete?: (record: HandoffRecord) => void;
   }): void {
+    // Unique internal key: agentId + counter to support multiple spawns of same agent.
+    // record.id stays as the agent identity so callers/observability can attribute
+    // results to the agent regardless of which spawn round they came from.
+    const spawnKey = `${params.id}__${this.spawnCounter++}`;
     const record: HandoffRecord = {
       id: params.id,
+      spawnKey,
       name: params.name,
       task: params.task,
       spawnedAt: Date.now(),
@@ -68,10 +78,7 @@ export class HandoffRegistry {
     // Wire up the promise to update the record on completion
     params.promise
       .then((result) => {
-        const resultText = params.extractResult(
-          result.messages,
-          params.id
-        );
+        const resultText = params.extractResult(result.messages, params.id);
         const truncated = params.truncateResult(
           resultText,
           params.maxResultChars
@@ -89,7 +96,7 @@ export class HandoffRegistry {
         params.onComplete?.(record);
       });
 
-    this.records.set(params.id, record);
+    this.records.set(spawnKey, record);
   }
 
   /** List all pending (running) handoffs */
@@ -111,9 +118,21 @@ export class HandoffRegistry {
     return Array.from(this.records.values());
   }
 
-  /** Get a specific handoff by ID */
-  get(id: string): HandoffRecord | undefined {
-    return this.records.get(id);
+  /**
+   * Get a handoff record by either its unique spawnKey or by agentId.
+   * - Exact spawnKey match wins (O(1)).
+   * - Falls back to the most recently spawned record for that agentId — matching
+   *   lookups by callers that only know the agent identity, not the spawn round.
+   */
+  get(idOrSpawnKey: string): HandoffRecord | undefined {
+    const direct = this.records.get(idOrSpawnKey);
+    if (direct) return direct;
+    let latest: HandoffRecord | undefined;
+    for (const record of this.records.values()) {
+      if (record.id !== idOrSpawnKey) continue;
+      if (!latest || record.spawnedAt >= latest.spawnedAt) latest = record;
+    }
+    return latest;
   }
 
   /** Check if any handoffs are still running */
@@ -122,15 +141,16 @@ export class HandoffRegistry {
   }
 
   /**
-   * Wait for ALL pending handoffs to complete.
-   * Returns all completed records (including previously completed ones).
+   * Wait for ALL pending handoffs to complete and return all records.
+   * Records are NOT auto-cleared — caller removes collected records via remove().
    */
   async waitForAll(): Promise<HandoffRecord[]> {
     const pending = this.listPending();
     if (pending.length > 0) {
       await Promise.allSettled(pending.map((r) => r.promise));
     }
-    return this.listAll();
+    const results = this.listAll();
+    return results;
   }
 
   /**
@@ -145,9 +165,7 @@ export class HandoffRegistry {
 
     // Race all pending promises — at least one will resolve
     await Promise.race(
-      pending.map((r) =>
-        r.promise.then(() => r).catch(() => r)
-      )
+      pending.map((r) => r.promise.then(() => r).catch(() => r))
     );
 
     // Small yield to let promise handlers update records
@@ -156,6 +174,19 @@ export class HandoffRegistry {
     return this.listCompleted();
   }
 
+  /**
+   * Remove record(s) by spawnKey or agentId.
+   * - Exact spawnKey match removes only that record.
+   * - agentId match removes ALL records for that agent (covers callers that
+   *   want to forget everything tied to a given agent).
+   */
+  remove(idOrSpawnKey: string): void {
+    if (this.records.delete(idOrSpawnKey)) return;
+    for (const [key, record] of this.records) {
+      if (record.id === idOrSpawnKey) this.records.delete(key);
+    }
+  }
+
   /** Clear all records (for cleanup between graph invocations) */
   clear(): void {
     this.records.clear();