@chatwarden/core 0.1.5 → 0.1.7

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 (131) hide show
  1. package/README.md +51 -1
  2. package/dist/src/ai/agreement.d.ts +46 -0
  3. package/dist/src/ai/agreement.d.ts.map +1 -0
  4. package/dist/src/ai/agreement.js +71 -0
  5. package/dist/src/ai/agreement.js.map +1 -0
  6. package/dist/src/ai/breaker.d.ts +31 -0
  7. package/dist/src/ai/breaker.d.ts.map +1 -0
  8. package/dist/src/ai/breaker.js +62 -0
  9. package/dist/src/ai/breaker.js.map +1 -0
  10. package/dist/src/ai/budget.d.ts +26 -0
  11. package/dist/src/ai/budget.d.ts.map +1 -0
  12. package/dist/src/ai/budget.js +57 -0
  13. package/dist/src/ai/budget.js.map +1 -0
  14. package/dist/src/ai/case.d.ts +37 -0
  15. package/dist/src/ai/case.d.ts.map +1 -0
  16. package/dist/src/ai/case.js +30 -0
  17. package/dist/src/ai/case.js.map +1 -0
  18. package/dist/src/ai/casebook.d.ts +59 -0
  19. package/dist/src/ai/casebook.d.ts.map +1 -0
  20. package/dist/src/ai/casebook.js +47 -0
  21. package/dist/src/ai/casebook.js.map +1 -0
  22. package/dist/src/ai/ceilings.d.ts +42 -0
  23. package/dist/src/ai/ceilings.d.ts.map +1 -0
  24. package/dist/src/ai/ceilings.js +59 -0
  25. package/dist/src/ai/ceilings.js.map +1 -0
  26. package/dist/src/ai/fake.d.ts +41 -0
  27. package/dist/src/ai/fake.d.ts.map +1 -0
  28. package/dist/src/ai/fake.js +75 -0
  29. package/dist/src/ai/fake.js.map +1 -0
  30. package/dist/src/ai/hash.d.ts +13 -0
  31. package/dist/src/ai/hash.d.ts.map +1 -0
  32. package/dist/src/ai/hash.js +19 -0
  33. package/dist/src/ai/hash.js.map +1 -0
  34. package/dist/src/ai/inert.d.ts +5 -0
  35. package/dist/src/ai/inert.d.ts.map +1 -0
  36. package/dist/src/ai/inert.js +22 -0
  37. package/dist/src/ai/inert.js.map +1 -0
  38. package/dist/src/ai/injection.d.ts +8 -0
  39. package/dist/src/ai/injection.d.ts.map +1 -0
  40. package/dist/src/ai/injection.js +30 -0
  41. package/dist/src/ai/injection.js.map +1 -0
  42. package/dist/src/ai/lines.d.ts +64 -0
  43. package/dist/src/ai/lines.d.ts.map +1 -0
  44. package/dist/src/ai/lines.js +172 -0
  45. package/dist/src/ai/lines.js.map +1 -0
  46. package/dist/src/ai/prompt.d.ts +44 -0
  47. package/dist/src/ai/prompt.d.ts.map +1 -0
  48. package/dist/src/ai/prompt.js +185 -0
  49. package/dist/src/ai/prompt.js.map +1 -0
  50. package/dist/src/ai/redact.d.ts +29 -0
  51. package/dist/src/ai/redact.d.ts.map +1 -0
  52. package/dist/src/ai/redact.js +160 -0
  53. package/dist/src/ai/redact.js.map +1 -0
  54. package/dist/src/ai/schema.d.ts +6 -0
  55. package/dist/src/ai/schema.d.ts.map +1 -0
  56. package/dist/src/ai/schema.js +50 -0
  57. package/dist/src/ai/schema.js.map +1 -0
  58. package/dist/src/ai/service.d.ts +328 -0
  59. package/dist/src/ai/service.d.ts.map +1 -0
  60. package/dist/src/ai/service.js +749 -0
  61. package/dist/src/ai/service.js.map +1 -0
  62. package/dist/src/ai/types.d.ts +180 -0
  63. package/dist/src/ai/types.d.ts.map +1 -0
  64. package/dist/src/ai/types.js +23 -0
  65. package/dist/src/ai/types.js.map +1 -0
  66. package/dist/src/ai/validate.d.ts +30 -0
  67. package/dist/src/ai/validate.d.ts.map +1 -0
  68. package/dist/src/ai/validate.js +160 -0
  69. package/dist/src/ai/validate.js.map +1 -0
  70. package/dist/src/ai/worker.d.ts +74 -0
  71. package/dist/src/ai/worker.d.ts.map +1 -0
  72. package/dist/src/ai/worker.js +286 -0
  73. package/dist/src/ai/worker.js.map +1 -0
  74. package/dist/src/audit.d.ts +12 -3
  75. package/dist/src/audit.d.ts.map +1 -1
  76. package/dist/src/audit.js +30 -4
  77. package/dist/src/audit.js.map +1 -1
  78. package/dist/src/chatwarden.d.ts +28 -0
  79. package/dist/src/chatwarden.d.ts.map +1 -1
  80. package/dist/src/chatwarden.js +60 -1
  81. package/dist/src/chatwarden.js.map +1 -1
  82. package/dist/src/decide.d.ts +36 -1
  83. package/dist/src/decide.d.ts.map +1 -1
  84. package/dist/src/decide.js +62 -2
  85. package/dist/src/decide.js.map +1 -1
  86. package/dist/src/documents.d.ts +1 -1
  87. package/dist/src/documents.d.ts.map +1 -1
  88. package/dist/src/documents.js +4 -1
  89. package/dist/src/documents.js.map +1 -1
  90. package/dist/src/index.d.ts +27 -5
  91. package/dist/src/index.d.ts.map +1 -1
  92. package/dist/src/index.js +17 -2
  93. package/dist/src/index.js.map +1 -1
  94. package/dist/src/profile.d.ts +30 -1
  95. package/dist/src/profile.d.ts.map +1 -1
  96. package/dist/src/profile.js +43 -4
  97. package/dist/src/profile.js.map +1 -1
  98. package/dist/src/retention.d.ts +19 -0
  99. package/dist/src/retention.d.ts.map +1 -1
  100. package/dist/src/retention.js +33 -10
  101. package/dist/src/retention.js.map +1 -1
  102. package/dist/src/types.d.ts +269 -2
  103. package/dist/src/types.d.ts.map +1 -1
  104. package/dist/src/types.js.map +1 -1
  105. package/package.json +2 -2
  106. package/src/ai/agreement.ts +106 -0
  107. package/src/ai/breaker.ts +73 -0
  108. package/src/ai/budget.ts +65 -0
  109. package/src/ai/case.ts +74 -0
  110. package/src/ai/casebook.ts +75 -0
  111. package/src/ai/ceilings.ts +68 -0
  112. package/src/ai/fake.ts +105 -0
  113. package/src/ai/hash.ts +20 -0
  114. package/src/ai/inert.ts +26 -0
  115. package/src/ai/injection.ts +32 -0
  116. package/src/ai/lines.ts +216 -0
  117. package/src/ai/prompt.ts +208 -0
  118. package/src/ai/redact.ts +174 -0
  119. package/src/ai/schema.ts +51 -0
  120. package/src/ai/service.ts +955 -0
  121. package/src/ai/types.ts +165 -0
  122. package/src/ai/validate.ts +173 -0
  123. package/src/ai/worker.ts +364 -0
  124. package/src/audit.ts +31 -5
  125. package/src/chatwarden.ts +82 -1
  126. package/src/decide.ts +97 -4
  127. package/src/documents.ts +5 -2
  128. package/src/index.ts +52 -1
  129. package/src/profile.ts +68 -4
  130. package/src/retention.ts +47 -10
  131. package/src/types.ts +294 -2
