@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,364 @@
1
+ import type { AiCallUsage, AiErrorKind, AiReadRow, Clock, ReportRecord, Store } from '../types.js';
2
+ import { nextUtcMidnight, startOfUtcDay } from './budget.js';
3
+ import type { CallWindow } from './budget.js';
4
+ import type { Breaker } from './breaker.js';
5
+ import type { Prepared } from './case.js';
6
+ import { usedExampleIds } from './prompt.js';
7
+ import { validateAIOutput } from './validate.js';
8
+ import type { AbortSignalLike, AIExampleInput, AIRead, AIReadInput, AIReadResult, AIUsage, ModerationAI } from './types.js';
9
+
10
+ // One read, start to finish (design section 4). The job reserves the right to call (one atomic write on the store, so two processes
11
+ // make one call), checks the budget, the breaker and the rate, calls the adapter under a deadline, validates the answer in core,
12
+ // maps line refs back to line ids and stores the result. Every outcome is written; nothing here can fail a report, a queue read or a
13
+ // decision, and nothing here can act on a person.
14
+
15
+ /** A call is allowed this long beyond its deadline before another process may take the read over. */
16
+ export const LEASE_SLACK_MS = 15_000;
17
+ /** How many calls a read gets in all (the first and two retries). */
18
+ export const MAX_ATTEMPTS = 3;
19
+ /** The wait after the first failed attempt, then after the second. */
20
+ export const RETRY_AFTER_MS: readonly number[] = [60_000, 600_000];
21
+ /** A job that lost a race for the breaker's probe or the call window tries again after this. */
22
+ const RACE_RETRY_MS = 60_000;
23
+ /** What one call is counted as costing while it is in flight, until a real cost is known: 0.1 cent. */
24
+ const DEFAULT_ESTIMATE_MICROS = 1000;
25
+
26
+ /** The store with the AI methods present (checked once, at creation). */
27
+ export type AiStore = Store &
28
+ Required<
29
+ Pick<
30
+ Store,
31
+ | 'reserveAiRead'
32
+ | 'completeAiRead'
33
+ | 'failAiRead'
34
+ | 'loadAiRead'
35
+ | 'loadAiReads'
36
+ | 'loadAiReadById'
37
+ | 'loadAiReadFor'
38
+ | 'listAiRetries'
39
+ | 'aiSpendSince'
40
+ | 'insertAiOutcome'
41
+ | 'loadAiOutcome'
42
+ | 'markAiOutcome'
43
+ | 'aiExamples'
44
+ | 'aiTeachableCount'
45
+ | 'aiStats'
46
+ >
47
+ >;
48
+
49
+ /** The counters of this process: calls in flight, the last cost, tokens for the cache hit rate, invalid answers by code. */
50
+ export class Meter {
51
+ inflight = 0;
52
+ lastCostMicros = 0;
53
+ inputTokens = 0;
54
+ cacheReadTokens = 0;
55
+ cacheWriteTokens = 0;
56
+ readonly invalid: Record<string, number> = Object.create(null) as Record<string, number>;
57
+
58
+ estimate(): number {
59
+ return Math.max(DEFAULT_ESTIMATE_MICROS, this.lastCostMicros);
60
+ }
61
+
62
+ usage(u: AiCallUsage): void {
63
+ this.lastCostMicros = u.costMicros;
64
+ this.inputTokens += u.inputTokens;
65
+ this.cacheReadTokens += u.cacheReadTokens;
66
+ this.cacheWriteTokens += u.cacheWriteTokens;
67
+ }
68
+
69
+ invalidCode(code: string): void {
70
+ this.invalid[code] = (this.invalid[code] ?? 0) + 1;
71
+ }
72
+
73
+ /** The share of input tokens served from the provider's cache, or null before any call used tokens. */
74
+ cacheHitRate(): number | null {
75
+ const total = this.inputTokens + this.cacheReadTokens + this.cacheWriteTokens;
76
+ return total === 0 ? null : this.cacheReadTokens / total;
77
+ }
78
+ }
79
+
80
+ /** What the worker needs from the service around it. */
81
+ export interface WorkerEnv {
82
+ readonly store: AiStore;
83
+ readonly clock: Clock;
84
+ readonly adapter: ModerationAI;
85
+ readonly timeoutMs: number;
86
+ readonly capMicros: number;
87
+ readonly breaker: Breaker;
88
+ readonly window: CallWindow;
89
+ readonly meter: Meter;
90
+ level(): number;
91
+ /** The owner's most calls in a UTC day (`profile.ai.dailyCalls`), read live. */
92
+ dailyCalls(): number;
93
+ closed(): boolean;
94
+ prepare(report: ReportRecord): Prepared;
95
+ /** Casebook examples for this case, newest first; empty when there are none, learning is off or something fails. */
96
+ examplesFor(report: ReportRecord, prepared: Prepared): AIExampleInput[];
97
+ track(controller: Abortable): void;
98
+ untrack(controller: Abortable): void;
99
+ /** The `ai.read` audit row for a terminal outcome. Fenced by the caller. */
100
+ auditRead(reportId: string): void;
101
+ warn(event: string, detail?: Record<string, string | number | boolean>): void;
102
+ }
103
+
104
+ const errName = (err: unknown): string => {
105
+ try {
106
+ return err instanceof Error ? err.name : typeof err;
107
+ } catch {
108
+ return 'unknown';
109
+ }
110
+ };
111
+
112
+ type CallKind = 'retryable' | 'fatal' | 'declined' | 'timeout';
113
+ const CALL_KINDS: readonly string[] = ['retryable', 'fatal', 'declined', 'timeout'];
114
+
115
+ /** The kind of an error an adapter threw. A copy of core's AIError is recognised by shape; anything else is retryable. */
116
+ function kindOf(err: unknown, ours: boolean): CallKind {
117
+ try {
118
+ const kind = (err as { name?: unknown; kind?: unknown } | null)?.kind;
119
+ const name = (err as { name?: unknown } | null)?.name;
120
+ if (name === 'AIError' && typeof kind === 'string' && CALL_KINDS.includes(kind)) return kind as CallKind;
121
+ } catch {
122
+ // A hostile error object: fall through.
123
+ }
124
+ return ours ? 'timeout' : 'retryable';
125
+ }
126
+
127
+ /** What the worker needs of an `AbortController` to give a call up. */
128
+ export interface Abortable {
129
+ abort(): void;
130
+ }
131
+
132
+ /** `promise`, or a timeout error as soon as the signal aborts, whichever comes first. The loser is never left unhandled. */
133
+ function raceAbort<T>(promise: Promise<T>, signal: AbortSignalLike): Promise<T> {
134
+ return new Promise<T>((resolve, reject) => {
135
+ const onAbort = (): void => reject(Object.assign(new Error('aborted'), { name: 'AIError', kind: 'timeout' }));
136
+ if (signal.aborted) onAbort();
137
+ else signal.addEventListener('abort', onAbort, { once: true });
138
+ promise.then(
139
+ (v) => {
140
+ signal.removeEventListener('abort', onAbort);
141
+ resolve(v);
142
+ },
143
+ (e: unknown) => {
144
+ signal.removeEventListener('abort', onAbort);
145
+ reject(e);
146
+ },
147
+ );
148
+ });
149
+ }
150
+
151
+ const count = (v: unknown): number => (typeof v === 'number' && Number.isFinite(v) && v > 0 ? Math.floor(v) : 0);
152
+
153
+ /** The usage an adapter reported, made safe to store: a model name of at most 100 characters, whole non-negative numbers. */
154
+ function safeUsage(u: Partial<AIUsage> | undefined, latencyMs: number): AiCallUsage {
155
+ return {
156
+ model: typeof u?.model === 'string' && u.model !== '' ? u.model.slice(0, 100) : 'unknown',
157
+ inputTokens: count(u?.inputTokens),
158
+ outputTokens: count(u?.outputTokens),
159
+ cacheReadTokens: count(u?.cacheReadTokens),
160
+ cacheWriteTokens: count(u?.cacheWriteTokens),
161
+ costMicros: typeof u?.costMicros === 'number' && Number.isFinite(u.costMicros) && u.costMicros > 0 ? Math.round(u.costMicros) : 0,
162
+ latencyMs: Math.max(0, Math.floor(latencyMs)),
163
+ };
164
+ }
165
+
166
+ /** Until when the sweeper should leave a report alone, given the row a reserve found: null (nothing to wait for) for a finished read. */
167
+ export function parkOf(row: AiReadRow, now: number): number | null {
168
+ switch (row.status) {
169
+ case 'ok':
170
+ return null;
171
+ case 'pending':
172
+ return row.leaseUntil ?? now + RACE_RETRY_MS;
173
+ case 'failed':
174
+ case 'skipped':
175
+ return row.retryAt ?? Number.POSITIVE_INFINITY;
176
+ default:
177
+ // declined, invalid: final for this input.
178
+ return Number.POSITIVE_INFINITY;
179
+ }
180
+ }
181
+
182
+ /**
183
+ * A row that ended without an answer and will not be tried again by itself (declined, invalid twice, fatal, given up): the only kind of
184
+ * row a moderator's explicit "read again" may retake, once (the row's `retaken` marker). A row waiting for its own retry is not final, and
185
+ * neither is a skipped one: it made no call and gave its attempt back, so an explicit ask simply takes it (no marker).
186
+ */
187
+ export function isFinalRow(row: AiReadRow): boolean {
188
+ return row.status === 'declined' || row.status === 'invalid' || (row.status === 'failed' && row.retryAt === null);
189
+ }
190
+
191
+ /** How a job ended. `park` is the time (epoch ms, possibly Infinity) before which the sweeper should not queue the report again, or null when there is nothing to wait for. */
192
+ export interface ReadEnd {
193
+ park: number | null;
194
+ }
195
+
196
+ const NOTHING: ReadEnd = { park: null };
197
+
198
+ /**
199
+ * Read one report. `opts.retake` is a moderator's explicit ask: a FINAL row (see {@link isFinalRow}) that has not been retaken is taken over once
200
+ * more (and the call is charged and audited like any other). Throws only on a store failure; the caller fences it.
201
+ */
202
+ export async function runRead(env: WorkerEnv, reportId: string, opts?: { retake?: boolean }): Promise<ReadEnd> {
203
+ if (env.level() === 0 || env.closed()) return NOTHING;
204
+ const report = env.store.loadReport(reportId);
205
+ if (report === null || report.status !== 'open') return NOTHING;
206
+
207
+ // Cheap refusals first, before anything is written: an unavailable breaker (open, or half-open with its probe out) or a full
208
+ // minute leaves no row behind.
209
+ const now = env.clock.now();
210
+ if (!env.breaker.available() || !env.window.peek(now)) return NOTHING;
211
+
212
+ const prepared = env.prepare(report);
213
+ const reserved = env.store.reserveAiRead(
214
+ { reportId, inputHash: prepared.hash, promptVersion: prepared.input.promptVersion, adapter: env.adapter.id },
215
+ now + env.timeoutMs + LEASE_SLACK_MS,
216
+ now,
217
+ opts?.retake === true ? { retake: true } : undefined,
218
+ );
219
+ if (!reserved.reserved) {
220
+ return { park: parkOf(reserved.existing, now) };
221
+ }
222
+ const { id, lease } = reserved;
223
+
224
+ // The daily caps. Money: what is stored for today, plus what the calls in flight here are estimated to cost. Calls: the owner's
225
+ // ceiling, which holds even for an adapter that reports no cost (the count includes this reservation).
226
+ const today = env.store.aiSpendSince(startOfUtcDay(now));
227
+ if (today.micros + env.meter.inflight * env.meter.estimate() >= env.capMicros || today.calls > env.dailyCalls()) {
228
+ const resume = nextUtcMidnight(now);
229
+ env.store.failAiRead(id, lease, 'skipped', 'budget', resume);
230
+ return { park: resume };
231
+ }
232
+
233
+ const gate = env.breaker.gate();
234
+ if (gate === 'no' || !env.window.tryTake(now)) {
235
+ if (gate === 'probe') env.breaker.release();
236
+ const again = now + RACE_RETRY_MS;
237
+ env.store.failAiRead(id, lease, 'skipped', 'retryable', again);
238
+ return { park: again };
239
+ }
240
+
241
+ let examples: AIExampleInput[] = [];
242
+ try {
243
+ examples = env.examplesFor(report, prepared);
244
+ } catch (err) {
245
+ env.warn('ai.examples_failed', { error: errName(err) });
246
+ }
247
+ let input: AIReadInput = prepared.input;
248
+ let exampleIds: string[] = [];
249
+ try {
250
+ if (examples.length > 0) {
251
+ input = prepared.build(examples);
252
+ exampleIds = usedExampleIds(examples);
253
+ }
254
+ } catch (err) {
255
+ env.warn('ai.examples_failed', { error: errName(err) });
256
+ }
257
+
258
+ // The call, under a hard deadline.
259
+ const controller = new AbortController();
260
+ env.track(controller);
261
+ let timedOut = false;
262
+ const timer = setTimeout(() => {
263
+ timedOut = true;
264
+ controller.abort();
265
+ }, env.timeoutMs);
266
+ (timer as { unref?: () => void }).unref?.();
267
+ env.meter.inflight += 1;
268
+ const startedAt = env.clock.now();
269
+ let result: AIReadResult | undefined;
270
+ let thrown: unknown;
271
+ let failed = false;
272
+ try {
273
+ result = await raceAbort(Promise.resolve(env.adapter.read(input, { signal: controller.signal })), controller.signal);
274
+ } catch (err) {
275
+ failed = true;
276
+ thrown = err;
277
+ } finally {
278
+ clearTimeout(timer);
279
+ env.untrack(controller);
280
+ env.meter.inflight -= 1;
281
+ }
282
+ // The service is closing: the store may already be going away. The lease runs out and the read is taken up later.
283
+ if (env.closed()) return NOTHING;
284
+ const latency = env.clock.now() - startedAt;
285
+
286
+ if (failed) return settleFailure(env, { id, lease, reportId, hash: prepared.hash, kind: kindOf(thrown, timedOut) });
287
+
288
+ const usage = safeUsage((result as { usage?: Partial<AIUsage> } | null)?.usage, latency);
289
+ env.meter.usage(usage);
290
+
291
+ let verdict: ReturnType<typeof validateAIOutput>;
292
+ try {
293
+ verdict = validateAIOutput((result as { output?: unknown } | null)?.output, {
294
+ sent: prepared.refs,
295
+ activeRules: prepared.activeRules,
296
+ ownRefs: prepared.ownRefs,
297
+ });
298
+ } catch {
299
+ verdict = { ok: false, code: 'unreadable' };
300
+ }
301
+ if (!verdict.ok) {
302
+ // Paid for, and counted in the spend, although there is no read. A model's malformed or truncated answer is not deterministic,
303
+ // so the first one is tried again once (a minute later); a second is final.
304
+ env.meter.invalidCode(verdict.code);
305
+ env.breaker.success();
306
+ if (lease < 2) {
307
+ const retryAt = env.clock.now() + (RETRY_AFTER_MS[0] ?? RACE_RETRY_MS);
308
+ env.store.failAiRead(id, lease, 'failed', 'invalid', retryAt, usage);
309
+ return { park: retryAt };
310
+ }
311
+ if (env.store.failAiRead(id, lease, 'invalid', 'invalid', null, usage)) env.auditRead(reportId);
312
+ return { park: Number.POSITIVE_INFINITY };
313
+ }
314
+
315
+ const toIds = (refs: readonly string[]): string[] => refs.flatMap((ref) => {
316
+ const lineId = prepared.idOf.get(ref);
317
+ return lineId === undefined ? [] : [lineId];
318
+ });
319
+ const injected = verdict.read.injectionSuspected || prepared.injection;
320
+ const rec = verdict.read.recommendation;
321
+ const read: AIRead = {
322
+ ...verdict.read,
323
+ evidence: toIds(verdict.read.evidence),
324
+ // A line that tried to instruct the AI makes the whole read low confidence, whatever the model said.
325
+ confidence: injected ? 'low' : verdict.read.confidence,
326
+ injectionSuspected: injected,
327
+ recommendation: rec === null ? null : { ...rec, evidence: toIds(rec.evidence) },
328
+ };
329
+ env.breaker.success();
330
+ const stored = env.store.completeAiRead(id, lease, { ...usage, read, exampleIds });
331
+ if (!stored) {
332
+ env.warn('ai.read_superseded');
333
+ return NOTHING;
334
+ }
335
+ env.auditRead(reportId);
336
+ return NOTHING;
337
+ }
338
+
339
+ /** An adapter failure: retry on the schedule, or give up (and say so once). */
340
+ function settleFailure(env: WorkerEnv, f: { id: string; lease: number; reportId: string; hash: string; kind: CallKind }): ReadEnd {
341
+ const { id, lease, reportId, kind } = f;
342
+ const final: ReadEnd = { park: Number.POSITIVE_INFINITY };
343
+ if (kind === 'declined') {
344
+ // A refusal is an answer: stored, not retried, and the provider is up.
345
+ env.breaker.success();
346
+ if (env.store.failAiRead(id, lease, 'declined', 'declined', null)) env.auditRead(reportId);
347
+ return final;
348
+ }
349
+ const errorKind: AiErrorKind = kind;
350
+ if (kind === 'fatal') {
351
+ env.breaker.failure(true);
352
+ if (env.store.failAiRead(id, lease, 'failed', errorKind, null)) env.auditRead(reportId);
353
+ return final;
354
+ }
355
+ env.breaker.failure();
356
+ if (lease >= MAX_ATTEMPTS) {
357
+ // Three calls in all: given up.
358
+ if (env.store.failAiRead(id, lease, 'failed', errorKind, null)) env.auditRead(reportId);
359
+ return final;
360
+ }
361
+ const retryAt = env.clock.now() + (RETRY_AFTER_MS[lease - 1] ?? RETRY_AFTER_MS[RETRY_AFTER_MS.length - 1] ?? RACE_RETRY_MS);
362
+ env.store.failAiRead(id, lease, 'failed', errorKind, retryAt);
363
+ return { park: retryAt };
364
+ }
package/src/audit.ts CHANGED
@@ -11,7 +11,11 @@ export type Role = (typeof ROLES)[number];
11
11
 
