plugin-agent-orchestrator 1.1.3 → 1.1.5

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 (218) 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/253.59577b40d9875be0.js +10 -0
  6. package/dist/client-v2/264.7ed8bee71fa5935c.js +10 -0
  7. package/dist/client-v2/{41.ba6e080cc0488143.js → 41.3deb9e57a0f64fc4.js} +1 -1
  8. package/dist/client-v2/418.41ed200e7d6da332.js +10 -0
  9. package/dist/client-v2/53.349fff8db80b19d4.js +10 -0
  10. package/dist/client-v2/619.0a2144aaffefe018.js +10 -0
  11. package/dist/client-v2/{70.bda9518881c05360.js → 70.ffff2997c10fd4b0.js} +1 -1
  12. package/dist/client-v2/{794.9bbb8d3a61b2bdf2.js → 794.a67a2614405ba627.js} +1 -1
  13. package/dist/client-v2/981.e4a1f41cfc94a856.js +10 -0
  14. package/dist/client-v2/{993.82778b6fd6db3cb1.js → 993.b0688fdc5ccb000a.js} +1 -1
  15. package/dist/client-v2/index.js +1 -1
  16. package/dist/externalVersion.js +8 -7
  17. package/dist/locale/en-US.json +199 -123
  18. package/dist/locale/vi-VN.json +199 -123
  19. package/dist/locale/zh-CN.json +199 -123
  20. package/dist/server/collections/agent-execution-spans.js +55 -0
  21. package/dist/server/collections/agent-harness-profile-versions.js +56 -0
  22. package/dist/server/collections/agent-harness-profiles.js +12 -0
  23. package/dist/server/collections/agent-loop-action-approvals.js +69 -0
  24. package/dist/server/collections/agent-loop-artifacts.js +55 -0
  25. package/dist/server/collections/agent-loop-circuit-states.js +53 -0
  26. package/dist/server/collections/agent-loop-control-settings.js +51 -0
  27. package/dist/server/collections/agent-loop-events.js +27 -0
  28. package/dist/server/collections/agent-loop-path-locks.js +57 -0
  29. package/dist/server/collections/agent-loop-patterns.js +72 -0
  30. package/dist/server/collections/agent-loop-runs.js +170 -3
  31. package/dist/server/collections/agent-loop-steps.js +76 -0
  32. package/dist/server/collections/agent-loop-usage-buckets.js +52 -0
  33. package/dist/server/collections/agent-loop-worktrees.js +55 -0
  34. package/dist/server/collections/skill-executions.js +8 -0
  35. package/dist/server/migrations/{20260427000000-change-packages-to-text.js → 20260427000002-change-packages-to-text.js} +2 -0
  36. package/dist/server/migrations/20260429000000-add-llm-fields.js +3 -2
  37. package/dist/server/migrations/{20260429000000-fix-inputargs-json-to-text.js → 20260429000001-fix-inputargs-json-to-text.js} +14 -6
  38. package/dist/server/migrations/20260503000000-add-orchestrator-trace-fields.js +2 -1
  39. package/dist/server/migrations/20260524000000-add-agent-loop-fields-to-skill-executions.js +2 -1
  40. package/dist/server/migrations/20260803010000-backfill-loop-control-plane-data.js +262 -0
  41. package/dist/server/plugin.js +54 -150
  42. package/dist/server/resources/agent-harness-profile.js +117 -0
  43. package/dist/server/resources/agent-knowledge-insights.js +1 -3
  44. package/dist/server/resources/agent-loop-approval.js +108 -0
  45. package/dist/server/resources/agent-loop-artifact.js +86 -0
  46. package/dist/server/resources/agent-loop-events-stream.js +130 -0
  47. package/dist/server/resources/agent-loop.js +183 -139
  48. package/dist/server/resources/resource-helpers.js +63 -0
  49. package/dist/server/resources/tracing.js +121 -107
  50. package/dist/server/services/AgentMemoryContextService.js +34 -0
  51. package/dist/server/services/DurableCircuitBreakerService.js +229 -0
  52. package/dist/server/services/HarnessCompiler.js +175 -0
  53. package/dist/server/services/HarnessProfileService.js +233 -0
  54. package/dist/server/services/HarnessSchema.js +194 -0
  55. package/dist/server/services/LoopBudgetService.js +269 -0
  56. package/dist/server/services/LoopControlService.js +139 -0
  57. package/dist/server/services/LoopPatternSchema.js +195 -0
  58. package/dist/server/services/LoopPatternService.js +132 -0
  59. package/dist/server/services/LoopRunRepository.js +285 -0
  60. package/dist/server/services/LoopRunStateMachine.js +478 -0
  61. package/dist/server/services/LoopSchedulerService.js +193 -0
  62. package/dist/server/services/LoopTriggerService.js +165 -0
  63. package/dist/server/services/LoopWorkerService.js +699 -0
  64. package/dist/server/services/NativeSubAgentObserver.js +165 -23
  65. package/dist/server/services/PathLockService.js +288 -0
  66. package/dist/server/services/PluginAiRuntimeAdapter.js +226 -0
  67. package/dist/server/services/ToolLoopDetectionService.js +210 -0
  68. package/dist/server/services/VerificationSchema.js +59 -0
  69. package/dist/server/services/VerificationService.js +235 -0
  70. package/dist/server/services/harness-runtime-policy.js +139 -0
  71. package/dist/server/skill-hub/actions/git-import.js +13 -7
  72. package/dist/server/skill-hub/plugin.js +36 -3
  73. package/dist/server/skill-hub/services/RegistrySkillSnapshotService.js +1 -5
  74. package/dist/server/skill-hub/tasks/SkillExecutionTask.js +29 -0
  75. package/dist/server/utils/ensure-indexes.js +111 -0
  76. package/dist/server/utils/loop-pattern-context.js +56 -0
  77. package/package.json +53 -53
  78. package/src/client/ApprovalsTab.tsx +2 -0
  79. package/src/client/OrchestratorSettings.tsx +55 -0
  80. package/src/client/skill-hub/components/GitSkillImport.tsx +3 -3
  81. package/src/client/skill-hub/components/SkillMetrics.tsx +15 -10
  82. package/src/client/skill-hub/index.tsx +0 -52
  83. package/src/client-v2/components/AgentRunsTab.tsx +100 -18
  84. package/src/client-v2/components/ApprovalsTab.tsx +337 -0
  85. package/src/client-v2/components/HarnessProfilesTab.tsx +385 -100
  86. package/src/client-v2/components/MemoryInspectorTab.tsx +141 -125
  87. package/src/client-v2/components/TracingTab.tsx +160 -77
  88. package/src/client-v2/hooks/useApiRequest.ts +28 -8
  89. package/src/client-v2/pages/ApprovalsPage.tsx +10 -0
  90. package/src/client-v2/plugin.tsx +6 -6
  91. package/src/client-v2/skill-hub/components/SkillMetrics.tsx +11 -6
  92. package/src/locale/en-US.json +199 -123
  93. package/src/locale/vi-VN.json +199 -123
  94. package/src/locale/zh-CN.json +199 -123
  95. package/src/server/__tests__/circuit-breaker.test.ts +248 -169
  96. package/src/server/__tests__/harness-compiler.test.ts +214 -0
  97. package/src/server/__tests__/harness-profile-service.test.ts +167 -0
  98. package/src/server/__tests__/harness-runtime-policy.test.ts +293 -0
  99. package/src/server/__tests__/harness-tool-plan.test.ts +172 -0
  100. package/src/server/__tests__/loop-approval-decision.test.ts +512 -0
  101. package/src/server/__tests__/loop-approval-expiry.test.ts +258 -0
  102. package/src/server/__tests__/loop-budget-service.test.ts +255 -0
  103. package/src/server/__tests__/loop-control-plane-backfill.test.ts +266 -0
  104. package/src/server/__tests__/loop-pattern-schema.test.ts +73 -0
  105. package/src/server/__tests__/loop-pattern-service.test.ts +148 -0
  106. package/src/server/__tests__/loop-run-state-machine.test.ts +101 -0
  107. package/src/server/__tests__/loop-trigger-service.test.ts +148 -0
  108. package/src/server/__tests__/loop-worker-claim.test.ts +341 -0
  109. package/src/server/__tests__/loop-worker-execution.test.ts +317 -0
  110. package/src/server/__tests__/native-sub-agent-observer.test.ts +288 -4
  111. package/src/server/__tests__/path-lock-service.test.ts +254 -0
  112. package/src/server/__tests__/skill-execution-task-policy.test.ts +140 -0
  113. package/src/server/__tests__/smoke.test.ts +162 -121
  114. package/src/server/__tests__/tool-loop-detection.test.ts +275 -0
  115. package/src/server/collections/agent-execution-spans.ts +55 -0
  116. package/src/server/collections/agent-harness-profile-versions.ts +26 -0
  117. package/src/server/collections/agent-harness-profiles.ts +71 -59
  118. package/src/server/collections/agent-loop-action-approvals.ts +39 -0
  119. package/src/server/collections/agent-loop-artifacts.ts +25 -0
  120. package/src/server/collections/agent-loop-circuit-states.ts +23 -0
  121. package/src/server/collections/agent-loop-control-settings.ts +21 -0
  122. package/src/server/collections/agent-loop-events.ts +98 -71
  123. package/src/server/collections/agent-loop-path-locks.ts +27 -0
  124. package/src/server/collections/agent-loop-patterns.ts +42 -0
  125. package/src/server/collections/agent-loop-runs.ts +170 -3
  126. package/src/server/collections/agent-loop-steps.ts +76 -0
  127. package/src/server/collections/agent-loop-usage-buckets.ts +22 -0
  128. package/src/server/collections/agent-loop-worktrees.ts +25 -0
  129. package/src/server/collections/skill-executions.ts +8 -0
  130. package/src/server/migrations/{20260427000000-change-packages-to-text.ts → 20260427000002-change-packages-to-text.ts} +52 -49
  131. package/src/server/migrations/20260429000000-add-llm-fields.ts +47 -46
  132. package/src/server/migrations/{20260429000000-fix-inputargs-json-to-text.ts → 20260429000001-fix-inputargs-json-to-text.ts} +45 -38
  133. package/src/server/migrations/20260503000000-add-orchestrator-trace-fields.ts +33 -32
  134. package/src/server/migrations/20260524000000-add-agent-loop-fields-to-skill-executions.ts +31 -30
  135. package/src/server/migrations/20260803010000-backfill-loop-control-plane-data.ts +293 -0
  136. package/src/server/plugin.ts +55 -167
  137. package/src/server/resources/agent-harness-profile.ts +94 -0
  138. package/src/server/resources/agent-knowledge-insights.ts +5 -3
  139. package/src/server/resources/agent-loop-approval.ts +84 -0
  140. package/src/server/resources/agent-loop-artifact.ts +56 -0
  141. package/src/server/resources/agent-loop-events-stream.ts +105 -0
  142. package/src/server/resources/agent-loop.ts +204 -143
  143. package/src/server/resources/agent-monitor.ts +482 -482
  144. package/src/server/resources/resource-helpers.ts +33 -0
  145. package/src/server/resources/tracing.ts +266 -258
  146. package/src/server/services/AgentMemoryContextService.ts +44 -0
  147. package/src/server/services/DurableCircuitBreakerService.ts +239 -0
  148. package/src/server/services/ExecutionSpanService.ts +2 -0
  149. package/src/server/services/HarnessCompiler.ts +170 -0
  150. package/src/server/services/HarnessProfileService.ts +239 -0
  151. package/src/server/services/HarnessSchema.ts +194 -0
  152. package/src/server/services/LoopBudgetService.ts +275 -0
  153. package/src/server/services/LoopControlService.ts +124 -0
  154. package/src/server/services/LoopPatternSchema.ts +185 -0
  155. package/src/server/services/LoopPatternService.ts +143 -0
  156. package/src/server/services/LoopRunRepository.ts +336 -0
  157. package/src/server/services/LoopRunStateMachine.ts +529 -0
  158. package/src/server/services/LoopSchedulerService.ts +199 -0
  159. package/src/server/services/LoopTriggerService.ts +157 -0
  160. package/src/server/services/LoopWorkerService.ts +822 -0
  161. package/src/server/services/NativeSubAgentObserver.ts +186 -21
  162. package/src/server/services/PathLockService.ts +321 -0
  163. package/src/server/services/PluginAiRuntimeAdapter.ts +332 -0
  164. package/src/server/services/ToolLoopDetectionService.ts +213 -0
  165. package/src/server/services/VerificationSchema.ts +31 -0
  166. package/src/server/services/VerificationService.ts +264 -0
  167. package/src/server/services/harness-runtime-policy.ts +141 -0
  168. package/src/server/skill-hub/actions/__tests__/git-import.test.ts +15 -1
  169. package/src/server/skill-hub/actions/git-import.ts +9 -3
  170. package/src/server/skill-hub/plugin.ts +41 -3
  171. package/src/server/skill-hub/services/RegistrySkillSnapshotService.ts +235 -239
  172. package/src/server/skill-hub/services/__tests__/RegistrySkillSnapshotService.test.ts +61 -63
  173. package/src/server/skill-hub/tasks/SkillExecutionTask.ts +43 -2
  174. package/src/server/utils/ensure-indexes.ts +96 -0
  175. package/src/server/utils/logging.ts +62 -63
  176. package/src/server/utils/loop-pattern-context.ts +20 -0
  177. package/dist/client-v2/214.79650a549273f163.js +0 -10
  178. package/dist/client-v2/253.9f0537713cee9e6c.js +0 -10
  179. package/dist/client-v2/264.718a107e43fc163c.js +0 -10
  180. package/dist/client-v2/373.f5d5292e53c4e832.js +0 -10
  181. package/dist/client-v2/418.ce8f5b2b8a229d1d.js +0 -10
  182. package/dist/client-v2/53.7c29c28043e9112d.js +0 -10
  183. package/dist/client-v2/619.bd3c5698b40705c3.js +0 -10
  184. package/dist/client-v2/677.a991ce0250ff5c77.js +0 -10
  185. package/dist/client-v2/925.f5370de8f6632d65.js +0 -10
  186. package/dist/server/services/AgentHarness.js +0 -81
  187. package/dist/server/services/AgentLoopController.js +0 -1023
  188. package/dist/server/services/AgentLoopRepository.js +0 -192
  189. package/dist/server/services/AgentLoopService.js +0 -142
  190. package/dist/server/services/AgentPlanValidator.js +0 -99
  191. package/dist/server/services/AgentPlannerService.js +0 -99
  192. package/dist/server/services/CircuitBreaker.js +0 -125
  193. package/dist/server/services/ContextAggregator.js +0 -201
  194. package/dist/server/services/PlanningPromptService.js +0 -95
  195. package/dist/server/tools/agent-loop.js +0 -373
  196. package/dist/server/tools/orchestrator-plan.js +0 -254
  197. package/src/client/AIEmployeeSelect.tsx +0 -47
  198. package/src/client/AIEmployeesContext.tsx +0 -102
  199. package/src/client/RulesTab.tsx +0 -2
  200. package/src/client/TracingTab.tsx +0 -436
  201. package/src/client/skill-hub/components/ExecutionProgress.tsx +0 -51
  202. package/src/client-v2/components/RulesTab.tsx +0 -2
  203. package/src/client-v2/pages/AgentRunsPage.tsx +0 -13
  204. package/src/server/__tests__/agent-loop-controller.test.ts +0 -375
  205. package/src/server/__tests__/context-aggregator.test.ts +0 -222
  206. package/src/server/__tests__/parallel-execution.test.ts +0 -318
  207. package/src/server/__tests__/planning-prompt-service.test.ts +0 -23
  208. package/src/server/services/AgentHarness.ts +0 -67
  209. package/src/server/services/AgentLoopController.ts +0 -1263
  210. package/src/server/services/AgentLoopRepository.ts +0 -178
  211. package/src/server/services/AgentLoopService.ts +0 -177
  212. package/src/server/services/AgentPlanValidator.ts +0 -73
  213. package/src/server/services/AgentPlannerService.ts +0 -80
  214. package/src/server/services/CircuitBreaker.ts +0 -126
  215. package/src/server/services/ContextAggregator.ts +0 -239
  216. package/src/server/services/PlanningPromptService.ts +0 -72
  217. package/src/server/tools/agent-loop.ts +0 -360
  218. package/src/server/tools/orchestrator-plan.ts +0 -255