@@ -0,0 +1,749 @@
1
+ import { errorClass, safeWarn } from '../log.js';
2
+ import { AI_DAILY_CALLS_DEFAULT } from '../profile.js';
3
+ import { suggestedRule } from '../reporting.js';
4
+ import { CONDUCT_LEVELS } from '../types.js';
5
+ import { agreementOf } from './agreement.js';
6
+ import { Breaker } from './breaker.js';
7
+ import { emptyStats } from './inert.js';
8
+ import { CallWindow, startOfUtcDay, utcDayLabel } from './budget.js';
9
+ import { prepareCase } from './case.js';
10
+ import { assertWithinCeilings, AICeilingError } from './ceilings.js';
11
+ import { actionsOnTarget, AI_EXAMPLES_MIN, pickExampleLines } from './casebook.js';
12
+ import { aiPolicyText } from './prompt.js';
13
+ import { sha256Hex } from '../crypto.js';
14
+ import { isFinalRow, Meter, runRead } from './worker.js';
15
+ /** How often the sweeper runs. */
16
+ export const SWEEP_EVERY_MS = 60_000;
17
+ /** The most reports one sweep queues. */
18
+ export const SWEEP_BATCH = 20;
19
+ /** The most stale reads one idle sweep queues. */
20
+ export const STALE_PER_SWEEP = 5;
21
+ /** How many times one moderator may ask for a read again in a minute. */
22
+ export const READ_AGAIN_PER_MINUTE = 10;
23
+ /** The most reports the sweeper remembers as not to be queued (and the most final reads it remembers). */
24
+ export const PARKED_MAX = 2000;
25
+ /** How many recent open reports a sweep looks at. */
26
+ const SWEEP_SCAN = 200;
27
+ /** The audit trail takes an actor of at most 128 characters of `A-Za-z0-9_.:@+-`. */
28
+ const ACTOR_MAX = 128;
29
+ const PREPARED_CACHE_MAX = 500;
30
+ const STATS_DEFAULT_WINDOW_MS = 30 * 24 * 3_600_000;
31
+ const DEFAULTS = { maxLevel: 2, dailyBudgetMicros: 1_000_000, perMinuteCalls: 30, concurrency: 2, timeoutMs: 30_000 };
32
+ /** The audit actor for the AI: `ai:` and the adapter's id with every character the trail refuses made an underscore, cut to fit. */
33
+ export function aiActorOf(adapterId) {
34
+ const id = String(adapterId).replace(/[^A-Za-z0-9_.:@+-]/gu, '_').slice(0, ACTOR_MAX - 'ai:'.length);
35
+ return `ai:${id === '' ? 'adapter' : id}`;
36
+ }
37
+ const REQUIRED_STORE_METHODS = [
38
+ 'reserveAiRead',
39
+ 'completeAiRead',
40
+ 'failAiRead',
41
+ 'loadAiRead',
42
+ 'loadAiReads',
43
+ 'loadAiReadById',
44
+ 'loadAiReadFor',
45
+ 'listAiRetries',
46
+ 'aiSpendSince',
47
+ 'insertAiOutcome',
48
+ 'loadAiOutcome',
49
+ 'markAiOutcome',
50
+ 'aiExamples',
51
+ 'aiTeachableCount',
52
+ 'aiStats',
53
+ ];
54
+ /** The store, typed with its AI methods; throws a plain error when it has not got them. */
55
+ export function requireAiStore(store) {
56
+ const missing = REQUIRED_STORE_METHODS.filter((m) => typeof store[m] !== 'function');
57
+ if (missing.length > 0) {
58
+ throw new Error(`createChatwarden: the AI needs a store with the AI methods (${missing.join(', ')}); use the memory or SQLite store, or leave the "ai" option out`);
59
+ }
60
+ return store;
61
+ }
62
+ /**
63
+ * Check the AI option before anything is started (throws a plain error for a bad one) and name the AI methods the store lacks. A store that
64
+ * lacks some leaves the AI inert: `createChatwarden` says so once and carries on, as it does for any optional Store method.
65
+ */
66
+ export function checkAiSetup(store, options) {
67
+ checkOptions(options);
68
+ return REQUIRED_STORE_METHODS.filter((m) => typeof store[m] !== 'function');
69
+ }
70
+ function checkOptions(o) {
71
+ const a = o?.adapter;
72
+ if (typeof a !== 'object' || a === null || typeof a.id !== 'string' || a.id === '' || typeof a.read !== 'function') {
73
+ throw new TypeError('createChatwarden: ai.adapter must be a ModerationAI ({ id, read })');
74
+ }
75
+ const maxLevel = o.maxLevel ?? DEFAULTS.maxLevel;
76
+ if (maxLevel !== 1 && maxLevel !== 2)
77
+ throw new RangeError('createChatwarden: ai.maxLevel must be 1 or 2');
78
+ const whole = (v, name, min) => {
79
+ if (typeof v !== 'number' || !Number.isFinite(v) || !Number.isInteger(v) || v < min)
80
+ throw new RangeError(`createChatwarden: ai.${name} must be a whole number of at least ${min}`);
81
+ return v;
82
+ };
83
+ const dailyBudgetMicros = whole(o.dailyBudgetMicros ?? DEFAULTS.dailyBudgetMicros, 'dailyBudgetMicros', 0);
84
+ const perMinuteCalls = whole(o.perMinuteCalls ?? DEFAULTS.perMinuteCalls, 'perMinuteCalls', 1);
85
+ const concurrency = whole(o.concurrency ?? DEFAULTS.concurrency, 'concurrency', 1);
86
+ const timeoutMs = whole(o.timeoutMs ?? DEFAULTS.timeoutMs, 'timeoutMs', 1);
87
+ const blockedLines = o.blockedLines ?? 'raw';
88
+ if (blockedLines !== 'raw' && blockedLines !== 'mask')
89
+ throw new RangeError("createChatwarden: ai.blockedLines must be 'raw' or 'mask'");
90
+ const contextTags = o.contextTags ?? [];
91
+ if (!Array.isArray(contextTags) || contextTags.some((t) => typeof t !== 'string'))
92
+ throw new TypeError('createChatwarden: ai.contextTags must be a list of strings');
93
+ return { maxLevel, dailyBudgetMicros, perMinuteCalls, concurrency, timeoutMs, blockedLines, contextTags: [...contextTags] };
94
+ }
95
+ const ruleOfText = (rule) => (rule === null ? null : /^\d+$/.test(rule) ? Number(rule) : rule === 'uncovered' ? 'uncovered' : null);
96
+ /** A suggestion's outcome as a step: a note, a warning or a restriction; none is no step. */
97
+ function stepOf(s) {
98
+ const o = s.outcome;
99
+ if (o === 'none')
100
+ return null;
101
+ if (o === 'note' || o === 'warning')
102
+ return { kind: o, durationMs: null, label: s.label };
103
+ return { kind: o.kind, durationMs: o.durationMs, label: s.label };
104
+ }
105
+ export class AiService {
106
+ store;
107
+ clock;
108
+ adapter;
109
+ actor;
110
+ opts;
111
+ meter = new Meter();
112
+ breaker;
113
+ window;
114
+ queue = [];
115
+ queued = new Set();
116
+ running = new Map();
117
+ parked = new Map();
118
+ retakes = new Set();
119
+ controllers = new Set();
120
+ cache = new Map();
121
+ asked = new Map();
122
+ pumpTimer;
123
+ sweepTimer;
124
+ unsubscribe;
125
+ waiters = [];
126
+ policyText = null;
127
+ lastStable = '';
128
+ stableKey = '';
129
+ isClosed = false;
130
+ deps;
131
+ constructor(deps) {
132
+ this.deps = deps;
133
+ this.store = requireAiStore(deps.store);
134
+ this.clock = deps.clock;
135
+ this.opts = checkOptions(deps.options);
136
+ this.adapter = deps.options.adapter;
137
+ this.actor = aiActorOf(this.adapter.id);
138
+ this.breaker = new Breaker(deps.clock);
139
+ this.window = new CallWindow(this.opts.perMinuteCalls);
140
+ // Only enqueue: no await, no store read, so the player's ack never waits for the AI.
141
+ this.unsubscribe = deps.subscribe('report.created', (e) => {
142
+ this.enqueue(e.reportId);
143
+ });
144
+ this.sweepTimer = setInterval(() => void this.sweep(), SWEEP_EVERY_MS);
145
+ this.sweepTimer.unref?.();
146
+ }
147
+ // --- the facade ------------------------------------------------------------------------------------------------------------
148
+ level() {
149
+ try {
150
+ return Math.min(this.deps.profile().ai.level, this.opts.maxLevel);
151
+ }
152
+ catch (err) {
153
+ this.warn('ai.level_failed', err);
154
+ return 0;
155
+ }
156
+ }
157
+ status() {
158
+ const level = this.level();
159
+ let spent = { micros: 0, calls: 0 };
160
+ try {
161
+ spent = this.store.aiSpendSince(startOfUtcDay(this.clock.now()));
162
+ }
163
+ catch (err) {
164
+ this.warn('ai.status_failed', err);
165
+ }
166
+ const cap = this.opts.dailyBudgetMicros;
167
+ const capCalls = this.dailyCalls();
168
+ let state = 'ok';
169
+ if (level === 0)
170
+ state = 'off';
171
+ else if (this.breaker.state() !== 'closed')
172
+ state = 'unavailable';
173
+ else if (spent.micros >= cap || spent.calls >= capCalls)
174
+ state = 'paused_budget';
175
+ return {
176
+ available: true,
177
+ level,
178
+ maxLevel: this.opts.maxLevel,
179
+ state,
180
+ spentMicros: spent.micros,
181
+ capMicros: cap,
182
+ capCalls,
183
+ day: utcDayLabel(this.clock.now()),
184
+ reads: spent.calls,
185
+ cacheHitRate: this.meter.cacheHitRate(),
186
+ invalid: { ...this.meter.invalid },
187
+ };
188
+ }
189
+ read(reportId, o) {
190
+ try {
191
+ const level = this.level();
192
+ if (level === 0 || typeof reportId !== 'string')
193
+ return null;
194
+ const report = this.store.loadReport(reportId);
195
+ if (report === null)
196
+ return null;
197
+ const row = this.store.loadAiRead(reportId);
198
+ const open = o?.open === true && report.status === 'open';
199
+ if (row === null || row.read === null) {
200
+ if (open)
201
+ this.enqueue(reportId);
202
+ return null;
203
+ }
204
+ const prepared = this.prepare(report);
205
+ const view = this.view(row, report, prepared, level);
206
+ if (open && view.stale)
207
+ this.enqueue(reportId);
208
+ return view;
209
+ }
210
+ catch (err) {
211
+ this.warn('ai.read_view_failed', err);
212
+ return null;
213
+ }
214
+ }
215
+ expected(reportId) {
216
+ try {
217
+ if (this.level() === 0 || typeof reportId !== 'string')
218
+ return false;
219
+ if (this.status().state !== 'ok')
220
+ return false;
221
+ const report = this.store.loadReport(reportId);
222
+ if (report === null || report.status !== 'open')
223
+ return false;
224
+ const own = this.store.loadAiReadFor(reportId, this.prepare(report).hash);
225
+ return !(own !== null && isFinalRow(own));
226
+ }
227
+ catch (err) {
228
+ this.warn('ai.expected_failed', err);
229
+ return false;
230
+ }
231
+ }
232
+ readAgain(reportId, actor) {
233
+ try {
234
+ const level = this.level();
235
+ if (level === 0 || typeof reportId !== 'string')
236
+ return Promise.resolve('off');
237
+ const report = this.store.loadReport(reportId);
238
+ if (report === null || report.status !== 'open')
239
+ return Promise.resolve('off');
240
+ if (!this.allowAsk(actor))
241
+ return Promise.resolve('rate');
242
+ const prepared = this.prepare(report);
243
+ const row = this.store.loadAiRead(reportId);
244
+ if (row !== null && row.read !== null && row.inputHash === prepared.hash)
245
+ return Promise.resolve(this.view(row, report, prepared, level));
246
+ const own = this.store.loadAiReadFor(reportId, prepared.hash);
247
+ const now = this.clock.now();
248
+ const today = this.store.aiSpendSince(startOfUtcDay(now));
249
+ if (today.micros >= this.opts.dailyBudgetMicros || today.calls >= this.dailyCalls())
250
+ return Promise.resolve('budget');
251
+ // Nothing can be called now: say so, with the wait, rather than queue a job that cannot run.
252
+ if (!this.breaker.available()) {
253
+ const reopens = this.breaker.reopensAt() ?? now;
254
+ return Promise.resolve({ unavailable: { retryAfterMs: Math.max(1000, reopens - now) } });
255
+ }
256
+ if (!this.window.peek(now))
257
+ return Promise.resolve({ unavailable: { retryAfterMs: Math.max(1000, this.window.nextFree(now) - now) } });
258
+ // A moderator's explicit ask retakes a FINAL row (one that ended without an answer and will not be tried again by itself) once;
259
+ // the store keeps that on the row, so asking again has nothing left to try, whichever process or restart comes between. A row
260
+ // still waiting for its own retry is not retaken: the ask just makes sure it is queued, and the call waits for its time.
261
+ if (own !== null && isFinalRow(own)) {
262
+ if (own.retaken)
263
+ return Promise.resolve('final');
264
+ this.retakes.add(reportId);
265
+ }
266
+ else if (own?.status === 'skipped') {
267
+ // A skipped read made no call: the ask takes it now instead of at its retry time (the caps were checked above).
268
+ this.retakes.add(reportId);
269
+ }
270
+ this.enqueue(reportId, { force: true });
271
+ return Promise.resolve('pending');
272
+ }
273
+ catch (err) {
274
+ this.warn('ai.read_again_failed', err);
275
+ return Promise.resolve('off');
276
+ }
277
+ }
278
+ /** A sliding minute per actor. Held in memory: it guards the provider's bill from one eager hand, not a security boundary. */
279
+ allowAsk(actor) {
280
+ const now = this.clock.now();
281
+ const key = String(actor);
282
+ const recent = (this.asked.get(key) ?? []).filter((t) => t > now - 60_000);
283
+ if (recent.length >= READ_AGAIN_PER_MINUTE) {
284
+ this.asked.set(key, recent);
285
+ return false;
286
+ }
287
+ recent.push(now);
288
+ this.asked.set(key, recent);
289
+ if (this.asked.size > 1000)
290
+ this.asked.delete(this.asked.keys().next().value);
291
+ return true;
292
+ }
293
+ briefs(reportIds) {
294
+ const out = new Map();
295
+ try {
296
+ const level = this.level();
297
+ if (level === 0 || !Array.isArray(reportIds) || reportIds.length === 0)
298
+ return out;
299
+ for (const row of this.store.loadAiReads(reportIds)) {
300
+ const read = row.read;
301
+ if (read === null)
302
+ continue;
303
+ const report = this.store.loadReport(row.reportId);
304
+ if (report === null)
305
+ continue;
306
+ const rec = read.recommendation;
307
+ out.set(row.reportId, {
308
+ severity: read.severity,
309
+ confidence: read.confidence,
310
+ rule: read.rule,
311
+ stale: this.prepare(report).hash !== row.inputHash,
312
+ injectionSuspected: read.injectionSuspected,
313
+ hasRecommendation: level >= 2 && rec !== null && rec.verdict !== 'unclear',
314
+ });
315
+ }
316
+ }
317
+ catch (err) {
318
+ this.warn('ai.briefs_failed', err);
319
+ return new Map();
320
+ }
321
+ return out;
322
+ }
323
+ stats(q) {
324
+ const since = typeof q?.since === 'number' && Number.isFinite(q.since) ? q.since : this.clock.now() - STATS_DEFAULT_WINDOW_MS;
325
+ try {
326
+ const rows = this.store.aiStats(since);
327
+ const view = emptyStats(since);
328
+ for (const r of rows) {
329
+ view.decided += r.decided;
330
+ view.agree += r.agree;
331
+ view.override += r.override;
332
+ view.none += r.none;
333
+ view.falsePositives += r.falsePositives;
334
+ view.oneClick += r.oneClick;
335
+ view.rules.push({ rule: ruleOfText(r.rule), decided: r.decided, agree: r.agree, override: r.override, none: r.none, falsePositives: r.falsePositives, oneClick: r.oneClick });
336
+ }
337
+ const shown = view.agree + view.override;
338
+ view.agreementRate = shown === 0 ? null : view.agree / shown;
339
+ view.falsePositiveRate = shown === 0 ? null : view.falsePositives / shown;
340
+ view.oneClickRate = shown === 0 ? null : view.oneClick / shown;
341
+ return view;
342
+ }
343
+ catch (err) {
344
+ this.warn('ai.stats_failed', err);
345
+ return emptyStats(since);
346
+ }
347
+ }
348
+ markReversed(reportId) {
349
+ return this.mark(reportId, { reversed: true });
350
+ }
351
+ dontTeach(reportId) {
352
+ return this.mark(reportId, { dontTeach: true });
353
+ }
354
+ mark(reportId, patch) {
355
+ try {
356
+ return typeof reportId === 'string' && this.store.markAiOutcome(reportId, patch);
357
+ }
358
+ catch (err) {
359
+ this.warn('ai.mark_failed', err);
360
+ return false;
361
+ }
362
+ }
363
+ idle() {
364
+ if (this.isIdle())
365
+ return Promise.resolve();
366
+ return new Promise((resolve) => void this.waiters.push(resolve));
367
+ }
368
+ close() {
369
+ this.isClosed = true;
370
+ if (this.sweepTimer !== undefined)
371
+ clearInterval(this.sweepTimer);
372
+ this.sweepTimer = undefined;
373
+ if (this.pumpTimer !== undefined)
374
+ clearTimeout(this.pumpTimer);
375
+ this.pumpTimer = undefined;
376
+ this.unsubscribe?.();
377
+ this.unsubscribe = undefined;
378
+ this.queue.length = 0;
379
+ this.queued.clear();
380
+ for (const c of this.controllers)
381
+ c.abort();
382
+ this.settleIdle();
383
+ }
384
+ // --- the queue -------------------------------------------------------------------------------------------------------------
385
+ /**
386
+ * Put a report on the queue. Synchronous and cheap: no store read, no await. Does nothing at level 0. `force` is for a case that
387
+ * changed or was asked for (it forgets any wait the sweeper was keeping).
388
+ */
389
+ enqueue(reportId, o) {
390
+ try {
391
+ if (this.isClosed || typeof reportId !== 'string' || this.level() === 0)
392
+ return false;
393
+ if (o?.force === true)
394
+ this.parked.delete(reportId);
395
+ const job = this.running.get(reportId);
396
+ if (job !== undefined) {
397
+ // A change arrived while it was being read: read once more when this one ends.
398
+ job.dirty = true;
399
+ return false;
400
+ }
401
+ if (this.queued.has(reportId))
402
+ return false;
403
+ this.queued.add(reportId);
404
+ this.queue.push(reportId);
405
+ this.schedulePump();
406
+ return true;
407
+ }
408
+ catch (err) {
409
+ this.warn('ai.enqueue_failed', err);
410
+ return false;
411
+ }
412
+ }
413
+ /** The reporter's follow-up changed the case: read it again once. Called by the facade's `reports.addDetail`. */
414
+ caseChanged(reportId) {
415
+ this.enqueue(reportId, { force: true });
416
+ }
417
+ schedulePump() {
418
+ if (this.pumpTimer !== undefined || this.isClosed)
419
+ return;
420
+ this.pumpTimer = setTimeout(() => {
421
+ this.pumpTimer = undefined;
422
+ this.pump();
423
+ }, 0);
424
+ this.pumpTimer.unref?.();
425
+ }
426
+ pump() {
427
+ while (!this.isClosed && this.running.size < this.opts.concurrency && this.queue.length > 0) {
428
+ const id = this.queue.shift();
429
+ this.queued.delete(id);
430
+ this.running.set(id, { dirty: false });
431
+ void this.runOne(id);
432
+ }
433
+ this.settleIdle();
434
+ }
435
+ async runOne(id) {
436
+ try {
437
+ const retake = this.retakes.delete(id);
438
+ const end = await runRead(this.env(), id, retake ? { retake: true } : undefined);
439
+ if (end.park !== null)
440
+ this.park(id, end.park);
441
+ else
442
+ this.parked.delete(id);
443
+ }
444
+ catch (err) {
445
+ this.warn('ai.job_failed', err);
446
+ }
447
+ finally {
448
+ const job = this.running.get(id);
449
+ this.running.delete(id);
450
+ if (job?.dirty === true && !this.isClosed)
451
+ this.enqueue(id, { force: true });
452
+ this.pump();
453
+ }
454
+ }
455
+ /** Remember not to queue `reportId` before `until`. Bounded: the oldest entry goes when the list is full. */
456
+ park(reportId, until) {
457
+ this.parked.delete(reportId);
458
+ if (this.parked.size >= PARKED_MAX)
459
+ this.parked.delete(this.parked.keys().next().value);
460
+ this.parked.set(reportId, until);
461
+ }
462
+ /** How many reports the sweeper is holding back (tests). */
463
+ parkedSize() {
464
+ return this.parked.size;
465
+ }
466
+ isIdle() {
467
+ return this.queue.length === 0 && this.running.size === 0 && this.pumpTimer === undefined;
468
+ }
469
+ settleIdle() {
470
+ if (!this.isIdle())
471
+ return;
472
+ const waiting = this.waiters;
473
+ this.waiters = [];
474
+ for (const resolve of waiting)
475
+ resolve();
476
+ }
477
+ // --- the sweeper -----------------------------------------------------------------------------------------------------------
478
+ async sweep() {
479
+ try {
480
+ if (this.isClosed || this.level() === 0 || !this.breaker.available())
481
+ return;
482
+ const now = this.clock.now();
483
+ const quiet = this.isIdle();
484
+ let added = 0;
485
+ const room = () => SWEEP_BATCH - added;
486
+ // 1. Reads whose retry has come, and reads whose owner died.
487
+ for (const row of this.store.listAiRetries(now, 200)) {
488
+ if (room() <= 0)
489
+ break;
490
+ const report = this.store.loadReport(row.reportId);
491
+ if (report === null || report.status !== 'open' || this.prepare(report).hash !== row.inputHash)
492
+ continue;
493
+ if (this.enqueue(row.reportId, { force: true }))
494
+ added += 1;
495
+ }
496
+ // 2. Open reports with no usable read, newest first.
497
+ const page = this.store.listReports({ status: 'open', limit: SWEEP_SCAN });
498
+ const ids = page.map((r) => r.id);
499
+ const read = new Map(this.store.loadAiReads(ids).map((r) => [r.reportId, r]));
500
+ // Forget what is held back for reports that are decided or no longer open: the list only keeps the live ones.
501
+ const open = new Set(ids);
502
+ for (const id of [...this.parked.keys()])
503
+ if (!open.has(id))
504
+ this.parked.delete(id);
505
+ for (const report of page) {
506
+ if (room() <= 0)
507
+ break;
508
+ if (read.has(report.id) || this.isParked(report.id, now))
509
+ continue;
510
+ if (this.enqueue(report.id))
511
+ added += 1;
512
+ }
513
+ // 3. When there is nothing new, bring a few stale reads up to date (rules or case changed), at the pace of the budget.
514
+ if (added === 0 && quiet) {
515
+ let stale = 0;
516
+ for (const report of page) {
517
+ if (stale >= STALE_PER_SWEEP)
518
+ break;
519
+ const row = read.get(report.id);
520
+ if (row === undefined || this.isParked(report.id, now))
521
+ continue;
522
+ if (this.prepare(report).hash !== row.inputHash && this.enqueue(report.id))
523
+ stale += 1;
524
+ }
525
+ }
526
+ }
527
+ catch (err) {
528
+ this.warn('ai.sweep_failed', err);
529
+ }
530
+ }
531
+ isParked(reportId, now) {
532
+ const until = this.parked.get(reportId);
533
+ return until !== undefined && until > now;
534
+ }
535
+ // --- views -----------------------------------------------------------------------------------------------------------------
536
+ /** A report made ready for a read, cached by what it is made from. */
537
+ prepare(report) {
538
+ const profile = this.deps.profile();
539
+ const policy = { profile, rules: this.deps.rules };
540
+ // The text is rendered once per profile in force (the resolved profile is deep-frozen and replaced, never edited, on a change; the rules
541
+ // are fixed for the kit's life): a queue poll asks about 200 reports and each call would otherwise validate and render the policy again.
542
+ let stable;
543
+ if (this.policyText !== null && this.policyText.profile === profile)
544
+ stable = this.policyText.text;
545
+ else {
546
+ stable = aiPolicyText(policy);
547
+ this.policyText = { profile, text: stable };
548
+ }
549
+ if (stable !== this.lastStable) {
550
+ // The rules, the level meanings or the standard changed: what was waiting for a retry may now read differently.
551
+ this.lastStable = stable;
552
+ this.stableKey = sha256Hex(stable);
553
+ this.parked.clear();
554
+ }
555
+ const reasons = profile.reporting.reasons;
556
+ const label = report.reportedReason === null || report.reportedReason === undefined ? '' : (reasons.find((r) => r.id === report.reportedReason)?.label ?? '');
557
+ const key = [report.id, report.detailAt ?? 0, this.stableKey, label].join('|');
558
+ const hit = this.cache.get(key);
559
+ if (hit !== undefined)
560
+ return hit;
561
+ const made = prepareCase({ report, policy, reasons, adapterId: this.adapter.id, mask: this.opts.blockedLines === 'mask' });
562
+ if (this.cache.size >= PREPARED_CACHE_MAX)
563
+ this.cache.delete(this.cache.keys().next().value);
564
+ this.cache.set(key, made);
565
+ return made;
566
+ }
567
+ view(row, report, prepared, level) {
568
+ const read = row.read;
569
+ const rec = read.recommendation;
570
+ return {
571
+ id: row.id,
572
+ severity: read.severity,
573
+ rule: read.rule,
574
+ summary: read.summary,
575
+ evidenceLineIds: [...read.evidence],
576
+ confidence: read.confidence,
577
+ stale: row.inputHash !== prepared.hash,
578
+ injectionSuspected: read.injectionSuspected,
579
+ model: row.model,
580
+ at: row.createdAt,
581
+ recommendation: level >= 2 && rec !== null ? { verdict: rec.verdict, severity: rec.severity, rule: rec.rule, evidenceLineIds: [...rec.evidence], ...this.stepFor(report, prepared, rec) } : null,
582
+ };
583
+ }
584
+ /** The step the ladder gives for the recommendation, and whether it is within the ceilings. */
585
+ stepFor(report, prepared, rec) {
586
+ if (rec.verdict === 'no_action' || rec.verdict === 'unclear')
587
+ return { step: null, stepWithinCeiling: true };
588
+ try {
589
+ const profile = this.deps.profile();
590
+ const ruleRef = typeof rec.rule === 'number' ? rec.rule : suggestedRule(profile.reporting.reasons, report.reportedReason ?? null, this.deps.rules);
591
+ const step = rec.verdict === 'noted'
592
+ ? { kind: 'note', durationMs: null, label: 'Note' }
593
+ : stepOf(this.deps.suggest(report.targetSubject, rec.severity, ruleRef, { roomId: report.roomId === '' ? null : report.roomId }));
594
+ if (step === null)
595
+ return { step: null, stepWithinCeiling: true };
596
+ try {
597
+ assertWithinCeilings(step, { cited: rec.evidence, ownRefs: prepared.ownLineIds });
598
+ return { step, stepWithinCeiling: true };
599
+ }
600
+ catch (err) {
601
+ if (!(err instanceof AICeilingError))
602
+ throw err;
603
+ return { step, stepWithinCeiling: false };
604
+ }
605
+ }
606
+ catch (err) {
607
+ this.warn('ai.step_failed', err);
608
+ return { step: null, stepWithinCeiling: false };
609
+ }
610
+ }
611
+ // --- the worker's environment ----------------------------------------------------------------------------------------------
612
+ env() {
613
+ return {
614
+ store: this.store,
615
+ clock: this.clock,
616
+ adapter: this.adapter,
617
+ timeoutMs: this.opts.timeoutMs,
618
+ capMicros: this.opts.dailyBudgetMicros,
619
+ breaker: this.breaker,
620
+ window: this.window,
621
+ meter: this.meter,
622
+ level: () => this.level(),
623
+ dailyCalls: () => this.dailyCalls(),
624
+ closed: () => this.isClosed,
625
+ prepare: (report) => this.prepare(report),
626
+ examplesFor: (report, prepared) => this.examplesFor(report, prepared),
627
+ track: (c) => void this.controllers.add(c),
628
+ untrack: (c) => void this.controllers.delete(c),
629
+ auditRead: (reportId) => {
630
+ try {
631
+ this.deps.audit({ actor: this.actor, role: null, action: 'ai.read', target: { type: 'report', ref: reportId } });
632
+ }
633
+ catch (err) {
634
+ this.warn('ai.audit_failed', err);
635
+ }
636
+ },
637
+ warn: (event, detail) => safeWarn(this.deps.logger, event, detail),
638
+ };
639
+ }
640
+ /**
641
+ * Casebook examples for a read: none unless learning is on, example text is kept at all, the case names a reason that maps to a rule,
642
+ * and at least 30 teachable decisions exist. Then the two newest of that rule at the conduct level the AI gave this report before
643
+ * (or, for a first read, at any level), newest first. Each is pseudonymised already; the row's report id is its id.
644
+ */
645
+ examplesFor(report, prepared) {
646
+ void prepared;
647
+ const profile = this.deps.profile();
648
+ const keepMs = this.deps.exampleRetentionMs();
649
+ if (!profile.ai.learn || !(keepMs > 0))
650
+ return [];
651
+ const rule = suggestedRule(profile.reporting.reasons, report.reportedReason ?? null, this.deps.rules);
652
+ if (typeof rule !== 'number')
653
+ return [];
654
+ const since = this.clock.now() - keepMs;
655
+ if (this.store.aiTeachableCount(since) < AI_EXAMPLES_MIN)
656
+ return [];
657
+ const known = this.store.loadAiRead(report.id)?.read?.severity;
658
+ const levels = known === undefined ? CONDUCT_LEVELS : [known];
659
+ return levels
660
+ .flatMap((level) => this.store.aiExamples(String(rule), level, 2, since))
661
+ .sort((a, b) => b.decidedAt - a.decidedAt || (a.reportId < b.reportId ? 1 : -1))
662
+ .slice(0, 2)
663
+ .map((row) => ({ ...row.example, id: row.reportId }));
664
+ }
665
+ // --- the casebook ----------------------------------------------------------------------------------------------------------
666
+ /**
667
+ * The casebook row for a decision (the hook `DecisionService` calls inside its transaction), computed here from the stored read and
668
+ * the decision. The server always records it when a read exists at level 1 or 2, whichever way the decision came (the hub, `cw.decide`,
669
+ * a webhook, a bulk dismissal); the echo, when there is one, only names the read the moderator saw, says whether they clicked accept
670
+ * (kept only when the decision is the pre-fill) and gives the conduct level of their form (kept only when it fits the verdict).
671
+ * With no echo there is no example text. Null at level 0 and when the report has no read. Fenced by the caller.
672
+ */
673
+ outcomeOf(args) {
674
+ const level = this.level();
675
+ if (level === 0)
676
+ return null;
677
+ const { report, verdict, ai } = args;
678
+ // The read the moderator saw when the echo names one of this report's finished reads, else the newest.
679
+ const named = ai.readId === null ? null : this.store.loadAiReadById(ai.readId);
680
+ const row = named !== null && named.reportId === report.id && named.status === 'ok' && named.read !== null ? named : this.store.loadAiRead(report.id);
681
+ if (row === null)
682
+ return null;
683
+ const read = row.read;
684
+ const rec = read?.recommendation ?? null;
685
+ const own = actionsOnTarget(args.actions, args.target);
686
+ // What the ladder would have pre-filled for the AI's conduct level: the step the human's is compared with.
687
+ let prefill = null;
688
+ if (level >= 2 && rec !== null && (rec.verdict === 'upheld' || rec.verdict === 'noted')) {
689
+ const step = this.stepFor(report, this.prepare(report), rec).step;
690
+ prefill = step === null ? null : { kind: step.kind, durationMs: step.durationMs };
691
+ }
692
+ const verdictClass = verdict === 'bad_faith' ? 'no_action' : verdict;
693
+ const result = agreementOf(read, { verdict, rule: own.rule, lineIds: own.lineIds, step: own.step, prefill, others: own.others, oneClick: ai.accepted }, level);
694
+ // The conduct level the human settled on: their form's when it fits the verdict (a dismissal carries none; an action is not
695
+ // banter), else the AI's on an agreement, else banter for a dismissal.
696
+ const claimed = verdict === 'upheld' || verdict === 'noted' ? (ai.severity !== null && ai.severity !== 'banter' ? ai.severity : null) : null;
697
+ const severity = claimed ?? (result.agreement === 'agree' && rec !== null ? rec.severity : verdict === 'no_action' ? 'banter' : null);
698
+ const badFaith = verdict === 'bad_faith';
699
+ // The row is filed under the rule the human cited; a dismissal cites none, so it goes under the rule the AI cited (that is where its
700
+ // false positive belongs), else the rule of the reporter's reason.
701
+ const reasonRule = suggestedRule(this.deps.profile().reporting.reasons, report.reportedReason ?? null, this.deps.rules);
702
+ const filedUnder = own.rule ?? rec?.rule ?? read?.rule ?? (typeof reasonRule === 'number' ? reasonRule : null);
703
+ const profile = this.deps.profile();
704
+ const teachable = ai.readId !== null &&
705
+ (result.agreement === 'agree' || result.agreement === 'override') &&
706
+ !badFaith &&
707
+ profile.ai.learn &&
708
+ this.deps.exampleRetentionMs() > 0 &&
709
+ severity !== null &&
710
+ own.rule !== null;
711
+ let example = null;
712
+ // A case whose read flagged an injection, or whose chat tripped the tripwire, is never taught: its lines would be replayed into later prompts.
713
+ const injected = read?.injectionSuspected === true || this.prepare(report).injection;
714
+ if (teachable && !injected && severity !== null && own.rule !== null) {
715
+ const cited = new Set([...own.lineIds, ...(rec?.evidence ?? []), ...(read?.evidence ?? [])]);
716
+ const lines = pickExampleLines(this.prepare(report).chosen, cited);
717
+ if (lines.length > 0)
718
+ example = { rule: own.rule, severity, verdict: verdictClass, lines };
719
+ }
720
+ return {
721
+ reportId: report.id,
722
+ readId: row.id,
723
+ decidedAt: args.now,
724
+ level,
725
+ verdict: verdictClass,
726
+ rule: filedUnder === null ? null : String(filedUnder),
727
+ severity,
728
+ aiVerdict: result.aiVerdict,
729
+ agreement: result.agreement,
730
+ detail: result.detail,
731
+ badFaith,
732
+ example,
733
+ };
734
+ }
735
+ /** The owner's most calls in a UTC day, read live from the profile. */
736
+ dailyCalls() {
737
+ try {
738
+ return this.deps.profile().ai.dailyCalls;
739
+ }
740
+ catch (err) {
741
+ this.warn('ai.level_failed', err);
742
+ return AI_DAILY_CALLS_DEFAULT;
743
+ }
744
+ }
745
+ warn(event, err) {
746
+ safeWarn(this.deps.logger, event, { error: errorClass(err) });
747
+ }
748
+ }
749
+ //# sourceMappingURL=service.js.map