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.
- package/README.md +204 -114
- package/dist/client/index.js +1 -1
- package/dist/client-v2/117.7565cff57c39318a.js +10 -0
- package/dist/client-v2/214.106635011859dede.js +10 -0
- package/dist/client-v2/418.41ed200e7d6da332.js +10 -0
- package/dist/client-v2/53.349fff8db80b19d4.js +10 -0
- package/dist/client-v2/981.e4a1f41cfc94a856.js +10 -0
- package/dist/client-v2/index.js +1 -1
- package/dist/externalVersion.js +7 -8
- package/dist/locale/en-US.json +226 -170
- package/dist/locale/vi-VN.json +226 -170
- package/dist/locale/zh-CN.json +226 -170
- package/dist/server/collections/agent-execution-spans.js +8 -0
- package/dist/server/collections/agent-loop-action-approvals.js +1 -0
- package/dist/server/collections/agent-loop-runs.js +7 -1
- package/dist/server/collections/agent-loop-steps.js +7 -0
- package/dist/server/collections/skill-executions.js +8 -0
- package/dist/server/plugin.js +3 -1
- package/dist/server/resources/agent-harness-profile.js +117 -0
- package/dist/server/resources/agent-knowledge-insights.js +1 -3
- package/dist/server/resources/agent-loop-approval.js +25 -0
- package/dist/server/resources/agent-loop.js +3 -1
- package/dist/server/services/AgentMemoryContextService.js +34 -0
- package/dist/server/services/HarnessCompiler.js +35 -2
- package/dist/server/services/HarnessProfileService.js +74 -9
- package/dist/server/services/HarnessSchema.js +30 -3
- package/dist/server/services/LoopPatternSchema.js +16 -1
- package/dist/server/services/LoopRunRepository.js +80 -0
- package/dist/server/services/LoopRunStateMachine.js +92 -3
- package/dist/server/services/LoopTriggerService.js +37 -0
- package/dist/server/services/LoopWorkerService.js +261 -23
- package/dist/server/services/NativeSubAgentObserver.js +165 -23
- package/dist/server/services/PluginAiRuntimeAdapter.js +16 -5
- package/dist/server/services/ToolLoopDetectionService.js +210 -0
- package/dist/server/services/VerificationService.js +66 -0
- package/dist/server/services/harness-runtime-policy.js +139 -0
- package/dist/server/skill-hub/plugin.js +36 -3
- package/dist/server/skill-hub/tasks/SkillExecutionTask.js +29 -0
- package/package.json +53 -53
- package/src/client/ApprovalsTab.tsx +2 -0
- package/src/client/OrchestratorSettings.tsx +11 -0
- package/src/client/skill-hub/components/GitSkillImport.tsx +3 -3
- package/src/client/skill-hub/components/SkillMetrics.tsx +15 -10
- package/src/client/skill-hub/index.tsx +0 -52
- package/src/client-v2/components/AgentRunsTab.tsx +576 -576
- package/src/client-v2/components/ApprovalsTab.tsx +337 -0
- package/src/client-v2/components/HarnessProfilesTab.tsx +385 -105
- package/src/client-v2/components/MemoryInspectorTab.tsx +141 -141
- package/src/client-v2/components/TracingTab.tsx +515 -515
- package/src/client-v2/hooks/useApiRequest.ts +141 -141
- package/src/client-v2/pages/ApprovalsPage.tsx +10 -0
- package/src/client-v2/plugin.tsx +6 -6
- package/src/client-v2/skill-hub/components/SkillMetrics.tsx +5 -2
- package/src/locale/en-US.json +226 -174
- package/src/locale/vi-VN.json +226 -174
- package/src/locale/zh-CN.json +226 -174
- package/src/server/__tests__/circuit-breaker.test.ts +248 -248
- package/src/server/__tests__/harness-compiler.test.ts +83 -0
- package/src/server/__tests__/harness-profile-service.test.ts +51 -0
- package/src/server/__tests__/harness-runtime-policy.test.ts +293 -0
- package/src/server/__tests__/harness-tool-plan.test.ts +24 -0
- package/src/server/__tests__/loop-approval-decision.test.ts +512 -0
- package/src/server/__tests__/loop-approval-expiry.test.ts +258 -0
- package/src/server/__tests__/loop-budget-service.test.ts +255 -255
- package/src/server/__tests__/loop-control-plane-backfill.test.ts +266 -266
- package/src/server/__tests__/loop-pattern-schema.test.ts +18 -1
- package/src/server/__tests__/loop-pattern-service.test.ts +148 -148
- package/src/server/__tests__/loop-run-state-machine.test.ts +11 -0
- package/src/server/__tests__/loop-trigger-service.test.ts +148 -0
- package/src/server/__tests__/loop-worker-claim.test.ts +341 -341
- package/src/server/__tests__/loop-worker-execution.test.ts +82 -1
- package/src/server/__tests__/native-sub-agent-observer.test.ts +288 -4
- package/src/server/__tests__/path-lock-service.test.ts +254 -254
- package/src/server/__tests__/skill-execution-task-policy.test.ts +140 -0
- package/src/server/__tests__/smoke.test.ts +162 -162
- package/src/server/__tests__/tool-loop-detection.test.ts +275 -0
- package/src/server/collections/agent-execution-spans.ts +8 -0
- package/src/server/collections/agent-harness-profile-versions.ts +26 -26
- package/src/server/collections/agent-harness-profiles.ts +71 -71
- package/src/server/collections/agent-loop-action-approvals.ts +1 -0
- package/src/server/collections/agent-loop-artifacts.ts +25 -25
- package/src/server/collections/agent-loop-circuit-states.ts +23 -23
- package/src/server/collections/agent-loop-control-settings.ts +21 -21
- package/src/server/collections/agent-loop-events.ts +98 -98
- package/src/server/collections/agent-loop-path-locks.ts +27 -27
- package/src/server/collections/agent-loop-patterns.ts +42 -42
- package/src/server/collections/agent-loop-runs.ts +7 -1
- package/src/server/collections/agent-loop-steps.ts +7 -0
- package/src/server/collections/agent-loop-usage-buckets.ts +22 -22
- package/src/server/collections/agent-loop-worktrees.ts +25 -25
- package/src/server/collections/skill-executions.ts +8 -0
- package/src/server/migrations/20260427000002-change-packages-to-text.ts +52 -52
- package/src/server/migrations/20260429000000-add-llm-fields.ts +47 -47
- package/src/server/migrations/20260429000001-fix-inputargs-json-to-text.ts +45 -45
- package/src/server/migrations/20260503000000-add-orchestrator-trace-fields.ts +33 -33
- package/src/server/migrations/20260524000000-add-agent-loop-fields-to-skill-executions.ts +31 -31
- package/src/server/migrations/20260803010000-backfill-loop-control-plane-data.ts +293 -293
- package/src/server/plugin.ts +3 -1
- package/src/server/resources/agent-harness-profile.ts +94 -0
- package/src/server/resources/agent-knowledge-insights.ts +5 -3
- package/src/server/resources/agent-loop-approval.ts +32 -0
- package/src/server/resources/agent-loop-artifact.ts +56 -56
- package/src/server/resources/agent-loop-events-stream.ts +105 -105
- package/src/server/resources/agent-loop.ts +3 -1
- package/src/server/resources/resource-helpers.ts +33 -33
- package/src/server/resources/tracing.ts +266 -266
- package/src/server/services/AgentMemoryContextService.ts +44 -0
- package/src/server/services/DurableCircuitBreakerService.ts +239 -239
- package/src/server/services/ExecutionSpanService.ts +2 -0
- package/src/server/services/HarnessCompiler.ts +37 -0
- package/src/server/services/HarnessProfileService.ts +92 -10
- package/src/server/services/HarnessSchema.ts +31 -0
- package/src/server/services/LoopBudgetService.ts +275 -275
- package/src/server/services/LoopControlService.ts +124 -124
- package/src/server/services/LoopPatternSchema.ts +19 -1
- package/src/server/services/LoopPatternService.ts +143 -143
- package/src/server/services/LoopRunRepository.ts +99 -0
- package/src/server/services/LoopRunStateMachine.ts +100 -3
- package/src/server/services/LoopSchedulerService.ts +199 -199
- package/src/server/services/LoopTriggerService.ts +42 -0
- package/src/server/services/LoopWorkerService.ts +327 -27
- package/src/server/services/NativeSubAgentObserver.ts +186 -21
- package/src/server/services/PathLockService.ts +321 -321
- package/src/server/services/PluginAiRuntimeAdapter.ts +24 -7
- package/src/server/services/ToolLoopDetectionService.ts +213 -0
- package/src/server/services/VerificationSchema.ts +31 -31
- package/src/server/services/VerificationService.ts +81 -2
- package/src/server/services/harness-runtime-policy.ts +141 -0
- package/src/server/skill-hub/plugin.ts +41 -3
- package/src/server/skill-hub/services/RegistrySkillSnapshotService.ts +235 -235
- package/src/server/skill-hub/services/__tests__/RegistrySkillSnapshotService.test.ts +61 -61
- package/src/server/skill-hub/tasks/SkillExecutionTask.ts +43 -2
- package/src/server/utils/ensure-indexes.ts +96 -96
- package/src/server/utils/logging.ts +62 -62
- package/src/server/utils/loop-pattern-context.ts +20 -20
- package/dist/client-v2/214.b063f33ba044a808.js +0 -10
- package/dist/client-v2/373.f5d5292e53c4e832.js +0 -10
- package/dist/client-v2/418.58fa350f5496efd3.js +0 -10
- package/dist/client-v2/53.9a10455323390f14.js +0 -10
- package/dist/client-v2/677.a991ce0250ff5c77.js +0 -10
- package/dist/client-v2/925.e5925bf21ed68e7a.js +0 -10
- package/src/client/AIEmployeeSelect.tsx +0 -47
- package/src/client/AIEmployeesContext.tsx +0 -102
- package/src/client/RulesTab.tsx +0 -2
- package/src/client/TracingTab.tsx +0 -436
- package/src/client/skill-hub/components/ExecutionProgress.tsx +0 -51
- package/src/client-v2/components/RulesTab.tsx +0 -2
- 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
|
-
|
|
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
|
-
|
|
228
|
+
decisions: Array<{ toolCallId: string; decision: ToolCallDecision }>;
|
|
219
229
|
signal: AbortSignal;
|
|
220
230
|
}): Promise<InvocationOutcome> {
|
|
221
231
|
const plugin = this.plugin();
|
|
222
232
|
|
|
223
|
-
|
|
224
|
-
.getModel('aiToolMessages')
|
|
225
|
-
|
|
226
|
-
{
|
|
227
|
-
|
|
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
|
+
}
|