plugin-agent-orchestrator 1.1.4 → 1.1.6

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 (148) hide show
  1. package/README.md +204 -114
  2. package/dist/client/index.js +1 -1
  3. package/dist/client-v2/117.7565cff57c39318a.js +10 -0
  4. package/dist/client-v2/214.106635011859dede.js +10 -0
  5. package/dist/client-v2/418.41ed200e7d6da332.js +10 -0
  6. package/dist/client-v2/53.349fff8db80b19d4.js +10 -0
  7. package/dist/client-v2/981.e4a1f41cfc94a856.js +10 -0
  8. package/dist/client-v2/index.js +1 -1
  9. package/dist/externalVersion.js +7 -8
  10. package/dist/locale/en-US.json +226 -170
  11. package/dist/locale/vi-VN.json +226 -170
  12. package/dist/locale/zh-CN.json +226 -170
  13. package/dist/server/collections/agent-execution-spans.js +8 -0
  14. package/dist/server/collections/agent-loop-action-approvals.js +1 -0
  15. package/dist/server/collections/agent-loop-runs.js +7 -1
  16. package/dist/server/collections/agent-loop-steps.js +7 -0
  17. package/dist/server/collections/skill-executions.js +8 -0
  18. package/dist/server/plugin.js +3 -1
  19. package/dist/server/resources/agent-harness-profile.js +117 -0
  20. package/dist/server/resources/agent-knowledge-insights.js +1 -3
  21. package/dist/server/resources/agent-loop-approval.js +25 -0
  22. package/dist/server/resources/agent-loop.js +3 -1
  23. package/dist/server/services/AgentMemoryContextService.js +34 -0
  24. package/dist/server/services/HarnessCompiler.js +35 -2
  25. package/dist/server/services/HarnessProfileService.js +74 -9
  26. package/dist/server/services/HarnessSchema.js +30 -3
  27. package/dist/server/services/LoopPatternSchema.js +16 -1
  28. package/dist/server/services/LoopRunRepository.js +80 -0
  29. package/dist/server/services/LoopRunStateMachine.js +92 -3
  30. package/dist/server/services/LoopTriggerService.js +37 -0
  31. package/dist/server/services/LoopWorkerService.js +261 -23
  32. package/dist/server/services/NativeSubAgentObserver.js +165 -23
  33. package/dist/server/services/PluginAiRuntimeAdapter.js +16 -5
  34. package/dist/server/services/ToolLoopDetectionService.js +210 -0
  35. package/dist/server/services/VerificationService.js +66 -0
  36. package/dist/server/services/harness-runtime-policy.js +139 -0
  37. package/dist/server/skill-hub/plugin.js +36 -3
  38. package/dist/server/skill-hub/tasks/SkillExecutionTask.js +29 -0
  39. package/package.json +53 -53
  40. package/src/client/ApprovalsTab.tsx +2 -0
  41. package/src/client/OrchestratorSettings.tsx +11 -0
  42. package/src/client/skill-hub/components/GitSkillImport.tsx +3 -3
  43. package/src/client/skill-hub/components/SkillMetrics.tsx +15 -10
  44. package/src/client/skill-hub/index.tsx +0 -52
  45. package/src/client-v2/components/AgentRunsTab.tsx +576 -576
  46. package/src/client-v2/components/ApprovalsTab.tsx +337 -0
  47. package/src/client-v2/components/HarnessProfilesTab.tsx +385 -105
  48. package/src/client-v2/components/MemoryInspectorTab.tsx +141 -141
  49. package/src/client-v2/components/TracingTab.tsx +515 -515
  50. package/src/client-v2/hooks/useApiRequest.ts +141 -141
  51. package/src/client-v2/pages/ApprovalsPage.tsx +10 -0
  52. package/src/client-v2/plugin.tsx +6 -6
  53. package/src/client-v2/skill-hub/components/SkillMetrics.tsx +5 -2
  54. package/src/locale/en-US.json +226 -174
  55. package/src/locale/vi-VN.json +226 -174
  56. package/src/locale/zh-CN.json +226 -174
  57. package/src/server/__tests__/circuit-breaker.test.ts +248 -248
  58. package/src/server/__tests__/harness-compiler.test.ts +83 -0
  59. package/src/server/__tests__/harness-profile-service.test.ts +51 -0
  60. package/src/server/__tests__/harness-runtime-policy.test.ts +293 -0
  61. package/src/server/__tests__/harness-tool-plan.test.ts +24 -0
  62. package/src/server/__tests__/loop-approval-decision.test.ts +512 -0
  63. package/src/server/__tests__/loop-approval-expiry.test.ts +258 -0
  64. package/src/server/__tests__/loop-budget-service.test.ts +255 -255
  65. package/src/server/__tests__/loop-control-plane-backfill.test.ts +266 -266
  66. package/src/server/__tests__/loop-pattern-schema.test.ts +18 -1
  67. package/src/server/__tests__/loop-pattern-service.test.ts +148 -148
  68. package/src/server/__tests__/loop-run-state-machine.test.ts +11 -0
  69. package/src/server/__tests__/loop-trigger-service.test.ts +148 -0
  70. package/src/server/__tests__/loop-worker-claim.test.ts +341 -341
  71. package/src/server/__tests__/loop-worker-execution.test.ts +82 -1
  72. package/src/server/__tests__/native-sub-agent-observer.test.ts +288 -4
  73. package/src/server/__tests__/path-lock-service.test.ts +254 -254
  74. package/src/server/__tests__/skill-execution-task-policy.test.ts +140 -0
  75. package/src/server/__tests__/smoke.test.ts +162 -162
  76. package/src/server/__tests__/tool-loop-detection.test.ts +275 -0
  77. package/src/server/collections/agent-execution-spans.ts +8 -0
  78. package/src/server/collections/agent-harness-profile-versions.ts +26 -26
  79. package/src/server/collections/agent-harness-profiles.ts +71 -71
  80. package/src/server/collections/agent-loop-action-approvals.ts +1 -0
  81. package/src/server/collections/agent-loop-artifacts.ts +25 -25
  82. package/src/server/collections/agent-loop-circuit-states.ts +23 -23
  83. package/src/server/collections/agent-loop-control-settings.ts +21 -21
  84. package/src/server/collections/agent-loop-events.ts +98 -98
  85. package/src/server/collections/agent-loop-path-locks.ts +27 -27
  86. package/src/server/collections/agent-loop-patterns.ts +42 -42
  87. package/src/server/collections/agent-loop-runs.ts +7 -1
  88. package/src/server/collections/agent-loop-steps.ts +7 -0
  89. package/src/server/collections/agent-loop-usage-buckets.ts +22 -22
  90. package/src/server/collections/agent-loop-worktrees.ts +25 -25
  91. package/src/server/collections/skill-executions.ts +8 -0
  92. package/src/server/migrations/20260427000002-change-packages-to-text.ts +52 -52
  93. package/src/server/migrations/20260429000000-add-llm-fields.ts +47 -47
  94. package/src/server/migrations/20260429000001-fix-inputargs-json-to-text.ts +45 -45
  95. package/src/server/migrations/20260503000000-add-orchestrator-trace-fields.ts +33 -33
  96. package/src/server/migrations/20260524000000-add-agent-loop-fields-to-skill-executions.ts +31 -31
  97. package/src/server/migrations/20260803010000-backfill-loop-control-plane-data.ts +293 -293
  98. package/src/server/plugin.ts +3 -1
  99. package/src/server/resources/agent-harness-profile.ts +94 -0
  100. package/src/server/resources/agent-knowledge-insights.ts +5 -3
  101. package/src/server/resources/agent-loop-approval.ts +32 -0
  102. package/src/server/resources/agent-loop-artifact.ts +56 -56
  103. package/src/server/resources/agent-loop-events-stream.ts +105 -105
  104. package/src/server/resources/agent-loop.ts +3 -1
  105. package/src/server/resources/resource-helpers.ts +33 -33
  106. package/src/server/resources/tracing.ts +266 -266
  107. package/src/server/services/AgentMemoryContextService.ts +44 -0
  108. package/src/server/services/DurableCircuitBreakerService.ts +239 -239
  109. package/src/server/services/ExecutionSpanService.ts +2 -0
  110. package/src/server/services/HarnessCompiler.ts +37 -0
  111. package/src/server/services/HarnessProfileService.ts +92 -10
  112. package/src/server/services/HarnessSchema.ts +31 -0
  113. package/src/server/services/LoopBudgetService.ts +275 -275
  114. package/src/server/services/LoopControlService.ts +124 -124
  115. package/src/server/services/LoopPatternSchema.ts +19 -1
  116. package/src/server/services/LoopPatternService.ts +143 -143
  117. package/src/server/services/LoopRunRepository.ts +99 -0
  118. package/src/server/services/LoopRunStateMachine.ts +100 -3
  119. package/src/server/services/LoopSchedulerService.ts +199 -199
  120. package/src/server/services/LoopTriggerService.ts +42 -0
  121. package/src/server/services/LoopWorkerService.ts +327 -27
  122. package/src/server/services/NativeSubAgentObserver.ts +186 -21
  123. package/src/server/services/PathLockService.ts +321 -321
  124. package/src/server/services/PluginAiRuntimeAdapter.ts +24 -7
  125. package/src/server/services/ToolLoopDetectionService.ts +213 -0
  126. package/src/server/services/VerificationSchema.ts +31 -31
  127. package/src/server/services/VerificationService.ts +81 -2
  128. package/src/server/services/harness-runtime-policy.ts +141 -0
  129. package/src/server/skill-hub/plugin.ts +41 -3
  130. package/src/server/skill-hub/services/RegistrySkillSnapshotService.ts +235 -235
  131. package/src/server/skill-hub/services/__tests__/RegistrySkillSnapshotService.test.ts +61 -61
  132. package/src/server/skill-hub/tasks/SkillExecutionTask.ts +43 -2
  133. package/src/server/utils/ensure-indexes.ts +96 -96
  134. package/src/server/utils/logging.ts +62 -62
  135. package/src/server/utils/loop-pattern-context.ts +20 -20
  136. package/dist/client-v2/214.b063f33ba044a808.js +0 -10
  137. package/dist/client-v2/373.f5d5292e53c4e832.js +0 -10
  138. package/dist/client-v2/418.58fa350f5496efd3.js +0 -10
  139. package/dist/client-v2/53.9a10455323390f14.js +0 -10
  140. package/dist/client-v2/677.a991ce0250ff5c77.js +0 -10
  141. package/dist/client-v2/925.e5925bf21ed68e7a.js +0 -10
  142. package/src/client/AIEmployeeSelect.tsx +0 -47
  143. package/src/client/AIEmployeesContext.tsx +0 -102
  144. package/src/client/RulesTab.tsx +0 -2
  145. package/src/client/TracingTab.tsx +0 -436
  146. package/src/client/skill-hub/components/ExecutionProgress.tsx +0 -51
  147. package/src/client-v2/components/RulesTab.tsx +0 -2
  148. package/src/client-v2/pages/AgentRunsPage.tsx +0 -13