12
12
  /**
13
13
  * The closed list of things the audit trail records. The `term.*` and `exception.*` names also cover the rows the
14
- * term editor (`LiveTerms`) wrote before the trail existed.
14
+ * term editor (`LiveTerms`) wrote before the trail existed. The list only ever grows at the end.
15
+ *
16
+ * The three `ai.*` actions target a report and carry no detail: `ai.read` is written by the AI itself (an `ai:` actor, no role)
17
+ * when a read finishes, `ai.rerun` by a moderator who asked for another read, `ai.outcome` by a moderator whose decision was
18
+ * recorded against a read.
15
19
  */
16
20
  export const AUDIT_ACTIONS = [
17
21
  'report.view',
@@ -37,6 +41,9 @@ export const AUDIT_ACTIONS = [
37
41
  'policy.reset',
38
42
  'report.dismiss_case',
39
43
  'report.dismiss_reporter',
44
+ 'ai.read',
45
+ 'ai.rerun',
46
+ 'ai.outcome',
40
47
  ] as const;
41
48
  export type AuditAction = (typeof AUDIT_ACTIONS)[number];
42
49
 
@@ -53,6 +60,12 @@ export interface AuditDetail {
53
60
  /** The longest reason a policy audit row keeps. */
54
61
  export const AUDIT_REASON_MAX = 2000;
55
62
 
63
+ /** The actions that point at a report (and only at one), and carry nothing else. */
64
+ const AI_ACTIONS: readonly string[] = ['ai.read', 'ai.rerun', 'ai.outcome'];
65
+
66
+ /** An actor that is the AI itself, not a person: `ai:` and the adapter's id (`ai:anthropic:claude-haiku-5-5`). */
67
+ const AI_ACTOR_PREFIX = 'ai:';
68
+
56
69
  /** The actions whose row carries an {@link AuditDetail}, and the only ones that may. */
57
70
  const DETAIL_ACTIONS: readonly string[] = ['policy.update', 'policy.reset'];
58
71
 
@@ -77,7 +90,8 @@ export interface AuditRecordInput {
77
90
  * them as they are.)
78
91
  */
79
92
  actor: string;
80
- role: Role;
93
+ /** The staff member's role. `null` only for the AI's own actor (`ai:<adapter id>`), which records `ai.read` and nothing else. */
94
+ role: Role | null;
81
95
  action: AuditAction;
82
96
  target?: AuditTarget;
83
97
  /** Required for `policy.update` and `policy.reset` (and refused for every other action). */
@@ -204,7 +218,14 @@ function parse(input: unknown): AuditRecordInput | null {
204
218
  if (typeof input !== 'object' || input === null) return null;
205
219
  const { actor, role, action, target, detail } = input as Record<string, unknown>;
206
220
  if (typeof actor !== 'string' || !ACTOR_RE.test(actor)) return null;
207
- if (!isRole(role) || !isAction(action)) return null;
221
+ if (!isAction(action)) return null;
222
+ // The AI is the one actor with no role: `ai:<adapter id>` records `ai.read`, and only it does. A person always has a role.
223
+ if (actor.startsWith(AI_ACTOR_PREFIX)) {
224
+ if (actor.length === AI_ACTOR_PREFIX.length || role !== null || action !== 'ai.read') return null;
225
+ } else if (!isRole(role) || action === 'ai.read') {
226
+ return null;
227
+ }
228
+ const roleOut: Role | null = actor.startsWith(AI_ACTOR_PREFIX) ? null : (role as Role);
208
229
  // A policy row must say what it changed; no other row may carry anything but ids.
209
230
  let parsedDetail: AuditDetail | undefined;
210
231
  if (DETAIL_ACTIONS.includes(action)) {
@@ -215,11 +236,12 @@ function parse(input: unknown): AuditRecordInput | null {
215
236
  return null;
216
237
  }
217
238
  const extra = parsedDetail === undefined ? {} : { detail: parsedDetail };
218
- if (target === undefined) return { actor, role, action, ...extra };
239
+ if (target === undefined) return AI_ACTIONS.includes(action) ? null : { actor, role: roleOut, action, ...extra };
219
240
  if (typeof target !== 'object' || target === null) return null;
220
241
  const { type, ref } = target as Record<string, unknown>;
221
242
  if (!isTargetType(type) || typeof ref !== 'string' || !REF_RE.test(ref)) return null;
222
- return { actor, role, action, target: { type, ref }, ...extra };
243
+ if (AI_ACTIONS.includes(action) && type !== 'report') return null;
244
+ return { actor, role: roleOut, action, target: { type, ref }, ...extra };
223
245
  }
224
246
 
225
247
  /**
@@ -241,6 +263,10 @@ export class AuditService {
241
263
  /**
242
264
  * Write one entry, now. Synchronous and fenced: it never throws, and returns false (nothing written, one log line
243
265
  * carrying the event name and at most the error class) for an input outside the closed lists or a store failure.
266
+ *
267
+ * A person always has a `role`. The AI is the one actor without: pass `role: null` explicitly (`undefined` is refused) with an actor
268
+ * that begins `ai:` (and is longer than that), for `ai.read` only. So a staff ref or login that begins `ai:` is refused (false), and
269
+ * so is `ai.read` from anyone else. The three `ai.*` actions need a `report` target and take no detail.
244
270
  */
245
271
  record(input: AuditRecordInput): boolean {
246
272
  try {
package/src/chatwarden.ts CHANGED
@@ -1,3 +1,5 @@
1
+ import { createInertAi } from './ai/inert.js';
2
+ import type { AiFacade, AiOptions, AiService } from './ai/service.js';
1
3
  import { AuditService } from './audit.js';
2
4
  import type { AuditPage, AuditQuery, AuditRecordInput } from './audit.js';
3
5
  import { ChatService } from './chat.js';
@@ -194,6 +196,14 @@ export interface ChatwardenOptions {
194
196
  * `RangeError`; set it when your registry numbers slurs differently.
195
197
  */
196
198
  autoRestrictRule?: number;
199
+ /**
200
+ * AI levels 1 and 2 (read, and recommend). Off unless you give an adapter; the level itself is a moderator setting
201
+ * (`profile.ai.level`, default 0) held to at most `maxLevel`. Needs a store with the AI methods (SQLite has them; the
202
+ * in-memory store has them through `withMemoryAi`). A store without them leaves the AI inert and logs `chatwarden.ai_store_unsupported`
203
+ * once at creation, as with any optional Store method; a bad option still throws. The adapter runs on the server only; see `ModerationAI`.
204
+ * @experimental
205
+ */
206
+ ai?: AiOptions;
197
207
  }
198
208
 
199
209
  /** The moderation kit as an adopter uses it. Nothing here returns an identifier meant for a player. */
@@ -243,6 +253,15 @@ export interface Chatwarden {
243
253
  * address alone finds nobody). An empty `roomId` or `seatId` counts as not given. Never carries an identifier.
244
254
  */
245
255
  restricted(who: RawWho, opts?: { roomId?: string | null; seatId?: string | null }): RestrictedAnswer;
256
+ /**
257
+ * `restricted` for a person you already hold as a subject id (`cw.rooms.subjectAt`), so a server that keeps a seated player's
258
+ * connection open can ask again without keeping their raw client key, account or address in memory. The same answer, the same
259
+ * rules (a merge is followed, a failure reads as not restricted and is logged once a minute), the same shape; `opts` as in
260
+ * `restricted`. A value that is not a subject id, or a subject nobody holds, reads `{ restricted: false, until: null, kind: null }`.
261
+ * A subject id is an identifier: pass it from server code, never from what a client sent, and never send it to a player.
262
+ * @experimental
263
+ */
264
+ restrictedBySubject(subject: SubjectId, opts?: { roomId?: string | null; seatId?: string | null }): RestrictedAnswer;
246
265
  };
247
266
  mutes: {
248
267
  /** `viewerSeat`'s occupant mutes (`on`) or unmutes `targetSeat`'s occupant. Does nothing if either seat has no subject. */
@@ -451,6 +470,13 @@ export interface Chatwarden {
451
470
  */
452
471
  check(text: string): { ok: true } | { ok: false; reason: 'name_not_allowed'; rule: number };
453
472
  };
473
+ /**
474
+ * The AI read and recommend service. Always present: without an `ai` option (or at level 0) it answers as if there were no AI. A
475
+ * read is made after the report is stored and never delays the player's ack; a failing, slow or refusing provider changes nothing
476
+ * for players or moderators. Staff only: a read describes chat lines.
477
+ * @experimental
478
+ */
479
+ ai: AiFacade;
454
480
  /** The registry in use (the one given, or the starter rules for the profile). Retired rules stay listed. */
455
481
  rules: CommunityRules;
456
482
  /**
@@ -663,6 +689,12 @@ export async function createChatwarden(opts: ChatwardenOptions): Promise<Chatwar
663
689
  if (opts.retention !== false && purgeEveryMs > MAX_PURGE_EVERY_MS) {
664
690
  throw new RangeError(`retention.everyMs must be at most ${MAX_PURGE_EVERY_MS}`);
665
691
  }
692
+ // The AI service is loaded only when an adapter is given, so a bundler can leave it (about 40 KB minified) out of a build that never passes one.
693
+ const aiModule = opts.ai === undefined ? undefined : await import('./ai/service.js');
694
+ // A bad option throws here. A store without the AI methods (the in-memory store has them only through `withMemoryAi`) does not: the AI stays
695
+ // inert and the kit says so once, like any optional Store method it cannot use.
696
+ const aiMissing = opts.ai !== undefined && aiModule !== undefined ? aiModule.checkAiSetup(store, opts.ai) : [];
697
+ if (aiMissing.length > 0) safeWarn(logger, 'chatwarden.ai_store_unsupported', { missing: aiMissing.join(',') });
666
698
  const rules = opts.rules ?? defineRules(starterRules(baseProfile.rules));
667
699
  const autoRestrictRule = opts.autoRestrictRule ?? 1;
668
700
  const autoRule = rules.get(autoRestrictRule);
@@ -737,6 +769,8 @@ export async function createChatwarden(opts: ChatwardenOptions): Promise<Chatwar
737
769
  limits: limits.reports,
738
770
  });
739
771
  const doors = new DoorService({ hasher, subjects, sanctions, clock, logger, notices });
772
+ // The AI service is built after the audit trail it writes to; a decision reaches it through this late binding.
773
+ const aiRef: { service?: AiService } = {};
740
774
  const decisions = new DecisionService({
741
775
  store,
742
776
  subjects,
@@ -746,6 +780,7 @@ export async function createChatwarden(opts: ChatwardenOptions): Promise<Chatwar
746
780
  index: sanctions,
747
781
  logger,
748
782
  reporterFeedback: limits.reporterFeedback,
783
+ aiOutcome: (args) => aiRef.service?.outcomeOf(args) ?? null,
749
784
  });
750
785
 
751
786
  // The person behind a player's connection details, FOUND and never created. An IP alone finds nobody.
@@ -837,6 +872,15 @@ export async function createChatwarden(opts: ChatwardenOptions): Promise<Chatwar
837
872
  } catch (err) {
838
873
  eventFailed(err);
839
874
  }
875
+ // A decision recorded against an AI read leaves one audit row, written by the moderator (best effort: it never fails the decision).
876
+ const recorded = committed.aiOutcome;
877
+ if (recorded !== null && recorded.role !== null) {
878
+ try {
879
+ audit.record({ actor: recorded.actor, role: recorded.role, action: 'ai.outcome', target: { type: 'report', ref: committed.reportId } });
880
+ } catch (err) {
881
+ eventFailed(err);
882
+ }
883
+ }
840
884
  }
841
885
  return result;
842
886
  };
@@ -851,7 +895,27 @@ export async function createChatwarden(opts: ChatwardenOptions): Promise<Chatwar
851
895
  });
852
896
  const reasonBook = new ReasonBook(store);
853
897
 
898
+ // The AI read service. It listens for new reports and only enqueues; with no adapter it is a facade that is always off.
899
+ const aiService =
900
+ opts.ai === undefined || aiModule === undefined || aiMissing.length > 0
901
+ ? undefined
902
+ : new aiModule.AiService({
903
+ options: opts.ai,
904
+ store,
905
+ clock,
906
+ logger,
907
+ profile: () => policy.profileNow(),
908
+ rules,
909
+ suggest: (subject, level, rule, context) => suggest(policy.profileNow(), historyOf(store, subjects, subject, clock.now()), level, rule, clock.now(), context),
910
+ subscribe: bus.on,
911
+ audit: (input) => audit.record(input),
912
+ exampleRetentionMs: () => retentionPolicy.aiExamplesMs ?? RETENTION_DEFAULTS.aiExamplesMs,
913
+ });
914
+ aiRef.service = aiService;
915
+ const ai: AiFacade = aiService ?? createInertAi();
916
+
854
917
  return {
918
+ ai,
855
919
  rooms: {
856
920
  seat,
857
921
  seatConnection: (roomId, seatId, ctx, handle, tags) => {
@@ -880,6 +944,15 @@ export async function createChatwarden(opts: ChatwardenOptions): Promise<Chatwar
880
944
  return { restricted: false, until: null, kind: null };
881
945
  }
882
946
  },
947
+ restrictedBySubject: (subject, o) => {
948
+ if (typeof subject !== 'string' || subject === '') return { restricted: false, until: null, kind: null };
949
+ try {
950
+ return chat.restricted(subject, o?.roomId, o?.seatId);
951
+ } catch (err) {
952
+ restrictedWarn.warn('chatwarden.restricted_failed', { error: err instanceof Error ? err.name : typeof err });
953
+ return { restricted: false, until: null, kind: null };
954
+ }
955
+ },
883
956
  },
884
957
  mutes: {
885
958
  set: (roomId, viewerSeat, targetSeat, on) => {
@@ -896,7 +969,12 @@ export async function createChatwarden(opts: ChatwardenOptions): Promise<Chatwar
896
969
  if (res.ok) announceReport(res.reportId);
897
970
  return res;
898
971
  },
899
- addDetail: (reportId, reporterSeat, detail) => reports.addDetail(reportId, reporterSeat, detail),
972
+ addDetail: async (reportId, reporterSeat, detail) => {
973
+ const res = await reports.addDetail(reportId, reporterSeat, detail);
974
+ // The follow-up changes what the AI would read: queue one new read (it only enqueues; the reporter's ack never waits).
975
+ if (res.ok) aiService?.caseChanged(reportId);
976
+ return res;
977
+ },
900
978
  list: (q) => listStaffReports(store, subjects, q, policy.profileNow().reporting.reasons),
901
979
  get: (id) => {
902
980
  const record = typeof id === 'string' ? store.loadReport(id) : null;
@@ -1092,6 +1170,9 @@ export async function createChatwarden(opts: ChatwardenOptions): Promise<Chatwar
1092
1170
  close: async () => {
1093
1171
  if (timer !== undefined) clearInterval(timer);
1094
1172
  timer = undefined;
1173
+ // Stop reading and abort calls in flight, and let them end before the store goes.
1174
+ ai.close();
1175
+ await ai.idle();
1095
1176
  await subjects.flush();
1096
1177
  store.close();
1097
1178
  },