orchajs 0.27.1 → 0.27.3

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 (37) hide show
  1. package/dist/amarsia/analytics.d.ts +1 -0
  2. package/dist/amarsia/analytics.js +128 -50
  3. package/dist/amarsia/inference.js +4 -9
  4. package/dist/compiler/build-project.js +15 -4
  5. package/dist/compiler/compile.js +53 -11
  6. package/dist/errors.d.ts +2 -0
  7. package/dist/errors.js +128 -9
  8. package/dist/file-content.js +13 -1
  9. package/dist/providers/anthropic.js +6 -12
  10. package/dist/providers/bedrock.js +4 -8
  11. package/dist/providers/deepseek.js +6 -13
  12. package/dist/providers/dependencies.js +15 -4
  13. package/dist/providers/google-gemini.js +4 -9
  14. package/dist/providers/openai.js +6 -13
  15. package/dist/runtime/agent.js +177 -10
  16. package/dist/runtime/create-orcha.js +18 -17
  17. package/dist/runtime/structured-output.d.ts +18 -1
  18. package/dist/runtime/structured-output.js +75 -5
  19. package/dist/testing.js +23 -14
  20. package/dist/types.d.ts +1 -0
  21. package/dist-cjs/amarsia/analytics.js +129 -49
  22. package/dist-cjs/amarsia/inference.js +12 -9
  23. package/dist-cjs/compiler/build-project.js +14 -4
  24. package/dist-cjs/compiler/compile.js +65 -20
  25. package/dist-cjs/errors.js +106 -8
  26. package/dist-cjs/file-content.js +16 -1
  27. package/dist-cjs/providers/anthropic.js +19 -19
  28. package/dist-cjs/providers/bedrock.js +18 -17
  29. package/dist-cjs/providers/deepseek.js +13 -16
  30. package/dist-cjs/providers/dependencies.js +14 -4
  31. package/dist-cjs/providers/google-gemini.js +12 -9
  32. package/dist-cjs/providers/openai.js +13 -13
  33. package/dist-cjs/runtime/agent.js +164 -9
  34. package/dist-cjs/runtime/create-orcha.js +29 -26
  35. package/dist-cjs/runtime/structured-output.js +81 -5
  36. package/dist-cjs/testing.js +30 -16
  37. package/package.json +1 -1
@@ -1,24 +1,94 @@
1
+ export class StructuredOutputError extends Error {
2
+ kind;
3
+ rawText;
4
+ responsePreview;
5
+ schemaErrors;
6
+ response;
7
+ constructor(message, options) {
8
+ super(message, { cause: options.cause });
9
+ this.name = "StructuredOutputError";
10
+ this.kind = options.kind;
11
+ this.rawText = options.rawText;
12
+ this.responsePreview = options.responsePreview;
13
+ this.schemaErrors = options.schemaErrors;
14
+ }
15
+ }
16
+ export function resolveProviderStructuredOutput(request, baseResponse, textOutput) {
17
+ if (request.outputType !== "json" ||
18
+ baseResponse.toolCalls.length > 0 ||
19
+ baseResponse.stopReason === "max_tokens" ||
20
+ baseResponse.stopReason === "content_filter") {
21
+ return baseResponse;
22
+ }
23
+ try {
24
+ return {
25
+ ...baseResponse,
26
+ output: parseStructuredOutput(textOutput, request.outputSchema ?? {}),
27
+ };
28
+ }
29
+ catch (error) {
30
+ if (error instanceof StructuredOutputError) {
31
+ error.response = baseResponse;
32
+ }
33
+ throw error;
34
+ }
35
+ }
1
36
  export function parseStructuredOutput(text, schema) {
37
+ const preview = previewText(text);
2
38
  const candidate = extractJsonCandidate(text);
3
39
  if (!candidate) {
4
- throw new Error("Model response did not contain a JSON object or array.");
40
+ const suffix = preview
41
+ ? ` Model returned plain text: ${JSON.stringify(preview)}`
42
+ : " Model returned an empty response.";
43
+ throw new StructuredOutputError(`Model response did not contain a JSON object or array.${suffix}`, {
44
+ kind: "missing_json",
45
+ rawText: text,
46
+ responsePreview: preview,
47
+ });
5
48
  }
6
49
  let value;
7
50
  try {
8
51
  value = JSON.parse(candidate);
9
52
  }
10
53
  catch (error) {
11
- throw new Error("Model response contained invalid JSON.", { cause: error });
54
+ const detail = error instanceof Error ? error.message : "Invalid JSON";
55
+ const suffix = preview
56
+ ? ` Model returned: ${JSON.stringify(preview)}`
57
+ : "";
58
+ throw new StructuredOutputError(`Model response contained invalid JSON (${detail}).${suffix}`, {
59
+ kind: "invalid_json",
60
+ rawText: text,
61
+ responsePreview: preview,
62
+ cause: error,
63
+ });
64
+ }
65
+ const errors = [];
66
+ validateSchemaValue(value, schema, "$", errors);
67
+ if (errors.length > 0) {
68
+ throw new StructuredOutputError(`Value failed outputSchema: ${errors.join("; ")}`, {
69
+ kind: "schema_mismatch",
70
+ rawText: text,
71
+ responsePreview: preview,
72
+ schemaErrors: errors,
73
+ });
12
74
  }
13
- validateStructuredValue(value, schema);
14
75
  return value;
15
76
  }