@@ -0,0 +1,194 @@
1
+ import { z } from 'zod';
2
+
3
+ export const toolDecisionSchema = z.enum(['allow', 'ask', 'deny']);
4
+ export const toolEffectSchema = z.enum(['read', 'write', 'external']);
5
+
6
+ const nullableLimit = z.number().finite().nonnegative().nullable().default(null);
7
+ const nullablePositiveLimit = z.number().finite().positive().nullable().default(null);
8
+
9
+ export const harnessSettingsSchema = z
10
+ .object({
11
+ tools: z
12
+ .object({
13
+ allow: z.array(z.string().min(1)).default([]),
14
+ ask: z.array(z.string().min(1)).default([]),
15
+ deny: z.array(z.string().min(1)).default([]),
16
+ // Tools the harness does not grant but may be requested for a single call: invoking one
17
+ // interrupts exactly like `ask` and parks the run, but the approval row is tagged as an
18
+ // escalation. Approving widens authority for that one call only; the harness is unchanged.
19
+ escalate: z.array(z.string().min(1)).default([]),
20
+ effects: z.record(toolEffectSchema).default({}),
21
+ trustedPreHandlerTools: z.array(z.string().min(1)).default([]),
22
+ // Per-tool wall-clock caps in milliseconds. Only enforceable where this plugin owns the
23
+ // execution pipeline (skill hub sandbox); elsewhere it is advisory observability data.
24
+ timeouts: z.record(z.number().int().positive()).default({}),
25
+ })
26
+ .default({}),
27
+ memory: z
28
+ .object({
29
+ enabled: z.boolean().default(true),
30
+ scopes: z.array(z.enum(['public', 'user', 'agent_user'])).default(['public', 'user', 'agent_user']),
31
+ maxChars: z.number().int().min(500).max(20_000).default(6000),
32
+ })
33
+ .default({}),
34
+ delegation: z
35
+ .object({
36
+ allowedEmployees: z.array(z.string().min(1)).default([]),
37
+ maxDepth: z.number().int().nonnegative().nullable().default(null),
38
+ maxCount: z.number().int().nonnegative().nullable().default(null),
39
+ })
40
+ .default({}),
41
+ limits: z
42
+ .object({
43
+ timeoutMs: nullablePositiveLimit,
44
+ recursionLimit: z.number().int().positive().nullable().default(null),
45
+ maxInvocations: z.number().int().nonnegative().nullable().default(null),
46
+ maxToolCalls: z.number().int().nonnegative().nullable().default(null),
47
+ maxInputTokens: z.number().int().nonnegative().nullable().default(null),
48
+ maxOutputTokens: z.number().int().nonnegative().nullable().default(null),
49
+ maxTotalTokens: z.number().int().nonnegative().nullable().default(null),
50
+ maxCost: nullableLimit,
51
+ })
52
+ .default({}),
53
+ context: z
54
+ .object({
55
+ spill: z
56
+ .object({
57
+ // Tool/sub-agent outputs larger than this many UTF-8 bytes are stored on disk and
58
+ // replaced inline by a head/tail preview plus a locator. null keeps everything inline.
59
+ maxInlineBytes: z.number().int().positive().nullable().default(null),
60
+ })
61
+ .default({}),
62
+ })
63
+ .default({}),
64
+ isolation: z
65
+ .object({
66
+ mode: z.enum(['none', 'worktree']).default('none'),
67
+ requireWorktree: z.boolean().default(false),
68
+ allowedConnectors: z.array(z.string().min(1)).default([]),
69
+ networkAccess: z.enum(['deny', 'restricted', 'allow']).default('restricted'),
70
+ })
71
+ .default({}),
72
+ observability: z
73
+ .object({
74
+ enabled: z.boolean().default(true),
75
+ tracingRetentionDays: z.number().int().positive().max(3650).default(30),
76
+ captureInputs: z.boolean().default(true),
77
+ captureOutputs: z.boolean().default(true),
78
+ // Scrub values whose key names look secret-bearing (KEY/SECRET/TOKEN/PASSWORD/CREDENTIAL)
79
+ // before span inputs are persisted. Defaults on: telemetry must never be the leak vector.
80
+ redactSecrets: z.boolean().default(true),
81
+ // Who span content may be shared with: full = inputs+outputs, feedback-only = outputs
82
+ // only, disabled = no span content persisted at all.
83
+ sharing: z.enum(['full', 'feedback-only', 'disabled']).default('full'),
84
+ })
85
+ .default({}),
86
+ })
87
+ .strict();
88
+
89
+ export type HarnessSettings = z.infer<typeof harnessSettingsSchema>;
90
+ export type ToolDecision = z.infer<typeof toolDecisionSchema>;
91
+ export type ToolEffect = z.infer<typeof toolEffectSchema>;
92
+
93
+ function isRecord(value: unknown): value is Record<string, unknown> {
94
+ return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
95
+ }
96
+
97
+ function stringArray(value: unknown) {
98
+ return Array.isArray(value)
99
+ ? value.filter((item): item is string => typeof item === 'string' && item.length > 0)
100
+ : [];
101
+ }
102
+
103
+ function optionalNumber(value: unknown) {
104
+ return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
105
+ }
106
+
107
+ export function normalizeHarnessSettings(value: unknown): unknown {
108
+ if (!isRecord(value)) return value;
109
+ const source = value;
110
+ const tools = isRecord(source.tools) ? source.tools : {};
111
+ const memory = isRecord(source.memory) ? source.memory : {};
112
+ const delegation = isRecord(source.delegation) ? source.delegation : {};
113
+ const limits = isRecord(source.limits) ? source.limits : {};
114
+ const context = isRecord(source.context) ? source.context : {};
115
+ const isolation = isRecord(source.isolation) ? source.isolation : {};
116
+ const observability = isRecord(source.observability) ? source.observability : {};
117
+ const knownKeys = new Set([
118
+ 'tools',
119
+ 'memory',
120
+ 'delegation',
121
+ 'limits',
122
+ 'isolation',
123
+ 'observability',
124
+ 'nativeObserverEnabled',
125
+ 'memoryInjectionEnabled',
126
+ 'memoryScopes',
127
+ 'maxMemoryContextChars',
128
+ 'maxContextChars',
129
+ 'tracingRetentionDays',
130
+ 'knowledgeScopes',
131
+ 'preferFileTools',
132
+ 'requirePlanApproval',
133
+ 'allowSubAgents',
134
+ 'allowToolCalls',
135
+ 'maxParallelSubAgents',
136
+ 'maxControllerSteps',
137
+ 'requireVerification',
138
+ ]);
139
+ const unknownSettings = Object.fromEntries(Object.entries(source).filter(([key]) => !knownKeys.has(key)));
140
+
141
+ return {
142
+ ...unknownSettings,
143
+ tools: {
144
+ ...tools,
145
+ allow: stringArray(tools.allow),
146
+ ask: stringArray(tools.ask),
147
+ deny: stringArray(tools.deny),
148
+ escalate: stringArray(tools.escalate),
149
+ effects: isRecord(tools.effects) ? tools.effects : {},
150
+ trustedPreHandlerTools: stringArray(tools.trustedPreHandlerTools),
151
+ timeouts: isRecord(tools.timeouts) ? tools.timeouts : {},
152
+ },
153
+ memory: {
154
+ ...memory,
155
+ enabled:
156
+ typeof memory.enabled === 'boolean'
157
+ ? memory.enabled
158
+ : typeof source.memoryInjectionEnabled === 'boolean'
159
+ ? source.memoryInjectionEnabled
160
+ : undefined,
161
+ scopes: Array.isArray(memory.scopes) ? memory.scopes : source.memoryScopes,
162
+ maxChars: optionalNumber(memory.maxChars) ?? optionalNumber(source.maxMemoryContextChars),
163
+ },
164
+ delegation: {
165
+ ...delegation,
166
+ allowedEmployees: stringArray(delegation.allowedEmployees),
167
+ },
168
+ limits,
169
+ context: {
170
+ ...context,
171
+ spill: isRecord(context.spill) ? context.spill : {},
172
+ },
173
+ isolation,
174
+ observability: {
175
+ ...observability,
176
+ enabled:
177
+ typeof observability.enabled === 'boolean'
178
+ ? observability.enabled
179
+ : typeof source.nativeObserverEnabled === 'boolean'
180
+ ? source.nativeObserverEnabled
181
+ : undefined,
182
+ tracingRetentionDays:
183
+ optionalNumber(observability.tracingRetentionDays) ?? optionalNumber(source.tracingRetentionDays),
184
+ },
185
+ };
186
+ }
187
+
188
+ export function parseHarnessSettings(value: unknown): HarnessSettings {
189
+ return harnessSettingsSchema.parse(normalizeHarnessSettings(value));
190
+ }
191
+
192
+ export function validateHarnessSettings(value: unknown) {
193
+ return harnessSettingsSchema.safeParse(normalizeHarnessSettings(value));
194
+ }
@@ -0,0 +1,275 @@
1
+ import type { Database, Model } from '@nocobase/database';
2
+ import type { LoopPatternPolicy } from './LoopPatternSchema';
3
+
4
+ export type UsageDelta = {
5
+ invocations?: number;
6
+ toolCalls?: number;
7
+ delegations?: number;
8
+ verifications?: number;
9
+ inputTokens?: number;
10
+ outputTokens?: number;
11
+ totalTokens?: number;
12
+ cost?: number;
13
+ };
14
+
15
+ type UsageTotals = Required<UsageDelta>;
16
+
17
+ function read(record: Model | Record<string, unknown>, key: string) {
18
+ const model = record as Model & { get?: (name: string) => unknown };
19
+ return typeof model.get === 'function' ? model.get(key) : (record as Record<string, unknown>)[key];
20
+ }
21
+
22
+ function storedCount(value: unknown, label: string) {
23
+ if (value === null || value === undefined) return 0;
24
+ const parsed = Number(value);
25
+ if (!Number.isSafeInteger(parsed) || parsed < 0) throw new Error(`${label} counter is invalid.`);
26
+ return parsed;
27
+ }
28
+
29
+ function storedCost(value: unknown, label: string) {
30
+ if (value === null || value === undefined) return 0;
31
+ const parsed = Number(value);
32
+ if (!Number.isFinite(parsed) || parsed < 0) throw new Error(`${label} counter is invalid.`);
33
+ return parsed;
34
+ }
35
+
36
+ function deltaCount(value: unknown, label: string) {
37
+ if (value === null || value === undefined) return 0;
38
+ const parsed = Number(value);
39
+ if (!Number.isSafeInteger(parsed) || parsed < 0)
40
+ throw new Error(`${label} usage delta must be a nonnegative integer.`);
41
+ return parsed;
42
+ }
43
+
44
+ function deltaCost(value: unknown) {
45
+ if (value === null || value === undefined) return 0;
46
+ const parsed = Number(value);
47
+ if (!Number.isFinite(parsed) || parsed < 0) throw new Error('Cost usage delta must be a nonnegative finite number.');
48
+ return parsed;
49
+ }
50
+
51
+ function normalizedDelta(delta: UsageDelta): UsageTotals {
52
+ const result = {
53
+ invocations: deltaCount(delta.invocations, 'Invocation'),
54
+ toolCalls: deltaCount(delta.toolCalls, 'Tool call'),
55
+ delegations: deltaCount(delta.delegations, 'Delegation'),
56
+ verifications: deltaCount(delta.verifications, 'Verification'),
57
+ inputTokens: deltaCount(delta.inputTokens, 'Input token'),
58
+ outputTokens: deltaCount(delta.outputTokens, 'Output token'),
59
+ totalTokens: deltaCount(delta.totalTokens, 'Total token'),
60
+ cost: deltaCost(delta.cost),
61
+ };
62
+ result.totalTokens = Math.max(result.totalTokens, result.inputTokens + result.outputTokens);
63
+ return result;
64
+ }
65
+
66
+ function storedLimit(value: unknown, label: string) {
67
+ if (value === null || value === undefined) return null;
68
+ const parsed = Number(value);
69
+ if (!Number.isFinite(parsed) || parsed < 0) throw new Error(`${label} limit is invalid.`);
70
+ return parsed;
71
+ }
72
+
73
+ function exceeds(current: number, delta: number, limit: number | null, label: string) {
74
+ if (limit !== null && current + delta > limit) {
75
+ throw new Error(`${label} budget exceeded: ${current} + ${delta} > ${limit}.`);
76
+ }
77
+ }
78
+
79
+ function bucketDate(date: Date) {
80
+ return date.toISOString().slice(0, 10);
81
+ }
82
+
83
+ type DistributedLock = {
84
+ runExclusive<T>(key: string, operation: () => Promise<T>, ttl?: number): Promise<T>;
85
+ };
86
+
87
+ export class LoopBudgetService {
88
+ constructor(
89
+ private readonly database: Database,
90
+ private readonly distributedLock: DistributedLock,
91
+ ) {}
92
+
93
+ async reserve(input: { runId: number; patternId: number; policy: LoopPatternPolicy; delta: UsageDelta; now?: Date }) {
94
+ if (!Number.isSafeInteger(input.runId) || input.runId <= 0) throw new Error('A valid run identifier is required.');
95
+ if (!Number.isSafeInteger(input.patternId) || input.patternId <= 0)
96
+ throw new Error('A valid pattern identifier is required.');
97
+ const delta = normalizedDelta(input.delta);
98
+ const date = bucketDate(input.now || new Date());
99
+ return this.distributedLock.runExclusive(
100
+ `agent-loop:budget:global:${date}`,
101
+ () => this.reserveInTransaction(input, delta, date),
102
+ 30_000,
103
+ );
104
+ }
105
+
106
+ private async reserveInTransaction(
107
+ input: { runId: number; patternId: number; policy: LoopPatternPolicy; delta: UsageDelta },
108
+ delta: UsageTotals,
109
+ date: string,
110
+ ) {
111
+ return this.database.sequelize.transaction(async (transaction) => {
112
+ const controls = this.database.getRepository('agentLoopControlSettings');
113
+ const control = await controls.findOne({
114
+ filter: { key: 'global' },
115
+ transaction,
116
+ lock: transaction.LOCK.UPDATE,
117
+ });
118
+ if (!control) throw new Error('Global Loop Control settings were not found.');
119
+ if (String(read(control, 'state')) !== 'running') {
120
+ throw new Error(String(read(control, 'reason') || 'Loop Control Plane is not running.'));
121
+ }
122
+
123
+ const runs = this.database.getRepository('agentLoopRuns');
124
+ const run = await runs.findOne({
125
+ filterByTk: input.runId,
126
+ transaction,
127
+ lock: transaction.LOCK.UPDATE,
128
+ });
129
+ if (!run) throw new Error(`Agent loop run ${input.runId} was not found.`);
130
+ if (String(read(run, 'runtimeVersion')) !== 'control-plane-v2') {
131
+ throw new Error('Historical plan-era runs cannot consume Loop Control Plane budgets.');
132
+ }
133
+ if (Number(read(run, 'patternId')) !== input.patternId) {
134
+ throw new Error(`Agent loop run ${input.runId} does not belong to pattern ${input.patternId}.`);
135
+ }
136
+
137
+ const buckets = this.database.getRepository('agentLoopUsageBuckets');
138
+ let bucket = await buckets.findOne({
139
+ filter: { patternId: input.patternId, bucketDate: date },
140
+ transaction,
141
+ lock: transaction.LOCK.UPDATE,
142
+ });
143
+ if (!bucket) {
144
+ bucket = await buckets.create({
145
+ values: { patternId: input.patternId, bucketDate: date },
146
+ transaction,
147
+ });
148
+ }
149
+ const dailyBuckets = await buckets.find({
150
+ filter: { bucketDate: date },
151
+ transaction,
152
+ lock: transaction.LOCK.UPDATE,
153
+ });
154
+
155
+ this.assertRunBudget(run, input.policy, delta);
156
+ this.assertDailyBudget(bucket, input.policy, delta);
157
+ this.assertGlobalDailyBudget(dailyBuckets, control, delta);
158
+ await runs.update({
159
+ filterByTk: input.runId,
160
+ values: {
161
+ invocationCount: storedCount(read(run, 'invocationCount'), 'Run invocation') + delta.invocations,
162
+ toolCallCount: storedCount(read(run, 'toolCallCount'), 'Run tool call') + delta.toolCalls,
163
+ delegationCount: storedCount(read(run, 'delegationCount'), 'Run delegation') + delta.delegations,
164
+ verificationCount: storedCount(read(run, 'verificationCount'), 'Run verification') + delta.verifications,
165
+ totalInputTokens: storedCount(read(run, 'totalInputTokens'), 'Run input token') + delta.inputTokens,
166
+ totalOutputTokens: storedCount(read(run, 'totalOutputTokens'), 'Run output token') + delta.outputTokens,
167
+ totalTokens: storedCount(read(run, 'totalTokens'), 'Run total token') + delta.totalTokens,
168
+ totalCost: storedCost(read(run, 'totalCost'), 'Run cost') + delta.cost,
169
+ },
170
+ transaction,
171
+ });
172
+ await buckets.update({
173
+ filterByTk: read(bucket, 'id'),
174
+ values: {
175
+ invocationCount: storedCount(read(bucket, 'invocationCount'), 'Daily invocation') + delta.invocations,
176
+ toolCallCount: storedCount(read(bucket, 'toolCallCount'), 'Daily tool call') + delta.toolCalls,
177
+ delegationCount: storedCount(read(bucket, 'delegationCount'), 'Daily delegation') + delta.delegations,
178
+ inputTokens: storedCount(read(bucket, 'inputTokens'), 'Daily input token') + delta.inputTokens,
179
+ outputTokens: storedCount(read(bucket, 'outputTokens'), 'Daily output token') + delta.outputTokens,
180
+ totalTokens: storedCount(read(bucket, 'totalTokens'), 'Daily total token') + delta.totalTokens,
181
+ totalCost: storedCost(read(bucket, 'totalCost'), 'Daily cost') + delta.cost,
182
+ },
183
+ transaction,
184
+ });
185
+ return { reserved: delta, bucketDate: date };
186
+ });
187
+ }
188
+
189
+ private assertRunBudget(run: Model, policy: LoopPatternPolicy, delta: UsageTotals) {
190
+ const limits = policy.perRun;
191
+ exceeds(
192
+ storedCount(read(run, 'invocationCount'), 'Run invocation'),
193
+ delta.invocations,
194
+ limits.maxInvocations,
195
+ 'Per-run invocation',
196
+ );
197
+ exceeds(
198
+ storedCount(read(run, 'toolCallCount'), 'Run tool call'),
199
+ delta.toolCalls,
200
+ limits.maxToolCalls,
201
+ 'Per-run tool call',
202
+ );
203
+ exceeds(
204
+ storedCount(read(run, 'delegationCount'), 'Run delegation'),
205
+ delta.delegations,
206
+ limits.maxDelegations,
207
+ 'Per-run delegation',
208
+ );
209
+ exceeds(
210
+ storedCount(read(run, 'verificationCount'), 'Run verification'),
211
+ delta.verifications,
212
+ limits.maxVerifications,
213
+ 'Per-run verification',
214
+ );
215
+ exceeds(
216
+ storedCount(read(run, 'totalTokens'), 'Run total token'),
217
+ delta.totalTokens,
218
+ limits.maxTokens,
219
+ 'Per-run token',
220
+ );
221
+ exceeds(storedCost(read(run, 'totalCost'), 'Run cost'), delta.cost, limits.maxCost, 'Per-run cost');
222
+ }
223
+
224
+ private assertDailyBudget(bucket: Model, policy: LoopPatternPolicy, delta: UsageTotals) {
225
+ const limits = policy.daily;
226
+ exceeds(
227
+ storedCount(read(bucket, 'invocationCount'), 'Daily invocation'),
228
+ delta.invocations,
229
+ limits.maxInvocations,
230
+ 'Daily invocation',
231
+ );
232
+ exceeds(
233
+ storedCount(read(bucket, 'toolCallCount'), 'Daily tool call'),
234
+ delta.toolCalls,
235
+ limits.maxToolCalls,
236
+ 'Daily tool call',
237
+ );
238
+ exceeds(
239
+ storedCount(read(bucket, 'delegationCount'), 'Daily delegation'),
240
+ delta.delegations,
241
+ limits.maxDelegations,
242
+ 'Daily delegation',
243
+ );
244
+ exceeds(
245
+ storedCount(read(bucket, 'totalTokens'), 'Daily total token'),
246
+ delta.totalTokens,
247
+ limits.maxTokens,
248
+ 'Daily token',
249
+ );
250
+ exceeds(storedCost(read(bucket, 'totalCost'), 'Daily cost'), delta.cost, limits.maxCost, 'Daily cost');
251
+ }
252
+
253
+ private assertGlobalDailyBudget(buckets: Model[], control: Model, delta: UsageTotals) {
254
+ const currentTokens = buckets.reduce(
255
+ (total, bucket) => total + storedCount(read(bucket, 'totalTokens'), 'Daily total token'),
256
+ 0,
257
+ );
258
+ const currentCost = buckets.reduce(
259
+ (total, bucket) => total + storedCost(read(bucket, 'totalCost'), 'Daily cost'),
260
+ 0,
261
+ );
262
+ exceeds(
263
+ currentTokens,
264
+ delta.totalTokens,
265
+ storedLimit(read(control, 'dailyMaxTokens'), 'Global daily token'),
266
+ 'Global daily token',
267
+ );
268
+ exceeds(
269
+ currentCost,
270
+ delta.cost,
271
+ storedLimit(read(control, 'dailyMaxCost'), 'Global daily cost'),
272
+ 'Global daily cost',
273
+ );
274
+ }
275
+ }
@@ -0,0 +1,124 @@
1
+ import type { Database, Model, Transaction } from '@nocobase/database';
2
+
3
+ export type LoopControlState = 'running' | 'paused' | 'killed';
4
+
5
+ export type LoopControlSnapshot = {
6
+ id: number;
7
+ acceptNewRuns: boolean;
8
+ state: LoopControlState;
9
+ reason: string;
10
+ globalMaxConcurrency: number;
11
+ dailyMaxTokens: number | null;
12
+ dailyMaxCost: number | null;
13
+ };
14
+
15
+ function read(record: Model | Record<string, unknown>, key: string) {
16
+ const model = record as Model & { get?: (name: string) => unknown };
17
+ return typeof model.get === 'function' ? model.get(key) : (record as Record<string, unknown>)[key];
18
+ }
19
+
20
+ function optionalLimit(value: unknown, label: string) {
21
+ if (value === null || value === undefined) return null;
22
+ const parsed = Number(value);
23
+ if (!Number.isFinite(parsed) || parsed < 0) throw new Error(`${label} is invalid.`);
24
+ return parsed;
25
+ }
26
+
27
+ function snapshot(record: Model | Record<string, unknown>): LoopControlSnapshot {
28
+ const id = Number(read(record, 'id'));
29
+ const state = read(record, 'state');
30
+ const maxConcurrency = Number(read(record, 'globalMaxConcurrency'));
31
+ if (!Number.isSafeInteger(id) || id <= 0) throw new Error('Global Loop Control settings have an invalid identifier.');
32
+ if (state !== 'running' && state !== 'paused' && state !== 'killed') {
33
+ throw new Error('Global Loop Control state is invalid.');
34
+ }
35
+ if (!Number.isSafeInteger(maxConcurrency) || maxConcurrency <= 0) {
36
+ throw new Error('Global Loop Control concurrency is invalid.');
37
+ }
38
+ return {
39
+ id,
40
+ acceptNewRuns: read(record, 'acceptNewRuns') === true,
41
+ state,
42
+ reason: typeof read(record, 'reason') === 'string' ? String(read(record, 'reason')) : '',
43
+ globalMaxConcurrency: maxConcurrency,
44
+ dailyMaxTokens: optionalLimit(read(record, 'dailyMaxTokens'), 'Global daily token limit'),
45
+ dailyMaxCost: optionalLimit(read(record, 'dailyMaxCost'), 'Global daily cost limit'),
46
+ };
47
+ }
48
+
49
+ export class LoopControlService {
50
+ constructor(private readonly database: Database) {}
51
+
52
+ async get(transaction?: Transaction) {
53
+ const repository = this.database.getRepository('agentLoopControlSettings');
54
+ let record = await repository.findOne({ filter: { key: 'global' }, transaction });
55
+ if (!record) {
56
+ record = await repository.create({
57
+ values: {
58
+ key: 'global',
59
+ acceptNewRuns: true,
60
+ state: 'running',
61
+ globalMaxConcurrency: 5,
62
+ createdAt: new Date(),
63
+ updatedAt: new Date(),
64
+ },
65
+ transaction,
66
+ });
67
+ }
68
+ return snapshot(record);
69
+ }
70
+
71
+ async getForUpdate(transaction: Transaction) {
72
+ const repository = this.database.getRepository('agentLoopControlSettings');
73
+ const record = await repository.findOne({
74
+ filter: { key: 'global' },
75
+ transaction,
76
+ lock: transaction.LOCK.UPDATE,
77
+ });
78
+ if (!record) throw new Error('Global Loop Control settings were not found.');
79
+ return snapshot(record);
80
+ }
81
+
82
+ async assertCanEnqueue(transaction?: Transaction) {
83
+ const control = await this.get(transaction);
84
+ if (!control.acceptNewRuns || control.state !== 'running') {
85
+ throw new Error(control.reason || `Loop Control Plane is ${control.state}; new runs are disabled.`);
86
+ }
87
+ return control;
88
+ }
89
+
90
+ async assertCanExecute(transaction?: Transaction) {
91
+ const control = await this.get(transaction);
92
+ if (control.state !== 'running') {
93
+ throw new Error(control.reason || `Loop Control Plane is ${control.state}.`);
94
+ }
95
+ return control;
96
+ }
97
+
98
+ async update(input: { state: LoopControlState; acceptNewRuns: boolean; reason: string; changedById?: number }) {
99
+ return this.database.sequelize.transaction(async (transaction) => {
100
+ const repository = this.database.getRepository('agentLoopControlSettings');
101
+ const current = await this.get(transaction);
102
+ const record = await repository.findOne({
103
+ filterByTk: current.id,
104
+ transaction,
105
+ lock: transaction.LOCK.UPDATE,
106
+ });
107
+ if (!record) throw new Error('Global Loop Control settings were not found.');
108
+ await repository.update({
109
+ filterByTk: current.id,
110
+ values: {
111
+ state: input.state,
112
+ acceptNewRuns: input.acceptNewRuns,
113
+ reason: input.reason,
114
+ changedById: input.changedById || null,
115
+ changedAt: new Date(),
116
+ },
117
+ transaction,
118
+ });
119
+ const updated = await repository.findOne({ filterByTk: current.id, transaction });
120
+ if (!updated) throw new Error('Global Loop Control settings were not found after update.');
121
+ return snapshot(updated);
122
+ });
123
+ }
124
+ }