plugin-agent-orchestrator 1.0.38 → 1.1.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.
Files changed (43) hide show
  1. package/dist/client/index.js +1 -1
  2. package/dist/client-v2/253.9f0537713cee9e6c.js +10 -0
  3. package/dist/client-v2/418.ce8f5b2b8a229d1d.js +10 -0
  4. package/dist/client-v2/53.7c29c28043e9112d.js +10 -0
  5. package/dist/client-v2/794.9bbb8d3a61b2bdf2.js +10 -0
  6. package/dist/client-v2/993.82778b6fd6db3cb1.js +10 -0
  7. package/dist/client-v2/index.js +1 -1
  8. package/dist/externalVersion.js +6 -6
  9. package/dist/locale/en-US.json +50 -2
  10. package/dist/locale/vi-VN.json +50 -2
  11. package/dist/locale/zh-CN.json +50 -2
  12. package/dist/server/migrations/20260621000000-native-policy-profile-defaults.js +0 -3
  13. package/dist/server/migrations/20260727000000-remove-unused-knowledge-scopes.js +51 -0
  14. package/dist/server/plugin.js +11 -1
  15. package/dist/server/resources/agent-knowledge-insights.js +273 -0
  16. package/dist/server/services/AgentMemoryContextService.js +57 -19
  17. package/dist/server/services/NativeSubAgentObserver.js +11 -3
  18. package/dist/server/tools/external-rag-search.js +152 -12
  19. package/package.json +1 -1
  20. package/src/client-v2/components/AgentBindingsTab.tsx +269 -0
  21. package/src/client-v2/components/HarnessProfilesTab.tsx +1 -2
  22. package/src/client-v2/components/KnowledgeAccessTab.tsx +116 -0
  23. package/src/client-v2/components/MemoryInspectorTab.tsx +125 -0
  24. package/src/client-v2/components/RetrievalTraceTab.tsx +162 -0
  25. package/src/client-v2/pages/AgentBindingsPage.tsx +13 -0
  26. package/src/client-v2/pages/KnowledgeAccessPage.tsx +10 -0
  27. package/src/client-v2/pages/MemoryInspectorPage.tsx +13 -0
  28. package/src/client-v2/pages/RetrievalTracePage.tsx +10 -0
  29. package/src/client-v2/plugin.tsx +28 -0
  30. package/src/locale/en-US.json +50 -2
  31. package/src/locale/vi-VN.json +50 -2
  32. package/src/locale/zh-CN.json +50 -2
  33. package/src/server/__tests__/agent-knowledge-insights.test.ts +123 -0
  34. package/src/server/__tests__/external-rag-search.test.ts +107 -0
  35. package/src/server/__tests__/native-sub-agent-observer.test.ts +89 -7
  36. package/src/server/migrations/20260621000000-native-policy-profile-defaults.ts +0 -3
  37. package/src/server/migrations/20260727000000-remove-unused-knowledge-scopes.ts +25 -0
  38. package/src/server/plugin.ts +3 -0
  39. package/src/server/resources/agent-knowledge-insights.ts +304 -0
  40. package/src/server/services/AgentMemoryContextService.ts +63 -19
  41. package/src/server/services/NativeSubAgentObserver.ts +538 -528
  42. package/src/server/tools/external-rag-search.ts +215 -14
  43. package/dist/client-v2/418.29e713f79131eece.js +0 -10