@@ -17,6 +17,12 @@ const SYSTEM_TOOL_KNOWLEDGE_BASE = 'knowledge-base-retrieve';
17
17
 
18
18
  export type LoopRole = 'leader' | 'maker' | 'verifier';
19
19
 
20
+ export type ToolCallDecision = {
21
+ type: 'approve' | 'edit' | 'reject';
22
+ message?: string;
23
+ editedAction?: { name: string; args: unknown };
24
+ };
25
+
20
26
  export type InterruptedToolCall = {
21
27
  toolCallId: string;
22
28
  toolName: string;
@@ -128,7 +134,9 @@ export async function planHarnessTools(
128
134
  discovery?: { ctx?: unknown; sessionId?: string },
129
135
  ): Promise<HarnessToolPlan> {
130
136
  const toolsManager = getAIToolsManager(app);
131
- const candidates = Array.from(new Set([...harness.tools.allow, ...harness.tools.ask]));
137
+ // Escalatable tools join the plan as ask-gated candidates: the model can invoke them, but every
138
+ // call interrupts and parks the run until a human approves that single call.
139
+ const candidates = Array.from(new Set([...harness.tools.allow, ...harness.tools.ask, ...harness.tools.escalate]));
132
140
  const plan: HarnessToolPlan = { filter: [], employeeTools: [], withheld: [], blockedSystemTools: [] };
133
141
  const filter = discovery ? { ctx: discovery.ctx, sessionId: discovery.sessionId } : undefined;
134
142
 
@@ -208,6 +216,8 @@ export class PluginAiRuntimeAdapter {
208
216
 
209
217
  // Resume mirrors the official workflow employee node: flip the persisted tool call to
210
218
  // `waiting` with a decision, then re-invoke so plugin-ai resumes its own checkpoint.
219
+ // Decisions are per tool call: plugin-ai stores one `userDecision` per interrupted row and
220
+ // `getUserDecisions` only unblocks once every interrupted call of the message has one.
211
221
  async resume(input: {
212
222
  username: string;
213
223
  sessionId: string;
@@ -215,17 +225,24 @@ export class PluginAiRuntimeAdapter {
215
225
  userId?: number;
216
226
  systemMessage: string;
217
227
  harness: CompiledHarness;
218
- decision: { type: 'approve' | 'reject'; message?: string; editedAction?: { name: string; args: unknown } };
228
+ decisions: Array<{ toolCallId: string; decision: ToolCallDecision }>;
219
229
  signal: AbortSignal;
220
230
  }): Promise<InvocationOutcome> {
221
231
  const plugin = this.plugin();
222
232
 
223
- await this.app.db
224
- .getModel('aiToolMessages')
225
- .update(
226
- { userDecision: input.decision, invokeStatus: 'waiting' },
227
- { where: { sessionId: input.sessionId, messageId: input.messageId, invokeStatus: 'interrupted' } },
233
+ for (const entry of input.decisions) {
234
+ await this.app.db.getModel('aiToolMessages').update(
235
+ { userDecision: entry.decision, invokeStatus: 'waiting' },
236
+ {
237
+ where: {
238
+ sessionId: input.sessionId,
239
+ messageId: input.messageId,
240
+ toolCallId: entry.toolCallId,
241
+ invokeStatus: 'interrupted',
242
+ },
243
+ },
228
244
  );
245
+ }
229
246
  const userDecisions = await plugin.aiConversationsManager.getUserDecisions(input.messageId);
230
247
  if (!userDecisions) throw new Error('The interrupted tool calls are not all ready to resume.');
231
248
 
@@ -0,0 +1,213 @@
1
+ import { createHash } from 'node:crypto';
2
+ import type { Database, Model } from '@nocobase/database';
3
+ import { getRunEventBus } from './RunEventBus';
4
+ import type { LoopPatternPolicy } from './LoopPatternSchema';
5
+
6
+ export type ToolLoopLevel = 'none' | 'warn' | 'block' | 'escalate';
7
+
8
+ export type ToolLoopFinding = {
9
+ level: Exclude<ToolLoopLevel, 'none'>;
10
+ toolName: string;
11
+ signature: string;
12
+ count: number;
13
+ sampleArgs: Record<string, unknown>;
14
+ };
15
+
16
+ export type ToolCallEntry = {
17
+ name: string;
18
+ args: unknown;
19
+ };
20
+
21
+ export type ToolLoopRecordContext = {
22
+ runId: number;
23
+ role: string;
24
+ username: string;
25
+ runStatus: string;
26
+ actorType: string;
27
+ actorIdentity: string;
28
+ };
29
+
30
+ function read(record: Model | Record<string, unknown>, key: string) {
31
+ const model = record as Model & { get?: (name: string) => unknown };
32
+ return typeof model.get === 'function' ? model.get(key) : (record as Record<string, unknown>)[key];
33
+ }
34
+
35
+ function asObject(value: unknown): Record<string, unknown> {
36
+ return value && typeof value === 'object' && !Array.isArray(value) ? (value as Record<string, unknown>) : {};
37
+ }
38
+
39
+ // Key order alone must not change the signature, so object keys are sorted before hashing.
40
+ function canonicalize(value: unknown): unknown {
41
+ if (Array.isArray(value)) return value.map((entry) => canonicalize(entry));
42
+ if (value && typeof value === 'object') {
43
+ const source = value as Record<string, unknown>;
44
+ const ordered: Record<string, unknown> = {};
45
+ for (const key of Object.keys(source).sort()) ordered[key] = canonicalize(source[key]);
46
+ return ordered;
47
+ }
48
+ return value;
49
+ }
50
+
51
+ // A NUL byte cannot appear unescaped in JSON string output, so the name/args boundary of the
52
+ // hashed payload is unambiguous.
53
+ const NAME_ARGS_SEPARATOR = String.fromCharCode(0);
54
+
55
+ export function toolCallSignature(name: string, args: unknown): string {
56
+ return createHash('sha256')
57
+ .update(name + NAME_ARGS_SEPARATOR + JSON.stringify(canonicalize(args ?? null)))
58
+ .digest('hex');
59
+ }
60
+
61
+ type RepetitionEntry = { toolName: string; signature: string; count: number; sampleArgs: Record<string, unknown> };
62
+
63
+ export function countToolRepetitions(calls: ToolCallEntry[]): Map<string, RepetitionEntry> {
64
+ const counts = new Map<string, RepetitionEntry>();
65
+ for (const call of calls) {
66
+ if (!call.name) continue;
67
+ const signature = toolCallSignature(call.name, call.args);
68
+ const entry = counts.get(signature) ?? {
69
+ toolName: call.name,
70
+ signature,
71
+ count: 0,
72
+ sampleArgs: asObject(call.args),
73
+ };
74
+ entry.count += 1;
75
+ counts.set(signature, entry);
76
+ }
77
+ return counts;
78
+ }
79
+
80
+ export function toolLoopLevel(count: number, detection: LoopPatternPolicy['loopDetection']): ToolLoopLevel {
81
+ if (!detection.enabled) return 'none';
82
+ if (count >= detection.escalateAt) return 'escalate';
83
+ if (count >= detection.blockAt) return 'block';
84
+ if (count >= detection.warnAt) return 'warn';
85
+ return 'none';
86
+ }
87
+
88
+ export function toolLoopReason(finding: ToolLoopFinding): string {
89
+ return `Tool loop detected: "${finding.toolName}" was invoked ${finding.count} times with identical arguments.`;
90
+ }
91
+
92
+ export function toolLoopNotice(toolName: string, count: number): string {
93
+ return [
94
+ '<tool_loop_warning>',
95
+ `An earlier pass of this run invoked the tool "${toolName}" with identical arguments ${count} times.`,
96
+ 'Do not repeat this pattern. If the tool did not return what you expected, change your approach or report the blocker explicitly instead of retrying the same call.',
97
+ '</tool_loop_warning>',
98
+ ].join('\n');
99
+ }
100
+
101
+ export class ToolLoopDetectionService {
102
+ constructor(private readonly database: Database) {}
103
+
104
+ // Scans every tool call the run has issued so far (across all pass sessions, which are linked
105
+ // through agentLoopSteps.sessionId) and returns the most repeated signature once it crosses the
106
+ // policy's warn threshold. Returns null while the run stays under every threshold.
107
+ async scanRun(runId: number, policy: LoopPatternPolicy): Promise<ToolLoopFinding | null> {
108
+ const detection = policy.loopDetection;
109
+ if (!detection.enabled) return null;
110
+
111
+ const steps = await this.database.getRepository('agentLoopSteps').find({ filter: { runId } });
112
+ const sessionIds = new Set<string>();
113
+ for (const step of steps) {
114
+ const sessionId = read(step, 'sessionId');
115
+ if (typeof sessionId === 'string' && sessionId) sessionIds.add(sessionId);
116
+ }
117
+ if (!sessionIds.size) return null;
118
+
119
+ const messages = await this.database.getRepository('aiMessages').find({
120
+ filter: { sessionId: { $in: [...sessionIds] } },
121
+ });
122
+ const calls: ToolCallEntry[] = [];
123
+ for (const message of messages) {
124
+ const toolCalls = read(message, 'toolCalls');
125
+ if (!Array.isArray(toolCalls)) continue;
126
+ for (const toolCall of toolCalls) {
127
+ const entry = asObject(toolCall);
128
+ if (typeof entry.name === 'string' && entry.name) calls.push({ name: entry.name, args: entry.args });
129
+ }
130
+ }
131
+ if (!calls.length) return null;
132
+
133
+ let worst: ToolLoopFinding | null = null;
134
+ for (const entry of countToolRepetitions(calls).values()) {
135
+ const level = toolLoopLevel(entry.count, detection);
136
+ if (level === 'none') continue;
137
+ if (!worst || entry.count > worst.count) worst = { level, ...entry };
138
+ }
139
+ return worst;
140
+ }
141
+
142
+ // Persists the guard step and event for a finding, deduplicated by signature so a run records
143
+ // each loop once no matter how many subsequent passes observe it. Returns true when a new
144
+ // record was created.
145
+ async recordFinding(context: ToolLoopRecordContext, finding: ToolLoopFinding): Promise<boolean> {
146
+ const steps = this.database.getRepository('agentLoopSteps');
147
+ const existing = await steps.findOne({
148
+ filter: { runId: context.runId, kind: 'guard', inputHash: finding.signature },
149
+ });
150
+ if (existing) return false;
151
+
152
+ const now = new Date();
153
+ const runSteps = await steps.find({ filter: { runId: context.runId } });
154
+ const step = await steps.create({
155
+ values: {
156
+ runId: context.runId,
157
+ runtimeVersion: 'control-plane-v2',
158
+ sequence: runSteps.length,
159
+ role: context.role,
160
+ kind: 'guard',
161
+ type: 'tool_loop',
162
+ employeeUsername: context.username,
163
+ toolName: finding.toolName,
164
+ inputHash: finding.signature,
165
+ title: `Tool loop ${finding.level}: ${finding.toolName} x${finding.count}`,
166
+ description: toolLoopReason(finding),
167
+ status: 'succeeded',
168
+ metadata: { level: finding.level, count: finding.count, sampleArgs: finding.sampleArgs },
169
+ startedAt: now,
170
+ endedAt: now,
171
+ createdAt: now,
172
+ },
173
+ });
174
+ const event = await this.database.getRepository('agentLoopEvents').create({
175
+ values: {
176
+ runId: context.runId,
177
+ stepId: read(step, 'id'),
178
+ type: 'tool_loop_detected',
179
+ title: `Tool loop ${finding.level}: ${finding.toolName}`,
180
+ content: toolLoopReason(finding),
181
+ status: context.runStatus,
182
+ payload: {
183
+ level: finding.level,
184
+ toolName: finding.toolName,
185
+ count: finding.count,
186
+ signature: finding.signature,
187
+ },
188
+ actorType: context.actorType,
189
+ actorIdentity: context.actorIdentity,
190
+ correlationKey: `tool-loop:${finding.signature}`,
191
+ createdAt: now,
192
+ },
193
+ });
194
+ getRunEventBus().emit(context.runId, typeof event.toJSON === 'function' ? event.toJSON() : event);
195
+ return true;
196
+ }
197
+
198
+ // Rebuilds the model-facing notices from guard steps recorded before the current worker claim,
199
+ // so a run that parked and resumed keeps warning later roles about an earlier loop.
200
+ async existingNotices(runId: number): Promise<string[]> {
201
+ const steps = await this.database.getRepository('agentLoopSteps').find({
202
+ filter: { runId, kind: 'guard' },
203
+ });
204
+ const notices: string[] = [];
205
+ for (const step of steps) {
206
+ const toolName = String(read(step, 'toolName') || '');
207
+ const count = Number(asObject(read(step, 'metadata')).count) || 0;
208
+ if (!toolName || !count) continue;
209
+ notices.push(toolLoopNotice(toolName, count));
210
+ }
211
+ return notices;
212
+ }
213
+ }
@@ -1,31 +1,31 @@
1
- import { z } from 'zod';
2
-
3
- export const verificationVerdictSchema = z.object({
4
- verdict: z.enum(['pass', 'reject', 'escalate']),
5
- summary: z.string().min(1),
6
- checks: z
7
- .array(
8
- z.object({
9
- name: z.string().min(1),
10
- status: z.enum(['pass', 'fail', 'skipped']),
11
- evidenceArtifactIds: z.array(z.number().int().positive()).default([]),
12
- }),
13
- )
14
- .min(1),
15
- residualRisks: z.array(z.string()).default([]),
16
- });
17
-
18
- export type VerificationVerdict = z.infer<typeof verificationVerdictSchema>;
19
-
20
- export function parseVerificationVerdict(value: unknown) {
21
- return verificationVerdictSchema.parse(value);
22
- }
23
-
24
- export function isPassingVerification(value: unknown) {
25
- const parsed = verificationVerdictSchema.safeParse(value);
26
- return (
27
- parsed.success &&
28
- parsed.data.verdict === 'pass' &&
29
- parsed.data.checks.every((check) => check.status === 'pass' && check.evidenceArtifactIds.length > 0)
30
- );
31
- }
1
+ import { z } from 'zod';
2
+
3
+ export const verificationVerdictSchema = z.object({
4
+ verdict: z.enum(['pass', 'reject', 'escalate']),
5
+ summary: z.string().min(1),
6
+ checks: z
7
+ .array(
8
+ z.object({
9
+ name: z.string().min(1),
10
+ status: z.enum(['pass', 'fail', 'skipped']),
11
+ evidenceArtifactIds: z.array(z.number().int().positive()).default([]),
12
+ }),
13
+ )
14
+ .min(1),
15
+ residualRisks: z.array(z.string()).default([]),
16
+ });
17
+
18
+ export type VerificationVerdict = z.infer<typeof verificationVerdictSchema>;
19
+
20
+ export function parseVerificationVerdict(value: unknown) {
21
+ return verificationVerdictSchema.parse(value);
22
+ }
23
+
24
+ export function isPassingVerification(value: unknown) {
25
+ const parsed = verificationVerdictSchema.safeParse(value);
26
+ return (
27
+ parsed.success &&
28
+ parsed.data.verdict === 'pass' &&
29
+ parsed.data.checks.every((check) => check.status === 'pass' && check.evidenceArtifactIds.length > 0)
30
+ );
31
+ }
@@ -3,6 +3,7 @@ import type { CompiledHarness } from './HarnessCompiler';
3
3
  import type { LoopPatternPolicy } from './LoopPatternSchema';
4
4
  import type { LoopRunStateMachine } from './LoopRunStateMachine';
5
5
  import type { PluginAiRuntimeAdapter } from './PluginAiRuntimeAdapter';
6
+ import { ToolLoopDetectionService, toolLoopReason } from './ToolLoopDetectionService';
6
7
  import { parseVerificationVerdict } from './VerificationSchema';
7
8
  import type { VerificationVerdict } from './VerificationSchema';
8
9
 
@@ -19,12 +20,13 @@ export type VerificationRequest = {
19
20
  userId?: number;
20
21
  workerId: string;
21
22
  leaseToken: string;
23
+ loopNotices?: string[];
22
24
  signal: AbortSignal;
23
25
  };
24
26
 
25
27
  export type VerificationOutcome = {
26
28
  verdict: VerificationVerdict;
27
- finalStatus: 'succeeded' | 'waiting_human' | 'failed';
29
+ finalStatus: 'succeeded' | 'waiting_human' | 'failed' | 'halted';
28
30
  };
29
31
 
30
32
  function read(record: Model | Record<string, unknown>, key: string) {
@@ -61,6 +63,7 @@ function verifierPrompt(input: VerificationRequest, artifacts: Array<Record<stri
61
63
  '',
62
64
  `Required checks: ${input.policy.verification.requiredChecks.join(', ')}`,
63
65
  '',
66
+ ...(input.loopNotices ?? []),
64
67
  'Reply with a single JSON object and nothing else:',
65
68
  '{"verdict":"pass|reject|escalate","summary":"...","checks":[{"name":"...","status":"pass|fail|skipped",',
66
69
  '"evidenceArtifactIds":[<artifact ids from the list above>]}],"residualRisks":["..."]}',
@@ -70,16 +73,28 @@ function verifierPrompt(input: VerificationRequest, artifacts: Array<Record<stri
70
73
  }
71
74
 
72
75
  export class VerificationService {
76
+ private readonly loopGuard: ToolLoopDetectionService;
77
+
73
78
  constructor(
74
79
  private readonly database: Database,
75
80
  private readonly runtime: PluginAiRuntimeAdapter,
76
81
  private readonly stateMachine: LoopRunStateMachine,
77
- ) {}
82
+ ) {
83
+ this.loopGuard = new ToolLoopDetectionService(database);
84
+ }
78
85
 
79
86
  async verifyAndFinalize(input: VerificationRequest): Promise<VerificationOutcome> {
80
87
  this.assertIndependentVerifier(input);
81
88
  const artifacts = await this.runArtifacts(input.runId);
82
89
  const verdict = await this.collectVerdict(input, artifacts);
90
+
91
+ // The guard also sees the verifier's own tool calls: a verifier retrying the same evidence
92
+ // lookup over and over is the same behavioral failure as a maker looping on its tools.
93
+ const guard = await this.enforceToolLoopGuard(input);
94
+ if (guard === 'halt') {
95
+ return { verdict, finalStatus: 'halted' };
96
+ }
97
+
83
98
  await this.assertEvidenceBelongsToRun(verdict, artifacts, input.verifierUsername);
84
99
 
85
100
  const finalStatus = this.finalStatusFor(verdict, input.autonomyLevel);
@@ -110,6 +125,44 @@ export class VerificationService {
110
125
  }
111
126
  }
112
127
 
128
+ private async enforceToolLoopGuard(input: VerificationRequest): Promise<'continue' | 'halt'> {
129
+ const finding = await this.loopGuard.scanRun(input.runId, input.policy);
130
+ if (!finding) return 'continue';
131
+
132
+ await this.loopGuard.recordFinding(
133
+ {
134
+ runId: input.runId,
135
+ role: 'verifier',
136
+ username: input.verifierUsername,
137
+ runStatus: 'verifying',
138
+ actorType: 'worker',
139
+ actorIdentity: input.workerId,
140
+ },
141
+ finding,
142
+ );
143
+ if (finding.level === 'warn') return 'continue';
144
+
145
+ const reason = toolLoopReason(finding);
146
+ await this.stateMachine.transition({
147
+ runId: input.runId,
148
+ to: finding.level === 'block' ? 'blocked' : 'waiting_human',
149
+ actorType: 'worker',
150
+ actorIdentity: input.workerId,
151
+ leaseToken: input.leaseToken,
152
+ eventType: finding.level === 'block' ? 'run_blocked' : 'run_escalated',
153
+ title: finding.level === 'block' ? 'Run blocked by tool loop detection' : 'Run escalated by tool loop detection',
154
+ content: reason,
155
+ correlationKey: `tool-loop-${finding.level}:${input.runId}:${finding.signature}`,
156
+ values: finding.level === 'block' ? { blockedReason: reason } : { escalationReason: reason },
157
+ });
158
+ return 'halt';
159
+ }
160
+
161
+ private async nextSequence(runId: number) {
162
+ const steps = await this.database.getRepository('agentLoopSteps').find({ filter: { runId } });
163
+ return steps.length;
164
+ }
165
+
113
166
  private async collectVerdict(input: VerificationRequest, artifacts: Array<Record<string, unknown>>) {
114
167
  const sessionId = await this.runtime.createConversation({
115
168
  username: input.verifierUsername,
@@ -117,6 +170,24 @@ export class VerificationService {
117
170
  runId: input.runId,
118
171
  title: `Verification of run ${input.runId}`,
119
172
  });
173
+ // Recording the session on a step row is what lets the tool loop guard include the verifier's
174
+ // own tool calls in its run-level scan.
175
+ const step = await this.database.getRepository('agentLoopSteps').create({
176
+ values: {
177
+ runId: input.runId,
178
+ runtimeVersion: 'control-plane-v2',
179
+ sequence: await this.nextSequence(input.runId),
180
+ role: 'verifier',
181
+ kind: 'invocation',
182
+ type: 'verification',
183
+ employeeUsername: input.verifierUsername,
184
+ sessionId,
185
+ title: 'verifier invocation',
186
+ status: 'running',
187
+ startedAt: new Date(),
188
+ createdAt: new Date(),
189
+ },
190
+ });
120
191
  const outcome = await this.runtime.invoke({
121
192
  username: input.verifierUsername,
122
193
  sessionId,
@@ -127,6 +198,14 @@ export class VerificationService {
127
198
  prompt: verifierPrompt(input, artifacts),
128
199
  signal: input.signal,
129
200
  });
201
+ await this.database.getRepository('agentLoopSteps').update({
202
+ filterByTk: read(step, 'id'),
203
+ values: {
204
+ status: 'succeeded',
205
+ output: { content: outcome.content },
206
+ endedAt: new Date(),
207
+ },
208
+ });
130
209
  // A verifier that stops to ask for approval cannot produce a trustworthy verdict, and its
131
210
  // interrupted tool call would otherwise be silently dropped.
132
211
  if (outcome.interrupted.length) {
@@ -0,0 +1,141 @@
1
+ import type { Database } from '@nocobase/database';
2
+ import { compileHarness } from './HarnessCompiler';
3
+ import type { CompiledHarness } from './HarnessCompiler';
4
+ import { HarnessProfileService } from './HarnessProfileService';
5
+ import { parseHarnessSettings } from './HarnessSchema';
6
+
7
+ export type TraceLike = {
8
+ agentLoopRunId?: string | number;
9
+ employeeUsername?: string;
10
+ };
11
+
12
+ function read(record: unknown, key: string) {
13
+ const model = record as { get?: (name: string) => unknown } | null;
14
+ return typeof model?.get === 'function' ? model.get(key) : (model as Record<string, unknown> | null)?.[key];
15
+ }
16
+
17
+ function asObject(value: unknown): Record<string, unknown> {
18
+ return value && typeof value === 'object' && !Array.isArray(value) ? (value as Record<string, unknown>) : {};
19
+ }
20
+
21
+ // Run snapshots were compiled at enqueue time, possibly by an older schema revision. Re-parsing
22
+ // through the current schema backfills new policy fields with their defaults. `sources` is a
23
+ // compiler artifact the strict schema rejects, so it is stripped first.
24
+ function compiledFromSnapshot(snapshot: unknown): CompiledHarness | null {
25
+ const effective = asObject(asObject(snapshot).effective);
26
+ if (!effective.tools) return null;
27
+ const { sources: _sources, ...settings } = effective;
28
+ return compileHarness([{ source: 'run-snapshot', settings: parseHarnessSettings(settings) }]);
29
+ }
30
+
31
+ function snapshotForEmployee(run: Record<string, unknown>, username: string | undefined) {
32
+ const bindings = asObject(run.roleBindingsSnapshot);
33
+ if (!username) return null;
34
+ if (bindings.leader === username) return run.leaderHarnessSnapshot;
35
+ if (bindings.verifier === username) return run.verifierHarnessSnapshot;
36
+ const makers = asObject(run.makerHarnessSnapshot);
37
+ return makers[username] ?? null;
38
+ }
39
+
40
+ // Resolves the compiled harness of one role inside a loop run, or null when the run or the role's
41
+ // snapshot is unavailable. Loop snapshots are immutable and authoritative for everything the run
42
+ // delegates, so callers outside the run (sub-agent inheritance, skill enforcement) resolve through
43
+ // this instead of re-deriving policy.
44
+ export async function resolveRunRoleHarness(
45
+ database: Database,
46
+ runId: number,
47
+ username: string | undefined,
48
+ ): Promise<CompiledHarness | null> {
49
+ if (!Number.isSafeInteger(runId) || runId <= 0 || !username) return null;
50
+ const run = await database.getRepository('agentLoopRuns').findOne({ filterByTk: runId });
51
+ if (!run) return null;
52
+ const snapshot = snapshotForEmployee(asObject((run as { toJSON?: () => unknown }).toJSON?.() ?? run), username);
53
+ return compiledFromSnapshot(snapshot);
54
+ }
55
+
56
+ // Resolves the compiled harness governing a tool call. Loop runs carry an immutable snapshot per
57
+ // role, which is authoritative; anything outside a loop run falls back to the employee's
58
+ // harness-tag profile. Returns null when no policy applies (enforcement points then keep their
59
+ // existing behavior).
60
+ export async function resolveTraceHarness(database: Database, trace: TraceLike): Promise<CompiledHarness | null> {
61
+ const runHarness = await resolveRunRoleHarness(database, Number(trace.agentLoopRunId), trace.employeeUsername);
62
+ if (runHarness) return runHarness;
63
+ if (!trace.employeeUsername) return null;
64
+
65
+ const employee = await database.getRepository('aiEmployees').findOne({
66
+ filter: { username: trace.employeeUsername },
67
+ });
68
+ if (!employee) return null;
69
+ const settings = asObject(read(employee, 'skillSettings'));
70
+ const tag =
71
+ typeof settings.harnessTag === 'string' && settings.harnessTag.trim() ? settings.harnessTag.trim() : 'default';
72
+
73
+ const profiles = new HarnessProfileService(database);
74
+ const version =
75
+ (await profiles.getPublishedByTag(tag)) || (tag !== 'default' ? await profiles.getPublishedByTag('default') : null);
76
+ if (!version) return null;
77
+ return compileHarness([{ source: `profile:${tag}`, settings: version.settings }]);
78
+ }
79
+
80
+ export function harnessTimeoutMs(harness: CompiledHarness, toolName: string): number | null {
81
+ const timeouts = harness.tools.timeouts;
82
+ const direct = timeouts[toolName];
83
+ if (typeof direct === 'number' && direct > 0) return direct;
84
+ const generic = timeouts['skill_hub_execute'];
85
+ return typeof generic === 'number' && generic > 0 ? generic : null;
86
+ }
87
+
88
+ const SECRET_KEY_PATTERN = /(?:KEY|SECRET|TOKEN|PASSWORD|PASSWD|CREDENTIAL)/i;
89
+ export const REDACTED_PLACEHOLDER = '[REDACTED]';
90
+
91
+ // Key-name scrubbing for persisted telemetry: any value whose key looks secret-bearing is
92
+ // replaced wholesale. Free text is deliberately left alone — pattern-matching arbitrary output
93
+ // produces false negatives that only look like safety.
94
+ export function redactSecretsIn<T>(value: T): T {
95
+ const scrub = (input: unknown, depth: number): unknown => {
96
+ if (depth > 8 || input === null || input === undefined) return input;
97
+ if (Array.isArray(input)) return input.map((item) => scrub(item, depth + 1));
98
+ if (typeof input === 'object') {
99
+ const source = input as Record<string, unknown>;
100
+ const output: Record<string, unknown> = {};
101
+ for (const [key, entry] of Object.entries(source)) {
102
+ output[key] = SECRET_KEY_PATTERN.test(key) ? REDACTED_PLACEHOLDER : scrub(entry, depth + 1);
103
+ }
104
+ return output;
105
+ }
106
+ return input;
107
+ };
108
+ return scrub(value, 0) as T;
109
+ }
110
+
111
+ // Byte-safe slice that never splits a multi-byte character: the cut point advances past any
112
+ // continuation bytes (10xxxxxx) left dangling at the boundary.
113
+ function sliceBytes(buffer: Buffer, start: number, end: number) {
114
+ let from = Math.max(0, start);
115
+ while (from < end && (buffer[from] & 0xc0) === 0x80) from += 1;
116
+ return buffer.subarray(from, Math.min(buffer.length, end));
117
+ }
118
+
119
+ // Builds the model-facing replacement for an oversized output: head/tail preview plus a locator
120
+ // supplied by the caller (download URL for skill output, file path for sub-agent results).
121
+ // Returns null when the text already fits the inline budget. Mirrors the dsh spill policy.
122
+ export function spilledText(text: string, maxInlineBytes: number, locator: string): string | null {
123
+ const buffer = Buffer.from(text, 'utf8');
124
+ if (buffer.byteLength <= maxInlineBytes) return null;
125
+
126
+ const headTarget = Math.floor(maxInlineBytes * 0.6);
127
+ const tailTarget = Math.floor(maxInlineBytes * 0.2);
128
+ let head = sliceBytes(buffer, 0, headTarget).toString('utf8');
129
+ let tail = sliceBytes(buffer, buffer.byteLength - tailTarget, buffer.byteLength).toString('utf8');
130
+ const notice = () =>
131
+ `\n\n... (${
132
+ buffer.byteLength - Buffer.byteLength(head, 'utf8') - Buffer.byteLength(tail, 'utf8')
133
+ } bytes omitted. Full output stored at: ${locator}) ...`;
134
+ while (Buffer.byteLength(head + notice() + tail, 'utf8') > maxInlineBytes && head.length + tail.length > 0) {
135
+ head = head.slice(0, Math.floor(head.length * 0.9));
136
+ // Keep the true end of the output: shrinking from the front preserves the final lines.
137
+ const keepTail = Math.floor(tail.length * 0.9);
138
+ tail = keepTail > 0 ? tail.slice(-keepTail) : '';
139
+ }
140
+ return `${head}${notice()}${tail}`;
141
+ }