@illuma-ai/agents 1.1.28 → 1.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/cjs/agents/AgentContext.cjs.map +1 -1
- package/dist/cjs/common/spawnPath.cjs +104 -0
- package/dist/cjs/common/spawnPath.cjs.map +1 -0
- package/dist/cjs/graphs/Graph.cjs +84 -33
- package/dist/cjs/graphs/Graph.cjs.map +1 -1
- package/dist/cjs/graphs/HandoffRegistry.cjs +47 -8
- package/dist/cjs/graphs/HandoffRegistry.cjs.map +1 -1
- package/dist/cjs/graphs/MultiAgentGraph.cjs +493 -267
- package/dist/cjs/graphs/MultiAgentGraph.cjs.map +1 -1
- package/dist/cjs/graphs/phases/flushLoop.cjs +214 -0
- package/dist/cjs/graphs/phases/flushLoop.cjs.map +1 -0
- package/dist/cjs/graphs/phases/memoryFlushPhase.cjs +102 -0
- package/dist/cjs/graphs/phases/memoryFlushPhase.cjs.map +1 -0
- package/dist/cjs/llm/bedrock/index.cjs +4 -3
- package/dist/cjs/llm/bedrock/index.cjs.map +1 -1
- package/dist/cjs/main.cjs +113 -0
- package/dist/cjs/main.cjs.map +1 -1
- package/dist/cjs/memory/citations.cjs +69 -0
- package/dist/cjs/memory/citations.cjs.map +1 -0
- package/dist/cjs/memory/compositeBackend.cjs +60 -0
- package/dist/cjs/memory/compositeBackend.cjs.map +1 -0
- package/dist/cjs/memory/constants.cjs +232 -0
- package/dist/cjs/memory/constants.cjs.map +1 -0
- package/dist/cjs/memory/embeddings.cjs +151 -0
- package/dist/cjs/memory/embeddings.cjs.map +1 -0
- package/dist/cjs/memory/factory.cjs +95 -0
- package/dist/cjs/memory/factory.cjs.map +1 -0
- package/dist/cjs/memory/migrate.cjs +81 -0
- package/dist/cjs/memory/migrate.cjs.map +1 -0
- package/dist/cjs/memory/mmr.cjs +138 -0
- package/dist/cjs/memory/mmr.cjs.map +1 -0
- package/dist/cjs/memory/paths.cjs +217 -0
- package/dist/cjs/memory/paths.cjs.map +1 -0
- package/dist/cjs/memory/pgvectorStore.cjs +225 -0
- package/dist/cjs/memory/pgvectorStore.cjs.map +1 -0
- package/dist/cjs/memory/recallTracking.cjs +98 -0
- package/dist/cjs/memory/recallTracking.cjs.map +1 -0
- package/dist/cjs/memory/schema.sql +51 -0
- package/dist/cjs/memory/temporalDecay.cjs +118 -0
- package/dist/cjs/memory/temporalDecay.cjs.map +1 -0
- package/dist/cjs/nodes/ApprovalGateNode.cjs +1 -1
- package/dist/cjs/nodes/ApprovalGateNode.cjs.map +1 -1
- package/dist/cjs/prompts/memoryFlushPrompt.cjs +49 -0
- package/dist/cjs/prompts/memoryFlushPrompt.cjs.map +1 -0
- package/dist/cjs/run.cjs +16 -3
- package/dist/cjs/run.cjs.map +1 -1
- package/dist/cjs/tools/AskUser.cjs +6 -1
- package/dist/cjs/tools/AskUser.cjs.map +1 -1
- package/dist/cjs/tools/BrowserTools.cjs +1 -1
- package/dist/cjs/tools/BrowserTools.cjs.map +1 -1
- package/dist/cjs/tools/ToolNode.cjs +127 -10
- package/dist/cjs/tools/ToolNode.cjs.map +1 -1
- package/dist/cjs/tools/approval/constants.cjs +2 -2
- package/dist/cjs/tools/approval/constants.cjs.map +1 -1
- package/dist/cjs/tools/memory/index.cjs +58 -0
- package/dist/cjs/tools/memory/index.cjs.map +1 -0
- package/dist/cjs/tools/memory/memoryAppendTool.cjs +69 -0
- package/dist/cjs/tools/memory/memoryAppendTool.cjs.map +1 -0
- package/dist/cjs/tools/memory/memoryGetTool.cjs +49 -0
- package/dist/cjs/tools/memory/memoryGetTool.cjs.map +1 -0
- package/dist/cjs/tools/memory/memorySearchTool.cjs +65 -0
- package/dist/cjs/tools/memory/memorySearchTool.cjs.map +1 -0
- package/dist/cjs/tools/memory/shared.cjs +106 -0
- package/dist/cjs/tools/memory/shared.cjs.map +1 -0
- package/dist/cjs/types/graph.cjs.map +1 -1
- package/dist/cjs/utils/childAgentContext.cjs +242 -0
- package/dist/cjs/utils/childAgentContext.cjs.map +1 -0
- package/dist/cjs/utils/events.cjs +36 -7
- package/dist/cjs/utils/events.cjs.map +1 -1
- package/dist/cjs/utils/finishReasons.cjs +44 -0
- package/dist/cjs/utils/finishReasons.cjs.map +1 -0
- package/dist/cjs/utils/llm.cjs.map +1 -1
- package/dist/cjs/utils/logging.cjs +34 -0
- package/dist/cjs/utils/logging.cjs.map +1 -0
- package/dist/cjs/utils/toolCallNormalization.cjs +250 -0
- package/dist/cjs/utils/toolCallNormalization.cjs.map +1 -0
- package/dist/esm/agents/AgentContext.mjs.map +1 -1
- package/dist/esm/common/spawnPath.mjs +95 -0
- package/dist/esm/common/spawnPath.mjs.map +1 -0
- package/dist/esm/graphs/Graph.mjs +84 -33
- package/dist/esm/graphs/Graph.mjs.map +1 -1
- package/dist/esm/graphs/HandoffRegistry.mjs +47 -8
- package/dist/esm/graphs/HandoffRegistry.mjs.map +1 -1
- package/dist/esm/graphs/MultiAgentGraph.mjs +493 -267
- package/dist/esm/graphs/MultiAgentGraph.mjs.map +1 -1
- package/dist/esm/graphs/phases/flushLoop.mjs +209 -0
- package/dist/esm/graphs/phases/flushLoop.mjs.map +1 -0
- package/dist/esm/graphs/phases/memoryFlushPhase.mjs +99 -0
- package/dist/esm/graphs/phases/memoryFlushPhase.mjs.map +1 -0
- package/dist/esm/llm/bedrock/index.mjs +4 -3
- package/dist/esm/llm/bedrock/index.mjs.map +1 -1
- package/dist/esm/main.mjs +20 -0
- package/dist/esm/main.mjs.map +1 -1
- package/dist/esm/memory/citations.mjs +64 -0
- package/dist/esm/memory/citations.mjs.map +1 -0
- package/dist/esm/memory/compositeBackend.mjs +58 -0
- package/dist/esm/memory/compositeBackend.mjs.map +1 -0
- package/dist/esm/memory/constants.mjs +198 -0
- package/dist/esm/memory/constants.mjs.map +1 -0
- package/dist/esm/memory/embeddings.mjs +148 -0
- package/dist/esm/memory/embeddings.mjs.map +1 -0
- package/dist/esm/memory/factory.mjs +93 -0
- package/dist/esm/memory/factory.mjs.map +1 -0
- package/dist/esm/memory/migrate.mjs +78 -0
- package/dist/esm/memory/migrate.mjs.map +1 -0
- package/dist/esm/memory/mmr.mjs +130 -0
- package/dist/esm/memory/mmr.mjs.map +1 -0
- package/dist/esm/memory/paths.mjs +207 -0
- package/dist/esm/memory/paths.mjs.map +1 -0
- package/dist/esm/memory/pgvectorStore.mjs +223 -0
- package/dist/esm/memory/pgvectorStore.mjs.map +1 -0
- package/dist/esm/memory/recallTracking.mjs +94 -0
- package/dist/esm/memory/recallTracking.mjs.map +1 -0
- package/dist/esm/memory/schema.sql +51 -0
- package/dist/esm/memory/temporalDecay.mjs +110 -0
- package/dist/esm/memory/temporalDecay.mjs.map +1 -0
- package/dist/esm/nodes/ApprovalGateNode.mjs +1 -1
- package/dist/esm/nodes/ApprovalGateNode.mjs.map +1 -1
- package/dist/esm/prompts/memoryFlushPrompt.mjs +44 -0
- package/dist/esm/prompts/memoryFlushPrompt.mjs.map +1 -0
- package/dist/esm/run.mjs +16 -3
- package/dist/esm/run.mjs.map +1 -1
- package/dist/esm/tools/AskUser.mjs +6 -1
- package/dist/esm/tools/AskUser.mjs.map +1 -1
- package/dist/esm/tools/BrowserTools.mjs +1 -1
- package/dist/esm/tools/BrowserTools.mjs.map +1 -1
- package/dist/esm/tools/ToolNode.mjs +128 -11
- package/dist/esm/tools/ToolNode.mjs.map +1 -1
- package/dist/esm/tools/approval/constants.mjs +2 -2
- package/dist/esm/tools/approval/constants.mjs.map +1 -1
- package/dist/esm/tools/memory/index.mjs +46 -0
- package/dist/esm/tools/memory/index.mjs.map +1 -0
- package/dist/esm/tools/memory/memoryAppendTool.mjs +67 -0
- package/dist/esm/tools/memory/memoryAppendTool.mjs.map +1 -0
- package/dist/esm/tools/memory/memoryGetTool.mjs +47 -0
- package/dist/esm/tools/memory/memoryGetTool.mjs.map +1 -0
- package/dist/esm/tools/memory/memorySearchTool.mjs +63 -0
- package/dist/esm/tools/memory/memorySearchTool.mjs.map +1 -0
- package/dist/esm/tools/memory/shared.mjs +98 -0
- package/dist/esm/tools/memory/shared.mjs.map +1 -0
- package/dist/esm/types/graph.mjs.map +1 -1
- package/dist/esm/utils/childAgentContext.mjs +237 -0
- package/dist/esm/utils/childAgentContext.mjs.map +1 -0
- package/dist/esm/utils/events.mjs +36 -8
- package/dist/esm/utils/events.mjs.map +1 -1
- package/dist/esm/utils/finishReasons.mjs +41 -0
- package/dist/esm/utils/finishReasons.mjs.map +1 -0
- package/dist/esm/utils/llm.mjs.map +1 -1
- package/dist/esm/utils/logging.mjs +31 -0
- package/dist/esm/utils/logging.mjs.map +1 -0
- package/dist/esm/utils/toolCallNormalization.mjs +247 -0
- package/dist/esm/utils/toolCallNormalization.mjs.map +1 -0
- package/dist/types/common/index.d.ts +1 -0
- package/dist/types/common/spawnPath.d.ts +59 -0
- package/dist/types/graphs/HandoffRegistry.d.ts +24 -7
- package/dist/types/graphs/MultiAgentGraph.d.ts +43 -23
- package/dist/types/graphs/phases/flushLoop.d.ts +106 -0
- package/dist/types/graphs/phases/memoryFlushPhase.d.ts +100 -0
- package/dist/types/index.d.ts +7 -0
- package/dist/types/memory/__tests__/mockBackend.d.ts +40 -0
- package/dist/types/memory/citations.d.ts +39 -0
- package/dist/types/memory/compositeBackend.d.ts +30 -0
- package/dist/types/memory/constants.d.ts +121 -0
- package/dist/types/memory/embeddings.d.ts +15 -0
- package/dist/types/memory/factory.d.ts +23 -0
- package/dist/types/memory/index.d.ts +21 -0
- package/dist/types/memory/migrate.d.ts +14 -0
- package/dist/types/memory/mmr.d.ts +50 -0
- package/dist/types/memory/paths.d.ts +107 -0
- package/dist/types/memory/pgvectorStore.d.ts +56 -0
- package/dist/types/memory/recallTracking.d.ts +30 -0
- package/dist/types/memory/temporalDecay.d.ts +53 -0
- package/dist/types/memory/types.d.ts +182 -0
- package/dist/types/prompts/memoryFlushPrompt.d.ts +54 -0
- package/dist/types/run.d.ts +1 -0
- package/dist/types/tools/AskUser.d.ts +1 -1
- package/dist/types/tools/BrowserTools.d.ts +2 -2
- package/dist/types/tools/approval/constants.d.ts +2 -2
- package/dist/types/tools/memory/index.d.ts +39 -0
- package/dist/types/tools/memory/memoryAppendTool.d.ts +27 -0
- package/dist/types/tools/memory/memoryGetTool.d.ts +22 -0
- package/dist/types/tools/memory/memorySearchTool.d.ts +22 -0
- package/dist/types/tools/memory/shared.d.ts +106 -0
- package/dist/types/types/graph.d.ts +10 -3
- package/dist/types/utils/childAgentContext.d.ts +99 -0
- package/dist/types/utils/events.d.ts +21 -0
- package/dist/types/utils/finishReasons.d.ts +32 -0
- package/dist/types/utils/logging.d.ts +2 -0
- package/dist/types/utils/toolCallNormalization.d.ts +44 -0
- package/package.json +6 -4
- package/src/agents/AgentContext.ts +12 -4
- package/src/common/__tests__/enum.test.ts +4 -2
- package/src/common/__tests__/spawnPath.test.ts +110 -0
- package/src/common/index.ts +1 -0
- package/src/common/spawnPath.ts +101 -0
- package/src/graphs/Graph.ts +90 -47
- package/src/graphs/HandoffRegistry.ts +48 -17
- package/src/graphs/MultiAgentGraph.ts +588 -327
- package/src/graphs/__tests__/HandoffRegistry.test.ts +4 -1
- package/src/graphs/__tests__/multi-agent-delegate.test.ts +61 -16
- package/src/graphs/__tests__/multi-agent-edges.test.ts +4 -2
- package/src/graphs/__tests__/multi-agent-nested-subgraph.test.ts +221 -0
- package/src/graphs/__tests__/structured-output.integration.test.ts +212 -118
- package/src/graphs/contextManagement.e2e.test.ts +1 -1
- package/src/graphs/phases/__tests__/flushLoop.test.ts +264 -0
- package/src/graphs/phases/__tests__/memoryFlushPhase.test.ts +37 -0
- package/src/graphs/phases/__tests__/runMemoryFlush.test.ts +150 -0
- package/src/graphs/phases/flushLoop.ts +303 -0
- package/src/graphs/phases/memoryFlushPhase.ts +209 -0
- package/src/index.ts +30 -1
- package/src/llm/bedrock/index.ts +4 -5
- package/src/memory/__tests__/citations.test.ts +61 -0
- package/src/memory/__tests__/compositeBackend.test.ts +79 -0
- package/src/memory/__tests__/isolation.test.ts +206 -0
- package/src/memory/__tests__/mmr.test.ts +148 -0
- package/src/memory/__tests__/mockBackend.ts +161 -0
- package/src/memory/__tests__/paths.test.ts +168 -0
- package/src/memory/__tests__/recallTracking.test.ts +96 -0
- package/src/memory/__tests__/temporalDecay.test.ts +151 -0
- package/src/memory/citations.ts +80 -0
- package/src/memory/compositeBackend.ts +99 -0
- package/src/memory/constants.ts +229 -0
- package/src/memory/embeddings.ts +188 -0
- package/src/memory/factory.ts +111 -0
- package/src/memory/index.ts +46 -0
- package/src/memory/migrate.ts +116 -0
- package/src/memory/mmr.ts +161 -0
- package/src/memory/paths.ts +258 -0
- package/src/memory/pgvectorStore.ts +324 -0
- package/src/memory/recallTracking.ts +127 -0
- package/src/memory/schema.sql +51 -0
- package/src/memory/temporalDecay.ts +134 -0
- package/src/memory/types.ts +185 -0
- package/src/nodes/ApprovalGateNode.ts +4 -10
- package/src/nodes/__tests__/ApprovalGateNode.test.ts +11 -20
- package/src/prompts/memoryFlushPrompt.ts +78 -0
- package/src/run.ts +17 -6
- package/src/scripts/test-bedrock-handoff-autonomous.ts +56 -20
- package/src/specs/agent-handoffs-bedrock.integration.test.ts +8 -5
- package/src/specs/agent-handoffs.test.ts +8 -2
- package/src/tools/AskUser.ts +7 -2
- package/src/tools/BrowserTools.ts +3 -5
- package/src/tools/ToolNode.ts +150 -13
- package/src/tools/__tests__/ToolApproval.test.ts +22 -9
- package/src/tools/approval/__tests__/constants.test.ts +1 -1
- package/src/tools/approval/constants.ts +2 -2
- package/src/tools/memory/__tests__/memoryTools.test.ts +205 -0
- package/src/tools/memory/index.ts +96 -0
- package/src/tools/memory/memoryAppendTool.ts +101 -0
- package/src/tools/memory/memoryGetTool.ts +53 -0
- package/src/tools/memory/memorySearchTool.ts +80 -0
- package/src/tools/memory/shared.ts +169 -0
- package/src/tools/search/search.test.ts +6 -1
- package/src/types/graph.ts +10 -3
- package/src/utils/__tests__/childAgentContext.test.ts +217 -0
- package/src/utils/__tests__/finishReasons.test.ts +55 -0
- package/src/utils/__tests__/toolCallNormalization.test.ts +181 -0
- package/src/utils/childAgentContext.ts +259 -0
- package/src/utils/events.ts +37 -7
- package/src/utils/finishReasons.ts +40 -0
- package/src/utils/llm.ts +0 -1
- package/src/utils/logging.ts +45 -8
- package/src/utils/toolCallNormalization.ts +271 -0
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
/**
|
|
4
4
|
* Registry for async handoff execution.
|
|
5
5
|
*
|
|
6
|
-
* Enables the
|
|
6
|
+
* Enables the autonomous orchestration pattern:
|
|
7
7
|
* 1. Orchestrator spawns children (non-blocking)
|
|
8
8
|
* 2. Orchestrator stays alive to reason, spawn more, or check status
|
|
9
9
|
* 3. Orchestrator collects results when ready
|
|
@@ -12,13 +12,22 @@
|
|
|
12
12
|
*/
|
|
13
13
|
class HandoffRegistry {
|
|
14
14
|
records = new Map();
|
|
15
|
+
/** Monotonically increasing counter for unique spawn IDs */
|
|
16
|
+
spawnCounter = 0;
|
|
15
17
|
/**
|
|
16
18
|
* Register a spawned handoff child.
|
|
17
19
|
* The promise runs in the background — not awaited here.
|
|
20
|
+
* Uses a unique key per spawn so the same agent can be spawned multiple times
|
|
21
|
+
* across rounds without overwriting prior records.
|
|
18
22
|
*/
|
|
19
23
|
spawn(params) {
|
|
24
|
+
// Unique internal key: agentId + counter to support multiple spawns of same agent.
|
|
25
|
+
// record.id stays as the agent identity so callers/observability can attribute
|
|
26
|
+
// results to the agent regardless of which spawn round they came from.
|
|
27
|
+
const spawnKey = `${params.id}__${this.spawnCounter++}`;
|
|
20
28
|
const record = {
|
|
21
29
|
id: params.id,
|
|
30
|
+
spawnKey,
|
|
22
31
|
name: params.name,
|
|
23
32
|
task: params.task,
|
|
24
33
|
spawnedAt: Date.now(),
|
|
@@ -42,7 +51,7 @@ class HandoffRegistry {
|
|
|
42
51
|
record.durationMs = Date.now() - record.spawnedAt;
|
|
43
52
|
params.onComplete?.(record);
|
|
44
53
|
});
|
|
45
|
-
this.records.set(
|
|
54
|
+
this.records.set(spawnKey, record);
|
|
46
55
|
}
|
|
47
56
|
/** List all pending (running) handoffs */
|
|
48
57
|
listPending() {
|
|
@@ -56,24 +65,40 @@ class HandoffRegistry {
|
|
|
56
65
|
listAll() {
|
|
57
66
|
return Array.from(this.records.values());
|
|
58
67
|
}
|
|
59
|
-
/**
|
|
60
|
-
|
|
61
|
-
|
|
68
|
+
/**
|
|
69
|
+
* Get a handoff record by either its unique spawnKey or by agentId.
|
|
70
|
+
* - Exact spawnKey match wins (O(1)).
|
|
71
|
+
* - Falls back to the most recently spawned record for that agentId — matching
|
|
72
|
+
* lookups by callers that only know the agent identity, not the spawn round.
|
|
73
|
+
*/
|
|
74
|
+
get(idOrSpawnKey) {
|
|
75
|
+
const direct = this.records.get(idOrSpawnKey);
|
|
76
|
+
if (direct)
|
|
77
|
+
return direct;
|
|
78
|
+
let latest;
|
|
79
|
+
for (const record of this.records.values()) {
|
|
80
|
+
if (record.id !== idOrSpawnKey)
|
|
81
|
+
continue;
|
|
82
|
+
if (!latest || record.spawnedAt >= latest.spawnedAt)
|
|
83
|
+
latest = record;
|
|
84
|
+
}
|
|
85
|
+
return latest;
|
|
62
86
|
}
|
|
63
87
|
/** Check if any handoffs are still running */
|
|
64
88
|
hasPending() {
|
|
65
89
|
return this.listPending().length > 0;
|
|
66
90
|
}
|
|
67
91
|
/**
|
|
68
|
-
* Wait for ALL pending handoffs to complete.
|
|
69
|
-
*
|
|
92
|
+
* Wait for ALL pending handoffs to complete and return all records.
|
|
93
|
+
* Records are NOT auto-cleared — caller removes collected records via remove().
|
|
70
94
|
*/
|
|
71
95
|
async waitForAll() {
|
|
72
96
|
const pending = this.listPending();
|
|
73
97
|
if (pending.length > 0) {
|
|
74
98
|
await Promise.allSettled(pending.map((r) => r.promise));
|
|
75
99
|
}
|
|
76
|
-
|
|
100
|
+
const results = this.listAll();
|
|
101
|
+
return results;
|
|
77
102
|
}
|
|
78
103
|
/**
|
|
79
104
|
* Wait for ANY pending handoff to complete.
|
|
@@ -90,6 +115,20 @@ class HandoffRegistry {
|
|
|
90
115
|
await new Promise((resolve) => setTimeout(resolve, 0));
|
|
91
116
|
return this.listCompleted();
|
|
92
117
|
}
|
|
118
|
+
/**
|
|
119
|
+
* Remove record(s) by spawnKey or agentId.
|
|
120
|
+
* - Exact spawnKey match removes only that record.
|
|
121
|
+
* - agentId match removes ALL records for that agent (covers callers that
|
|
122
|
+
* want to forget everything tied to a given agent).
|
|
123
|
+
*/
|
|
124
|
+
remove(idOrSpawnKey) {
|
|
125
|
+
if (this.records.delete(idOrSpawnKey))
|
|
126
|
+
return;
|
|
127
|
+
for (const [key, record] of this.records) {
|
|
128
|
+
if (record.id === idOrSpawnKey)
|
|
129
|
+
this.records.delete(key);
|
|
130
|
+
}
|
|
131
|
+
}
|
|
93
132
|
/** Clear all records (for cleanup between graph invocations) */
|
|
94
133
|
clear() {
|
|
95
134
|
this.records.clear();
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"HandoffRegistry.cjs","sources":["../../../src/graphs/HandoffRegistry.ts"],"sourcesContent":["import type { BaseMessage } from '@langchain/core/messages';\nimport type * as t from '@/types';\n\n/**\n * Tracks the lifecycle of a spawned handoff child agent.\n * Mirrors OpenClaw's SubagentRunRecord pattern.\n */\nexport type HandoffRecord = {\n /** Unique handoff ID (destination agentId) */\n id: string;\n /** Display name of the child agent */\n name: string;\n /** Task description / instructions passed to child */\n task: string;\n /** When the handoff was spawned */\n spawnedAt: number;\n /** Current status */\n status: 'pending' | 'running' | 'completed' | 'failed';\n /** The background promise executing the child subgraph */\n promise: Promise<t.BaseGraphState>;\n /** Resolved result text (populated on completion) */\n resultText?: string;\n /** Error message (populated on failure) */\n error?: string;\n /** Duration in ms (populated on completion/failure) */\n durationMs?: number;\n /** Number of messages in child's output */\n resultMessageCount?: number;\n};\n\n/**\n * Registry for async handoff execution.\n *\n * Enables the OpenClaw-style autonomous orchestration pattern:\n * 1. Orchestrator spawns children (non-blocking)\n * 2. Orchestrator stays alive to reason, spawn more, or check status\n * 3. Orchestrator collects results when ready\n *\n * Scoped per MultiAgentGraph instance — each orchestrator graph gets its own registry.\n */\nexport class HandoffRegistry {\n private records: Map<string, HandoffRecord> = new Map();\n\n /**\n * Register a spawned handoff child.\n * The promise runs in the background — not awaited here.\n */\n spawn(params: {\n id: string;\n name: string;\n task: string;\n promise: Promise<t.BaseGraphState>;\n extractResult: (messages: BaseMessage[], agentId: string) => string;\n truncateResult: (text: string, maxChars: number) => string;\n maxResultChars: number;\n /** Callback when child completes (for SSE events) */\n onComplete?: (record: HandoffRecord) => void;\n }): void {\n const record: HandoffRecord = {\n id: params.id,\n name: params.name,\n task: params.task,\n spawnedAt: Date.now(),\n status: 'running',\n promise: params.promise,\n };\n\n // Wire up the promise to update the record on completion\n params.promise\n .then((result) => {\n const resultText = params.extractResult(\n result.messages,\n params.id\n );\n const truncated = params.truncateResult(\n resultText,\n params.maxResultChars\n );\n record.status = 'completed';\n record.resultText = truncated;\n record.durationMs = Date.now() - record.spawnedAt;\n record.resultMessageCount = result.messages.length;\n params.onComplete?.(record);\n })\n .catch((err) => {\n record.status = 'failed';\n record.error = err instanceof Error ? err.message : String(err);\n record.durationMs = Date.now() - record.spawnedAt;\n params.onComplete?.(record);\n });\n\n this.records.set(params.id, record);\n }\n\n /** List all pending (running) handoffs */\n listPending(): HandoffRecord[] {\n return Array.from(this.records.values()).filter(\n (r) => r.status === 'running'\n );\n }\n\n /** List all completed handoffs (not yet collected) */\n listCompleted(): HandoffRecord[] {\n return Array.from(this.records.values()).filter(\n (r) => r.status === 'completed' || r.status === 'failed'\n );\n }\n\n /** List all handoffs regardless of status */\n listAll(): HandoffRecord[] {\n return Array.from(this.records.values());\n }\n\n /** Get a specific handoff by ID */\n get(id: string): HandoffRecord | undefined {\n return this.records.get(id);\n }\n\n /** Check if any handoffs are still running */\n hasPending(): boolean {\n return this.listPending().length > 0;\n }\n\n /**\n * Wait for ALL pending handoffs to complete.\n * Returns all completed records (including previously completed ones).\n */\n async waitForAll(): Promise<HandoffRecord[]> {\n const pending = this.listPending();\n if (pending.length > 0) {\n await Promise.allSettled(pending.map((r) => r.promise));\n }\n return this.listAll();\n }\n\n /**\n * Wait for ANY pending handoff to complete.\n * Returns the newly completed record(s).\n */\n async waitForAny(): Promise<HandoffRecord[]> {\n const pending = this.listPending();\n if (pending.length === 0) {\n return this.listCompleted();\n }\n\n // Race all pending promises — at least one will resolve\n await Promise.race(\n pending.map((r) =>\n r.promise.then(() => r).catch(() => r)\n )\n );\n\n // Small yield to let promise handlers update records\n await new Promise((resolve) => setTimeout(resolve, 0));\n\n return this.listCompleted();\n }\n\n /** Clear all records (for cleanup between graph invocations) */\n clear(): void {\n this.records.clear();\n }\n\n /** Number of total tracked handoffs */\n get size(): number {\n return this.records.size;\n }\n}\n"],"names":[],"mappings":"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"}
|
|
1
|
+
{"version":3,"file":"HandoffRegistry.cjs","sources":["../../../src/graphs/HandoffRegistry.ts"],"sourcesContent":["import type { BaseMessage } from '@langchain/core/messages';\nimport type * as t from '@/types';\n\n/**\n * Tracks the lifecycle of a spawned handoff child agent.\n */\nexport type HandoffRecord = {\n /** Agent identity (destination agentId) — stable across multiple spawns of the same agent */\n id: string;\n /** Unique internal key for this specific spawn (agentId + monotonic counter) */\n spawnKey: string;\n /** Display name of the child agent */\n name: string;\n /** Task description / instructions passed to child */\n task: string;\n /** When the handoff was spawned */\n spawnedAt: number;\n /** Current status */\n status: 'pending' | 'running' | 'completed' | 'failed';\n /** The background promise executing the child subgraph */\n promise: Promise<t.BaseGraphState>;\n /** Resolved result text (populated on completion) */\n resultText?: string;\n /** Error message (populated on failure) */\n error?: string;\n /** Duration in ms (populated on completion/failure) */\n durationMs?: number;\n /** Number of messages in child's output */\n resultMessageCount?: number;\n};\n\n/**\n * Registry for async handoff execution.\n *\n * Enables the autonomous orchestration pattern:\n * 1. Orchestrator spawns children (non-blocking)\n * 2. Orchestrator stays alive to reason, spawn more, or check status\n * 3. Orchestrator collects results when ready\n *\n * Scoped per MultiAgentGraph instance — each orchestrator graph gets its own registry.\n */\nexport class HandoffRegistry {\n private records: Map<string, HandoffRecord> = new Map();\n /** Monotonically increasing counter for unique spawn IDs */\n private spawnCounter = 0;\n\n /**\n * Register a spawned handoff child.\n * The promise runs in the background — not awaited here.\n * Uses a unique key per spawn so the same agent can be spawned multiple times\n * across rounds without overwriting prior records.\n */\n spawn(params: {\n id: string;\n name: string;\n task: string;\n promise: Promise<t.BaseGraphState>;\n extractResult: (messages: BaseMessage[], agentId: string) => string;\n truncateResult: (text: string, maxChars: number) => string;\n maxResultChars: number;\n /** Callback when child completes (for SSE events) */\n onComplete?: (record: HandoffRecord) => void;\n }): void {\n // Unique internal key: agentId + counter to support multiple spawns of same agent.\n // record.id stays as the agent identity so callers/observability can attribute\n // results to the agent regardless of which spawn round they came from.\n const spawnKey = `${params.id}__${this.spawnCounter++}`;\n const record: HandoffRecord = {\n id: params.id,\n spawnKey,\n name: params.name,\n task: params.task,\n spawnedAt: Date.now(),\n status: 'running',\n promise: params.promise,\n };\n\n // Wire up the promise to update the record on completion\n params.promise\n .then((result) => {\n const resultText = params.extractResult(result.messages, params.id);\n const truncated = params.truncateResult(\n resultText,\n params.maxResultChars\n );\n record.status = 'completed';\n record.resultText = truncated;\n record.durationMs = Date.now() - record.spawnedAt;\n record.resultMessageCount = result.messages.length;\n params.onComplete?.(record);\n })\n .catch((err) => {\n record.status = 'failed';\n record.error = err instanceof Error ? err.message : String(err);\n record.durationMs = Date.now() - record.spawnedAt;\n params.onComplete?.(record);\n });\n\n this.records.set(spawnKey, record);\n }\n\n /** List all pending (running) handoffs */\n listPending(): HandoffRecord[] {\n return Array.from(this.records.values()).filter(\n (r) => r.status === 'running'\n );\n }\n\n /** List all completed handoffs (not yet collected) */\n listCompleted(): HandoffRecord[] {\n return Array.from(this.records.values()).filter(\n (r) => r.status === 'completed' || r.status === 'failed'\n );\n }\n\n /** List all handoffs regardless of status */\n listAll(): HandoffRecord[] {\n return Array.from(this.records.values());\n }\n\n /**\n * Get a handoff record by either its unique spawnKey or by agentId.\n * - Exact spawnKey match wins (O(1)).\n * - Falls back to the most recently spawned record for that agentId — matching\n * lookups by callers that only know the agent identity, not the spawn round.\n */\n get(idOrSpawnKey: string): HandoffRecord | undefined {\n const direct = this.records.get(idOrSpawnKey);\n if (direct) return direct;\n let latest: HandoffRecord | undefined;\n for (const record of this.records.values()) {\n if (record.id !== idOrSpawnKey) continue;\n if (!latest || record.spawnedAt >= latest.spawnedAt) latest = record;\n }\n return latest;\n }\n\n /** Check if any handoffs are still running */\n hasPending(): boolean {\n return this.listPending().length > 0;\n }\n\n /**\n * Wait for ALL pending handoffs to complete and return all records.\n * Records are NOT auto-cleared — caller removes collected records via remove().\n */\n async waitForAll(): Promise<HandoffRecord[]> {\n const pending = this.listPending();\n if (pending.length > 0) {\n await Promise.allSettled(pending.map((r) => r.promise));\n }\n const results = this.listAll();\n return results;\n }\n\n /**\n * Wait for ANY pending handoff to complete.\n * Returns the newly completed record(s).\n */\n async waitForAny(): Promise<HandoffRecord[]> {\n const pending = this.listPending();\n if (pending.length === 0) {\n return this.listCompleted();\n }\n\n // Race all pending promises — at least one will resolve\n await Promise.race(\n pending.map((r) => r.promise.then(() => r).catch(() => r))\n );\n\n // Small yield to let promise handlers update records\n await new Promise((resolve) => setTimeout(resolve, 0));\n\n return this.listCompleted();\n }\n\n /**\n * Remove record(s) by spawnKey or agentId.\n * - Exact spawnKey match removes only that record.\n * - agentId match removes ALL records for that agent (covers callers that\n * want to forget everything tied to a given agent).\n */\n remove(idOrSpawnKey: string): void {\n if (this.records.delete(idOrSpawnKey)) return;\n for (const [key, record] of this.records) {\n if (record.id === idOrSpawnKey) this.records.delete(key);\n }\n }\n\n /** Clear all records (for cleanup between graph invocations) */\n clear(): void {\n this.records.clear();\n }\n\n /** Number of total tracked handoffs */\n get size(): number {\n return this.records.size;\n }\n}\n"],"names":[],"mappings":"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"}
|