@@ -1,528 +1,538 @@
1
- import { createHash } from 'crypto';
2
- import { ExecutionSpanService } from './ExecutionSpanService';
3
- import { AgentMemoryContextService } from './AgentMemoryContextService';
4
- import { TokenTracker } from './TokenTracker';
5
- import { asObject, currentUserId, toPlain, trimText } from '../utils/ctx-utils';
6
-
7
- const WRAP_STATE_KEY = Symbol.for('plugin-agent-orchestrator.nativeSubAgentObserver');
8
- const NATIVE_SOURCE = 'native-plugin-ai';
9
-
10
- type NativeWriter = (chunk: Record<string, unknown>) => unknown;
11
-
12
- type NativeSubAgentTask = {
13
- ctx: {
14
- action?: { params?: { values?: Record<string, unknown> } };
15
- auth?: { user?: { id?: string | number } };
16
- db?: { getRepository?: (name: string) => unknown };
17
- app?: unknown;
18
- };
19
- sessionId: string;
20
- employee: unknown;
21
- model?: unknown;
22
- question: string;
23
- skillSettings?: Record<string, unknown>;
24
- writer?: NativeWriter;
25
- };
26
-
27
- type DispatchToolMessage = {
28
- id?: string | number;
29
- messageId?: string | number;
30
- toolCallId?: string;
31
- sessionId?: string;
32
- status?: string;
33
- invokeStatus?: string;
34
- };
35
-
36
- type SpanRecord = {
37
- id?: string | number;
38
- rootRunId?: string;
39
- metadata?: Record<string, unknown>;
40
- };
41
-
42
- type ToolSpanState = {
43
- spanId?: string | number;
44
- startedAt: number;
45
- ready: Promise<void>;
46
- };
47
-
48
- type RunState = {
49
- rootRunId: string;
50
- rootSpanId?: string | number;
51
- rootStartedAt: number;
52
- rootMetadata: Record<string, unknown>;
53
- parentSessionId?: string;
54
- subSessionId?: string;
55
- toolCallId?: string;
56
- leaderUsername?: string;
57
- employeeUsername?: string;
58
- userId?: string | number;
59
- toolSpans: Map<string, ToolSpanState>;
60
- pending: Set<Promise<void>>;
61
- };
62
-
63
- type DispatcherWithRun = {
64
- run: (task: NativeSubAgentTask) => Promise<string>;
65
- [WRAP_STATE_KEY]?: {
66
- originalRun: (task: NativeSubAgentTask) => Promise<string>;
67
- wrappedRun: (task: NativeSubAgentTask) => Promise<string>;
68
- };
69
- };
70
-
71
- function readValue(record: unknown, key: string) {
72
- const model = record as { get?: (name: string) => unknown; [key: string]: unknown };
73
- return typeof model?.get === 'function' ? model.get(key) : model?.[key];
74
- }
75
-
76
- function normalizeString(value: unknown) {
77
- return typeof value === 'string' ? value.trim() : '';
78
- }
79
-
80
- function modelUsername(model: unknown) {
81
- return (
82
- normalizeString(readValue(model, 'username')) ||
83
- normalizeString(readValue(model, 'aiEmployeeUsername')) ||
84
- normalizeString(readValue(model, 'name')) ||
85
- undefined
86
- );
87
- }
88
-
89
- function makeNativeRunId(parts: Array<string | number | undefined>) {
90
- const source = parts.map((part) => String(part || '')).join('|');
91
- return `native_${createHash('sha1')
92
- .update(source || String(Date.now()))
93
- .digest('hex')
94
- .slice(0, 24)}`;
95
- }
96
-
97
- function errorMessage(error: unknown) {
98
- return error instanceof Error ? error.message : String(error || 'Unknown error');
99
- }
100
-
101
- function chunkBody(chunk: Record<string, unknown>) {
102
- return asObject(chunk.body);
103
- }
104
-
105
- function chunkCurrentConversation(chunk: Record<string, unknown>) {
106
- return asObject(chunk.currentConversation);
107
- }
108
-
109
- export class NativeSubAgentObserver {
110
- private readonly spanService: ExecutionSpanService;
111
- private readonly memoryService: AgentMemoryContextService;
112
- private readonly tokenTracker: TokenTracker;
113
-
114
- constructor(private readonly plugin: { app: any; db: any; name?: string }) {
115
- this.spanService = new ExecutionSpanService(plugin);
116
- this.memoryService = new AgentMemoryContextService(plugin);
117
- this.tokenTracker = new TokenTracker(plugin);
118
- }
119
-
120
- install() {
121
- const aiPlugin = this.plugin.app.pm?.get?.('ai');
122
- const dispatcher = aiPlugin?.subAgentsDispatcher as DispatcherWithRun | undefined;
123
- if (!dispatcher?.run) {
124
- this.plugin.app.logger?.warn?.(
125
- '[AgentOrchestrator] plugin-ai subAgentsDispatcher not available; observer skipped.',
126
- );
127
- return false;
128
- }
129
-
130
- const existing = dispatcher[WRAP_STATE_KEY];
131
- if (existing?.wrappedRun === dispatcher.run) {
132
- return false;
133
- }
134
-
135
- const originalRun = existing?.originalRun || dispatcher.run.bind(dispatcher);
136
- const observer = this;
137
- const wrappedRun = async function wrappedNativeSubAgentRun(task: NativeSubAgentTask) {
138
- return observer.runObserved(originalRun, task);
139
- };
140
-
141
- dispatcher.run = wrappedRun;
142
- dispatcher[WRAP_STATE_KEY] = {
143
- originalRun,
144
- wrappedRun,
145
- };
146
-
147
- this.plugin.app.logger?.info?.('[AgentOrchestrator] Native plugin-ai sub-agent observer installed.');
148
- return true;
149
- }
150
-
151
- uninstall() {
152
- const aiPlugin = this.plugin.app.pm?.get?.('ai');
153
- const dispatcher = aiPlugin?.subAgentsDispatcher as DispatcherWithRun | undefined;
154
- const existing = dispatcher?.[WRAP_STATE_KEY];
155
- if (!dispatcher?.run || !existing || existing.wrappedRun !== dispatcher.run) {
156
- return false;
157
- }
158
-
159
- dispatcher.run = existing.originalRun;
160
- delete dispatcher[WRAP_STATE_KEY];
161
- this.plugin.app.logger?.info?.('[AgentOrchestrator] Native plugin-ai sub-agent observer uninstalled.');
162
- return true;
163
- }
164
-
165
- private async runObserved(originalRun: (task: NativeSubAgentTask) => Promise<string>, task: NativeSubAgentTask) {
166
- const settings = await this.safeResolvePolicy(task);
167
- if (settings.nativeObserverEnabled === false) {
168
- return originalRun(task);
169
- }
170
-
171
- const parentSessionId = this.resolveParentSessionId(task) || undefined;
172
- const subSessionId = normalizeString(task.sessionId) || undefined;
173
- const employeeUsername = modelUsername(task.employee);
174
- const userId = currentUserId(task.ctx) || task.ctx?.auth?.user?.id;
175
- const dispatchToolMessage = await this.resolveDispatchToolMessage(task.ctx, parentSessionId, subSessionId);
176
- const toolCallId = dispatchToolMessage?.toolCallId;
177
- const leaderUsername = await this.resolveLeaderUsername(task.ctx, parentSessionId);
178
- const rootRunId = makeNativeRunId([parentSessionId, subSessionId, toolCallId, employeeUsername]);
179
- const memory = await this.safeBuildMemoryContext({
180
- userId,
181
- aiEmployeeUsername: employeeUsername,
182
- settings,
183
- });
184
- const observedTask = memory.context
185
- ? {
186
- ...task,
187
- question: `${task.question}\n\n${memory.context}`,
188
- }
189
- : task;
190
-
191
- const state: RunState = {
192
- rootRunId,
193
- rootStartedAt: Date.now(),
194
- rootMetadata: {
195
- source: NATIVE_SOURCE,
196
- parentSessionId,
197
- subSessionId,
198
- toolCallId,
199
- dispatchToolMessageId: dispatchToolMessage?.id,
200
- dispatchMessageId: dispatchToolMessage?.messageId,
201
- memoryContextApplied: Boolean(memory.context),
202
- memoryScopes: memory.appliedScopes,
203
- memoryContextChars: memory.chars,
204
- harnessTag: settings.harnessTag || 'default',
205
- },
206
- parentSessionId,
207
- subSessionId,
208
- toolCallId,
209
- leaderUsername,
210
- employeeUsername,
211
- userId,
212
- toolSpans: new Map(),
213
- pending: new Set(),
214
- };
215
-
216
- await this.safeCreateRootSpan(state, task.question);
217
-
218
- const originalWriter = task.writer;
219
- observedTask.writer = (chunk: Record<string, unknown>) => {
220
- const pending = this.handleWriterChunk(state, chunk).catch((error) => {
221
- this.plugin.app.logger?.warn?.('[AgentOrchestrator] Native writer observer failed', error);
222
- });
223
- state.pending.add(pending);
224
- return originalWriter?.(chunk);
225
- };
226
-
227
- try {
228
- const result = await originalRun(observedTask);
229
- await this.flushPending(state);
230
- await this.spanService.finish(state.rootSpanId, 'success', state.rootStartedAt, {
231
- output: trimText(result, 20000),
232
- metadata: {
233
- ...state.rootMetadata,
234
- completedAt: new Date().toISOString(),
235
- },
236
- });
237
- await this.tokenTracker.estimateAndTrack(
238
- state.rootSpanId,
239
- task.question,
240
- result,
241
- state.rootMetadata.agentLoopRunId ? Number(state.rootMetadata.agentLoopRunId) : undefined,
242
- );
243
- return result;
244
- } catch (error) {
245
- await this.flushPending(state);
246
- await this.spanService.finish(state.rootSpanId, 'error', state.rootStartedAt, {
247
- error: trimText(errorMessage(error), 10000),
248
- metadata: {
249
- ...state.rootMetadata,
250
- failedAt: new Date().toISOString(),
251
- },
252
- });
253
- await this.tokenTracker.estimateAndTrack(
254
- state.rootSpanId,
255
- task.question,
256
- errorMessage(error),
257
- state.rootMetadata.agentLoopRunId ? Number(state.rootMetadata.agentLoopRunId) : undefined,
258
- );
259
- throw error;
260
- }
261
- }
262
-
263
- private async safeResolvePolicy(task: NativeSubAgentTask) {
264
- try {
265
- return await this.memoryService.resolvePolicySettings(task);
266
- } catch (error) {
267
- this.plugin.app.logger?.warn?.('[AgentOrchestrator] Failed to resolve native observer policy', error);
268
- return { harnessTag: 'default' };
269
- }
270
- }
271
-
272
- private async safeBuildMemoryContext(options: {
273
- userId?: string | number;
274
- aiEmployeeUsername?: string;
275
- settings: Record<string, unknown>;
276
- }) {
277
- try {
278
- return await this.memoryService.buildContext(options);
279
- } catch (error) {
280
- this.plugin.app.logger?.warn?.('[AgentOrchestrator] Failed to build agent memory context', error);
281
- return { context: '', appliedScopes: [] as string[], chars: 0 };
282
- }
283
- }
284
-
285
- private async safeCreateRootSpan(state: RunState, question: string) {
286
- const span = (await this.spanService.create({
287
- rootRunId: state.rootRunId,
288
- parentSpanId: undefined,
289
- source: NATIVE_SOURCE,
290
- parentSessionId: state.parentSessionId,
291
- subSessionId: state.subSessionId,
292
- toolCallId: state.toolCallId,
293
- type: 'sub_agent',
294
- status: 'running',
295
- leaderUsername: state.leaderUsername,
296
- employeeUsername: state.employeeUsername,
297
- toolName: 'dispatch-sub-agent-task',
298
- title: `${state.leaderUsername || 'main'} -> ${state.employeeUsername || 'sub-agent'}`,
299
- input: {
300
- question,
301
- parentSessionId: state.parentSessionId,
302
- subSessionId: state.subSessionId,
303
- },
304
- metadata: state.rootMetadata,
305
- userId: state.userId,
306
- })) as SpanRecord | null;
307
-
308
- state.rootSpanId = span?.id;
309
- }
310
-
311
- private async handleWriterChunk(state: RunState, chunk: Record<string, unknown>) {
312
- const action = chunk.action;
313
- if (action === 'beforeToolCall') {
314
- await this.handleBeforeToolCall(state, chunk);
315
- return;
316
- }
317
- if (action === 'afterToolCall') {
318
- await this.handleAfterToolCall(state, chunk, false);
319
- return;
320
- }
321
- if (action === 'afterToolCallError') {
322
- await this.handleAfterToolCall(state, chunk, true);
323
- return;
324
- }
325
- if (action === 'afterSubAgentInvoke') {
326
- state.rootMetadata = {
327
- ...state.rootMetadata,
328
- afterSubAgentInvokeAt: new Date().toISOString(),
329
- };
330
- await this.spanService.update(state.rootSpanId, { metadata: state.rootMetadata });
331
- }
332
- }
333
-
334
- private async handleBeforeToolCall(state: RunState, chunk: Record<string, unknown>) {
335
- const body = chunkBody(chunk);
336
- const toolCall = asObject(body.toolCall);
337
- const toolCallId = normalizeString(toolCall.id);
338
- if (!toolCallId || state.toolSpans.has(toolCallId)) return;
339
-
340
- const conversation = chunkCurrentConversation(chunk);
341
- const startedAt = Date.now();
342
- const toolSpan: ToolSpanState = {
343
- startedAt,
344
- ready: Promise.resolve(),
345
- };
346
- state.toolSpans.set(toolCallId, toolSpan);
347
-
348
- toolSpan.ready = this.spanService
349
- .create({
350
- rootRunId: state.rootRunId,
351
- parentSpanId: state.rootSpanId ? String(state.rootSpanId) : undefined,
352
- source: NATIVE_SOURCE,
353
- parentSessionId: state.parentSessionId || undefined,
354
- subSessionId: normalizeString(conversation.sessionId) || state.subSessionId || undefined,
355
- toolCallId,
356
- type: normalizeString(toolCall.name) === 'dispatch-sub-agent-task' ? 'dispatch' : 'tool',
357
- status: 'running',
358
- leaderUsername: state.leaderUsername,
359
- employeeUsername: normalizeString(conversation.username) || state.employeeUsername,
360
- toolName: normalizeString(toolCall.name),
361
- title: normalizeString(toolCall.name) || 'tool call',
362
- input: asObject(toolCall.args),
363
- metadata: {
364
- source: NATIVE_SOURCE,
365
- currentConversation: conversation,
366
- messageId: toolCall.messageId,
367
- },
368
- userId: state.userId,
369
- })
370
- .then((span) => {
371
- toolSpan.spanId = (span as SpanRecord | null)?.id;
372
- });
373
-
374
- await toolSpan.ready;
375
- }
376
-
377
- private async handleAfterToolCall(state: RunState, chunk: Record<string, unknown>, forceError: boolean) {
378
- const body = chunkBody(chunk);
379
- const toolCall = asObject(body.toolCall);
380
- const toolCallId = normalizeString(toolCall.id);
381
- const existing = toolCallId ? state.toolSpans.get(toolCallId) : undefined;
382
- if (!existing) return;
383
- await existing.ready;
384
-
385
- const result = asObject(toPlain(body.toolCallResult));
386
- const error = body.error;
387
- const status = forceError || result.status === 'error' ? 'error' : 'success';
388
- const output = result.content ?? result.result ?? result;
389
- const invokeStart = Number(result.invokeStartTime);
390
- const invokeEnd = Number(result.invokeEndTime);
391
- const durationMs =
392
- Number.isFinite(invokeStart) && Number.isFinite(invokeEnd) && invokeEnd >= invokeStart
393
- ? invokeEnd - invokeStart
394
- : Date.now() - existing.startedAt;
395
-
396
- await this.spanService.update(existing.spanId, {
397
- status,
398
- endedAt: new Date(),
399
- durationMs,
400
- output: forceError ? undefined : trimText(output, 20000),
401
- error: forceError ? trimText(errorMessage(error), 10000) : undefined,
402
- metadata: {
403
- source: NATIVE_SOURCE,
404
- toolCallResultStatus: result.status,
405
- invokeStatus: result.invokeStatus,
406
- messageId: toolCall.messageId,
407
- },
408
- });
409
-
410
- await this.tokenTracker.estimateAndTrack(
411
- existing.spanId,
412
- normalizeString(toolCall.name),
413
- typeof output === 'string' ? output : JSON.stringify(output),
414
- );
415
- }
416
-
417
- private resolveParentSessionId(task: NativeSubAgentTask) {
418
- const values = task.ctx?.action?.params?.values || {};
419
- return normalizeString(values.sessionId) || undefined;
420
- }
421
-
422
- private async resolveLeaderUsername(ctx: NativeSubAgentTask['ctx'], parentSessionId?: string) {
423
- const values = ctx?.action?.params?.values || {};
424
- const direct =
425
- normalizeString(values.aiEmployeeUsername) ||
426
- normalizeString((asObject(values.aiEmployee) as Record<string, unknown>).username);
427
- if (direct) return direct;
428
- if (!parentSessionId) return undefined;
429
-
430
- try {
431
- const repo = ctx.db?.getRepository?.('aiConversations') as
432
- | { findOne?: (options: Record<string, unknown>) => Promise<unknown> }
433
- | undefined;
434
- const conversation = await repo?.findOne?.({
435
- filter: { sessionId: parentSessionId },
436
- });
437
- return normalizeString(readValue(conversation, 'aiEmployeeUsername')) || undefined;
438
- } catch {
439
- return undefined;
440
- }
441
- }
442
-
443
- private async resolveDispatchToolMessage(
444
- ctx: NativeSubAgentTask['ctx'],
445
- parentSessionId?: string,
446
- subSessionId?: string,
447
- ) {
448
- if (!parentSessionId) return null;
449
- try {
450
- const fromMetadata = await this.resolveDispatchToolMessageFromMetadata(ctx, parentSessionId, subSessionId);
451
- if (fromMetadata) {
452
- return fromMetadata;
453
- }
454
-
455
- const repo = ctx.db?.getRepository?.('aiToolMessages') as
456
- | { findOne?: (options: Record<string, unknown>) => Promise<unknown> }
457
- | undefined;
458
- const record = await repo?.findOne?.({
459
- filter: {
460
- sessionId: parentSessionId,
461
- toolName: 'dispatch-sub-agent-task',
462
- invokeStatus: {
463
- $ne: 'confirmed',
464
- },
465
- },
466
- sort: ['-id'],
467
- });
468
- return toPlain(record) as DispatchToolMessage | null;
469
- } catch {
470
- return null;
471
- }
472
- }
473
-
474
- private async resolveDispatchToolMessageFromMetadata(
475
- ctx: NativeSubAgentTask['ctx'],
476
- parentSessionId?: string,
477
- subSessionId?: string,
478
- ) {
479
- if (!parentSessionId || !subSessionId) return null;
480
-
481
- const messageRepo = ctx.db?.getRepository?.('aiMessages') as
482
- | { find?: (options: Record<string, unknown>) => Promise<unknown[]> }
483
- | undefined;
484
- const toolRepo = ctx.db?.getRepository?.('aiToolMessages') as
485
- | { findOne?: (options: Record<string, unknown>) => Promise<unknown> }
486
- | undefined;
487
- const messages = await messageRepo?.find?.({
488
- filter: { sessionId: parentSessionId },
489
- sort: ['-messageId'],
490
- limit: 20,
491
- });
492
- if (!Array.isArray(messages)) return null;
493
-
494
- for (const rawMessage of messages) {
495
- const message = toPlain(rawMessage);
496
- const conversations = asObject(message?.metadata).subAgentConversations;
497
- if (!Array.isArray(conversations)) continue;
498
-
499
- const matched = conversations.find((item) => normalizeString(item?.sessionId) === subSessionId);
500
- const toolCallId = normalizeString(matched?.toolCallId);
501
- if (!toolCallId) continue;
502
-
503
- const toolMessage = await toolRepo?.findOne?.({
504
- filter: {
505
- sessionId: parentSessionId,
506
- toolCallId,
507
- },
508
- });
509
- return {
510
- ...(toPlain(toolMessage) || {}),
511
- toolCallId,
512
- messageId: readValue(toolMessage, 'messageId') || message?.messageId,
513
- sessionId: parentSessionId,
514
- status: matched?.status,
515
- } as DispatchToolMessage;
516
- }
517
-
518
- return null;
519
- }
520
-
521
- private async flushPending(state: RunState) {
522
- const pending = Array.from(state.pending);
523
- if (!pending.length) return;
524
- await Promise.allSettled(pending);
525
- }
526
- }
527
-
528
- export { NATIVE_SOURCE, makeNativeRunId };
1
+ import { createHash } from 'crypto';
2
+ import { ExecutionSpanService } from './ExecutionSpanService';
3
+ import { AgentMemoryContextService } from './AgentMemoryContextService';
4
+ import { TokenTracker } from './TokenTracker';
5
+ import { asObject, currentUserId, toPlain, trimText } from '../utils/ctx-utils';
6
+
7
+ const WRAP_STATE_KEY = Symbol.for('plugin-agent-orchestrator.nativeSubAgentObserver');
8
+ const NATIVE_SOURCE = 'native-plugin-ai';
9
+
10
+ type NativeWriter = (chunk: Record<string, unknown>) => unknown;
11
+
12
+ type NativeSubAgentTask = {
13
+ ctx: {
14
+ action?: { params?: { values?: Record<string, unknown> } };
15
+ auth?: { user?: { id?: string | number } };
16
+ db?: { getRepository?: (name: string) => unknown };
17
+ app?: unknown;
18
+ };
19
+ sessionId: string;
20
+ employee: unknown;
21
+ model?: unknown;
22
+ question: string;
23
+ skillSettings?: Record<string, unknown>;
24
+ writer?: NativeWriter;
25
+ };
26
+
27
+ type DispatchToolMessage = {
28
+ id?: string | number;
29
+ messageId?: string | number;
30
+ toolCallId?: string;
31
+ sessionId?: string;
32
+ status?: string;
33
+ invokeStatus?: string;
34
+ };
35
+
36
+ type SpanRecord = {
37
+ id?: string | number;
38
+ rootRunId?: string;
39
+ metadata?: Record<string, unknown>;
40
+ };
41
+
42
+ type ToolSpanState = {
43
+ spanId?: string | number;
44
+ startedAt: number;
45
+ ready: Promise<void>;
46
+ };
47
+
48
+ type RunState = {
49
+ rootRunId: string;
50
+ rootSpanId?: string | number;
51
+ rootStartedAt: number;
52
+ rootMetadata: Record<string, unknown>;
53
+ parentSessionId?: string;
54
+ subSessionId?: string;
55
+ toolCallId?: string;
56
+ leaderUsername?: string;
57
+ employeeUsername?: string;
58
+ userId?: string | number;
59
+ toolSpans: Map<string, ToolSpanState>;
60
+ pending: Set<Promise<void>>;
61
+ };
62
+
63
+ type DispatcherWithRun = {
64
+ run: (task: NativeSubAgentTask) => Promise<string>;
65
+ [WRAP_STATE_KEY]?: {
66
+ originalRun: (task: NativeSubAgentTask) => Promise<string>;
67
+ wrappedRun: (task: NativeSubAgentTask) => Promise<string>;
68
+ };
69
+ };
70
+
71
+ function readValue(record: unknown, key: string) {
72
+ const model = record as { get?: (name: string) => unknown; [key: string]: unknown };
73
+ return typeof model?.get === 'function' ? model.get(key) : model?.[key];
74
+ }
75
+
76
+ function normalizeString(value: unknown) {
77
+ return typeof value === 'string' ? value.trim() : '';
78
+ }
79
+
80
+ function modelUsername(model: unknown) {
81
+ return (
82
+ normalizeString(readValue(model, 'username')) ||
83
+ normalizeString(readValue(model, 'aiEmployeeUsername')) ||
84
+ normalizeString(readValue(model, 'name')) ||
85
+ undefined
86
+ );
87
+ }
88
+
89
+ function makeNativeRunId(parts: Array<string | number | undefined>) {
90
+ const source = parts.map((part) => String(part || '')).join('|');
91
+ return `native_${createHash('sha1')
92
+ .update(source || String(Date.now()))
93
+ .digest('hex')
94
+ .slice(0, 24)}`;
95
+ }
96
+
97
+ function errorMessage(error: unknown) {
98
+ return error instanceof Error ? error.message : String(error || 'Unknown error');
99
+ }
100
+
101
+ function chunkBody(chunk: Record<string, unknown>) {
102
+ return asObject(chunk.body);
103
+ }
104
+
105
+ function chunkCurrentConversation(chunk: Record<string, unknown>) {
106
+ return asObject(chunk.currentConversation);
107
+ }
108
+
109
+ export class NativeSubAgentObserver {
110
+ private readonly spanService: ExecutionSpanService;
111
+ private readonly memoryService: AgentMemoryContextService;
112
+ private readonly tokenTracker: TokenTracker;
113
+
114
+ constructor(private readonly plugin: { app: any; db: any; name?: string }) {
115
+ this.spanService = new ExecutionSpanService(plugin);
116
+ this.memoryService = new AgentMemoryContextService(plugin);
117
+ this.tokenTracker = new TokenTracker(plugin);
118
+ }
119
+
120
+ install() {
121
+ const aiPlugin = this.plugin.app.pm?.get?.('ai');
122
+ const dispatcher = aiPlugin?.subAgentsDispatcher as DispatcherWithRun | undefined;
123
+ if (!dispatcher?.run) {
124
+ this.plugin.app.logger?.warn?.(
125
+ '[AgentOrchestrator] plugin-ai subAgentsDispatcher not available; observer skipped.',
126
+ );
127
+ return false;
128
+ }
129
+
130
+ const existing = dispatcher[WRAP_STATE_KEY];
131
+ if (existing?.wrappedRun === dispatcher.run) {
132
+ return false;
133
+ }
134
+
135
+ const originalRun = existing?.originalRun || dispatcher.run.bind(dispatcher);
136
+ const observer = this;
137
+ const wrappedRun = async function wrappedNativeSubAgentRun(task: NativeSubAgentTask) {
138
+ return observer.runObserved(originalRun, task);
139
+ };
140
+
141
+ dispatcher.run = wrappedRun;
142
+ dispatcher[WRAP_STATE_KEY] = {
143
+ originalRun,
144
+ wrappedRun,
145
+ };
146
+
147
+ this.plugin.app.logger?.info?.('[AgentOrchestrator] Native plugin-ai sub-agent observer installed.');
148
+ return true;
149
+ }
150
+
151
+ uninstall() {
152
+ const aiPlugin = this.plugin.app.pm?.get?.('ai');
153
+ const dispatcher = aiPlugin?.subAgentsDispatcher as DispatcherWithRun | undefined;
154
+ const existing = dispatcher?.[WRAP_STATE_KEY];
155
+ if (!dispatcher?.run || !existing || existing.wrappedRun !== dispatcher.run) {
156
+ return false;
157
+ }
158
+
159
+ dispatcher.run = existing.originalRun;
160
+ delete dispatcher[WRAP_STATE_KEY];
161
+ this.plugin.app.logger?.info?.('[AgentOrchestrator] Native plugin-ai sub-agent observer uninstalled.');
162
+ return true;
163
+ }
164
+
165
+ private async runObserved(originalRun: (task: NativeSubAgentTask) => Promise<string>, task: NativeSubAgentTask) {
166
+ const settings = await this.safeResolvePolicy(task);
167
+ if (settings.nativeObserverEnabled === false) {
168
+ return originalRun(task);
169
+ }
170
+
171
+ const parentSessionId = this.resolveParentSessionId(task) || undefined;
172
+ const subSessionId = normalizeString(task.sessionId) || undefined;
173
+ const employeeUsername = modelUsername(task.employee);
174
+ const userId = currentUserId(task.ctx) || task.ctx?.auth?.user?.id;
175
+ const dispatchToolMessage = await this.resolveDispatchToolMessage(task.ctx, parentSessionId, subSessionId);
176
+ const toolCallId = dispatchToolMessage?.toolCallId;
177
+ const leaderUsername = await this.resolveLeaderUsername(task.ctx, parentSessionId);
178
+ const rootRunId = makeNativeRunId([parentSessionId, subSessionId, toolCallId, employeeUsername]);
179
+ const memory = await this.safeBuildMemoryContext({
180
+ userId,
181
+ aiEmployeeUsername: employeeUsername,
182
+ settings,
183
+ });
184
+ const observedTask = memory.context
185
+ ? {
186
+ ...task,
187
+ question: `${memory.context}\n\n<agent_task>\n${task.question}\n</agent_task>`,
188
+ }
189
+ : task;
190
+
191
+ const state: RunState = {
192
+ rootRunId,
193
+ rootStartedAt: Date.now(),
194
+ rootMetadata: {
195
+ source: NATIVE_SOURCE,
196
+ parentSessionId,
197
+ subSessionId,
198
+ toolCallId,
199
+ dispatchToolMessageId: dispatchToolMessage?.id,
200
+ dispatchMessageId: dispatchToolMessage?.messageId,
201
+ memoryContextApplied: Boolean(memory.context),
202
+ memoryScopes: memory.appliedScopes,
203
+ memoryContextChars: memory.chars,
204
+ harnessTag: settings.harnessTag || 'default',
205
+ },
206
+ parentSessionId,
207
+ subSessionId,
208
+ toolCallId,
209
+ leaderUsername,
210
+ employeeUsername,
211
+ userId,
212
+ toolSpans: new Map(),
213
+ pending: new Set(),
214
+ };
215
+
216
+ await this.safeCreateRootSpan(state, task.question);
217
+
218
+ const originalWriter = task.writer;
219
+ observedTask.writer = (chunk: Record<string, unknown>) => {
220
+ const pending = this.handleWriterChunk(state, chunk).catch((error) => {
221
+ this.plugin.app.logger?.warn?.('[AgentOrchestrator] Native writer observer failed', error);
222
+ });
223
+ state.pending.add(pending);
224
+ return originalWriter?.(chunk);
225
+ };
226
+
227
+ try {
228
+ const result = await this.runWithKnowledgeBaseAgentContext(employeeUsername, () => originalRun(observedTask));
229
+ await this.flushPending(state);
230
+ await this.spanService.finish(state.rootSpanId, 'success', state.rootStartedAt, {
231
+ output: trimText(result, 20000),
232
+ metadata: {
233
+ ...state.rootMetadata,
234
+ completedAt: new Date().toISOString(),
235
+ },
236
+ });
237
+ await this.tokenTracker.estimateAndTrack(
238
+ state.rootSpanId,
239
+ task.question,
240
+ result,
241
+ state.rootMetadata.agentLoopRunId ? Number(state.rootMetadata.agentLoopRunId) : undefined,
242
+ );
243
+ return result;
244
+ } catch (error) {
245
+ await this.flushPending(state);
246
+ await this.spanService.finish(state.rootSpanId, 'error', state.rootStartedAt, {
247
+ error: trimText(errorMessage(error), 10000),
248
+ metadata: {
249
+ ...state.rootMetadata,
250
+ failedAt: new Date().toISOString(),
251
+ },
252
+ });
253
+ await this.tokenTracker.estimateAndTrack(
254
+ state.rootSpanId,
255
+ task.question,
256
+ errorMessage(error),
257
+ state.rootMetadata.agentLoopRunId ? Number(state.rootMetadata.agentLoopRunId) : undefined,
258
+ );
259
+ throw error;
260
+ }
261
+ }
262
+
263
+ private async safeResolvePolicy(task: NativeSubAgentTask) {
264
+ try {
265
+ return await this.memoryService.resolvePolicySettings(task);
266
+ } catch (error) {
267
+ this.plugin.app.logger?.warn?.('[AgentOrchestrator] Failed to resolve native observer policy', error);
268
+ return { harnessTag: 'default' };
269
+ }
270
+ }
271
+
272
+ private async safeBuildMemoryContext(options: {
273
+ userId?: string | number;
274
+ aiEmployeeUsername?: string;
275
+ settings: Record<string, unknown>;
276
+ }) {
277
+ try {
278
+ return await this.memoryService.buildContext(options);
279
+ } catch (error) {
280
+ this.plugin.app.logger?.warn?.('[AgentOrchestrator] Failed to build agent memory context', error);
281
+ return { context: '', appliedScopes: [] as string[], chars: 0 };
282
+ }
283
+ }
284
+
285
+ private async safeCreateRootSpan(state: RunState, question: string) {
286
+ const span = (await this.spanService.create({
287
+ rootRunId: state.rootRunId,
288
+ parentSpanId: undefined,
289
+ source: NATIVE_SOURCE,
290
+ parentSessionId: state.parentSessionId,
291
+ subSessionId: state.subSessionId,
292
+ toolCallId: state.toolCallId,
293
+ type: 'sub_agent',
294
+ status: 'running',
295
+ leaderUsername: state.leaderUsername,
296
+ employeeUsername: state.employeeUsername,
297
+ toolName: 'dispatch-sub-agent-task',
298
+ title: `${state.leaderUsername || 'main'} -> ${state.employeeUsername || 'sub-agent'}`,
299
+ input: {
300
+ question,
301
+ parentSessionId: state.parentSessionId,
302
+ subSessionId: state.subSessionId,
303
+ },
304
+ metadata: state.rootMetadata,
305
+ userId: state.userId,
306
+ })) as SpanRecord | null;
307
+
308
+ state.rootSpanId = span?.id;
309
+ }
310
+
311
+ private runWithKnowledgeBaseAgentContext<T>(employeeUsername: string | undefined, fn: () => Promise<T>) {
312
+ if (!employeeUsername) return fn();
313
+ const knowledgeBasePlugin = this.plugin.app.pm?.get?.('plugin-knowledge-base') as
314
+ | { runWithAgentContext?: <TResult>(username: string, callback: () => Promise<TResult>) => Promise<TResult> }
315
+ | undefined;
316
+ return knowledgeBasePlugin?.runWithAgentContext
317
+ ? knowledgeBasePlugin.runWithAgentContext(employeeUsername, fn)
318
+ : fn();
319
+ }
320
+
321
+ private async handleWriterChunk(state: RunState, chunk: Record<string, unknown>) {
322
+ const action = chunk.action;
323
+ if (action === 'beforeToolCall') {
324
+ await this.handleBeforeToolCall(state, chunk);
325
+ return;
326
+ }
327
+ if (action === 'afterToolCall') {
328
+ await this.handleAfterToolCall(state, chunk, false);
329
+ return;
330
+ }
331
+ if (action === 'afterToolCallError') {
332
+ await this.handleAfterToolCall(state, chunk, true);
333
+ return;
334
+ }
335
+ if (action === 'afterSubAgentInvoke') {
336
+ state.rootMetadata = {
337
+ ...state.rootMetadata,
338
+ afterSubAgentInvokeAt: new Date().toISOString(),
339
+ };
340
+ await this.spanService.update(state.rootSpanId, { metadata: state.rootMetadata });
341
+ }
342
+ }
343
+
344
+ private async handleBeforeToolCall(state: RunState, chunk: Record<string, unknown>) {
345
+ const body = chunkBody(chunk);
346
+ const toolCall = asObject(body.toolCall);
347
+ const toolCallId = normalizeString(toolCall.id);
348
+ if (!toolCallId || state.toolSpans.has(toolCallId)) return;
349
+
350
+ const conversation = chunkCurrentConversation(chunk);
351
+ const startedAt = Date.now();
352
+ const toolSpan: ToolSpanState = {
353
+ startedAt,
354
+ ready: Promise.resolve(),
355
+ };
356
+ state.toolSpans.set(toolCallId, toolSpan);
357
+
358
+ toolSpan.ready = this.spanService
359
+ .create({
360
+ rootRunId: state.rootRunId,
361
+ parentSpanId: state.rootSpanId ? String(state.rootSpanId) : undefined,
362
+ source: NATIVE_SOURCE,
363
+ parentSessionId: state.parentSessionId || undefined,
364
+ subSessionId: normalizeString(conversation.sessionId) || state.subSessionId || undefined,
365
+ toolCallId,
366
+ type: normalizeString(toolCall.name) === 'dispatch-sub-agent-task' ? 'dispatch' : 'tool',
367
+ status: 'running',
368
+ leaderUsername: state.leaderUsername,
369
+ employeeUsername: normalizeString(conversation.username) || state.employeeUsername,
370
+ toolName: normalizeString(toolCall.name),
371
+ title: normalizeString(toolCall.name) || 'tool call',
372
+ input: asObject(toolCall.args),
373
+ metadata: {
374
+ source: NATIVE_SOURCE,
375
+ currentConversation: conversation,
376
+ messageId: toolCall.messageId,
377
+ },
378
+ userId: state.userId,
379
+ })
380
+ .then((span) => {
381
+ toolSpan.spanId = (span as SpanRecord | null)?.id;
382
+ });
383
+
384
+ await toolSpan.ready;
385
+ }
386
+
387
+ private async handleAfterToolCall(state: RunState, chunk: Record<string, unknown>, forceError: boolean) {
388
+ const body = chunkBody(chunk);
389
+ const toolCall = asObject(body.toolCall);
390
+ const toolCallId = normalizeString(toolCall.id);
391
+ const existing = toolCallId ? state.toolSpans.get(toolCallId) : undefined;
392
+ if (!existing) return;
393
+ await existing.ready;
394
+
395
+ const result = asObject(toPlain(body.toolCallResult));
396
+ const error = body.error;
397
+ const status = forceError || result.status === 'error' ? 'error' : 'success';
398
+ const output = result.content ?? result.result ?? result;
399
+ const invokeStart = Number(result.invokeStartTime);
400
+ const invokeEnd = Number(result.invokeEndTime);
401
+ const durationMs =
402
+ Number.isFinite(invokeStart) && Number.isFinite(invokeEnd) && invokeEnd >= invokeStart
403
+ ? invokeEnd - invokeStart
404
+ : Date.now() - existing.startedAt;
405
+
406
+ await this.spanService.update(existing.spanId, {
407
+ status,
408
+ endedAt: new Date(),
409
+ durationMs,
410
+ output: forceError ? undefined : trimText(output, 20000),
411
+ error: forceError ? trimText(errorMessage(error), 10000) : undefined,
412
+ metadata: {
413
+ source: NATIVE_SOURCE,
414
+ toolCallResultStatus: result.status,
415
+ invokeStatus: result.invokeStatus,
416
+ messageId: toolCall.messageId,
417
+ },
418
+ });
419
+
420
+ await this.tokenTracker.estimateAndTrack(
421
+ existing.spanId,
422
+ normalizeString(toolCall.name),
423
+ typeof output === 'string' ? output : JSON.stringify(output),
424
+ );
425
+ }
426
+
427
+ private resolveParentSessionId(task: NativeSubAgentTask) {
428
+ const values = task.ctx?.action?.params?.values || {};
429
+ return normalizeString(values.sessionId) || undefined;
430
+ }
431
+
432
+ private async resolveLeaderUsername(ctx: NativeSubAgentTask['ctx'], parentSessionId?: string) {
433
+ const values = ctx?.action?.params?.values || {};
434
+ const direct =
435
+ normalizeString(values.aiEmployeeUsername) ||
436
+ normalizeString((asObject(values.aiEmployee) as Record<string, unknown>).username);
437
+ if (direct) return direct;
438
+ if (!parentSessionId) return undefined;
439
+
440
+ try {
441
+ const repo = ctx.db?.getRepository?.('aiConversations') as
442
+ | { findOne?: (options: Record<string, unknown>) => Promise<unknown> }
443
+ | undefined;
444
+ const conversation = await repo?.findOne?.({
445
+ filter: { sessionId: parentSessionId },
446
+ });
447
+ return normalizeString(readValue(conversation, 'aiEmployeeUsername')) || undefined;
448
+ } catch {
449
+ return undefined;
450
+ }
451
+ }
452
+
453
+ private async resolveDispatchToolMessage(
454
+ ctx: NativeSubAgentTask['ctx'],
455
+ parentSessionId?: string,
456
+ subSessionId?: string,
457
+ ) {
458
+ if (!parentSessionId) return null;
459
+ try {
460
+ const fromMetadata = await this.resolveDispatchToolMessageFromMetadata(ctx, parentSessionId, subSessionId);
461
+ if (fromMetadata) {
462
+ return fromMetadata;
463
+ }
464
+
465
+ const repo = ctx.db?.getRepository?.('aiToolMessages') as
466
+ | { findOne?: (options: Record<string, unknown>) => Promise<unknown> }
467
+ | undefined;
468
+ const record = await repo?.findOne?.({
469
+ filter: {
470
+ sessionId: parentSessionId,
471
+ toolName: 'dispatch-sub-agent-task',
472
+ invokeStatus: {
473
+ $ne: 'confirmed',
474
+ },
475
+ },
476
+ sort: ['-id'],
477
+ });
478
+ return toPlain(record) as DispatchToolMessage | null;
479
+ } catch {
480
+ return null;
481
+ }
482
+ }
483
+
484
+ private async resolveDispatchToolMessageFromMetadata(
485
+ ctx: NativeSubAgentTask['ctx'],
486
+ parentSessionId?: string,
487
+ subSessionId?: string,
488
+ ) {
489
+ if (!parentSessionId || !subSessionId) return null;
490
+
491
+ const messageRepo = ctx.db?.getRepository?.('aiMessages') as
492
+ | { find?: (options: Record<string, unknown>) => Promise<unknown[]> }
493
+ | undefined;
494
+ const toolRepo = ctx.db?.getRepository?.('aiToolMessages') as
495
+ | { findOne?: (options: Record<string, unknown>) => Promise<unknown> }
496
+ | undefined;
497
+ const messages = await messageRepo?.find?.({
498
+ filter: { sessionId: parentSessionId },
499
+ sort: ['-messageId'],
500
+ limit: 20,
501
+ });
502
+ if (!Array.isArray(messages)) return null;
503
+
504
+ for (const rawMessage of messages) {
505
+ const message = toPlain(rawMessage);
506
+ const conversations = asObject(message?.metadata).subAgentConversations;
507
+ if (!Array.isArray(conversations)) continue;
508
+
509
+ const matched = conversations.find((item) => normalizeString(item?.sessionId) === subSessionId);
510
+ const toolCallId = normalizeString(matched?.toolCallId);
511
+ if (!toolCallId) continue;
512
+
513
+ const toolMessage = await toolRepo?.findOne?.({
514
+ filter: {
515
+ sessionId: parentSessionId,
516
+ toolCallId,
517
+ },
518
+ });
519
+ return {
520
+ ...(toPlain(toolMessage) || {}),
521
+ toolCallId,
522
+ messageId: readValue(toolMessage, 'messageId') || message?.messageId,
523
+ sessionId: parentSessionId,
524
+ status: matched?.status,
525
+ } as DispatchToolMessage;
526
+ }
527
+
528
+ return null;
529
+ }
530
+
531
+ private async flushPending(state: RunState) {
532
+ const pending = Array.from(state.pending);
533
+ if (!pending.length) return;
534
+ await Promise.allSettled(pending);
535
+ }
536
+ }
537
+
538
+ export { NATIVE_SOURCE, makeNativeRunId };