16
- export function validateStructuredValue(value, schema) {
77
+ export function validateStructuredValue(value, schema, label = "outputSchema") {
17
78
  const errors = [];
18
79
  validateSchemaValue(value, schema, "$", errors);
19
80
  if (errors.length > 0) {
20
- throw new Error(`Value failed outputSchema: ${errors.join("; ")}`);
81
+ throw new Error(`Value failed ${label}: ${errors.join("; ")}`);
82
+ }
83
+ }
84
+ function previewText(text, maxLength = 240) {
85
+ const compact = text.replace(/\s+/g, " ").trim();
86
+ if (!compact) {
87
+ return undefined;
21
88
  }
89
+ return compact.length > maxLength
90
+ ? `${compact.slice(0, maxLength)}...`
91
+ : compact;
22
92
  }
23
93
  function extractJsonCandidate(text) {
24
94
  const trimmed = text.trim();
package/dist/testing.js CHANGED
@@ -52,20 +52,29 @@ export async function runTests(orcha, options = {}) {
52
52
  const store = createStore(manifest);
53
53
  const activeSessions = new Set();
54
54
  const sessionControls = new Map();
55
- const subagents = Object.fromEntries(Object.entries(manifest.subagents ?? {}).map(([name, subagentManifest]) => [
56
- name,
57
- new RuntimeAgent({
58
- manifest: subagentManifest,
59
- configuration: context.configuration,
60
- store: createStore(subagentManifest),
61
- activeSessions,
62
- sessionControls,
63
- generateProviderResponse: context.generateProviderResponse,
64
- delegatedOnly: true,
65
- sessionIdPrefix: "ses_test_",
66
- projectRoot: context.projectRoot,
67
- }),
68
- ]));
55
+ const createTestSubagents = (parentManifest, ancestry) => Object.fromEntries(Object.entries(parentManifest.subagents ?? {}).map(([name, subagentManifest]) => {
56
+ if (ancestry.has(name)) {
57
+ throw new Error(`Circular subagent registration detected: ${[...ancestry, name].join(" -> ")}.`);
58
+ }
59
+ const nextAncestry = new Set(ancestry);
60
+ nextAncestry.add(name);
61
+ return [
62
+ name,
63
+ new RuntimeAgent({
64
+ manifest: subagentManifest,
65
+ configuration: context.configuration,
66
+ store: createStore(subagentManifest),
67
+ activeSessions,
68
+ sessionControls,
69
+ generateProviderResponse: context.generateProviderResponse,
70
+ subagents: createTestSubagents(subagentManifest, nextAncestry),
71
+ delegatedOnly: true,
72
+ sessionIdPrefix: "ses_test_",
73
+ projectRoot: context.projectRoot,
74
+ }),
75
+ ];
76
+ }));
77
+ const subagents = createTestSubagents(manifest, new Set([manifest.key ?? manifest.name]));
69
78
  const agent = new RuntimeAgent({
70
79
  manifest: withTestActions(manifest, Object.keys(testCase.configuration.actions ?? {})),
71
80
  configuration: context.configuration,
package/dist/types.d.ts CHANGED
@@ -54,6 +54,7 @@ export type McpRegistration = Record<string, string>;
54
54
  export type SubagentRegistration = string | {
55
55
  path: string;
56
56
  mcp?: McpRegistration;
57
+ subagents?: Record<string, SubagentRegistration>;
57
58
  };
58
59
  export type AgentRegistration = string | {
59
60
  path: string;
@@ -33,20 +33,28 @@ const RELEVANT_EVENTS = /* @__PURE__ */ new Set([
33
33
  "evaluation.completed",
34
34
  "evaluation.failed"
35
35
  ]);
36
+ const PROGRESS_EVENTS = /* @__PURE__ */ new Set([
37
+ "message.created",
38
+ "action.completed",
39
+ "action.failed",
40
+ "subagent.completed",
41
+ "subagent.failed"
42
+ ]);
36
43
  const MAX_BATCH_RUNS = 100;
37
44
  const MAX_KEEPALIVE_BYTES = 48 * 1024;
38
45
  const HEARTBEAT_INTERVAL_MS = 3e4;
39
- const EVALUATION_FLUSH_TIMEOUT_MS = 5e3;
46
+ const MAX_CONCURRENT_FLUSHES = 2;
40
47
  class AmarsiaTelemetryClient {
41
48
  #key;
42
49
  #baseUrl;
43
50
  #queue = /* @__PURE__ */ new Map();
44
51
  #activeRuns = /* @__PURE__ */ new Map();
52
+ #terminalRuns = /* @__PURE__ */ new Set();
45
53
  #pendingProjections = /* @__PURE__ */ new Set();
54
+ #inFlightFlushes = /* @__PURE__ */ new Set();
46
55
  #timer;
47
56
  #heartbeatTimer;
48
57
  #attempt = 0;
49
- #flushPromise;
50
58
  constructor(options) {
51
59
  this.#key = options.key;
52
60
  this.#baseUrl = (0, import_endpoint.resolveAmarsiaEndpoint)(options.endpoint);
@@ -54,24 +62,38 @@ class AmarsiaTelemetryClient {
54
62
  enqueue(fact) {
55
63
  this.#queue.set(fact.event_id, fact);
56
64
  if (fact.status === "running") {
65
+ this.#terminalRuns.delete(fact.event_id);
57
66
  this.#activeRuns.set(fact.event_id, fact);
58
67
  this.#scheduleHeartbeat();
59
- } else {
60
- this.#activeRuns.delete(fact.event_id);
61
- if (this.#activeRuns.size === 0 && this.#heartbeatTimer) {
62
- clearTimeout(this.#heartbeatTimer);
63
- this.#heartbeatTimer = void 0;
68
+ if (this.#queue.size >= 20) {
69
+ void this.#flush();
70
+ return;
64
71
  }
65
- }
66
- if (fact.status !== "running") {
67
- this.#scheduleTerminal();
72
+ this.#schedule(250);
68
73
  return;
69
74
  }
70
- if (this.#queue.size >= 20) {
71
- void this.#flush();
75
+ this.#terminalRuns.add(fact.event_id);
76
+ this.#activeRuns.delete(fact.event_id);
77
+ if (this.#activeRuns.size === 0 && this.#heartbeatTimer) {
78
+ clearTimeout(this.#heartbeatTimer);
79
+ this.#heartbeatTimer = void 0;
80
+ }
81
+ if (this.#timer) {
82
+ clearTimeout(this.#timer);
83
+ this.#timer = void 0;
84
+ }
85
+ void this.#flush();
86
+ }
87
+ updateActiveRun(fact) {
88
+ if (fact.status !== "running" || this.#terminalRuns.has(fact.event_id)) {
72
89
  return;
73
90
  }
74
- this.#schedule(250);
91
+ if (this.#activeRuns.has(fact.event_id)) {
92
+ this.#activeRuns.set(fact.event_id, fact);
93
+ }
94
+ if (this.#queue.has(fact.event_id)) {
95
+ this.#queue.set(fact.event_id, fact);
96
+ }
75
97
  }
76
98
  #schedule(delay) {
77
99
  if (this.#timer) return;
@@ -89,19 +111,14 @@ class AmarsiaTelemetryClient {
89
111
  this.#pendingProjections.delete(projection);
90
112
  });
91
113
  }
92
- #scheduleTerminal() {
93
- if (this.#timer) clearTimeout(this.#timer);
94
- this.#timer = setTimeout(() => {
95
- this.#timer = void 0;
96
- void this.#flush();
97
- }, 0);
98
- }
99
114
  #scheduleHeartbeat() {
100
115
  if (this.#heartbeatTimer || this.#activeRuns.size === 0) return;
101
116
  this.#heartbeatTimer = setTimeout(() => {
102
117
  this.#heartbeatTimer = void 0;
103
118
  for (const fact of this.#activeRuns.values()) {
104
- this.#queue.set(fact.event_id, fact);
119
+ if (!this.#terminalRuns.has(fact.event_id)) {
120
+ this.#queue.set(fact.event_id, fact);
121
+ }
105
122
  }
106
123
  void this.#flush();
107
124
  this.#scheduleHeartbeat();
@@ -112,7 +129,7 @@ class AmarsiaTelemetryClient {
112
129
  async drain(options = {}) {
113
130
  const timeoutMs = Math.max(0, options.timeoutMs ?? 2e3);
114
131
  const deadline = Date.now() + timeoutMs;
115
- while (this.#pendingProjections.size > 0 || this.#queue.size > 0 || this.#flushPromise) {
132
+ while (this.#pendingProjections.size > 0 || this.#queue.size > 0 || this.#inFlightFlushes.size > 0) {
116
133
  const remaining = deadline - Date.now();
117
134
  if (remaining <= 0) return;
118
135
  if (this.#pendingProjections.size > 0) {
@@ -126,10 +143,19 @@ class AmarsiaTelemetryClient {
126
143
  clearTimeout(this.#timer);
127
144
  this.#timer = void 0;
128
145
  }
129
- await Promise.race([
130
- this.#flush(),
131
- new Promise((resolve) => setTimeout(resolve, remaining))
132
- ]);
146
+ if (this.#queue.size > 0) {
147
+ await Promise.race([
148
+ this.#flush(),
149
+ new Promise((resolve) => setTimeout(resolve, remaining))
150
+ ]);
151
+ continue;
152
+ }
153
+ if (this.#inFlightFlushes.size > 0) {
154
+ await Promise.race([
155
+ Promise.allSettled([...this.#inFlightFlushes]).then(() => void 0),
156
+ new Promise((resolve) => setTimeout(resolve, remaining))
157
+ ]);
158
+ }
133
159
  }
134
160
  }
135
161
  async close(options = {}) {
@@ -146,20 +172,33 @@ class AmarsiaTelemetryClient {
146
172
  this.#activeRuns.clear();
147
173
  }
148
174
  async #flush() {
149
- if (this.#flushPromise) return this.#flushPromise;
150
- if (this.#queue.size === 0) return;
151
- this.#flushPromise = this.#performFlush();
175
+ if (this.#queue.size === 0) {
176
+ if (this.#inFlightFlushes.size > 0) {
177
+ await Promise.allSettled([...this.#inFlightFlushes]);
178
+ }
179
+ return;
180
+ }
181
+ const hasTerminalFact = [...this.#queue.values()].some(
182
+ (fact) => fact.status !== "running"
183
+ );
184
+ const maxConcurrent = hasTerminalFact ? MAX_CONCURRENT_FLUSHES : 1;
185
+ if (this.#inFlightFlushes.size >= maxConcurrent) {
186
+ await Promise.allSettled([...this.#inFlightFlushes]);
187
+ return;
188
+ }
189
+ const flushPromise = this.#performFlush();
190
+ this.#inFlightFlushes.add(flushPromise);
152
191
  try {
153
- await this.#flushPromise;
192
+ await flushPromise;
154
193
  } finally {
155
- this.#flushPromise = void 0;
194
+ this.#inFlightFlushes.delete(flushPromise);
156
195
  if (this.#queue.size > 0 && !this.#timer) {
157
- const hasTerminalFact = [...this.#queue.values()].some(
196
+ const remainingHasTerminal = [...this.#queue.values()].some(
158
197
  (fact) => fact.status !== "running"
159
198
  );
160
- if (hasTerminalFact) {
199
+ if (remainingHasTerminal) {
161
200
  void this.#flush();
162
- } else {
201
+ } else if (this.#inFlightFlushes.size === 0) {
163
202
  this.#schedule(250);
164
203
  }
165
204
  }
@@ -194,6 +233,9 @@ class AmarsiaTelemetryClient {
194
233
  this.#attempt += 1;
195
234
  if (this.#attempt <= 6) {
196
235
  for (const fact of batch) {
236
+ if (fact.status === "running" && this.#terminalRuns.has(fact.event_id)) {
237
+ continue;
238
+ }
197
239
  if (!this.#queue.has(fact.event_id)) {
198
240
  this.#queue.set(fact.event_id, fact);
199
241
  }
@@ -233,19 +275,48 @@ function withAmarsiaTelemetry(options) {
233
275
  async append(sessionId, events) {
234
276
  await store.append(sessionId, events);
235
277
  const runs = relevantRuns(events);
236
- if (runs.size === 0 && !projections.has(sessionId) && !pending.has(sessionId)) {
278
+ const progressRuns = progressOnlyRuns(events, runs);
279
+ const hasSessionCreated = events.some(
280
+ (event) => event.type === "session.created"
281
+ );
282
+ if (runs.size === 0 && progressRuns.size === 0 && !hasSessionCreated && !projections.has(sessionId) && !pending.has(sessionId)) {
237
283
  return;
238
284
  }
285
+ if (!pending.has(sessionId)) {
286
+ let projection = projections.get(sessionId);
287
+ let hasNewEvents = false;
288
+ if (!projection && hasSessionCreated) {
289
+ projection = createProjection(events);
290
+ projections.set(sessionId, projection);
291
+ hasNewEvents = projection.seenSequences.size > 0;
292
+ } else if (projection) {
293
+ hasNewEvents = appendToProjection(projection, events);
294
+ }
295
+ if (projection) {
296
+ if (projection.isTest || !hasNewEvents) return;
297
+ for (const run of runs) {
298
+ const fact = projectRunFact(manifest, sessionId, run, projection);
299
+ if (fact) client.enqueue(fact);
300
+ }
301
+ for (const run of progressRuns) {
302
+ const fact = projectRunFact(manifest, sessionId, run, projection);
303
+ if (fact) client.updateActiveRun(fact);
304
+ }
305
+ return;
306
+ }
307
+ }
239
308
  const previous = pending.get(sessionId) ?? Promise.resolve();
240
309
  const processing = previous.then(async () => {
241
310
  let projection = projections.get(sessionId);
311
+ let hasNewEvents = false;
242
312
  if (!projection) {
243
313
  projection = createProjection(await store.read(sessionId));
244
314
  projections.set(sessionId, projection);
315
+ hasNewEvents = projection.seenSequences.size > 0;
245
316
  } else {
246
- appendToProjection(projection, events);
317
+ hasNewEvents = appendToProjection(projection, events);
247
318
  }
248
- if (projection.isTest) return;
319
+ if (projection.isTest || !hasNewEvents) return;
249
320
  for (const run of runs) {
250
321
  const fact = projectRunFact(
251
322
  manifest,
@@ -255,6 +326,15 @@ function withAmarsiaTelemetry(options) {
255
326
  );
256
327
  if (fact) client.enqueue(fact);
257
328
  }
329
+ for (const run of progressRuns) {
330
+ const fact = projectRunFact(
331
+ manifest,
332
+ sessionId,
333
+ run,
334
+ projection
335
+ );
336
+ if (fact) client.updateActiveRun(fact);
337
+ }
258
338
  }).catch(() => void 0);
259
339
  pending.set(sessionId, processing);
260
340
  client.trackProjection(processing);
@@ -263,18 +343,6 @@ function withAmarsiaTelemetry(options) {
263
343
  pending.delete(sessionId);
264
344
  }
265
345
  });
266
- const hasTerminalRunEvent = events.some(
267
- (event) => event.type === "run.completed" || event.type === "run.failed" || event.type === "run.paused"
268
- );
269
- const hasEvaluationResult = events.some(
270
- (event) => event.type === "evaluation.completed" || event.type === "evaluation.failed"
271
- );
272
- if (hasTerminalRunEvent || hasEvaluationResult) {
273
- await processing;
274
- }
275
- if (hasEvaluationResult) {
276
- await client.drain({ timeoutMs: EVALUATION_FLUSH_TIMEOUT_MS });
277
- }
278
346
  }
279
347
  };
280
348
  }
@@ -288,9 +356,11 @@ function createProjection(events) {
288
356
  return projection;
289
357
  }
290
358
  function appendToProjection(projection, events) {
359
+ let added = false;
291
360
  for (const event of events) {
292
361
  if (projection.seenSequences.has(event.sequence)) continue;
293
362
  projection.seenSequences.add(event.sequence);
363
+ added = true;
294
364
  if (event.type === "session.created") {
295
365
  projection.sessionCreated = event;
296
366
  const metadata = asRecord(event.data.metadata);
@@ -304,6 +374,7 @@ function appendToProjection(projection, events) {
304
374
  projection.runs.set(event.run, [event]);
305
375
  }
306
376
  }
377
+ return added;
307
378
  }
308
379
  function relevantRuns(events) {
309
380
  const runs = /* @__PURE__ */ new Set();
@@ -314,6 +385,15 @@ function relevantRuns(events) {
314
385
  }
315
386
  return runs;
316
387
  }
388
+ function progressOnlyRuns(events, relevant) {
389
+ const runs = /* @__PURE__ */ new Set();
390
+ for (const event of events) {
391
+ if (typeof event.run === "number" && !relevant.has(event.run) && PROGRESS_EVENTS.has(event.type)) {
392
+ runs.add(event.run);
393
+ }
394
+ }
395
+ return runs;
396
+ }
317
397
  function projectRunFact(manifest, sessionId, run, projection) {
318
398
  const runEvents = projection.runs.get(run);
319
399
  if (!runEvents) return void 0;
@@ -309,18 +309,21 @@ function toProviderResponse(request, response) {
309
309
  );
310
310
  const textOutput = response.output_text ?? content.filter((block) => block.type === "text").map((block) => block.text).join("");
311
311
  const stopReason = normalizeStopReason(response, toolCalls, refused);
312
- const output = request.outputType === "json" && toolCalls.length === 0 && stopReason !== "max_tokens" ? (0, import_structured_output.parseStructuredOutput)(textOutput, request.outputSchema ?? {}) : textOutput;
313
312
  if (textOutput) {
314
313
  request.publishOutput?.(textOutput);
315
314
  }
316
- return {
317
- output,
318
- responseId: response.id,
319
- stopReason,
320
- content,
321
- toolCalls,
322
- usage: normalizeUsage(response.usage)
323
- };
315
+ return (0, import_structured_output.resolveProviderStructuredOutput)(
316
+ request,
317
+ {
318
+ output: textOutput,
319
+ responseId: response.id,
320
+ stopReason,
321
+ content,
322
+ toolCalls,
323
+ usage: normalizeUsage(response.usage)
324
+ },
325
+ textOutput
326
+ );
324
327
  }
325
328
  function replay(item) {
326
329
  const value = {
@@ -387,10 +387,20 @@ function createNodeStorageExports() {
387
387
  ].join("\n");
388
388
  }
389
389
  function allCompiledAgents(agents) {
390
- return Object.values(agents).flatMap((agent) => [
391
- agent,
392
- ...Object.values(agent.subagents ?? {})
393
- ]);
390
+ const collected = [];
391
+ const visited = /* @__PURE__ */ new Set();
392
+ const visit = (agent) => {
393
+ if (visited.has(agent)) return;
394
+ visited.add(agent);
395
+ collected.push(agent);
396
+ for (const child of Object.values(agent.subagents ?? {})) {
397
+ visit(child);
398
+ }
399
+ };
400
+ for (const agent of Object.values(agents)) {
401
+ visit(agent);
402
+ }
403
+ return collected;
394
404
  }
395
405
  function createProviderRuntimeSource(providerNames, target) {
396
406
  const providersDirectory = (0, import_path.resolve)(
@@ -35,42 +35,74 @@ function compileRegistry(registrations, registryRoot, actionRuntime = "native",
35
35
  'orcha.init() requires an "agents" object of registered folder paths.'
36
36
  );
37
37
  }
38
- const agents = {};
38
+ const normalizedRegistrations = {};
39
+ const registrationsByPath = /* @__PURE__ */ new Map();
39
40
  for (const [key, registration] of Object.entries(registrations)) {
40
41
  if (!key.trim()) {
41
42
  throw new Error("Registered agent names cannot be empty.");
42
43
  }
43
44
  const normalized = normalizeAgentRegistration(key, registration);
45
+ normalizedRegistrations[key] = normalized;
46
+ const resolvedPath = (0, import_path.resolve)(registryRoot, normalized.path);
47
+ if (!registrationsByPath.has(resolvedPath)) {
48
+ registrationsByPath.set(resolvedPath, {
49
+ key,
50
+ registration: normalized
51
+ });
52
+ }
53
+ }
54
+ if (Object.keys(normalizedRegistrations).length === 0) {
55
+ throw new Error("At least one agent must be registered.");
56
+ }
57
+ const compileRegistrationTree = (key, normalized, ownerPath, ancestry) => {
58
+ const resolvedPath = (0, import_path.resolve)(registryRoot, normalized.path);
59
+ const inherited = normalizedRegistrations[key] ?? registrationsByPath.get(resolvedPath)?.registration;
60
+ const effectiveMcp = Object.keys(normalized.mcp).length > 0 ? normalized.mcp : inherited?.mcp ?? {};
61
+ const effectiveSubagentRegistrations = Object.keys(normalized.subagents).length > 0 ? normalized.subagents : inherited?.subagents ?? {};
44
62
  const subagents = {};
45
- for (const [subagentKey, registration2] of Object.entries(
46
- normalized.subagents
63
+ for (const [subagentKey, subagentRegistration] of Object.entries(
64
+ effectiveSubagentRegistrations
47
65
  )) {
48
66
  if (!subagentKey.trim()) {
49
- throw new Error(`Agent "${key}" has an empty subagent name.`);
67
+ throw new Error(`Agent "${ownerPath}" has an empty subagent name.`);
50
68
  }
51
- const subagent = normalizeSubagentRegistration(
52
- key,
69
+ const normalizedSubagent = normalizeSubagentRegistration(
70
+ ownerPath,
53
71
  subagentKey,
54
- registration2
72
+ subagentRegistration
55
73
  );
56
- subagents[subagentKey] = compileAgent(
57
- subagentKey,
58
- subagent.path,
59
- subagent.mcp,
74
+ const childResolvedPath = (0, import_path.resolve)(
60
75
  registryRoot,
61
- actionRuntime,
62
- target
76
+ normalizedSubagent.path
77
+ );
78
+ const cycleExists = ancestry.some(
79
+ (ancestor) => ancestor.resolvedPath === childResolvedPath || ancestor.key === subagentKey
80
+ );
81
+ if (cycleExists) {
82
+ const chain = [
83
+ ...ancestry.map((item) => item.key),
84
+ subagentKey
85
+ ].join(" -> ");
86
+ throw new Error(
87
+ `Circular subagent registration detected: ${chain}.`
88
+ );
89
+ }
90
+ subagents[subagentKey] = compileRegistrationTree(
91
+ subagentKey,
92
+ normalizedSubagent,
93
+ `${ownerPath}/${subagentKey}`,
94
+ [...ancestry, { key: subagentKey, resolvedPath: childResolvedPath }]
63
95
  );
64
96
  }
65
97
  const parent = compileAgent(
66
98
  key,
67
99
  normalized.path,
68
- normalized.mcp,
100
+ effectiveMcp,
69
101
  registryRoot,
70
102
  actionRuntime,
71
103
  target
72
104
  );
73
- agents[key] = Object.freeze({
105
+ return Object.freeze({
74
106
  ...parent,
75
107
  subagentPolicy: Object.keys(subagents).length > 0 ? Object.freeze({
76
108
  ...parent.subagentPolicy,
@@ -78,9 +110,16 @@ function compileRegistry(registrations, registryRoot, actionRuntime = "native",
78
110
  }) : parent.subagentPolicy,
79
111
  subagents: Object.freeze(subagents)
80
112
  });
81
- }
82
- if (Object.keys(agents).length === 0) {
83
- throw new Error("At least one agent must be registered.");
113
+ };
114
+ const agents = {};
115
+ for (const [key, normalized] of Object.entries(normalizedRegistrations)) {
116
+ const resolvedPath = (0, import_path.resolve)(registryRoot, normalized.path);
117
+ agents[key] = compileRegistrationTree(
118
+ key,
119
+ normalized,
120
+ key,
121
+ [{ key, resolvedPath }]
122
+ );
84
123
  }
85
124
  return Object.freeze({
86
125
  schemaVersion: 1,
@@ -120,20 +159,26 @@ function normalizeSubagentRegistration(parentKey, key, registration) {
120
159
  `Subagent "${parentKey}/${key}" must register a folder path.`
121
160
  );
122
161
  }
123
- return { path: registration, mcp: {} };
162
+ return { path: registration, mcp: {}, subagents: {} };
124
163
  }
125
164
  if (!registration || typeof registration !== "object" || typeof registration.path !== "string" || !registration.path.trim()) {
126
165
  throw new Error(
127
166
  `Subagent "${parentKey}/${key}" must register a folder path.`
128
167
  );
129
168
  }
169
+ if (registration.subagents !== void 0 && (!registration.subagents || typeof registration.subagents !== "object" || Array.isArray(registration.subagents))) {
170
+ throw new Error(
171
+ `Subagent "${parentKey}/${key}" subagents must be an object of named registrations.`
172
+ );
173
+ }
130
174
  validateMcpRegistration(
131
175
  `Subagent "${parentKey}/${key}"`,
132
176
  registration.mcp
133
177
  );
134
178
  return {
135
179
  path: registration.path,
136
- mcp: registration.mcp ?? {}
180
+ mcp: registration.mcp ?? {},
181
+ subagents: registration.subagents ?? {}
137
182
  };
138
183
  }
139
184
  function validateMcpRegistration(owner, registration) {