@hazeljs/agent 0.2.0-alpha.1

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.
Files changed (166) hide show
  1. package/IMPLEMENTATION_SUMMARY.md +400 -0
  2. package/LICENSE +192 -0
  3. package/PERSISTENCE.md +201 -0
  4. package/PRISMA_INTEGRATION.md +499 -0
  5. package/PRODUCTION_READINESS.md +264 -0
  6. package/QUICKSTART.md +135 -0
  7. package/README.md +541 -0
  8. package/STATE_VS_MEMORY.md +243 -0
  9. package/benchmarks/performance.benchmark.ts +157 -0
  10. package/coverage/clover.xml +1508 -0
  11. package/coverage/lcov-report/base.css +224 -0
  12. package/coverage/lcov-report/block-navigation.js +87 -0
  13. package/coverage/lcov-report/favicon.png +0 -0
  14. package/coverage/lcov-report/index.html +296 -0
  15. package/coverage/lcov-report/prettify.css +1 -0
  16. package/coverage/lcov-report/prettify.js +2 -0
  17. package/coverage/lcov-report/sort-arrow-sprite.png +0 -0
  18. package/coverage/lcov-report/sorter.js +210 -0
  19. package/coverage/lcov.info +2722 -0
  20. package/dist/agent.module.d.ts +57 -0
  21. package/dist/agent.module.d.ts.map +1 -0
  22. package/dist/agent.module.js +99 -0
  23. package/dist/agent.module.js.map +1 -0
  24. package/dist/context/agent.context.d.ts +27 -0
  25. package/dist/context/agent.context.d.ts.map +1 -0
  26. package/dist/context/agent.context.js +98 -0
  27. package/dist/context/agent.context.js.map +1 -0
  28. package/dist/decorators/agent.decorator.d.ts +21 -0
  29. package/dist/decorators/agent.decorator.d.ts.map +1 -0
  30. package/dist/decorators/agent.decorator.js +38 -0
  31. package/dist/decorators/agent.decorator.js.map +1 -0
  32. package/dist/decorators/delegate.decorator.d.ts +66 -0
  33. package/dist/decorators/delegate.decorator.d.ts.map +1 -0
  34. package/dist/decorators/delegate.decorator.js +108 -0
  35. package/dist/decorators/delegate.decorator.js.map +1 -0
  36. package/dist/decorators/tool.decorator.d.ts +23 -0
  37. package/dist/decorators/tool.decorator.d.ts.map +1 -0
  38. package/dist/decorators/tool.decorator.js +61 -0
  39. package/dist/decorators/tool.decorator.js.map +1 -0
  40. package/dist/events/event.emitter.d.ts +45 -0
  41. package/dist/events/event.emitter.d.ts.map +1 -0
  42. package/dist/events/event.emitter.js +96 -0
  43. package/dist/events/event.emitter.js.map +1 -0
  44. package/dist/executor/agent.executor.d.ts +58 -0
  45. package/dist/executor/agent.executor.d.ts.map +1 -0
  46. package/dist/executor/agent.executor.js +312 -0
  47. package/dist/executor/agent.executor.js.map +1 -0
  48. package/dist/executor/tool.executor.d.ts +55 -0
  49. package/dist/executor/tool.executor.d.ts.map +1 -0
  50. package/dist/executor/tool.executor.js +266 -0
  51. package/dist/executor/tool.executor.js.map +1 -0
  52. package/dist/graph/agent-graph.d.ts +131 -0
  53. package/dist/graph/agent-graph.d.ts.map +1 -0
  54. package/dist/graph/agent-graph.js +462 -0
  55. package/dist/graph/agent-graph.js.map +1 -0
  56. package/dist/graph/agent-graph.types.d.ts +210 -0
  57. package/dist/graph/agent-graph.types.d.ts.map +1 -0
  58. package/dist/graph/agent-graph.types.js +12 -0
  59. package/dist/graph/agent-graph.types.js.map +1 -0
  60. package/dist/index.d.ts +34 -0
  61. package/dist/index.d.ts.map +1 -0
  62. package/dist/index.js +51 -0
  63. package/dist/index.js.map +1 -0
  64. package/dist/prompts/agent-system.prompt.d.ts +10 -0
  65. package/dist/prompts/agent-system.prompt.d.ts.map +1 -0
  66. package/dist/prompts/agent-system.prompt.js +18 -0
  67. package/dist/prompts/agent-system.prompt.js.map +1 -0
  68. package/dist/prompts/index.d.ts +4 -0
  69. package/dist/prompts/index.d.ts.map +1 -0
  70. package/dist/prompts/index.js +20 -0
  71. package/dist/prompts/index.js.map +1 -0
  72. package/dist/prompts/supervisor-routing.prompt.d.ts +9 -0
  73. package/dist/prompts/supervisor-routing.prompt.d.ts.map +1 -0
  74. package/dist/prompts/supervisor-routing.prompt.js +22 -0
  75. package/dist/prompts/supervisor-routing.prompt.js.map +1 -0
  76. package/dist/prompts/supervisor-system.prompt.d.ts +9 -0
  77. package/dist/prompts/supervisor-system.prompt.d.ts.map +1 -0
  78. package/dist/prompts/supervisor-system.prompt.js +21 -0
  79. package/dist/prompts/supervisor-system.prompt.js.map +1 -0
  80. package/dist/registry/agent.registry.d.ts +49 -0
  81. package/dist/registry/agent.registry.d.ts.map +1 -0
  82. package/dist/registry/agent.registry.js +90 -0
  83. package/dist/registry/agent.registry.js.map +1 -0
  84. package/dist/registry/tool.registry.d.ts +54 -0
  85. package/dist/registry/tool.registry.d.ts.map +1 -0
  86. package/dist/registry/tool.registry.js +153 -0
  87. package/dist/registry/tool.registry.js.map +1 -0
  88. package/dist/runtime/agent.runtime.d.ts +218 -0
  89. package/dist/runtime/agent.runtime.d.ts.map +1 -0
  90. package/dist/runtime/agent.runtime.extensions.d.ts +49 -0
  91. package/dist/runtime/agent.runtime.extensions.d.ts.map +1 -0
  92. package/dist/runtime/agent.runtime.extensions.js +93 -0
  93. package/dist/runtime/agent.runtime.extensions.js.map +1 -0
  94. package/dist/runtime/agent.runtime.js +448 -0
  95. package/dist/runtime/agent.runtime.js.map +1 -0
  96. package/dist/state/agent-state.interface.d.ts +63 -0
  97. package/dist/state/agent-state.interface.d.ts.map +1 -0
  98. package/dist/state/agent-state.interface.js +7 -0
  99. package/dist/state/agent-state.interface.js.map +1 -0
  100. package/dist/state/agent.state.d.ts +67 -0
  101. package/dist/state/agent.state.d.ts.map +1 -0
  102. package/dist/state/agent.state.js +172 -0
  103. package/dist/state/agent.state.js.map +1 -0
  104. package/dist/state/database-state.manager.d.ts +63 -0
  105. package/dist/state/database-state.manager.d.ts.map +1 -0
  106. package/dist/state/database-state.manager.js +282 -0
  107. package/dist/state/database-state.manager.js.map +1 -0
  108. package/dist/state/redis-state.manager.d.ts +81 -0
  109. package/dist/state/redis-state.manager.d.ts.map +1 -0
  110. package/dist/state/redis-state.manager.js +253 -0
  111. package/dist/state/redis-state.manager.js.map +1 -0
  112. package/dist/supervisor/supervisor.d.ts +81 -0
  113. package/dist/supervisor/supervisor.d.ts.map +1 -0
  114. package/dist/supervisor/supervisor.js +220 -0
  115. package/dist/supervisor/supervisor.js.map +1 -0
  116. package/dist/types/agent.types.d.ts +166 -0
  117. package/dist/types/agent.types.d.ts.map +1 -0
  118. package/dist/types/agent.types.js +32 -0
  119. package/dist/types/agent.types.js.map +1 -0
  120. package/dist/types/event.types.d.ts +198 -0
  121. package/dist/types/event.types.d.ts.map +1 -0
  122. package/dist/types/event.types.js +46 -0
  123. package/dist/types/event.types.js.map +1 -0
  124. package/dist/types/llm.types.d.ts +66 -0
  125. package/dist/types/llm.types.d.ts.map +1 -0
  126. package/dist/types/llm.types.js +7 -0
  127. package/dist/types/llm.types.js.map +1 -0
  128. package/dist/types/rag.types.d.ts +40 -0
  129. package/dist/types/rag.types.d.ts.map +1 -0
  130. package/dist/types/rag.types.js +7 -0
  131. package/dist/types/rag.types.js.map +1 -0
  132. package/dist/types/tool.types.d.ts +118 -0
  133. package/dist/types/tool.types.d.ts.map +1 -0
  134. package/dist/types/tool.types.js +19 -0
  135. package/dist/types/tool.types.js.map +1 -0
  136. package/dist/utils/circuit-breaker.d.ts +9 -0
  137. package/dist/utils/circuit-breaker.d.ts.map +1 -0
  138. package/dist/utils/circuit-breaker.js +16 -0
  139. package/dist/utils/circuit-breaker.js.map +1 -0
  140. package/dist/utils/health-check.d.ts +71 -0
  141. package/dist/utils/health-check.d.ts.map +1 -0
  142. package/dist/utils/health-check.js +156 -0
  143. package/dist/utils/health-check.js.map +1 -0
  144. package/dist/utils/logger.d.ts +53 -0
  145. package/dist/utils/logger.d.ts.map +1 -0
  146. package/dist/utils/logger.js +133 -0
  147. package/dist/utils/logger.js.map +1 -0
  148. package/dist/utils/metrics.d.ts +90 -0
  149. package/dist/utils/metrics.d.ts.map +1 -0
  150. package/dist/utils/metrics.js +186 -0
  151. package/dist/utils/metrics.js.map +1 -0
  152. package/dist/utils/rate-limiter.d.ts +44 -0
  153. package/dist/utils/rate-limiter.d.ts.map +1 -0
  154. package/dist/utils/rate-limiter.js +82 -0
  155. package/dist/utils/rate-limiter.js.map +1 -0
  156. package/dist/utils/retry.d.ts +42 -0
  157. package/dist/utils/retry.d.ts.map +1 -0
  158. package/dist/utils/retry.js +103 -0
  159. package/dist/utils/retry.js.map +1 -0
  160. package/jest.config.js +30 -0
  161. package/logs/combined.log +1 -0
  162. package/logs/error.log +0 -0
  163. package/package.json +74 -0
  164. package/prisma-schema.example.prisma +76 -0
  165. package/tests/setup.ts +17 -0
  166. package/tsconfig.tsbuildinfo +1 -0
