@clawchatsai/connector 0.2.5 → 0.2.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.
@@ -0,0 +1,328 @@
1
+ // Tagger: gives each chat a one-line summary and a few tags, so search finds it by topic and the
2
+ // user can browse by subject (#proxmox). Runs in the connector, whether or not a browser is open.
3
+ //
4
+ // When: a chat is tagged once it has MIN_MESSAGES messages and has been quiet for QUIET_MS after
5
+ // the search index (server/search/) caught up with it, and tagged again once it has grown by half
6
+ // (and at least REGROW_MIN messages): the topic of a long chat drifts. Chats whose last activity
7
+ // predates tagging (the `since` mark) are the user's history: they're only tagged after the user
8
+ // accepts the backfill offer, which states the cost first.
9
+ //
10
+ // Input: the chat's text from the search index, so tagging never reads the gateway itself. Output:
11
+ // the tag store (store.js, global.db), copied into the index (chat_meta) so search matches it.
12
+ //
13
+ // Model: a host-run completion (api.runtime.llm.complete, no session). A cheap model is asked for
14
+ // first (CHEAP_MODELS); the gateway only allows that when the owner set
15
+ // plugins.entries.connector.llm.allowModelOverride + allowedModels, otherwise the call is refused
16
+ // before any inference and the gateway's default model is used. One chat at a time.
17
+
18
+ import { createCompletion } from '../controllers/title.js';
19
+ import { SYSTEM_PROMPT, buildPrompt, condense, parseReply, estimateCost, isSubscription } from './model.js';
20
+
21
+ export const MIN_MESSAGES = 6;
22
+ const REGROW_FACTOR = 1.5;
23
+ const REGROW_MIN = 10;
24
+ const QUIET_MS = 2 * 60 * 1000;
25
+ const SWEEP_MS = 10 * 60 * 1000;
26
+ const GAP_MS = 1500; // between two completions
27
+ const CHEAP_MODELS = ['anthropic/claude-haiku-4-5-20251001', 'claude-cli/claude-haiku-4-5-20251001'];
28
+ const MODEL_RECHECK_MS = 6 * 60 * 60 * 1000; // a refused model is tried again after this
29
+ const BACKOFF_MS = [5 * 60_000, 30 * 60_000, 3 * 60 * 60_000, 24 * 60 * 60_000];
30
+ const backoffMs = attempts => BACKOFF_MS[Math.min(Math.max(attempts, 1) - 1, BACKOFF_MS.length - 1)];
31
+ const LIFECYCLE_RETRY_MS = 30_000;
32
+ // A failure worth retrying later on the same cheap model (rather than moving the chat to a pricier
33
+ // one). Anything else on a cheap model (unknown to this gateway's catalog, no credentials, a runtime
34
+ // that can't run it) means it isn't usable here: the next candidate is tried.
35
+ const TRANSIENT_CODES = new Set(['LLM_COMPLETION_TIMEOUT', 'LLM_COMPLETION_ABORTED']);
36
+ const TRANSIENT = /rate.?limit|too many requests|\b429\b|overload|\b529\b|timed? ?out|timeout|ECONNRESET|ECONNREFUSED|ETIMEDOUT|EAI_AGAIN|socket hang up|\b50[0234]\b|temporar|try again/i;
37
+ const PROBE_DELAY_MS = 15_000;
38
+ // The host refused because the plugin is reloading or stopping (LLM_RUNTIME_LIFECYCLE; 2026.11.6 also
39
+ // reports a retired runtime by message only): no inference ran, nothing is wrong with the model or chat.
40
+ const isLifecycle = e => e?.code === 'LLM_RUNTIME_LIFECYCLE' || /runtime is no longer active|runtime (has )?retired|plugin is reloading/i.test(e?.message || '');
41
+ const SAMPLE_COSTS = 20; // recent measured costs behind the backfill estimate
42
+
43
+ export class Tagger {
44
+ /**
45
+ * @param {object} o
46
+ * @param {ReturnType<import('./store.js').createTagStore>} o.tags
47
+ * @param {import('../search/store.js').SearchStore} o.search
48
+ * @param {import('../search/indexer.js').SearchIndexer} o.indexer
49
+ * @param {{ complete?: Function }} o.llm api.runtime.llm
50
+ * @param {() => Array<{ key, summary, keywords, messages, taggedAt }>} [o.legacy] pre-gateway summaries
51
+ * @param {(frame: object) => void} [o.notify]
52
+ */
53
+ constructor({ tags, search, indexer, llm, legacy = () => [], notify = () => {}, logger = console, now = () => Date.now(), quietMs = QUIET_MS, gapMs = GAP_MS, sweepMs = SWEEP_MS }) {
54
+ Object.assign(this, { tags, search, indexer, llm, legacy, notify, log: logger, now, quietMs, gapMs, sweepMs });
55
+ this.complete = typeof llm?.complete === 'function' ? createCompletion(llm, { systemPrompt: SYSTEM_PROMPT, purpose: 'clawchats.tags', maxTokens: 400 }) : null;
56
+ this.timers = new Map(); // key -> debounce timer
57
+ this.queue = new Set();
58
+ this.forced = new Set(); // Re-tag asked by the user: runs regardless of the rules
59
+ this.refused = new Map(); // model -> when the gateway refused it
60
+ this.running = false;
61
+ this.current = null;
62
+ this.lastError = null;
63
+ this.lastModel = this.tags.meta('model');
64
+ this.closed = false;
65
+ if (this.tags.meta('since') == null) this.tags.setMeta('since', this.now());
66
+ }
67
+
68
+ start() {
69
+ this._onSynced = key => this._guard(() => this._changed(key));
70
+ this._onRemoved = key => this._guard(() => { this._drop(key); if (this.tags.delete(key)) this.announce(key); });
71
+ this._onReady = () => this._guard(() => this.sweep());
72
+ this.indexer.on('synced', this._onSynced);
73
+ this.indexer.on('removed', this._onRemoved);
74
+ this.indexer.on('ready', this._onReady);
75
+ this.interval = setInterval(() => this._guard(() => this.sweep()), this.sweepMs);
76
+ this.interval.unref?.();
77
+ this._guard(() => { this._copyAllToIndex(); this.sweep(); });
78
+ if (!this.lastModel) { this._probeTimer = setTimeout(() => this.probe().catch(() => {}), PROBE_DELAY_MS); this._probeTimer.unref?.(); }
79
+ }
80
+
81
+ /**
82
+ * Which model tags on this gateway, found once with a tiny completion (a refused override costs
83
+ * nothing; an allowed one a few tokens), so Settings and the backfill offer name the right model
84
+ * and price before the first chat is tagged.
85
+ */
86
+ async probe() {
87
+ if (this.lastModel || !this.enabled || !this.complete || this.closed) return;
88
+ try {
89
+ const { result, model } = await this._complete('Reply with {}');
90
+ const used = result?.provider && result?.model ? `${result.provider}/${result.model}` : model;
91
+ if (used && !this.lastModel) { this.lastModel = used; this.tags.setMeta('model', used); this._status(); }
92
+ } catch (e) { this.log.info?.(`[tags] model check: ${e?.code || e?.message}`); }
93
+ }
94
+
95
+ close() {
96
+ this.closed = true;
97
+ clearInterval(this.interval);
98
+ clearTimeout(this._probeTimer);
99
+ for (const t of this.timers.values()) clearTimeout(t);
100
+ this.timers.clear();
101
+ this.queue.clear();
102
+ this.indexer.off('synced', this._onSynced);
103
+ this.indexer.off('removed', this._onRemoved);
104
+ this.indexer.off('ready', this._onReady);
105
+ }
106
+
107
+ _guard(fn) { try { return fn(); } catch (e) { this.log.warn?.(`[tags] ${e.message}`); } }
108
+
109
+ get enabled() { return this.tags.meta('enabled') !== '0'; }
110
+
111
+ /** 'accepted' | 'declined' | null (not asked yet) */
112
+ get backfill() { return this.tags.meta('backfill'); }
113
+
114
+ setEnabled(on) {
115
+ this.tags.setMeta('enabled', on ? '1' : '0');
116
+ if (on) this.sweep(); else { this.queue.clear(); for (const t of this.timers.values()) clearTimeout(t); this.timers.clear(); }
117
+ this._status();
118
+ }
119
+
120
+ setBackfill(answer) {
121
+ this.tags.setMeta('backfill', answer === 'accepted' ? 'accepted' : 'declined');
122
+ if (answer === 'accepted') this.sweep();
123
+ else for (const key of [...this.queue]) if (!this.forced.has(key) && this._isHistory(key)) this.queue.delete(key);
124
+ this._status();
125
+ }
126
+
127
+ // ── When ──────────────────────────────────────────────────────────
128
+
129
+ /** The index caught up with a chat: copy its tags over (new chat, or after a Rebuild), and tag it once it has been quiet. */
130
+ _changed(key) {
131
+ const row = this.tags.get(key);
132
+ if (row && !this.search.hasMeta(key)) this._copyToIndex(key, row);
133
+ if (!this.enabled || this.closed) return;
134
+ clearTimeout(this.timers.get(key));
135
+ const t = setTimeout(() => { this.timers.delete(key); this._guard(() => { if (this._due(key)) { this.queue.add(key); this._drain(); } }); }, this.quietMs);
136
+ t.unref?.();
137
+ this.timers.set(key, t);
138
+ }
139
+
140
+ _isHistory(key) {
141
+ const chat = this.search.getChat(key);
142
+ return !chat || chat.stamp <= Number(this.tags.meta('since'));
143
+ }
144
+
145
+ /** Whether a chat should be tagged (again) now. */
146
+ _due(key, row = this.tags.get(key), count = this.search.messageCount(key)) {
147
+ if (!this.search.getChat(key) || count < MIN_MESSAGES) return false;
148
+ if (row?.error && this.now() - row.errorAt < backoffMs(row.attempts)) return false;
149
+ if (row?.source !== 'auto') return this.backfill === 'accepted' || !this._isHistory(key);
150
+ return count >= Math.max(row.messages * REGROW_FACTOR, row.messages + REGROW_MIN);
151
+ }
152
+
153
+ /** Queue every chat that's due (start, every SWEEP_MS, after enabling or accepting the backfill). */
154
+ sweep() {
155
+ if (this.closed) return;
156
+ // Housekeeping once the index has the whole roster: old summaries in, rows of deleted chats out.
157
+ if (this.search.completedAt != null) { this._importLegacy(); this._prune(); }
158
+ if (!this.enabled) return;
159
+ const rows = new Map(this.tags.all().map(r => [r.key, r]));
160
+ for (const c of this.search.taggable(MIN_MESSAGES)) if (this._due(c.key, rows.get(c.key), c.messages)) this.queue.add(c.key);
161
+ this._drain();
162
+ }
163
+
164
+ /** Re-tag one chat now (the user asked). */
165
+ retag(key) {
166
+ if (!this.search.getChat(key)) throw Object.assign(new Error('That chat isn\'t in the search index yet'), { status: 409 });
167
+ if (!this.complete) throw Object.assign(new Error('This OpenClaw version has no plugin model completion'), { status: 501 });
168
+ this.forced.add(key);
169
+ this.queue.delete(key);
170
+ this.queue = new Set([key, ...this.queue]); // ahead of the backlog
171
+ this._drain();
172
+ }
173
+
174
+ _drop(key) { clearTimeout(this.timers.get(key)); this.timers.delete(key); this.queue.delete(key); this.forced.delete(key); }
175
+
176
+ // ── Work ──────────────────────────────────────────────────────────
177
+
178
+ _drain() {
179
+ if (this.running || this.closed || !this.complete) return this.draining;
180
+ this.draining = this._drainLoop();
181
+ return this.draining;
182
+ }
183
+
184
+ async _drainLoop() {
185
+ this.running = true;
186
+ try {
187
+ while (this.queue.size && !this.closed) {
188
+ const key = this.queue.values().next().value;
189
+ this.queue.delete(key);
190
+ const forced = this.forced.delete(key);
191
+ if (!forced && (!this.enabled || !this._due(key))) continue;
192
+ this.current = key;
193
+ this._status();
194
+ try { await this.tagChat(key); }
195
+ catch (e) {
196
+ if (this.closed) break; // stopped mid-call (plugin reload): the next instance tags it
197
+ if (isLifecycle(e)) { // the gateway is reloading: no inference ran, try later
198
+ const t = setTimeout(() => { this.timers.delete(key); this.queue.add(key); this._drain(); }, LIFECYCLE_RETRY_MS);
199
+ t.unref?.();
200
+ this.timers.set(key, t);
201
+ break;
202
+ }
203
+ this.lastError = { key, message: e.message, at: this.now() };
204
+ if (this.search.getChat(key)) this.tags.markFailed(key, e.message);
205
+ this.log.warn?.(`[tags] ${key}: ${e.message}`);
206
+ }
207
+ this.current = null;
208
+ this._status();
209
+ if (this.queue.size) await new Promise(r => setTimeout(r, this.gapMs));
210
+ }
211
+ } finally {
212
+ this.running = false;
213
+ this.current = null;
214
+ this._status();
215
+ }
216
+ }
217
+
218
+ /** Tag one chat: its text from the index → the model → tag store → index. */
219
+ async tagChat(key) {
220
+ const chat = this.search.getChat(key);
221
+ if (!chat) return null;
222
+ const messages = this.search.messages(key);
223
+ const count = messages.filter(m => m.kind === 'message').length;
224
+ const vocabulary = this.tags.vocabulary().map(v => v.tag);
225
+ const prompt = buildPrompt({ title: chat.title, conversation: condense(messages), vocabulary });
226
+ const { result, model } = await this._complete(prompt);
227
+ if (this.closed) return null; // stopped while the model was answering
228
+ const parsed = parseReply(result?.text, { vocabulary: new Set(vocabulary), aliases: this.tags.aliases() });
229
+ if (!this.search.getChat(key)) return null; // deleted while the model was answering
230
+ const usedModel = result?.provider && result?.model ? `${result.provider}/${result.model}` : model;
231
+ if (usedModel && usedModel !== this.lastModel) this.tags.setMeta('model', usedModel);
232
+ this.lastModel = usedModel;
233
+ this.lastError = null;
234
+ const row = this.tags.saveAuto(key, { ...parsed, model: usedModel, messages: count, costUsd: result?.usage?.costUsd ?? null });
235
+ this._copyToIndex(key, row);
236
+ this.announce(key, row);
237
+ return row;
238
+ }
239
+
240
+ /** The completion on the first cheap model the gateway allows, else on its default model. */
241
+ async _complete(prompt) {
242
+ for (const model of CHEAP_MODELS) {
243
+ if (this._refused(model)) continue;
244
+ try {
245
+ const result = await this.complete(prompt, { model });
246
+ // Every credential for it failed (the host resolves rather than throws): not usable here.
247
+ if (result?.stopReason === 'error') throw new Error(result.errorMessage || 'provider error');
248
+ return { result, model };
249
+ } catch (e) {
250
+ if (isLifecycle(e) || TRANSIENT_CODES.has(e?.code) || TRANSIENT.test(e?.message || '')) throw e; // retried later, same model
251
+ // No override permission: refused before any inference, for every model.
252
+ if (e?.code === 'LLM_COMPLETION_NOT_AUTHORIZED') { for (const m of CHEAP_MODELS) this.refused.set(m, this.now()); }
253
+ else this.refused.set(model, this.now());
254
+ this.log.info?.(`[tags] ${model} unavailable here (${e?.code || e?.message}); trying the next`);
255
+ }
256
+ }
257
+ const result = await this.complete(prompt);
258
+ if (result?.stopReason === 'error') throw new Error(result.errorMessage || 'the model returned an error');
259
+ return { result, model: null };
260
+ }
261
+
262
+ _refused(model) {
263
+ const at = this.refused.get(model);
264
+ return at != null && this.now() - at < MODEL_RECHECK_MS;
265
+ }
266
+
267
+ // ── Index copy ────────────────────────────────────────────────────
268
+
269
+ _copyToIndex(key, row) {
270
+ if (row) this.search.setMeta(key, { tags: row.tags, summary: row.summary, keywords: row.keywords });
271
+ }
272
+
273
+ _copyAllToIndex() { for (const row of this.tags.all()) this._copyToIndex(row.key, row); }
274
+
275
+ /** The pre-gateway ClawChats summaries (once): searchable right away, tagged like history. */
276
+ _importLegacy() {
277
+ if (this.tags.meta('legacy_imported')) return;
278
+ const rows = (this.legacy() || []).filter(r => this.search.getChat(r.key));
279
+ const n = rows.length ? this.tags.importLegacy(rows) : 0;
280
+ this.tags.setMeta('legacy_imported', this.now());
281
+ if (n) { this.log.info?.(`[tags] imported ${n} summaries from the old ClawChats databases`); this._copyAllToIndex(); }
282
+ }
283
+
284
+ /** Rows of chats the (complete) index no longer has: deleted while the connector wasn't running. */
285
+ _prune() {
286
+ const live = new Set(this.search.chatKeys());
287
+ for (const key of this.tags.keys()) if (!live.has(key) && this.tags.delete(key)) this.announce(key);
288
+ }
289
+
290
+ // ── Status ────────────────────────────────────────────────────────
291
+
292
+ /** Tell browsers a chat's tags changed. */
293
+ announce(key, row = this.tags.get(key)) {
294
+ try { this.notify({ type: 'clawchats', event: 'tags', key, tags: row?.tags || [], summary: row?.summary || '' }); } catch { /* no browsers */ }
295
+ this._status();
296
+ }
297
+
298
+ _status() {
299
+ clearTimeout(this._statusTimer);
300
+ this._statusTimer = setTimeout(() => { try { this.notify({ type: 'clawchats', event: 'tags-status', status: this.status() }); } catch { /* no browsers */ } }, 500);
301
+ this._statusTimer.unref?.();
302
+ }
303
+
304
+ /** For Settings and the backfill offer. */
305
+ status() {
306
+ const rows = new Map(this.tags.all().map(r => [r.key, r]));
307
+ const taggable = this.search.taggable(MIN_MESSAGES);
308
+ let tagged = 0, failed = 0;
309
+ const history = [];
310
+ for (const c of taggable) {
311
+ const r = rows.get(c.key);
312
+ if (r?.source === 'auto') tagged++;
313
+ else if (this._isHistory(c.key)) history.push(c);
314
+ if (r?.error) failed++;
315
+ }
316
+ const costs = [...rows.values()].filter(r => r.source === 'auto' && r.costUsd != null).sort((a, b) => b.taggedAt - a.taggedAt).slice(0, SAMPLE_COSTS);
317
+ const cheapModelRefused = CHEAP_MODELS.every(m => this._refused(m));
318
+ const model = this.lastModel || (cheapModelRefused ? null : CHEAP_MODELS[0]);
319
+ const costUsd = isSubscription(model) ? null : costs.length >= 3 ? costs.reduce((n, r) => n + r.costUsd, 0) / costs.length * history.length : estimateCost(history.map(c => c.chars || 0), model);
320
+ return {
321
+ enabled: this.enabled, available: !!this.complete,
322
+ model: this.lastModel, cheapModelRefused, subscription: isSubscription(model),
323
+ tagged, failed, waiting: this.queue.size, working: this.current,
324
+ lastError: this.lastError,
325
+ backfill: { state: this.backfill, chats: history.length, costUsd: costUsd == null ? null : Math.round(costUsd * 100) / 100 },
326
+ };
327
+ }
328
+ }
@@ -0,0 +1,309 @@
1
+ import { test } from 'node:test';
2
+ import assert from 'node:assert/strict';
3
+ import { EventEmitter } from 'node:events';
4
+ import { Database } from '../bootstrap/native.js';
5
+ import { SearchStore } from '../search/store.js';
6
+ import { createTagStore } from './store.js';
7
+ import { Tagger } from './tagger.js';
8
+
9
+ const quiet = { info() {}, warn() {} };
10
+ const A = 'agent:main:dashboard:a', B = 'agent:main:dashboard:b', OLD = 'agent:main:dashboard:old';
11
+ const reply = (o = {}) => JSON.stringify({ summary: 'Restored VM 104 from backup.', tags: ['Proxmox', 'backups'], keywords: ['vm 104'], ...o });
12
+
13
+ /** A model that answers from a queue of replies (text, or an Error to throw) and records its calls. */
14
+ function fakeLlm(...replies) {
15
+ const calls = [];
16
+ return {
17
+ calls,
18
+ async complete(p) {
19
+ calls.push(p);
20
+ const r = replies.length > 1 ? replies.shift() : replies[0];
21
+ if (r instanceof Error) throw r;
22
+ return { text: r, provider: p.model ? p.model.split('/')[0] : 'anthropic', model: p.model ? p.model.split('/')[1] : 'claude-opus-5-5', usage: { costUsd: 0.002 } };
23
+ },
24
+ };
25
+ }
26
+
27
+ function setup({ llm = fakeLlm(reply()), since = 1000, legacy = [] } = {}) {
28
+ const search = new SearchStore(null);
29
+ let clock = 5000;
30
+ const db = new Database(':memory:');
31
+ const tags = createTagStore(() => db, { now: () => clock });
32
+ const indexer = new EventEmitter();
33
+ tags.setMeta('since', since);
34
+ const tagger = new Tagger({ tags, search, indexer, llm, legacy: () => legacy, logger: quiet, now: () => clock, quietMs: 5, gapMs: 0, sweepMs: 60_000 });
35
+ const chat = (key, n, { stamp = 2000, title = 'A chat', text = i => `message ${i} about the backup` } = {}) => {
36
+ search.upsertChat({ key, title, stamp });
37
+ search.writeDocs(key, Array.from({ length: n }, (_, i) => ({ messageId: `${key}-${i}`, kind: 'message', role: i % 2 ? 'assistant' : 'user', ts: i, text: text(i) })),
38
+ { full: true, sessionId: 's', cursor: null, stamp, now: clock });
39
+ };
40
+ const settle = async () => { await new Promise(r => setTimeout(r, 30)); await tagger.draining; };
41
+ return { search, tags, indexer, tagger, chat, settle, llm, tick: ms => { clock += ms; } };
42
+ }
43
+
44
+ test('a new chat is tagged once it has 6 messages and went quiet; short chats are not', async () => {
45
+ const t = setup();
46
+ t.tagger.start();
47
+ t.chat(A, 6);
48
+ t.chat(B, 5);
49
+ t.indexer.emit('synced', A);
50
+ t.indexer.emit('synced', B);
51
+ await t.settle();
52
+ assert.deepEqual(t.tags.get(A).tags, ['proxmox', 'backups']);
53
+ assert.equal(t.tags.get(A).messages, 6);
54
+ assert.equal(t.tags.get(B), null);
55
+ assert.equal(t.llm.calls.length, 1);
56
+ assert.equal(t.llm.calls[0].model, 'anthropic/claude-haiku-4-5-20251001');
57
+ assert.equal(t.llm.calls[0].purpose, 'clawchats.tags');
58
+ // Searchable: by tag word, by summary, and #tag lists it.
59
+ assert.equal(t.search.search({ q: 'proxm' }).results[0].tagMatch, true);
60
+ assert.equal(t.search.search({ q: 'restored' }).results[0].summaryMatch, true);
61
+ assert.deepEqual(t.search.search({ q: '#proxmox' }).results.map(r => r.key), [A]);
62
+ assert.deepEqual(t.search.search({ q: '#proxmox backup' }).results.map(r => r.key), [A]);
63
+ assert.deepEqual(t.search.search({ q: '#nope' }).results, []);
64
+ assert.deepEqual(t.search.search({ q: '#prox' }).results.map(r => r.key), [A], 'prefix, while typing');
65
+ t.tagger.close();
66
+ });
67
+
68
+ test('history waits for the backfill offer; the estimate comes from measured cost once there is some', async () => {
69
+ const t = setup();
70
+ t.chat(OLD, 8, { stamp: 500 });
71
+ t.tagger.start();
72
+ await t.settle();
73
+ assert.equal(t.llm.calls.length, 0);
74
+ let s = t.tagger.status();
75
+ assert.equal(s.backfill.state, null);
76
+ assert.equal(s.backfill.chats, 1);
77
+ assert.ok(s.backfill.costUsd >= 0, 'priced for Haiku before any measurement');
78
+ t.tagger.setBackfill('accepted');
79
+ await t.settle();
80
+ assert.deepEqual(t.tags.get(OLD).tags, ['proxmox', 'backups']);
81
+ s = t.tagger.status();
82
+ assert.equal(s.backfill.chats, 0);
83
+ assert.equal(s.tagged, 1);
84
+ // Activity in a history chat makes it a current chat: tagged without the offer.
85
+ const u = setup();
86
+ u.chat(OLD, 8, { stamp: 500 });
87
+ u.tagger.start();
88
+ u.tagger.setBackfill('declined');
89
+ u.chat(OLD, 9, { stamp: 3000 });
90
+ u.indexer.emit('synced', OLD);
91
+ await u.settle();
92
+ assert.equal(u.tags.get(OLD).source, 'auto');
93
+ t.tagger.close(); u.tagger.close();
94
+ });
95
+
96
+ test('cheap model not allowed: refused before inference, the default model tags; status says so', async () => {
97
+ const refused = Object.assign(new Error('model override not allowed'), { code: 'LLM_COMPLETION_NOT_AUTHORIZED' });
98
+ const llm = fakeLlm(refused, reply());
99
+ const t = setup({ llm });
100
+ t.tagger.start();
101
+ t.chat(A, 6);
102
+ t.indexer.emit('synced', A);
103
+ await t.settle();
104
+ assert.deepEqual(llm.calls.map(c => c.model ?? null), ['anthropic/claude-haiku-4-5-20251001', null]);
105
+ assert.equal(t.tags.get(A).model, 'anthropic/claude-opus-5-5');
106
+ const s = t.tagger.status();
107
+ assert.equal(s.cheapModelRefused, true);
108
+ assert.equal(s.model, 'anthropic/claude-opus-5-5');
109
+ // The next chat goes straight to the default (no second refusal round-trip).
110
+ t.chat(B, 6);
111
+ t.indexer.emit('synced', B);
112
+ await t.settle();
113
+ assert.equal(llm.calls.at(-1).model, undefined);
114
+ assert.equal(llm.calls.length, 3);
115
+ t.tagger.close();
116
+ });
117
+
118
+ test('a cheap model whose provider fails falls through to the next one', async () => {
119
+ const llm = { calls: [], async complete(p) {
120
+ this.calls.push(p.model ?? null);
121
+ if (p.model?.startsWith('anthropic/')) return { stopReason: 'error', errorMessage: 'No API key found for provider anthropic' };
122
+ return { text: reply(), provider: 'claude-cli', model: 'claude-haiku-4-5-20251001' };
123
+ } };
124
+ const t = setup({ llm });
125
+ t.tagger.start();
126
+ t.chat(A, 6);
127
+ t.indexer.emit('synced', A);
128
+ await t.settle();
129
+ assert.deepEqual(llm.calls, ['anthropic/claude-haiku-4-5-20251001', 'claude-cli/claude-haiku-4-5-20251001']);
130
+ assert.equal(t.tags.get(A).model, 'claude-cli/claude-haiku-4-5-20251001');
131
+ t.tagger.close();
132
+ });
133
+
134
+ test('user edits survive a re-tag; growth by half re-tags; Re-tag runs regardless', async () => {
135
+ const llm = fakeLlm(reply(), reply({ tags: ['proxmox', 'zfs'] }), reply({ tags: ['zfs'] }));
136
+ const t = setup({ llm });
137
+ t.tagger.start();
138
+ t.chat(A, 6);
139
+ t.indexer.emit('synced', A);
140
+ await t.settle();
141
+ t.tags.edit(A, { add: ['Home Lab'], remove: ['backups'] });
142
+ assert.deepEqual(t.tags.get(A).tags, ['proxmox', 'home-lab']);
143
+ t.chat(A, 12); // not yet 6 + 10
144
+ t.indexer.emit('synced', A);
145
+ await t.settle();
146
+ assert.equal(llm.calls.length, 1);
147
+ t.chat(A, 16);
148
+ t.indexer.emit('synced', A);
149
+ await t.settle();
150
+ assert.equal(llm.calls.length, 2);
151
+ assert.deepEqual(t.tags.get(A).tags, ['proxmox', 'zfs', 'home-lab']);
152
+ t.tagger.retag(A);
153
+ await t.settle();
154
+ assert.equal(llm.calls.length, 3);
155
+ assert.deepEqual(t.tags.get(A).tags, ['zfs', 'home-lab']);
156
+ assert.throws(() => t.tagger.retag('agent:main:dashboard:nope'), /isn't in the search index/);
157
+ t.tagger.close();
158
+ });
159
+
160
+ test('failures back off and show in status; a gateway reload is not a failure', async () => {
161
+ const boom = new Error('rate limited');
162
+ const llm = fakeLlm(boom, boom, boom);
163
+ const t = setup({ llm });
164
+ t.tagger.start();
165
+ t.chat(A, 6);
166
+ t.indexer.emit('synced', A);
167
+ await t.settle();
168
+ const row = t.tags.get(A);
169
+ // Direct, then the isolated retry (createCompletion); never the pricier default.
170
+ assert.deepEqual([...new Set(llm.calls.map(c => c.model ?? null))], ['anthropic/claude-haiku-4-5-20251001'], 'transient: no fall-through to a pricier model');
171
+ assert.equal(row.attempts, 1);
172
+ assert.match(row.error, /rate limited/);
173
+ assert.equal(t.tagger.status().failed, 1);
174
+ assert.match(t.tagger.status().lastError.message, /rate limited/);
175
+ const calls = llm.calls.length;
176
+ t.tagger.sweep();
177
+ await t.settle();
178
+ assert.equal(llm.calls.length, calls, 'inside the backoff');
179
+ t.tick(6 * 60_000);
180
+ t.tagger.sweep();
181
+ await t.settle();
182
+ assert.equal(t.tags.get(A).attempts, 2);
183
+
184
+ const lifecycle = Object.assign(new Error('reloading'), { code: 'LLM_RUNTIME_LIFECYCLE' });
185
+ const u = setup({ llm: fakeLlm(lifecycle) });
186
+ u.tagger.start();
187
+ u.chat(B, 6);
188
+ u.indexer.emit('synced', B);
189
+ await u.settle();
190
+ assert.equal(u.tags.get(B), null);
191
+ t.tagger.close(); u.tagger.close();
192
+ });
193
+
194
+ test('model check: the first usable model is found once, before any chat is tagged', async () => {
195
+ const refused = Object.assign(new Error('override not allowed'), { code: 'LLM_COMPLETION_NOT_AUTHORIZED' });
196
+ const t = setup({ llm: fakeLlm(refused, '{}') });
197
+ await t.tagger.probe();
198
+ assert.equal(t.tagger.status().model, 'anthropic/claude-opus-5-5');
199
+ assert.equal(t.tagger.status().cheapModelRefused, true);
200
+ assert.equal(t.tags.meta('model'), 'anthropic/claude-opus-5-5');
201
+ const calls = t.llm.calls.length;
202
+ await t.tagger.probe();
203
+ assert.equal(t.llm.calls.length, calls, 'once');
204
+ // A model this gateway doesn't know: the next candidate.
205
+ const unknown = { calls: [], async complete(p) { this.calls.push(p.model ?? null); if (p.model?.startsWith('anthropic/')) throw new Error('Unknown model: anthropic/claude-haiku-4-5-20251001'); return { text: '{}', provider: 'claude-cli', model: 'claude-haiku-4-5-20251001' }; } };
206
+ const u = setup({ llm: unknown });
207
+ await u.tagger.probe();
208
+ assert.equal(u.tagger.status().model, 'claude-cli/claude-haiku-4-5-20251001');
209
+ assert.equal(u.tagger.status().cheapModelRefused, false);
210
+ });
211
+
212
+ test('plugin reload mid-call: no failure recorded, the model is not marked unusable', async () => {
213
+ let release;
214
+ const llm = { calls: 0, complete() { this.calls++; return new Promise((_, reject) => { release = () => reject(new Error('Plugin "connector" runtime is no longer active.')); }); } };
215
+ const t = setup({ llm });
216
+ t.tagger.start();
217
+ t.chat(A, 6);
218
+ t.indexer.emit('synced', A);
219
+ for (let i = 0; i < 50 && !release; i++) await new Promise(r => setTimeout(r, 5));
220
+ t.tagger.close();
221
+ release();
222
+ await t.tagger.draining;
223
+ assert.equal(t.tags.get(A), null, 'nothing stored for the chat');
224
+ assert.equal(t.tagger.status().cheapModelRefused, false);
225
+ // Without a close (the host retired the runtime under a live instance): retried later, not a failure.
226
+ let n = 0;
227
+ const u = setup({ llm: { complete() { n++; return Promise.reject(new Error('Plugin "connector" runtime is no longer active.')); } } });
228
+ u.tagger.start();
229
+ u.chat(B, 6);
230
+ u.indexer.emit('synced', B);
231
+ await u.settle();
232
+ assert.equal(u.tags.get(B), null);
233
+ assert.equal(u.tagger.status().cheapModelRefused, false);
234
+ assert.equal(n, 1, 'stopped at the first lifecycle refusal');
235
+ u.tagger.close();
236
+ });
237
+
238
+ test('a garbage reply is a failure, not empty tags', async () => {
239
+ const t = setup({ llm: fakeLlm('I cannot help with that.') });
240
+ t.tagger.start();
241
+ t.chat(A, 6);
242
+ t.indexer.emit('synced', A);
243
+ await t.settle();
244
+ assert.deepEqual(t.tags.get(A).tags, []);
245
+ assert.match(t.tags.get(A).error, /no JSON/);
246
+ t.tagger.close();
247
+ });
248
+
249
+ test('disabled: nothing is tagged until it is switched back on', async () => {
250
+ const t = setup();
251
+ t.tagger.start();
252
+ t.tagger.setEnabled(false);
253
+ t.chat(A, 6);
254
+ t.indexer.emit('synced', A);
255
+ await t.settle();
256
+ assert.equal(t.llm.calls.length, 0);
257
+ t.tagger.setEnabled(true);
258
+ await t.settle();
259
+ assert.equal(t.llm.calls.length, 1);
260
+ t.tagger.close();
261
+ });
262
+
263
+ test('removed chats lose their tags; legacy summaries import for live chats once the index is complete', async () => {
264
+ const legacy = [{ key: OLD, summary: 'Old summary about galvos', keywords: ['galvanometer'], messages: 0 }, { key: 'agent:main:x:chat:gone', summary: 'gone', keywords: [] }];
265
+ const t = setup({ legacy });
266
+ t.chat(OLD, 3, { stamp: 500 });
267
+ t.tagger.start();
268
+ assert.equal(t.tags.get(OLD), null, 'index not complete yet');
269
+ t.search.completedAt = 4000;
270
+ t.tags.edit(A, { add: ['orphan'] }); // a row for a chat the index doesn't have
271
+ t.indexer.emit('ready');
272
+ assert.equal(t.tags.get(OLD).summary, 'Old summary about galvos');
273
+ assert.equal(t.tags.get('agent:main:x:chat:gone'), null);
274
+ assert.equal(t.tags.get(A), null, 'pruned');
275
+ assert.equal(t.search.search({ q: 'galvanom' }).results[0].summaryMatch, true);
276
+ assert.equal(t.tagger.status().backfill.chats, 0, 'too short to tag');
277
+ t.search.deleteChat(OLD);
278
+ t.indexer.emit('removed', OLD);
279
+ assert.equal(t.tags.get(OLD), null);
280
+ t.tagger.close();
281
+ });
282
+
283
+ test('rename, merge and delete apply everywhere and to future model output', async () => {
284
+ const llm = fakeLlm(reply({ tags: ['proxmox'] }), reply({ tags: ['pve', 'junk'] }), reply({ tags: ['proxmox', 'junk'] }));
285
+ const t = setup({ llm });
286
+ t.tagger.start();
287
+ t.chat(A, 6);
288
+ t.chat(B, 6);
289
+ t.indexer.emit('synced', A);
290
+ await t.settle();
291
+ t.indexer.emit('synced', B);
292
+ await t.settle();
293
+ assert.deepEqual(t.tags.get(B).tags, ['pve', 'junk']);
294
+ t.tags.edit(A, { add: ['pve'] });
295
+ assert.deepEqual(t.tags.renameTag('pve', 'proxmox').sort(), [A, B]);
296
+ assert.deepEqual(t.tags.get(A).tags, ['proxmox']);
297
+ assert.deepEqual(t.tags.get(B).tags, ['proxmox', 'junk']);
298
+ t.tags.renameTag('junk', '');
299
+ assert.deepEqual(t.tags.get(B).tags, ['proxmox']);
300
+ t.tagger.retag(B);
301
+ await t.settle();
302
+ assert.deepEqual(t.tags.get(B).tags, ['proxmox'], 'deleted tag stays deleted');
303
+ assert.deepEqual(t.tags.vocabulary(), [{ tag: 'proxmox', count: 2 }]);
304
+ // Renaming back makes the old name live again.
305
+ t.tags.renameTag('proxmox', 'pve');
306
+ assert.equal(t.tags.aliases().has('pve'), false);
307
+ assert.equal(t.tags.aliases().get('proxmox'), 'pve');
308
+ t.tagger.close();
309
+ });