plugin-agent-orchestrator 1.1.4 → 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 (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
@@ -1,321 +1,321 @@
1
- import type { Database, Model, Transaction } from '@nocobase/database';
2
-
3
- type DistributedLock = {
4
- runExclusive<T>(key: string, operation: () => Promise<T>, ttl?: number): Promise<T>;
5
- };
6
-
7
- type PathLockRow = {
8
- id: number;
9
- runId: number;
10
- repositoryKey: string;
11
- paths: string[];
12
- status: 'waiting' | 'held' | 'released' | 'expired';
13
- blockerRunIds: number[];
14
- };
15
-
16
- export type PathLockAcquisition =
17
- | { acquired: true; lock: PathLockRow; blockers: number[] }
18
- | { acquired: false; deadlocked: boolean; blockers: number[] };
19
-
20
- function read(record: Model | Record<string, unknown>, key: string) {
21
- const model = record as Model & { get?: (name: string) => unknown };
22
- return typeof model.get === 'function' ? model.get(key) : (record as Record<string, unknown>)[key];
23
- }
24
-
25
- function positiveInteger(value: unknown) {
26
- const parsed = Number(value);
27
- return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : null;
28
- }
29
-
30
- function asDate(value: unknown): Date | null {
31
- if (value instanceof Date) return Number.isNaN(value.getTime()) ? null : value;
32
- if (typeof value === 'string' || typeof value === 'number') {
33
- const parsed = new Date(value);
34
- return Number.isNaN(parsed.getTime()) ? null : parsed;
35
- }
36
- return null;
37
- }
38
-
39
- // A held lock without a readable expiry is treated as expired: a crashed worker must never
40
- // leave a row that blocks every later run forever.
41
- function lockIsExpired(record: Model | Record<string, unknown>, now: Date) {
42
- const expiresAt = asDate(read(record, 'expiresAt'));
43
- return !expiresAt || expiresAt.getTime() <= now.getTime();
44
- }
45
-
46
- function positiveTtl(ttlMs: number) {
47
- if (!Number.isSafeInteger(ttlMs) || ttlMs <= 0) {
48
- throw new Error('Path lock TTL must be a positive number of milliseconds.');
49
- }
50
- return ttlMs;
51
- }
52
-
53
- export function normalizeLockPath(value: string) {
54
- const normalized = value
55
- .trim()
56
- .replace(/\\/g, '/')
57
- .replace(/^\.\//, '')
58
- .replace(/\/{2,}/g, '/');
59
- if (!normalized || normalized.startsWith('/') || /^[a-zA-Z]:\//.test(normalized)) {
60
- throw new Error(`Lock path must be repository-relative: ${value}`);
61
- }
62
- const segments = normalized.split('/');
63
- if (segments.some((segment) => segment === '..' || segment === '.')) {
64
- throw new Error(`Lock path cannot contain dot segments: ${value}`);
65
- }
66
- return normalized.replace(/\/$/, '');
67
- }
68
-
69
- function literalPrefix(pattern: string) {
70
- const result: string[] = [];
71
- for (const segment of normalizeLockPath(pattern).split('/')) {
72
- if (/[*?{[\]]/.test(segment)) break;
73
- result.push(segment);
74
- }
75
- return result;
76
- }
77
-
78
- export function lockPathsOverlap(left: string, right: string) {
79
- const leftNormalized = normalizeLockPath(left);
80
- const rightNormalized = normalizeLockPath(right);
81
- if (leftNormalized === rightNormalized) return true;
82
-
83
- const leftPrefix = literalPrefix(leftNormalized);
84
- const rightPrefix = literalPrefix(rightNormalized);
85
- if (leftPrefix.length === 0 || rightPrefix.length === 0) return true;
86
- const shared = Math.min(leftPrefix.length, rightPrefix.length);
87
- for (let index = 0; index < shared; index += 1) {
88
- if (leftPrefix[index] !== rightPrefix[index]) return false;
89
- }
90
-
91
- const leftHasPattern = leftPrefix.length < leftNormalized.split('/').length;
92
- const rightHasPattern = rightPrefix.length < rightNormalized.split('/').length;
93
- if (leftHasPattern || rightHasPattern) return true;
94
- return leftPrefix.length !== rightPrefix.length;
95
- }
96
-
97
- export function pathSetsOverlap(left: string[], right: string[]) {
98
- return left.some((leftPath) => right.some((rightPath) => lockPathsOverlap(leftPath, rightPath)));
99
- }
100
-
101
- function row(record: Model | Record<string, unknown>): PathLockRow {
102
- const status = read(record, 'status');
103
- return {
104
- id: positiveInteger(read(record, 'id')) || 0,
105
- runId: positiveInteger(read(record, 'runId')) || 0,
106
- repositoryKey: String(read(record, 'repositoryKey') || ''),
107
- paths: Array.isArray(read(record, 'paths')) ? (read(record, 'paths') as string[]) : [],
108
- status: status === 'held' || status === 'released' || status === 'expired' ? status : 'waiting',
109
- blockerRunIds: Array.isArray(read(record, 'blockerRunIds'))
110
- ? (read(record, 'blockerRunIds') as unknown[])
111
- .map(positiveInteger)
112
- .filter((value): value is number => value !== null)
113
- : [],
114
- };
115
- }
116
-
117
- export function waitGraphHasCycle(rows: PathLockRow[], runId: number, blockers: number[]) {
118
- const graph = new Map<number, number[]>();
119
- for (const lock of rows) {
120
- if (lock.status === 'waiting') graph.set(lock.runId, lock.blockerRunIds);
121
- }
122
- graph.set(runId, blockers);
123
- const visiting = new Set<number>();
124
- const visited = new Set<number>();
125
-
126
- const visit = (node: number): boolean => {
127
- if (visiting.has(node)) return true;
128
- if (visited.has(node)) return false;
129
- visiting.add(node);
130
- for (const blocker of graph.get(node) || []) {
131
- if (visit(blocker)) return true;
132
- }
133
- visiting.delete(node);
134
- visited.add(node);
135
- return false;
136
- };
137
-
138
- return visit(runId);
139
- }
140
-
141
- export class PathLockService {
142
- constructor(
143
- private readonly database: Database,
144
- private readonly distributedLock: DistributedLock,
145
- ) {}
146
-
147
- async acquire(input: {
148
- runId: number;
149
- repositoryKey: string;
150
- owner: string;
151
- paths: string[];
152
- ttlMs: number;
153
- waitUntil?: Date;
154
- }): Promise<PathLockAcquisition> {
155
- const paths = Array.from(new Set(input.paths.map(normalizeLockPath))).sort();
156
- if (!paths.length) throw new Error('At least one repository path is required for a path lock.');
157
- const repositoryKey = input.repositoryKey.trim();
158
- if (!repositoryKey) throw new Error('Repository key is required for a path lock.');
159
- const ttlMs = positiveTtl(input.ttlMs);
160
-
161
- return this.distributedLock.runExclusive(
162
- `agent-loop:path:${repositoryKey}`,
163
- () =>
164
- this.database.sequelize.transaction(async (transaction) => {
165
- const repository = this.database.getRepository('agentLoopPathLocks');
166
- const now = new Date();
167
- const existing = await repository.findOne({
168
- filter: { runId: input.runId, repositoryKey },
169
- transaction,
170
- lock: transaction.LOCK.UPDATE,
171
- });
172
- if (existing && read(existing, 'status') === 'held') {
173
- const sameOwner = String(read(existing, 'owner') || '') === input.owner;
174
- const samePaths = JSON.stringify(row(existing).paths.slice().sort()) === JSON.stringify(paths);
175
- if (sameOwner && samePaths && !lockIsExpired(existing, now)) {
176
- return { acquired: true, lock: row(existing), blockers: [] as number[] };
177
- }
178
- }
179
-
180
- const held = await repository.find({
181
- filter: { repositoryKey, status: 'held' },
182
- transaction,
183
- lock: transaction.LOCK.UPDATE,
184
- });
185
- const active: typeof held = [];
186
- for (const lock of held) {
187
- if (!lockIsExpired(lock, now)) {
188
- active.push(lock);
189
- continue;
190
- }
191
- await repository.update({
192
- filterByTk: read(lock, 'id'),
193
- values: { status: 'expired', releasedAt: now, blockerRunIds: [] },
194
- transaction,
195
- });
196
- }
197
- const blockers = active
198
- .map(row)
199
- .filter((lock) => lock.runId !== input.runId && pathSetsOverlap(paths, lock.paths))
200
- .map((lock) => lock.runId);
201
-
202
- if (blockers.length) {
203
- const waitingRows = (
204
- await repository.find({
205
- filter: { repositoryKey, status: 'waiting' },
206
- transaction,
207
- lock: transaction.LOCK.UPDATE,
208
- })
209
- ).map(row);
210
- if (waitGraphHasCycle(waitingRows, input.runId, blockers)) {
211
- return { acquired: false, deadlocked: true, blockers };
212
- }
213
- const values = {
214
- runId: input.runId,
215
- repositoryKey,
216
- owner: input.owner,
217
- paths,
218
- status: 'waiting',
219
- blockerRunIds: blockers,
220
- waitUntil: input.waitUntil || null,
221
- acquiredAt: null,
222
- expiresAt: null,
223
- releasedAt: null,
224
- };
225
- if (existing) {
226
- await repository.update({ filterByTk: read(existing, 'id'), values, transaction });
227
- } else {
228
- await repository.create({ values, transaction });
229
- }
230
- return { acquired: false, deadlocked: false, blockers };
231
- }
232
-
233
- const values = {
234
- runId: input.runId,
235
- repositoryKey,
236
- owner: input.owner,
237
- paths,
238
- status: 'held',
239
- blockerRunIds: [],
240
- acquiredAt: now,
241
- expiresAt: new Date(now.getTime() + ttlMs),
242
- waitUntil: null,
243
- releasedAt: null,
244
- };
245
- const locked = existing
246
- ? await this.updateAndRead(repository, Number(read(existing, 'id')), values, transaction)
247
- : await repository.create({ values, transaction });
248
- return { acquired: true, lock: row(locked), blockers: [] as number[] };
249
- }),
250
- Math.max(ttlMs, 5000),
251
- );
252
- }
253
-
254
- async renew(runId: number, repositoryKey: string, ttlMs: number, owner?: string) {
255
- const ttl = positiveTtl(ttlMs);
256
- return this.distributedLock.runExclusive(`agent-loop:path:${repositoryKey}`, async () => {
257
- const repository = this.database.getRepository('agentLoopPathLocks');
258
- // An expired lock is marked `expired` in its own committed transaction. Doing the audit
259
- // write inside the renew transaction and then throwing would roll the mark back, leaving a
260
- // stale `held` row that still reads as expired to the next acquirer but never audits it.
261
- const expired = await this.database.sequelize.transaction(async (transaction) => {
262
- const lock = await repository.findOne({
263
- filter: { runId, repositoryKey, status: 'held' },
264
- transaction,
265
- lock: transaction.LOCK.UPDATE,
266
- });
267
- if (!lock) throw new Error('Held path lock was not found.');
268
- if (owner !== undefined && String(read(lock, 'owner') || '') !== owner) {
269
- throw new Error('Path lock is no longer owned by this worker.');
270
- }
271
- const now = new Date();
272
- if (lockIsExpired(lock, now)) return { id: read(lock, 'id'), at: now };
273
- await repository.update({
274
- filterByTk: read(lock, 'id'),
275
- values: { expiresAt: new Date(now.getTime() + ttl) },
276
- transaction,
277
- });
278
- return null;
279
- });
280
-
281
- if (expired) {
282
- await this.database.sequelize.transaction(async (transaction) => {
283
- await repository.update({
284
- filterByTk: expired.id,
285
- values: { status: 'expired', releasedAt: expired.at, blockerRunIds: [] },
286
- transaction,
287
- });
288
- });
289
- throw new Error('Path lock has expired and must be reacquired.');
290
- }
291
- });
292
- }
293
-
294
- // The owner token guards against a reclaimed run: once a stale worker's lease expires and another
295
- // worker takes over the same run, the original worker must not free a lock the new owner now holds.
296
- async release(runId: number, repositoryKey: string, owner?: string) {
297
- return this.distributedLock.runExclusive(`agent-loop:path:${repositoryKey}`, async () => {
298
- const repository = this.database.getRepository('agentLoopPathLocks');
299
- const lock = await repository.findOne({ filter: { runId, repositoryKey } });
300
- if (!lock || ['released', 'expired'].includes(String(read(lock, 'status')))) return false;
301
- if (owner !== undefined && String(read(lock, 'owner') || '') !== owner) return false;
302
- await repository.update({
303
- filterByTk: read(lock, 'id'),
304
- values: { status: 'released', releasedAt: new Date(), blockerRunIds: [] },
305
- });
306
- return true;
307
- });
308
- }
309
-
310
- private async updateAndRead(
311
- repository: ReturnType<Database['getRepository']>,
312
- id: number,
313
- values: Record<string, unknown>,
314
- transaction: Transaction,
315
- ) {
316
- await repository.update({ filterByTk: id, values, transaction });
317
- const updated = await repository.findOne({ filterByTk: id, transaction });
318
- if (!updated) throw new Error('Path lock disappeared during update.');
319
- return updated;
320
- }
321
- }
1
+ import type { Database, Model, Transaction } from '@nocobase/database';
2
+
3
+ type DistributedLock = {
4
+ runExclusive<T>(key: string, operation: () => Promise<T>, ttl?: number): Promise<T>;
5
+ };
6
+
7
+ type PathLockRow = {
8
+ id: number;
9
+ runId: number;
10
+ repositoryKey: string;
11
+ paths: string[];
12
+ status: 'waiting' | 'held' | 'released' | 'expired';
13
+ blockerRunIds: number[];
14
+ };
15
+
16
+ export type PathLockAcquisition =
17
+ | { acquired: true; lock: PathLockRow; blockers: number[] }
18
+ | { acquired: false; deadlocked: boolean; blockers: number[] };
19
+
20
+ function read(record: Model | Record<string, unknown>, key: string) {
21
+ const model = record as Model & { get?: (name: string) => unknown };
22
+ return typeof model.get === 'function' ? model.get(key) : (record as Record<string, unknown>)[key];
23
+ }
24
+
25
+ function positiveInteger(value: unknown) {
26
+ const parsed = Number(value);
27
+ return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : null;
28
+ }
29
+
30
+ function asDate(value: unknown): Date | null {
31
+ if (value instanceof Date) return Number.isNaN(value.getTime()) ? null : value;
32
+ if (typeof value === 'string' || typeof value === 'number') {
33
+ const parsed = new Date(value);
34
+ return Number.isNaN(parsed.getTime()) ? null : parsed;
35
+ }
36
+ return null;
37
+ }
38
+
39
+ // A held lock without a readable expiry is treated as expired: a crashed worker must never
40
+ // leave a row that blocks every later run forever.
41
+ function lockIsExpired(record: Model | Record<string, unknown>, now: Date) {
42
+ const expiresAt = asDate(read(record, 'expiresAt'));
43
+ return !expiresAt || expiresAt.getTime() <= now.getTime();
44
+ }
45
+
46
+ function positiveTtl(ttlMs: number) {
47
+ if (!Number.isSafeInteger(ttlMs) || ttlMs <= 0) {
48
+ throw new Error('Path lock TTL must be a positive number of milliseconds.');
49
+ }
50
+ return ttlMs;
51
+ }
52
+
53
+ export function normalizeLockPath(value: string) {
54
+ const normalized = value
55
+ .trim()
56
+ .replace(/\\/g, '/')
57
+ .replace(/^\.\//, '')
58
+ .replace(/\/{2,}/g, '/');
59
+ if (!normalized || normalized.startsWith('/') || /^[a-zA-Z]:\//.test(normalized)) {
60
+ throw new Error(`Lock path must be repository-relative: ${value}`);
61
+ }
62
+ const segments = normalized.split('/');
63
+ if (segments.some((segment) => segment === '..' || segment === '.')) {
64
+ throw new Error(`Lock path cannot contain dot segments: ${value}`);
65
+ }
66
+ return normalized.replace(/\/$/, '');
67
+ }
68
+
69
+ function literalPrefix(pattern: string) {
70
+ const result: string[] = [];
71
+ for (const segment of normalizeLockPath(pattern).split('/')) {
72
+ if (/[*?{[\]]/.test(segment)) break;
73
+ result.push(segment);
74
+ }
75
+ return result;
76
+ }
77
+
78
+ export function lockPathsOverlap(left: string, right: string) {
79
+ const leftNormalized = normalizeLockPath(left);
80
+ const rightNormalized = normalizeLockPath(right);
81
+ if (leftNormalized === rightNormalized) return true;
82
+
83
+ const leftPrefix = literalPrefix(leftNormalized);
84
+ const rightPrefix = literalPrefix(rightNormalized);
85
+ if (leftPrefix.length === 0 || rightPrefix.length === 0) return true;
86
+ const shared = Math.min(leftPrefix.length, rightPrefix.length);
87
+ for (let index = 0; index < shared; index += 1) {
88
+ if (leftPrefix[index] !== rightPrefix[index]) return false;
89
+ }
90
+
91
+ const leftHasPattern = leftPrefix.length < leftNormalized.split('/').length;
92
+ const rightHasPattern = rightPrefix.length < rightNormalized.split('/').length;
93
+ if (leftHasPattern || rightHasPattern) return true;
94
+ return leftPrefix.length !== rightPrefix.length;
95
+ }
96
+
97
+ export function pathSetsOverlap(left: string[], right: string[]) {
98
+ return left.some((leftPath) => right.some((rightPath) => lockPathsOverlap(leftPath, rightPath)));
99
+ }
100
+
101
+ function row(record: Model | Record<string, unknown>): PathLockRow {
102
+ const status = read(record, 'status');
103
+ return {
104
+ id: positiveInteger(read(record, 'id')) || 0,
105
+ runId: positiveInteger(read(record, 'runId')) || 0,
106
+ repositoryKey: String(read(record, 'repositoryKey') || ''),
107
+ paths: Array.isArray(read(record, 'paths')) ? (read(record, 'paths') as string[]) : [],
108
+ status: status === 'held' || status === 'released' || status === 'expired' ? status : 'waiting',
109
+ blockerRunIds: Array.isArray(read(record, 'blockerRunIds'))
110
+ ? (read(record, 'blockerRunIds') as unknown[])
111
+ .map(positiveInteger)
112
+ .filter((value): value is number => value !== null)
113
+ : [],
114
+ };
115
+ }
116
+
117
+ export function waitGraphHasCycle(rows: PathLockRow[], runId: number, blockers: number[]) {
118
+ const graph = new Map<number, number[]>();
119
+ for (const lock of rows) {
120
+ if (lock.status === 'waiting') graph.set(lock.runId, lock.blockerRunIds);
121
+ }
122
+ graph.set(runId, blockers);
123
+ const visiting = new Set<number>();
124
+ const visited = new Set<number>();
125
+
126
+ const visit = (node: number): boolean => {
127
+ if (visiting.has(node)) return true;
128
+ if (visited.has(node)) return false;
129
+ visiting.add(node);
130
+ for (const blocker of graph.get(node) || []) {
131
+ if (visit(blocker)) return true;
132
+ }
133
+ visiting.delete(node);
134
+ visited.add(node);
135
+ return false;
136
+ };
137
+
138
+ return visit(runId);
139
+ }
140
+
141
+ export class PathLockService {
142
+ constructor(
143
+ private readonly database: Database,
144
+ private readonly distributedLock: DistributedLock,
145
+ ) {}
146
+
147
+ async acquire(input: {
148
+ runId: number;
149
+ repositoryKey: string;
150
+ owner: string;
151
+ paths: string[];
152
+ ttlMs: number;
153
+ waitUntil?: Date;
154
+ }): Promise<PathLockAcquisition> {
155
+ const paths = Array.from(new Set(input.paths.map(normalizeLockPath))).sort();
156
+ if (!paths.length) throw new Error('At least one repository path is required for a path lock.');
157
+ const repositoryKey = input.repositoryKey.trim();
158
+ if (!repositoryKey) throw new Error('Repository key is required for a path lock.');
159
+ const ttlMs = positiveTtl(input.ttlMs);
160
+
161
+ return this.distributedLock.runExclusive(
162
+ `agent-loop:path:${repositoryKey}`,
163
+ () =>
164
+ this.database.sequelize.transaction(async (transaction) => {
165
+ const repository = this.database.getRepository('agentLoopPathLocks');
166
+ const now = new Date();
167
+ const existing = await repository.findOne({
168
+ filter: { runId: input.runId, repositoryKey },
169
+ transaction,
170
+ lock: transaction.LOCK.UPDATE,
171
+ });
172
+ if (existing && read(existing, 'status') === 'held') {
173
+ const sameOwner = String(read(existing, 'owner') || '') === input.owner;
174
+ const samePaths = JSON.stringify(row(existing).paths.slice().sort()) === JSON.stringify(paths);
175
+ if (sameOwner && samePaths && !lockIsExpired(existing, now)) {
176
+ return { acquired: true, lock: row(existing), blockers: [] as number[] };
177
+ }
178
+ }
179
+
180
+ const held = await repository.find({
181
+ filter: { repositoryKey, status: 'held' },
182
+ transaction,
183
+ lock: transaction.LOCK.UPDATE,
184
+ });
185
+ const active: typeof held = [];
186
+ for (const lock of held) {
187
+ if (!lockIsExpired(lock, now)) {
188
+ active.push(lock);
189
+ continue;
190
+ }
191
+ await repository.update({
192
+ filterByTk: read(lock, 'id'),
193
+ values: { status: 'expired', releasedAt: now, blockerRunIds: [] },
194
+ transaction,
195
+ });
196
+ }
197
+ const blockers = active
198
+ .map(row)
199
+ .filter((lock) => lock.runId !== input.runId && pathSetsOverlap(paths, lock.paths))
200
+ .map((lock) => lock.runId);
201
+
202
+ if (blockers.length) {
203
+ const waitingRows = (
204
+ await repository.find({
205
+ filter: { repositoryKey, status: 'waiting' },
206
+ transaction,
207
+ lock: transaction.LOCK.UPDATE,
208
+ })
209
+ ).map(row);
210
+ if (waitGraphHasCycle(waitingRows, input.runId, blockers)) {
211
+ return { acquired: false, deadlocked: true, blockers };
212
+ }
213
+ const values = {
214
+ runId: input.runId,
215
+ repositoryKey,
216
+ owner: input.owner,
217
+ paths,
218
+ status: 'waiting',
219
+ blockerRunIds: blockers,
220
+ waitUntil: input.waitUntil || null,
221
+ acquiredAt: null,
222
+ expiresAt: null,
223
+ releasedAt: null,
224
+ };
225
+ if (existing) {
226
+ await repository.update({ filterByTk: read(existing, 'id'), values, transaction });
227
+ } else {
228
+ await repository.create({ values, transaction });
229
+ }
230
+ return { acquired: false, deadlocked: false, blockers };
231
+ }
232
+
233
+ const values = {
234
+ runId: input.runId,
235
+ repositoryKey,
236
+ owner: input.owner,
237
+ paths,
238
+ status: 'held',
239
+ blockerRunIds: [],
240
+ acquiredAt: now,
241
+ expiresAt: new Date(now.getTime() + ttlMs),
242
+ waitUntil: null,
243
+ releasedAt: null,
244
+ };
245
+ const locked = existing
246
+ ? await this.updateAndRead(repository, Number(read(existing, 'id')), values, transaction)
247
+ : await repository.create({ values, transaction });
248
+ return { acquired: true, lock: row(locked), blockers: [] as number[] };
249
+ }),
250
+ Math.max(ttlMs, 5000),
251
+ );
252
+ }
253
+
254
+ async renew(runId: number, repositoryKey: string, ttlMs: number, owner?: string) {
255
+ const ttl = positiveTtl(ttlMs);
256
+ return this.distributedLock.runExclusive(`agent-loop:path:${repositoryKey}`, async () => {
257
+ const repository = this.database.getRepository('agentLoopPathLocks');
258
+ // An expired lock is marked `expired` in its own committed transaction. Doing the audit
259
+ // write inside the renew transaction and then throwing would roll the mark back, leaving a
260
+ // stale `held` row that still reads as expired to the next acquirer but never audits it.
261
+ const expired = await this.database.sequelize.transaction(async (transaction) => {
262
+ const lock = await repository.findOne({
263
+ filter: { runId, repositoryKey, status: 'held' },
264
+ transaction,
265
+ lock: transaction.LOCK.UPDATE,
266
+ });
267
+ if (!lock) throw new Error('Held path lock was not found.');
268
+ if (owner !== undefined && String(read(lock, 'owner') || '') !== owner) {
269
+ throw new Error('Path lock is no longer owned by this worker.');
270
+ }
271
+ const now = new Date();
272
+ if (lockIsExpired(lock, now)) return { id: read(lock, 'id'), at: now };
273
+ await repository.update({
274
+ filterByTk: read(lock, 'id'),
275
+ values: { expiresAt: new Date(now.getTime() + ttl) },
276
+ transaction,
277
+ });
278
+ return null;
279
+ });
280
+
281
+ if (expired) {
282
+ await this.database.sequelize.transaction(async (transaction) => {
283
+ await repository.update({
284
+ filterByTk: expired.id,
285
+ values: { status: 'expired', releasedAt: expired.at, blockerRunIds: [] },
286
+ transaction,
287
+ });
288
+ });
289
+ throw new Error('Path lock has expired and must be reacquired.');
290
+ }
291
+ });
292
+ }
293
+
294
+ // The owner token guards against a reclaimed run: once a stale worker's lease expires and another
295
+ // worker takes over the same run, the original worker must not free a lock the new owner now holds.
296
+ async release(runId: number, repositoryKey: string, owner?: string) {
297
+ return this.distributedLock.runExclusive(`agent-loop:path:${repositoryKey}`, async () => {
298
+ const repository = this.database.getRepository('agentLoopPathLocks');
299
+ const lock = await repository.findOne({ filter: { runId, repositoryKey } });
300
+ if (!lock || ['released', 'expired'].includes(String(read(lock, 'status')))) return false;
301
+ if (owner !== undefined && String(read(lock, 'owner') || '') !== owner) return false;
302
+ await repository.update({
303
+ filterByTk: read(lock, 'id'),
304
+ values: { status: 'released', releasedAt: new Date(), blockerRunIds: [] },
305
+ });
306
+ return true;
307
+ });
308
+ }
309
+
310
+ private async updateAndRead(
311
+ repository: ReturnType<Database['getRepository']>,
312
+ id: number,
313
+ values: Record<string, unknown>,
314
+ transaction: Transaction,
315
+ ) {
316
+ await repository.update({ filterByTk: id, values, transaction });
317
+ const updated = await repository.findOne({ filterByTk: id, transaction });
318
+ if (!updated) throw new Error('Path lock disappeared during update.');
319
+ return updated;
320
+ }
321
+ }