@@ -0,0 +1,253 @@
1
+ "use strict";
2
+ /**
3
+ * Redis State Manager
4
+ * Redis-backed persistence for agent execution state
5
+ * Provides fast, distributed state management with TTL support
6
+ */
7
+ Object.defineProperty(exports, "__esModule", { value: true });
8
+ exports.RedisStateManager = void 0;
9
+ const agent_types_1 = require("../types/agent.types");
10
+ const crypto_1 = require("crypto");
11
+ /**
12
+ * Redis-backed state manager for agent execution state
13
+ * Provides fast, distributed state management with automatic expiration
14
+ */
15
+ class RedisStateManager {
16
+ constructor(config) {
17
+ if (!config.client) {
18
+ throw new Error('Redis client is required');
19
+ }
20
+ this.client = config.client;
21
+ this.keyPrefix = config.keyPrefix || 'agent:state:';
22
+ this.defaultTTL = config.defaultTTL || 3600; // 1 hour
23
+ this.completedTTL = config.completedTTL || 86400; // 24 hours
24
+ this.failedTTL = config.failedTTL || 604800; // 7 days
25
+ }
26
+ /**
27
+ * Get the Redis key for an execution context
28
+ */
29
+ getKey(executionId) {
30
+ return `${this.keyPrefix}${executionId}`;
31
+ }
32
+ /**
33
+ * Get the Redis key for session contexts
34
+ */
35
+ getSessionKey(sessionId) {
36
+ return `${this.keyPrefix}session:${sessionId}`;
37
+ }
38
+ /**
39
+ * Serialize context to JSON
40
+ */
41
+ serialize(context) {
42
+ return JSON.stringify(context, (key, value) => {
43
+ if (value instanceof Date) {
44
+ return value.toISOString();
45
+ }
46
+ return value;
47
+ });
48
+ }
49
+ /**
50
+ * Deserialize context from JSON
51
+ */
52
+ deserialize(data) {
53
+ const parsed = JSON.parse(data);
54
+ return {
55
+ ...parsed,
56
+ createdAt: new Date(parsed.createdAt),
57
+ updatedAt: new Date(parsed.updatedAt),
58
+ steps: parsed.steps.map((step) => ({
59
+ ...step,
60
+ timestamp: new Date(step.timestamp),
61
+ })),
62
+ memory: {
63
+ ...parsed.memory,
64
+ conversationHistory: parsed.memory.conversationHistory.map((msg) => ({
65
+ ...msg,
66
+ timestamp: new Date(msg.timestamp),
67
+ })),
68
+ },
69
+ };
70
+ }
71
+ /**
72
+ * Get TTL based on state
73
+ */
74
+ getTTL(state) {
75
+ if (state === agent_types_1.AgentState.COMPLETED) {
76
+ return this.completedTTL;
77
+ }
78
+ if (state === agent_types_1.AgentState.FAILED) {
79
+ return this.failedTTL;
80
+ }
81
+ return this.defaultTTL;
82
+ }
83
+ async createContext(agentId, sessionId, input, userId, metadata) {
84
+ const executionId = (0, crypto_1.randomUUID)();
85
+ const now = new Date();
86
+ const context = {
87
+ executionId,
88
+ agentId,
89
+ sessionId,
90
+ userId,
91
+ input,
92
+ state: agent_types_1.AgentState.IDLE,
93
+ steps: [],
94
+ memory: {
95
+ conversationHistory: [],
96
+ workingMemory: {},
97
+ facts: [],
98
+ entities: [],
99
+ },
100
+ metadata: metadata || {},
101
+ createdAt: now,
102
+ updatedAt: now,
103
+ };
104
+ const key = this.getKey(executionId);
105
+ const serialized = this.serialize(context);
106
+ const ttl = this.getTTL(context.state);
107
+ // Store context
108
+ await this.client.setEx(key, ttl, serialized);
109
+ // Add to session index
110
+ await this.client.sAdd(this.getSessionKey(sessionId), executionId);
111
+ await this.client.expire(this.getSessionKey(sessionId), ttl);
112
+ return context;
113
+ }
114
+ async getContext(executionId) {
115
+ const key = this.getKey(executionId);
116
+ const data = await this.client.get(key);
117
+ if (!data) {
118
+ return undefined;
119
+ }
120
+ return this.deserialize(data);
121
+ }
122
+ async updateState(executionId, newState) {
123
+ const context = await this.getContext(executionId);
124
+ if (!context) {
125
+ throw new Error(`Execution context ${executionId} not found`);
126
+ }
127
+ context.state = newState;
128
+ context.updatedAt = new Date();
129
+ const key = this.getKey(executionId);
130
+ const serialized = this.serialize(context);
131
+ const ttl = this.getTTL(newState);
132
+ await this.client.setEx(key, ttl, serialized);
133
+ }
134
+ async addStep(executionId, step) {
135
+ const context = await this.getContext(executionId);
136
+ if (!context) {
137
+ throw new Error(`Execution context ${executionId} not found`);
138
+ }
139
+ context.steps.push(step);
140
+ context.updatedAt = new Date();
141
+ const key = this.getKey(executionId);
142
+ const serialized = this.serialize(context);
143
+ const ttl = this.getTTL(context.state);
144
+ await this.client.setEx(key, ttl, serialized);
145
+ }
146
+ async updateLastStep(executionId, updates) {
147
+ const context = await this.getContext(executionId);
148
+ if (!context) {
149
+ throw new Error(`Execution context ${executionId} not found`);
150
+ }
151
+ if (context.steps.length === 0) {
152
+ throw new Error('No steps to update');
153
+ }
154
+ const lastStep = context.steps[context.steps.length - 1];
155
+ Object.assign(lastStep, updates);
156
+ context.updatedAt = new Date();
157
+ const key = this.getKey(executionId);
158
+ const serialized = this.serialize(context);
159
+ const ttl = this.getTTL(context.state);
160
+ await this.client.setEx(key, ttl, serialized);
161
+ }
162
+ async addMessage(executionId, role, content) {
163
+ const context = await this.getContext(executionId);
164
+ if (!context) {
165
+ throw new Error(`Execution context ${executionId} not found`);
166
+ }
167
+ context.memory.conversationHistory.push({
168
+ role,
169
+ content,
170
+ timestamp: new Date(),
171
+ });
172
+ context.updatedAt = new Date();
173
+ const key = this.getKey(executionId);
174
+ const serialized = this.serialize(context);
175
+ const ttl = this.getTTL(context.state);
176
+ await this.client.setEx(key, ttl, serialized);
177
+ }
178
+ async setWorkingMemory(executionId, key, value) {
179
+ const context = await this.getContext(executionId);
180
+ if (!context) {
181
+ throw new Error(`Execution context ${executionId} not found`);
182
+ }
183
+ context.memory.workingMemory[key] = value;
184
+ context.updatedAt = new Date();
185
+ const redisKey = this.getKey(executionId);
186
+ const serialized = this.serialize(context);
187
+ const ttl = this.getTTL(context.state);
188
+ await this.client.setEx(redisKey, ttl, serialized);
189
+ }
190
+ async getWorkingMemory(executionId, key) {
191
+ const context = await this.getContext(executionId);
192
+ if (!context) {
193
+ throw new Error(`Execution context ${executionId} not found`);
194
+ }
195
+ return context.memory.workingMemory[key];
196
+ }
197
+ async addRAGContext(executionId, contexts) {
198
+ const context = await this.getContext(executionId);
199
+ if (!context) {
200
+ throw new Error(`Execution context ${executionId} not found`);
201
+ }
202
+ context.ragContext = contexts;
203
+ context.updatedAt = new Date();
204
+ const redisKey = this.getKey(executionId);
205
+ const serialized = this.serialize(context);
206
+ const ttl = this.getTTL(context.state);
207
+ await this.client.setEx(redisKey, ttl, serialized);
208
+ }
209
+ async canContinue(executionId, maxSteps) {
210
+ const context = await this.getContext(executionId);
211
+ if (!context) {
212
+ return false;
213
+ }
214
+ if (context.state === agent_types_1.AgentState.COMPLETED || context.state === agent_types_1.AgentState.FAILED) {
215
+ return false;
216
+ }
217
+ if (context.steps.length >= maxSteps) {
218
+ return false;
219
+ }
220
+ return true;
221
+ }
222
+ async deleteContext(executionId) {
223
+ const context = await this.getContext(executionId);
224
+ if (context) {
225
+ // Remove from session index
226
+ await this.client.sRem(this.getSessionKey(context.sessionId), executionId);
227
+ }
228
+ const key = this.getKey(executionId);
229
+ await this.client.del(key);
230
+ }
231
+ async clear() {
232
+ // Get all keys with prefix
233
+ const pattern = `${this.keyPrefix}*`;
234
+ const keys = await this.client.keys(pattern);
235
+ if (keys.length > 0) {
236
+ await this.client.del(...keys);
237
+ }
238
+ }
239
+ async getSessionContexts(sessionId) {
240
+ const sessionKey = this.getSessionKey(sessionId);
241
+ const executionIds = await this.client.sMembers(sessionKey);
242
+ const contexts = [];
243
+ for (const executionId of executionIds) {
244
+ const context = await this.getContext(executionId);
245
+ if (context) {
246
+ contexts.push(context);
247
+ }
248
+ }
249
+ return contexts;
250
+ }
251
+ }
252
+ exports.RedisStateManager = RedisStateManager;
253
+ //# sourceMappingURL=redis-state.manager.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"redis-state.manager.js","sourceRoot":"","sources":["../../src/state/redis-state.manager.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAEH,sDAA2E;AAE3E,mCAAoC;AAiCpC;;;GAGG;AACH,MAAa,iBAAiB;IAO5B,YAAY,MAA+B;QACzC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAC;QAC9C,CAAC;QACD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;QAC5B,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,SAAS,IAAI,cAAc,CAAC;QACpD,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC,UAAU,IAAI,IAAI,CAAC,CAAC,SAAS;QACtD,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC,YAAY,IAAI,KAAK,CAAC,CAAC,WAAW;QAC7D,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,SAAS,IAAI,MAAM,CAAC,CAAC,SAAS;IACxD,CAAC;IAED;;OAEG;IACK,MAAM,CAAC,WAAmB;QAChC,OAAO,GAAG,IAAI,CAAC,SAAS,GAAG,WAAW,EAAE,CAAC;IAC3C,CAAC;IAED;;OAEG;IACK,aAAa,CAAC,SAAiB;QACrC,OAAO,GAAG,IAAI,CAAC,SAAS,WAAW,SAAS,EAAE,CAAC;IACjD,CAAC;IAED;;OAEG;IACK,SAAS,CAAC,OAAqB;QACrC,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE;YAC5C,IAAI,KAAK,YAAY,IAAI,EAAE,CAAC;gBAC1B,OAAO,KAAK,CAAC,WAAW,EAAE,CAAC;YAC7B,CAAC;YACD,OAAO,KAAK,CAAC;QACf,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACK,WAAW,CAAC,IAAY;QAC9B,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAChC,OAAO;YACL,GAAG,MAAM;YACT,SAAS,EAAE,IAAI,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC;YACrC,SAAS,EAAE,IAAI,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC;YACrC,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAe,EAAE,EAAE,CAAC,CAAC;gBAC5C,GAAG,IAAI;gBACP,SAAS,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC;aACpC,CAAC,CAAC;YACH,MAAM,EAAE;gBACN,GAAG,MAAM,CAAC,MAAM;gBAChB,mBAAmB,EAAE,MAAM,CAAC,MAAM,CAAC,mBAAmB,CAAC,GAAG,CACxD,CAAC,GAA0B,EAAE,EAAE,CAAC,CAAC;oBAC/B,GAAG,GAAG;oBACN,SAAS,EAAE,IAAI,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC;iBACnC,CAAC,CACH;aACF;SACF,CAAC;IACJ,CAAC;IAED;;OAEG;IACK,MAAM,CAAC,KAAiB;QAC9B,IAAI,KAAK,KAAK,wBAAU,CAAC,SAAS,EAAE,CAAC;YACnC,OAAO,IAAI,CAAC,YAAY,CAAC;QAC3B,CAAC;QACD,IAAI,KAAK,KAAK,wBAAU,CAAC,MAAM,EAAE,CAAC;YAChC,OAAO,IAAI,CAAC,SAAS,CAAC;QACxB,CAAC;QACD,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED,KAAK,CAAC,aAAa,CACjB,OAAe,EACf,SAAiB,EACjB,KAAa,EACb,MAAe,EACf,QAAkC;QAElC,MAAM,WAAW,GAAG,IAAA,mBAAU,GAAE,CAAC;QACjC,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;QAEvB,MAAM,OAAO,GAAiB;YAC5B,WAAW;YACX,OAAO;YACP,SAAS;YACT,MAAM;YACN,KAAK;YACL,KAAK,EAAE,wBAAU,CAAC,IAAI;YACtB,KAAK,EAAE,EAAE;YACT,MAAM,EAAE;gBACN,mBAAmB,EAAE,EAAE;gBACvB,aAAa,EAAE,EAAE;gBACjB,KAAK,EAAE,EAAE;gBACT,QAAQ,EAAE,EAAE;aACb;YACD,QAAQ,EAAE,QAAQ,IAAI,EAAE;YACxB,SAAS,EAAE,GAAG;YACd,SAAS,EAAE,GAAG;SACf,CAAC;QAEF,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;QACrC,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QAC3C,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAEvC,gBAAgB;QAChB,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC;QAE9C,uBAAuB;QACvB,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,SAAS,CAAC,EAAE,WAAW,CAAC,CAAC;QACnE,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,SAAS,CAAC,EAAE,GAAG,CAAC,CAAC;QAE7D,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,WAAmB;QAClC,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;QACrC,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAExC,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,OAAO,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;IAChC,CAAC;IAED,KAAK,CAAC,WAAW,CAAC,WAAmB,EAAE,QAAoB;QACzD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;QACnD,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,qBAAqB,WAAW,YAAY,CAAC,CAAC;QAChE,CAAC;QAED,OAAO,CAAC,KAAK,GAAG,QAAQ,CAAC;QACzB,OAAO,CAAC,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC;QAE/B,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;QACrC,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QAC3C,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAElC,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC;IAChD,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,WAAmB,EAAE,IAAe;QAChD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;QACnD,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,qBAAqB,WAAW,YAAY,CAAC,CAAC;QAChE,CAAC;QAED,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACzB,OAAO,CAAC,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC;QAE/B,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;QACrC,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QAC3C,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAEvC,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC;IAChD,CAAC;IAED,KAAK,CAAC,cAAc,CAAC,WAAmB,EAAE,OAA2B;QACnE,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;QACnD,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,qBAAqB,WAAW,YAAY,CAAC,CAAC;QAChE,CAAC;QAED,IAAI,OAAO,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC/B,MAAM,IAAI,KAAK,CAAC,oBAAoB,CAAC,CAAC;QACxC,CAAC;QAED,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QACzD,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QACjC,OAAO,CAAC,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC;QAE/B,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;QACrC,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QAC3C,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAEvC,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC;IAChD,CAAC;IAED,KAAK,CAAC,UAAU,CACd,WAAmB,EACnB,IAA8C,EAC9C,OAAe;QAEf,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;QACnD,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,qBAAqB,WAAW,YAAY,CAAC,CAAC;QAChE,CAAC;QAED,OAAO,CAAC,MAAM,CAAC,mBAAmB,CAAC,IAAI,CAAC;YACtC,IAAI;YACJ,OAAO;YACP,SAAS,EAAE,IAAI,IAAI,EAAE;SACtB,CAAC,CAAC;QACH,OAAO,CAAC,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC;QAE/B,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;QACrC,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QAC3C,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAEvC,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC;IAChD,CAAC;IAED,KAAK,CAAC,gBAAgB,CAAC,WAAmB,EAAE,GAAW,EAAE,KAAc;QACrE,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;QACnD,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,qBAAqB,WAAW,YAAY,CAAC,CAAC;QAChE,CAAC;QAED,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QAC1C,OAAO,CAAC,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC;QAE/B,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;QAC1C,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QAC3C,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAEvC,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC;IACrD,CAAC;IAED,KAAK,CAAC,gBAAgB,CAAC,WAAmB,EAAE,GAAW;QACrD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;QACnD,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,qBAAqB,WAAW,YAAY,CAAC,CAAC;QAChE,CAAC;QAED,OAAO,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;IAC3C,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,WAAmB,EAAE,QAAkB;QACzD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;QACnD,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,qBAAqB,WAAW,YAAY,CAAC,CAAC;QAChE,CAAC;QAED,OAAO,CAAC,UAAU,GAAG,QAAQ,CAAC;QAC9B,OAAO,CAAC,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC;QAE/B,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;QAC1C,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QAC3C,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAEvC,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC;IACrD,CAAC;IAED,KAAK,CAAC,WAAW,CAAC,WAAmB,EAAE,QAAgB;QACrD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;QACnD,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,KAAK,CAAC;QACf,CAAC;QAED,IAAI,OAAO,CAAC,KAAK,KAAK,wBAAU,CAAC,SAAS,IAAI,OAAO,CAAC,KAAK,KAAK,wBAAU,CAAC,MAAM,EAAE,CAAC;YAClF,OAAO,KAAK,CAAC;QACf,CAAC;QAED,IAAI,OAAO,CAAC,KAAK,CAAC,MAAM,IAAI,QAAQ,EAAE,CAAC;YACrC,OAAO,KAAK,CAAC;QACf,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,WAAmB;QACrC,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;QACnD,IAAI,OAAO,EAAE,CAAC;YACZ,4BAA4B;YAC5B,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,WAAW,CAAC,CAAC;QAC7E,CAAC;QAED,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;QACrC,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAED,KAAK,CAAC,KAAK;QACT,2BAA2B;QAC3B,MAAM,OAAO,GAAG,GAAG,IAAI,CAAC,SAAS,GAAG,CAAC;QACrC,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC7C,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpB,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;IAED,KAAK,CAAC,kBAAkB,CAAC,SAAiB;QACxC,MAAM,UAAU,GAAG,IAAI,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;QACjD,MAAM,YAAY,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;QAE5D,MAAM,QAAQ,GAAmB,EAAE,CAAC;QACpC,KAAK,MAAM,WAAW,IAAI,YAAY,EAAE,CAAC;YACvC,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;YACnD,IAAI,OAAO,EAAE,CAAC;gBACZ,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;QAED,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF;AAjTD,8CAiTC"}
@@ -0,0 +1,81 @@
1
+ /**
2
+ * SupervisorAgent — Orchestrate a team of worker agents via an LLM router
3
+ *
4
+ * The supervisor uses an LLM to:
5
+ * 1. Decompose an incoming task into subtasks
6
+ * 2. Route each subtask to the most appropriate worker agent
7
+ * 3. Accumulate results and decide when the task is complete
8
+ *
9
+ * This implements the "Supervisor ↔ Workers" multi-agent pattern:
10
+ *
11
+ * ```
12
+ * User Task
13
+ * │
14
+ * Supervisor ←───────────────────────┐
15
+ * │ │
16
+ * ┌───▼────────────────┐ Worker result
17
+ * │ Route to worker? │ │
18
+ * └───────────┬────────┘ │
19
+ * │ │
20
+ * ┌──────▼──────┐ │
21
+ * │ WorkerAgent │───────────────┘
22
+ * └─────────────┘
23
+ * ```
24
+ *
25
+ * @example
26
+ * ```ts
27
+ * const supervisor = runtime.createSupervisor({
28
+ * name: 'project-manager',
29
+ * workers: ['ResearchAgent', 'CoderAgent', 'WriterAgent'],
30
+ * maxRounds: 6,
31
+ * });
32
+ *
33
+ * const result = await supervisor.run('Build a REST API for a todo app');
34
+ * console.log(result.response);
35
+ * ```
36
+ */
37
+ import { SupervisorConfig, SupervisorResult } from '../graph/agent-graph.types';
38
+ import { AgentExecutionResult } from '../types/agent.types';
39
+ import { LLMProvider } from '../types/llm.types';
40
+ import '../prompts/supervisor-system.prompt';
41
+ import '../prompts/supervisor-routing.prompt';
42
+ interface RuntimeLike {
43
+ execute(agentName: string, input: string, options?: Record<string, unknown>): Promise<AgentExecutionResult>;
44
+ getAgentMetadata(agentName: string): {
45
+ description?: string;
46
+ } | undefined;
47
+ }
48
+ /**
49
+ * A supervisor that routes tasks to worker agents using an LLM.
50
+ * Obtain one via `AgentRuntime.createSupervisor(config)`.
51
+ */
52
+ export declare class SupervisorAgent {
53
+ private readonly config;
54
+ private readonly llmProvider;
55
+ private readonly runtime;
56
+ private readonly name;
57
+ private readonly workers;
58
+ private readonly maxRounds;
59
+ private readonly systemPrompt;
60
+ private readonly model?;
61
+ private readonly temperature;
62
+ constructor(config: SupervisorConfig, llmProvider: LLMProvider, runtime: RuntimeLike);
63
+ /**
64
+ * Run the supervisor on a given task.
65
+ * The supervisor will iteratively route subtasks to workers until either:
66
+ * - The LLM decides the task is complete and emits a final response, or
67
+ * - `maxRounds` is reached (returns the accumulated context as the response).
68
+ */
69
+ run(task: string, options?: {
70
+ sessionId?: string;
71
+ userId?: string;
72
+ }): Promise<SupervisorResult>;
73
+ private makeRoutingDecision;
74
+ private parseDecision;
75
+ private buildDefaultSystemPrompt;
76
+ private buildWorkerList;
77
+ get supervisorName(): string;
78
+ get workerNames(): string[];
79
+ }
80
+ export {};
81
+ //# sourceMappingURL=supervisor.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"supervisor.d.ts","sourceRoot":"","sources":["../../src/supervisor/supervisor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAIjB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD,OAAO,qCAAqC,CAAC;AAC7C,OAAO,sCAAsC,CAAC;AAK9C,UAAU,WAAW;IACnB,OAAO,CACL,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACjC,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;CAC3E;AAED;;;GAGG;AACH,qBAAa,eAAe;IASxB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAV1B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAW;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;gBAGlB,MAAM,EAAE,gBAAgB,EACxB,WAAW,EAAE,WAAW,EACxB,OAAO,EAAE,WAAW;IAuBvC;;;;;OAKG;IACG,GAAG,CACP,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO,GACpD,OAAO,CAAC,gBAAgB,CAAC;YAkGd,mBAAmB;IAgCjC,OAAO,CAAC,aAAa;IAyBrB,OAAO,CAAC,wBAAwB;IAOhC,OAAO,CAAC,eAAe;IASvB,IAAI,cAAc,IAAI,MAAM,CAE3B;IAED,IAAI,WAAW,IAAI,MAAM,EAAE,CAE1B;CACF"}
@@ -0,0 +1,220 @@
1
+ "use strict";
2
+ /**
3
+ * SupervisorAgent — Orchestrate a team of worker agents via an LLM router
4
+ *
5
+ * The supervisor uses an LLM to:
6
+ * 1. Decompose an incoming task into subtasks
7
+ * 2. Route each subtask to the most appropriate worker agent
8
+ * 3. Accumulate results and decide when the task is complete
9
+ *
10
+ * This implements the "Supervisor ↔ Workers" multi-agent pattern:
11
+ *
12
+ * ```
13
+ * User Task
14
+ * │
15
+ * Supervisor ←───────────────────────┐
16
+ * │ │
17
+ * ┌───▼────────────────┐ Worker result
18
+ * │ Route to worker? │ │
19
+ * └───────────┬────────┘ │
20
+ * │ │
21
+ * ┌──────▼──────┐ │
22
+ * │ WorkerAgent │───────────────┘
23
+ * └─────────────┘
24
+ * ```
25
+ *
26
+ * @example
27
+ * ```ts
28
+ * const supervisor = runtime.createSupervisor({
29
+ * name: 'project-manager',
30
+ * workers: ['ResearchAgent', 'CoderAgent', 'WriterAgent'],
31
+ * maxRounds: 6,
32
+ * });
33
+ *
34
+ * const result = await supervisor.run('Build a REST API for a todo app');
35
+ * console.log(result.response);
36
+ * ```
37
+ */
38
+ Object.defineProperty(exports, "__esModule", { value: true });
39
+ exports.SupervisorAgent = void 0;
40
+ const prompts_1 = require("@hazeljs/prompts");
41
+ require("../prompts/supervisor-system.prompt");
42
+ require("../prompts/supervisor-routing.prompt");
43
+ const supervisor_system_prompt_1 = require("../prompts/supervisor-system.prompt");
44
+ const supervisor_routing_prompt_1 = require("../prompts/supervisor-routing.prompt");
45
+ /**
46
+ * A supervisor that routes tasks to worker agents using an LLM.
47
+ * Obtain one via `AgentRuntime.createSupervisor(config)`.
48
+ */
49
+ class SupervisorAgent {
50
+ constructor(config, llmProvider, runtime) {
51
+ this.config = config;
52
+ this.llmProvider = llmProvider;
53
+ this.runtime = runtime;
54
+ this.name = config.name;
55
+ this.workers = config.workers;
56
+ this.maxRounds = config.maxRounds ?? 10;
57
+ this.temperature = config.temperature ?? 0;
58
+ this.model = config.model;
59
+ // Collect worker descriptions for the system prompt
60
+ const workerInfos = this.workers.map((w) => ({
61
+ name: w,
62
+ description: runtime.getAgentMetadata(w)?.description ?? `Worker agent: ${w}`,
63
+ }));
64
+ this.systemPrompt = config.systemPrompt
65
+ ? `${config.systemPrompt}\n\n${this.buildWorkerList(workerInfos)}`
66
+ : this.buildDefaultSystemPrompt(workerInfos);
67
+ }
68
+ // ---------------------------------------------------------------------------
69
+ // Public API
70
+ // ---------------------------------------------------------------------------
71
+ /**
72
+ * Run the supervisor on a given task.
73
+ * The supervisor will iteratively route subtasks to workers until either:
74
+ * - The LLM decides the task is complete and emits a final response, or
75
+ * - `maxRounds` is reached (returns the accumulated context as the response).
76
+ */
77
+ async run(task, options = {}) {
78
+ const startTime = Date.now();
79
+ const rounds = [];
80
+ // Conversation context the supervisor maintains across rounds
81
+ const conversationContext = [`Task: ${task}`];
82
+ try {
83
+ for (let round = 1; round <= this.maxRounds; round++) {
84
+ const roundStart = Date.now();
85
+ // Ask the LLM supervisor to decide what to do next
86
+ const decision = await this.makeRoutingDecision(task, conversationContext);
87
+ if (decision.action === 'finish') {
88
+ const response = decision.response ?? conversationContext.join('\n\n');
89
+ rounds.push({
90
+ round,
91
+ decision,
92
+ duration: Date.now() - roundStart,
93
+ });
94
+ return {
95
+ response,
96
+ rounds,
97
+ totalDuration: Date.now() - startTime,
98
+ completedAt: new Date(),
99
+ success: true,
100
+ };
101
+ }
102
+ // Delegate to a worker agent
103
+ if (decision.action === 'delegate' && decision.worker && decision.subtask) {
104
+ if (!this.workers.includes(decision.worker)) {
105
+ throw new Error(`Supervisor "${this.name}" tried to route to unknown worker "${decision.worker}". ` +
106
+ `Available workers: ${this.workers.join(', ')}`);
107
+ }
108
+ const workerResult = await this.runtime.execute(decision.worker, decision.subtask, {
109
+ sessionId: options.sessionId,
110
+ userId: options.userId,
111
+ });
112
+ // Add the worker result to the conversation context
113
+ conversationContext.push(`Round ${round} — Worker: ${decision.worker}\n` +
114
+ `Subtask: ${decision.subtask}\n` +
115
+ `Result: ${workerResult.response ?? '(no response)'}`);
116
+ rounds.push({
117
+ round,
118
+ decision,
119
+ workerResult,
120
+ duration: Date.now() - roundStart,
121
+ });
122
+ continue;
123
+ }
124
+ // Unexpected decision shape — treat as finish
125
+ rounds.push({ round, decision, duration: Date.now() - roundStart });
126
+ break;
127
+ }
128
+ // maxRounds reached without a 'finish' decision
129
+ const finalResponse = conversationContext.length > 1
130
+ ? `Supervisor reached maximum rounds (${this.maxRounds}).\n\n` +
131
+ conversationContext.slice(1).join('\n\n')
132
+ : `Supervisor reached maximum rounds without producing a response.`;
133
+ return {
134
+ response: finalResponse,
135
+ rounds,
136
+ totalDuration: Date.now() - startTime,
137
+ completedAt: new Date(),
138
+ success: true,
139
+ };
140
+ }
141
+ catch (error) {
142
+ return {
143
+ response: '',
144
+ rounds,
145
+ totalDuration: Date.now() - startTime,
146
+ completedAt: new Date(),
147
+ success: false,
148
+ error: error,
149
+ };
150
+ }
151
+ }
152
+ // ---------------------------------------------------------------------------
153
+ // Private: LLM routing
154
+ // ---------------------------------------------------------------------------
155
+ async makeRoutingDecision(originalTask, context) {
156
+ const contextSummary = context.length > 1 ? '\n\nWork completed so far:\n' + context.slice(1).join('\n\n') : '';
157
+ const userMessage = prompts_1.PromptRegistry.get(supervisor_routing_prompt_1.SUPERVISOR_ROUTING_KEY).render({ originalTask, contextSummary });
158
+ try {
159
+ const llmResponse = await this.llmProvider.chat({
160
+ messages: [
161
+ { role: 'system', content: this.systemPrompt },
162
+ { role: 'user', content: userMessage },
163
+ ],
164
+ temperature: this.temperature,
165
+ ...(this.model ? { model: this.model } : {}),
166
+ });
167
+ return this.parseDecision(llmResponse.content);
168
+ }
169
+ catch {
170
+ // On LLM error, default to finishing with accumulated context
171
+ return {
172
+ action: 'finish',
173
+ response: context.slice(1).join('\n\n') || 'Unable to complete task due to LLM error.',
174
+ thought: 'LLM call failed, returning accumulated context.',
175
+ };
176
+ }
177
+ }
178
+ parseDecision(raw) {
179
+ // Strip markdown code fences if present
180
+ const cleaned = raw
181
+ .replace(/^```(?:json)?\s*/i, '')
182
+ .replace(/\s*```$/i, '')
183
+ .trim();
184
+ try {
185
+ const parsed = JSON.parse(cleaned);
186
+ if (parsed.action !== 'delegate' && parsed.action !== 'finish') {
187
+ return { action: 'finish', response: cleaned };
188
+ }
189
+ return parsed;
190
+ }
191
+ catch {
192
+ // If the LLM returned plain text, treat it as a final answer
193
+ return { action: 'finish', response: raw };
194
+ }
195
+ }
196
+ // ---------------------------------------------------------------------------
197
+ // Private: prompt builders
198
+ // ---------------------------------------------------------------------------
199
+ buildDefaultSystemPrompt(workers) {
200
+ return prompts_1.PromptRegistry.get(supervisor_system_prompt_1.SUPERVISOR_SYSTEM_KEY).render({
201
+ name: this.name,
202
+ workerList: this.buildWorkerList(workers),
203
+ });
204
+ }
205
+ buildWorkerList(workers) {
206
+ const lines = workers.map((w) => ` • ${w.name}: ${w.description}`);
207
+ return `Available workers:\n${lines.join('\n')}`;
208
+ }
209
+ // ---------------------------------------------------------------------------
210
+ // Introspection
211
+ // ---------------------------------------------------------------------------
212
+ get supervisorName() {
213
+ return this.name;
214
+ }
215
+ get workerNames() {
216
+ return [...this.workers];
217
+ }
218
+ }
219
+ exports.SupervisorAgent = SupervisorAgent;
220
+ //# sourceMappingURL=supervisor.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"supervisor.js","sourceRoot":"","sources":["../../src/supervisor/supervisor.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;;;AAWH,8CAAkD;AAClD,+CAA6C;AAC7C,gDAA8C;AAC9C,kFAA4E;AAC5E,oFAA8E;AAY9E;;;GAGG;AACH,MAAa,eAAe;IAQ1B,YACmB,MAAwB,EACxB,WAAwB,EACxB,OAAoB;QAFpB,WAAM,GAAN,MAAM,CAAkB;QACxB,gBAAW,GAAX,WAAW,CAAa;QACxB,YAAO,GAAP,OAAO,CAAa;QAErC,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;QACxB,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QAC9B,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,SAAS,IAAI,EAAE,CAAC;QACxC,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,WAAW,IAAI,CAAC,CAAC;QAC3C,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;QAE1B,oDAAoD;QACpD,MAAM,WAAW,GAA2B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACnE,IAAI,EAAE,CAAC;YACP,WAAW,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,EAAE,WAAW,IAAI,iBAAiB,CAAC,EAAE;SAC9E,CAAC,CAAC,CAAC;QAEJ,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC,YAAY;YACrC,CAAC,CAAC,GAAG,MAAM,CAAC,YAAY,OAAO,IAAI,CAAC,eAAe,CAAC,WAAW,CAAC,EAAE;YAClE,CAAC,CAAC,IAAI,CAAC,wBAAwB,CAAC,WAAW,CAAC,CAAC;IACjD,CAAC;IAED,8EAA8E;IAC9E,aAAa;IACb,8EAA8E;IAE9E;;;;;OAKG;IACH,KAAK,CAAC,GAAG,CACP,IAAY,EACZ,UAAmD,EAAE;QAErD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC7B,MAAM,MAAM,GAAsB,EAAE,CAAC;QAErC,8DAA8D;QAC9D,MAAM,mBAAmB,GAAa,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC;QAExD,IAAI,CAAC;YACH,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,IAAI,IAAI,CAAC,SAAS,EAAE,KAAK,EAAE,EAAE,CAAC;gBACrD,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;gBAE9B,mDAAmD;gBACnD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,mBAAmB,CAAC,IAAI,EAAE,mBAAmB,CAAC,CAAC;gBAE3E,IAAI,QAAQ,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;oBACjC,MAAM,QAAQ,GAAG,QAAQ,CAAC,QAAQ,IAAI,mBAAmB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;oBAEvE,MAAM,CAAC,IAAI,CAAC;wBACV,KAAK;wBACL,QAAQ;wBACR,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,UAAU;qBAClC,CAAC,CAAC;oBAEH,OAAO;wBACL,QAAQ;wBACR,MAAM;wBACN,aAAa,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;wBACrC,WAAW,EAAE,IAAI,IAAI,EAAE;wBACvB,OAAO,EAAE,IAAI;qBACd,CAAC;gBACJ,CAAC;gBAED,6BAA6B;gBAC7B,IAAI,QAAQ,CAAC,MAAM,KAAK,UAAU,IAAI,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,OAAO,EAAE,CAAC;oBAC1E,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;wBAC5C,MAAM,IAAI,KAAK,CACb,eAAe,IAAI,CAAC,IAAI,uCAAuC,QAAQ,CAAC,MAAM,KAAK;4BACjF,sBAAsB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAClD,CAAC;oBACJ,CAAC;oBAED,MAAM,YAAY,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,OAAO,EAAE;wBACjF,SAAS,EAAE,OAAO,CAAC,SAAS;wBAC5B,MAAM,EAAE,OAAO,CAAC,MAAM;qBACvB,CAAC,CAAC;oBAEH,oDAAoD;oBACpD,mBAAmB,CAAC,IAAI,CACtB,SAAS,KAAK,cAAc,QAAQ,CAAC,MAAM,IAAI;wBAC7C,YAAY,QAAQ,CAAC,OAAO,IAAI;wBAChC,WAAW,YAAY,CAAC,QAAQ,IAAI,eAAe,EAAE,CACxD,CAAC;oBAEF,MAAM,CAAC,IAAI,CAAC;wBACV,KAAK;wBACL,QAAQ;wBACR,YAAY;wBACZ,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,UAAU;qBAClC,CAAC,CAAC;oBAEH,SAAS;gBACX,CAAC;gBAED,8CAA8C;gBAC9C,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,UAAU,EAAE,CAAC,CAAC;gBACpE,MAAM;YACR,CAAC;YAED,gDAAgD;YAChD,MAAM,aAAa,GACjB,mBAAmB,CAAC,MAAM,GAAG,CAAC;gBAC5B,CAAC,CAAC,sCAAsC,IAAI,CAAC,SAAS,QAAQ;oBAC5D,mBAAmB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC;gBAC3C,CAAC,CAAC,iEAAiE,CAAC;YAExE,OAAO;gBACL,QAAQ,EAAE,aAAa;gBACvB,MAAM;gBACN,aAAa,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;gBACrC,WAAW,EAAE,IAAI,IAAI,EAAE;gBACvB,OAAO,EAAE,IAAI;aACd,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO;gBACL,QAAQ,EAAE,EAAE;gBACZ,MAAM;gBACN,aAAa,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;gBACrC,WAAW,EAAE,IAAI,IAAI,EAAE;gBACvB,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE,KAAc;aACtB,CAAC;QACJ,CAAC;IACH,CAAC;IAED,8EAA8E;IAC9E,uBAAuB;IACvB,8EAA8E;IAEtE,KAAK,CAAC,mBAAmB,CAC/B,YAAoB,EACpB,OAAiB;QAEjB,MAAM,cAAc,GAClB,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,8BAA8B,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAE3F,MAAM,WAAW,GAAG,wBAAc,CAAC,GAAG,CACpC,kDAAsB,CACvB,CAAC,MAAM,CAAC,EAAE,YAAY,EAAE,cAAc,EAAE,CAAC,CAAC;QAE3C,IAAI,CAAC;YACH,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC;gBAC9C,QAAQ,EAAE;oBACR,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,CAAC,YAAY,EAAE;oBAC9C,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE;iBACvC;gBACD,WAAW,EAAE,IAAI,CAAC,WAAW;gBAC7B,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC7C,CAAC,CAAC;YAEH,OAAO,IAAI,CAAC,aAAa,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;QACjD,CAAC;QAAC,MAAM,CAAC;YACP,8DAA8D;YAC9D,OAAO;gBACL,MAAM,EAAE,QAAQ;gBAChB,QAAQ,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,2CAA2C;gBACtF,OAAO,EAAE,iDAAiD;aAC3D,CAAC;QACJ,CAAC;IACH,CAAC;IAEO,aAAa,CAAC,GAAW;QAC/B,wCAAwC;QACxC,MAAM,OAAO,GAAG,GAAG;aAChB,OAAO,CAAC,mBAAmB,EAAE,EAAE,CAAC;aAChC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC;aACvB,IAAI,EAAE,CAAC;QAEV,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAuB,CAAC;YAEzD,IAAI,MAAM,CAAC,MAAM,KAAK,UAAU,IAAI,MAAM,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;gBAC/D,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;YACjD,CAAC;YAED,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,MAAM,CAAC;YACP,6DAA6D;YAC7D,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC;QAC7C,CAAC;IACH,CAAC;IAED,8EAA8E;IAC9E,2BAA2B;IAC3B,8EAA8E;IAEtE,wBAAwB,CAAC,OAA+B;QAC9D,OAAO,wBAAc,CAAC,GAAG,CAAuC,gDAAqB,CAAC,CAAC,MAAM,CAAC;YAC5F,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,UAAU,EAAE,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC;SAC1C,CAAC,CAAC;IACL,CAAC;IAEO,eAAe,CAAC,OAA+B;QACrD,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;QACpE,OAAO,uBAAuB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;IACnD,CAAC;IAED,8EAA8E;IAC9E,gBAAgB;IAChB,8EAA8E;IAE9E,IAAI,cAAc;QAChB,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IAED,IAAI,WAAW;QACb,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;IAC3B,CAAC;CACF;AA7ND,0CA6NC"}