renor-engine 1.1.0 → 1.2.0
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.
- package/README.md +7 -2
- package/dist/.tsbuildinfo +1 -1
- package/dist/cli.js +26 -0
- package/dist/eval/indexSnapshots.js +1 -0
- package/dist/evidence/ollamaChat.js +1 -1
- package/dist/extraction/jevDecisionModel.js +307 -0
- package/dist/extraction/secretGuard.js +7 -3
- package/dist/learning/cli.js +113 -0
- package/dist/learning/schema.js +144 -0
- package/dist/learning/settings.js +45 -0
- package/dist/learning/store.js +267 -0
- package/dist/learning/tap.js +401 -0
- package/dist/memory/dreamer/adjudicate.js +215 -0
- package/dist/memory/dreamer/apply.js +120 -0
- package/dist/memory/dreamer/budget.js +64 -0
- package/dist/memory/dreamer/candidates.js +149 -0
- package/dist/memory/dreamer/collection.js +104 -0
- package/dist/memory/dreamer/dreamer.js +352 -0
- package/dist/memory/dreamer/review.js +111 -0
- package/dist/memory/factConflicts.js +2 -0
- package/dist/memory/lifecycle.js +28 -5
- package/dist/memory/writer.js +3 -2
- package/dist/mvp/agentMemory.js +3 -0
- package/dist/mvp/cli.js +11 -0
- package/dist/mvp/config.js +4 -0
- package/dist/mvp/exportAll.js +19 -0
- package/dist/mvp/server.js +118 -10
- package/dist/retrieval/orchestrator.js +69 -16
- package/dist/retrieval/rankingTrace.js +184 -0
- package/dist/sharing/cli.js +181 -0
- package/dist/sharing/examples.js +136 -0
- package/dist/sharing/fields.js +225 -0
- package/dist/sharing/loop.js +80 -0
- package/dist/sharing/project.js +327 -0
- package/dist/sharing/send.js +466 -0
- package/dist/sharing/state.js +222 -0
- package/dist/sharing/wording.js +48 -0
- package/package.json +1 -1
- package/dist/BUILD.json +0 -6
|
@@ -0,0 +1,225 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* What sharing sends, level by level. This file is the contract: the projector builds only these fields, the engine's
|
|
4
|
+
* validator refuses anything else before a request is made, the ingestion endpoint (supabase/functions/sharing-ingest) holds
|
|
5
|
+
* a copy of the same table and refuses what it does not list, and docs/TELEMETRY.md lists every name here (a test compares).
|
|
6
|
+
*
|
|
7
|
+
* Levels, in order of what leaves the machine:
|
|
8
|
+
* off nothing is recorded for sharing and nothing is sent.
|
|
9
|
+
* signals anonymous labelled numbers, computed inside the user's own data folder from the learning log. No text, no queries,
|
|
10
|
+
* no memory ids, no keys, no names, no paths.
|
|
11
|
+
* data the signals, plus the text of the examples: the query behind a retrieval, the text of the memories it returned and
|
|
12
|
+
* of the statements that were saved. Only the user's explicit choice sends this.
|
|
13
|
+
*/
|
|
14
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
15
|
+
exports.MAX_ROWS_PER_BATCH = exports.RowError = exports.TERMINAL_REFUSALS = exports.SELF_HOSTED_BATCH_FIELDS = exports.CONSENT_FIELDS = exports.CONSENT_FIELD = exports.DELETE_FIELDS = exports.BATCH_FIELDS = exports.KINDS_WITH_CANDIDATES = exports.ROW_FIELDS = exports.CANDIDATE_FIELDS = exports.MAX_EXAMPLE_TEXT = exports.SAVE_ITEM_NAMES = exports.CANDIDATE_KIND_NAMES = exports.SAVE_TOOL_NAMES = exports.RETRIEVAL_TOOL_NAMES = exports.LENGTH_BUCKETS = exports.COUNT_BUCKETS = exports.DELAY_BUCKETS = exports.ROW_KINDS = exports.CLI_WORDING_VERSION = exports.SHARING_PROTOCOL = exports.SHARING_LEVELS = void 0;
|
|
16
|
+
exports.levelRank = levelRank;
|
|
17
|
+
exports.isSharingLevel = isSharingLevel;
|
|
18
|
+
exports.lowerLevel = lowerLevel;
|
|
19
|
+
exports.modelIdentifier = modelIdentifier;
|
|
20
|
+
exports.fieldsAtLevel = fieldsAtLevel;
|
|
21
|
+
exports.validateRow = validateRow;
|
|
22
|
+
exports.SHARING_LEVELS = ['off', 'signals', 'data'];
|
|
23
|
+
exports.SHARING_PROTOCOL = 1;
|
|
24
|
+
/** The version of the words the CLI shows before a user picks signals or data. A dashboard sends its own wording id. */
|
|
25
|
+
exports.CLI_WORDING_VERSION = 'engine-cli-2026-10-21';
|
|
26
|
+
/** The order of strength: off < signals < data. */
|
|
27
|
+
function levelRank(level) {
|
|
28
|
+
return exports.SHARING_LEVELS.indexOf(level);
|
|
29
|
+
}
|
|
30
|
+
function isSharingLevel(value) {
|
|
31
|
+
return typeof value === 'string' && exports.SHARING_LEVELS.includes(value);
|
|
32
|
+
}
|
|
33
|
+
/** The lower of two levels: how an override can only ever narrow what is shared. */
|
|
34
|
+
function lowerLevel(a, b) {
|
|
35
|
+
return levelRank(a) <= levelRank(b) ? a : b;
|
|
36
|
+
}
|
|
37
|
+
exports.ROW_KINDS = ['retrieval-labelled/1', 'save-outcome/1', 'session-aggregate/1'];
|
|
38
|
+
const HOUR = '^\\d{4}-\\d{2}-\\d{2}T\\d{2}$';
|
|
39
|
+
const LANE = '^[a-z][a-z0-9-]{0,31}$';
|
|
40
|
+
const BUILD = '^[0-9a-f]{7,40}$';
|
|
41
|
+
// The embedding model as `provider:model:dims` (contextRelevance.ts embeddingModelKey): a model identifier only, so no '/',
|
|
42
|
+
// '\\', space or other path or name character can pass. A local model named by a path or `org/name` is sent as null.
|
|
43
|
+
const MODEL = '^[a-z][a-z0-9-]{0,15}:[A-Za-z0-9._-]{1,64}:[0-9]{0,6}$';
|
|
44
|
+
/** The model identifier a signals row may carry, or null when the recorded value is anything else. */
|
|
45
|
+
function modelIdentifier(value) {
|
|
46
|
+
return value !== null && new RegExp(MODEL).test(value) ? value : null;
|
|
47
|
+
}
|
|
48
|
+
exports.DELAY_BUCKETS = ['<1m', '<10m', '<1h', '<1d', '>=1d'];
|
|
49
|
+
exports.COUNT_BUCKETS = ['0', '1', '2-3', '4-7', '8+'];
|
|
50
|
+
exports.LENGTH_BUCKETS = ['<1m', '<10m', '<1h', '<6h', '>=6h'];
|
|
51
|
+
exports.RETRIEVAL_TOOL_NAMES = ['get_context', 'search_memory', 'retrieve_memory'];
|
|
52
|
+
exports.SAVE_TOOL_NAMES = ['remember', 'save_memory', 'remember_note'];
|
|
53
|
+
exports.CANDIDATE_KIND_NAMES = ['fact', 'note', 'unkeyed'];
|
|
54
|
+
exports.SAVE_ITEM_NAMES = ['fact', 'note', 'event', 'unkeyed'];
|
|
55
|
+
/** The longest text one example may carry, in characters. A longer text is cut at this length by the projector. */
|
|
56
|
+
exports.MAX_EXAMPLE_TEXT = 2000;
|
|
57
|
+
const bool = { type: 'boolean' };
|
|
58
|
+
const boolOrNull = { type: 'boolean', nullable: true };
|
|
59
|
+
/** Fields of one entry of `candidates` in a retrieval-labelled row. */
|
|
60
|
+
exports.CANDIDATE_FIELDS = {
|
|
61
|
+
rank: { type: 'int' },
|
|
62
|
+
kind: { type: 'string', oneOf: exports.CANDIDATE_KIND_NAMES },
|
|
63
|
+
lane: { type: 'string', nullable: true, pattern: LANE },
|
|
64
|
+
score: { type: 'number', nullable: true },
|
|
65
|
+
matched: boolOrNull,
|
|
66
|
+
current: boolOrNull,
|
|
67
|
+
opened: boolOrNull,
|
|
68
|
+
cited: boolOrNull,
|
|
69
|
+
updated: boolOrNull,
|
|
70
|
+
retired: boolOrNull,
|
|
71
|
+
delay_bucket: { type: 'string', nullable: true, oneOf: exports.DELAY_BUCKETS },
|
|
72
|
+
text: { type: 'string', nullable: true, maxLength: exports.MAX_EXAMPLE_TEXT, level: 'data' },
|
|
73
|
+
};
|
|
74
|
+
/** Top-level fields of each row kind. `kind` is in every row and names the row's version. */
|
|
75
|
+
exports.ROW_FIELDS = {
|
|
76
|
+
'retrieval-labelled/1': {
|
|
77
|
+
kind: { type: 'string', oneOf: ['retrieval-labelled/1'] },
|
|
78
|
+
hour: { type: 'string', pattern: HOUR },
|
|
79
|
+
tool: { type: 'string', oneOf: exports.RETRIEVAL_TOOL_NAMES },
|
|
80
|
+
ranker: { type: 'string', pattern: LANE },
|
|
81
|
+
build: { type: 'string', nullable: true, pattern: BUILD },
|
|
82
|
+
model: { type: 'string', nullable: true, pattern: MODEL },
|
|
83
|
+
retrieval: { type: 'string', nullable: true, oneOf: ['facts', 'hybrid', 'semantic', 'keyword'] },
|
|
84
|
+
served: { type: 'int' },
|
|
85
|
+
reply_tokens_bucket: { type: 'int', nullable: true },
|
|
86
|
+
relevant: boolOrNull,
|
|
87
|
+
truncated: boolOrNull,
|
|
88
|
+
query: { type: 'string', nullable: true, maxLength: exports.MAX_EXAMPLE_TEXT, level: 'data' },
|
|
89
|
+
// candidates is an array of objects; it is checked against CANDIDATE_FIELDS.
|
|
90
|
+
},
|
|
91
|
+
'save-outcome/1': {
|
|
92
|
+
kind: { type: 'string', oneOf: ['save-outcome/1'] },
|
|
93
|
+
hour: { type: 'string', pattern: HOUR },
|
|
94
|
+
tool: { type: 'string', oneOf: exports.SAVE_TOOL_NAMES },
|
|
95
|
+
op: { type: 'string', oneOf: ['create', 'supersede'] },
|
|
96
|
+
item: { type: 'string', oneOf: exports.SAVE_ITEM_NAMES },
|
|
97
|
+
has_cites: bool,
|
|
98
|
+
reads_bucket: { type: 'string', oneOf: exports.COUNT_BUCKETS },
|
|
99
|
+
opened: bool,
|
|
100
|
+
cited: bool,
|
|
101
|
+
superseded: bool,
|
|
102
|
+
retired: bool,
|
|
103
|
+
text: { type: 'string', nullable: true, maxLength: exports.MAX_EXAMPLE_TEXT, level: 'data' },
|
|
104
|
+
},
|
|
105
|
+
'session-aggregate/1': {
|
|
106
|
+
kind: { type: 'string', oneOf: ['session-aggregate/1'] },
|
|
107
|
+
hour: { type: 'string', pattern: HOUR },
|
|
108
|
+
length_bucket: { type: 'string', oneOf: exports.LENGTH_BUCKETS },
|
|
109
|
+
reads_bucket: { type: 'string', oneOf: exports.COUNT_BUCKETS },
|
|
110
|
+
saves_bucket: { type: 'string', oneOf: exports.COUNT_BUCKETS },
|
|
111
|
+
empty_reads_bucket: { type: 'string', oneOf: exports.COUNT_BUCKETS },
|
|
112
|
+
first_call: { type: 'string', oneOf: [...exports.RETRIEVAL_TOOL_NAMES, ...exports.SAVE_TOOL_NAMES, 'other'] },
|
|
113
|
+
},
|
|
114
|
+
};
|
|
115
|
+
/** Row kinds that carry a `candidates` array. */
|
|
116
|
+
exports.KINDS_WITH_CANDIDATES = ['retrieval-labelled/1'];
|
|
117
|
+
/** Fields of the batch envelope the engine sends (not rows). */
|
|
118
|
+
exports.BATCH_FIELDS = ['protocol', 'action', 'batch_id', 'level', 'wording', 'rows'];
|
|
119
|
+
exports.DELETE_FIELDS = ['protocol', 'action'];
|
|
120
|
+
/**
|
|
121
|
+
* A self-hosted install's batch also carries its consent record, the evidence of the choice it sends under: the version of the
|
|
122
|
+
* record, the level chosen (at least the batch's), when it was chosen, the wording seen, and the 18-or-older confirmation.
|
|
123
|
+
* A hosted workspace's consent is the platform's own record, so its batch has none.
|
|
124
|
+
*/
|
|
125
|
+
exports.CONSENT_FIELD = 'consent';
|
|
126
|
+
exports.CONSENT_FIELDS = ['version', 'level', 'changed_at', 'wording', 'adult'];
|
|
127
|
+
exports.SELF_HOSTED_BATCH_FIELDS = [...exports.BATCH_FIELDS, exports.CONSENT_FIELD];
|
|
128
|
+
/** The endpoint's refusals after which the same rows must never be sent again (send.ts stops instead of retrying). */
|
|
129
|
+
exports.TERMINAL_REFUSALS = ['sharing_closed', 'consent_off', 'consent_required'];
|
|
130
|
+
/** Every field name a level may send, for the documentation check. `signals` is a subset of `data`. */
|
|
131
|
+
function fieldsAtLevel(level) {
|
|
132
|
+
const names = new Set();
|
|
133
|
+
const allowed = (spec) => spec.level === undefined || levelRank(spec.level) <= levelRank(level);
|
|
134
|
+
for (const kind of exports.ROW_KINDS) {
|
|
135
|
+
for (const [name, spec] of Object.entries(exports.ROW_FIELDS[kind]))
|
|
136
|
+
if (allowed(spec))
|
|
137
|
+
names.add(`${kind}.${name}`);
|
|
138
|
+
}
|
|
139
|
+
for (const [name, spec] of Object.entries(exports.CANDIDATE_FIELDS))
|
|
140
|
+
if (allowed(spec))
|
|
141
|
+
names.add(`retrieval-labelled/1.candidates.${name}`);
|
|
142
|
+
return [...names].sort();
|
|
143
|
+
}
|
|
144
|
+
class RowError extends Error {
|
|
145
|
+
}
|
|
146
|
+
exports.RowError = RowError;
|
|
147
|
+
function checkValue(path, spec, value) {
|
|
148
|
+
if (value === null) {
|
|
149
|
+
if (spec.nullable)
|
|
150
|
+
return;
|
|
151
|
+
throw new RowError(`${path} must not be null`);
|
|
152
|
+
}
|
|
153
|
+
switch (spec.type) {
|
|
154
|
+
case 'string': {
|
|
155
|
+
if (typeof value !== 'string')
|
|
156
|
+
throw new RowError(`${path} must be a string`);
|
|
157
|
+
if (spec.oneOf && !spec.oneOf.includes(value))
|
|
158
|
+
throw new RowError(`${path} is not one of the listed values`);
|
|
159
|
+
if (spec.pattern && !new RegExp(spec.pattern).test(value))
|
|
160
|
+
throw new RowError(`${path} does not match its pattern`);
|
|
161
|
+
if (spec.maxLength !== undefined && value.length > spec.maxLength)
|
|
162
|
+
throw new RowError(`${path} is longer than ${spec.maxLength}`);
|
|
163
|
+
return;
|
|
164
|
+
}
|
|
165
|
+
case 'int':
|
|
166
|
+
if (typeof value !== 'number' || !Number.isInteger(value))
|
|
167
|
+
throw new RowError(`${path} must be an integer`);
|
|
168
|
+
return;
|
|
169
|
+
case 'number':
|
|
170
|
+
if (typeof value !== 'number' || !Number.isFinite(value))
|
|
171
|
+
throw new RowError(`${path} must be a finite number`);
|
|
172
|
+
return;
|
|
173
|
+
case 'boolean':
|
|
174
|
+
if (typeof value !== 'boolean')
|
|
175
|
+
throw new RowError(`${path} must be a boolean`);
|
|
176
|
+
return;
|
|
177
|
+
}
|
|
178
|
+
}
|
|
179
|
+
function checkObject(path, specs, value, level, skip = []) {
|
|
180
|
+
if (typeof value !== 'object' || value === null || Array.isArray(value))
|
|
181
|
+
throw new RowError(`${path} must be an object`);
|
|
182
|
+
const record = value;
|
|
183
|
+
for (const name of Object.keys(record)) {
|
|
184
|
+
if (skip.includes(name))
|
|
185
|
+
continue;
|
|
186
|
+
const spec = specs[name];
|
|
187
|
+
if (spec === undefined)
|
|
188
|
+
throw new RowError(`${path}.${name} is not a listed field`);
|
|
189
|
+
if (spec.level !== undefined && levelRank(spec.level) > levelRank(level)) {
|
|
190
|
+
throw new RowError(`${path}.${name} is not shared at level ${level}`);
|
|
191
|
+
}
|
|
192
|
+
}
|
|
193
|
+
for (const [name, spec] of Object.entries(specs)) {
|
|
194
|
+
if (skip.includes(name))
|
|
195
|
+
continue;
|
|
196
|
+
if (spec.level !== undefined && levelRank(spec.level) > levelRank(level))
|
|
197
|
+
continue;
|
|
198
|
+
if (spec.level !== undefined && !(name in record))
|
|
199
|
+
continue; // a text field may be absent
|
|
200
|
+
if (!(name in record))
|
|
201
|
+
throw new RowError(`${path}.${name} is missing`);
|
|
202
|
+
checkValue(`${path}.${name}`, spec, record[name]);
|
|
203
|
+
}
|
|
204
|
+
}
|
|
205
|
+
/** Throws a RowError unless the row holds exactly the listed fields for its kind, with the listed value shapes, at `level`. */
|
|
206
|
+
function validateRow(row, level) {
|
|
207
|
+
if (typeof row !== 'object' || row === null)
|
|
208
|
+
throw new RowError('a row must be an object');
|
|
209
|
+
const kind = row.kind;
|
|
210
|
+
if (typeof kind !== 'string' || !exports.ROW_KINDS.includes(kind))
|
|
211
|
+
throw new RowError('kind is not a listed row kind');
|
|
212
|
+
const specs = exports.ROW_FIELDS[kind];
|
|
213
|
+
const withCandidates = exports.KINDS_WITH_CANDIDATES.includes(kind);
|
|
214
|
+
checkObject(kind, specs, row, level, withCandidates ? ['candidates'] : []);
|
|
215
|
+
if (withCandidates) {
|
|
216
|
+
const candidates = row.candidates;
|
|
217
|
+
if (!Array.isArray(candidates))
|
|
218
|
+
throw new RowError(`${kind}.candidates must be an array`);
|
|
219
|
+
if (candidates.length > 200)
|
|
220
|
+
throw new RowError(`${kind}.candidates has more than 200 entries`);
|
|
221
|
+
candidates.forEach((candidate, index) => checkObject(`${kind}.candidates[${index}]`, exports.CANDIDATE_FIELDS, candidate, level));
|
|
222
|
+
}
|
|
223
|
+
}
|
|
224
|
+
/** Largest batch: rows per request. The endpoint enforces the same. */
|
|
225
|
+
exports.MAX_ROWS_PER_BATCH = 200;
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.MIN_SHARE_INTERVAL_MS = exports.DEFAULT_SHARE_INTERVAL_MS = void 0;
|
|
4
|
+
exports.applyInstallOff = applyInstallOff;
|
|
5
|
+
exports.shareIntervalMs = shareIntervalMs;
|
|
6
|
+
exports.startSharingLoop = startSharingLoop;
|
|
7
|
+
const state_1 = require("./state");
|
|
8
|
+
const send_1 = require("./send");
|
|
9
|
+
/**
|
|
10
|
+
* The install said off (`renor setup` answered No, or `renor-engine telemetry off` without a memory folder) while this workspace's
|
|
11
|
+
* own record is still on: turn the workspace off the way its own off does, which stops collection, deletes the example texts and
|
|
12
|
+
* owes the deletion of what was sent. effectiveLevel already reads it as off; this makes the workspace's record say so too.
|
|
13
|
+
*/
|
|
14
|
+
async function applyInstallOff(options) {
|
|
15
|
+
const env = options.env ?? process.env;
|
|
16
|
+
if ((0, state_1.installLimit)(options.dir, env) !== 'off')
|
|
17
|
+
return false;
|
|
18
|
+
const own = (0, state_1.readConsent)(options.dir);
|
|
19
|
+
if (own === null || own.level === 'off')
|
|
20
|
+
return false;
|
|
21
|
+
const install = (0, state_1.readConsent)((0, state_1.defaultSharingDir)(env));
|
|
22
|
+
await (0, send_1.chooseLevel)({
|
|
23
|
+
dir: options.dir, level: 'off', wording: install?.wording ?? 'install-off', adult: own.adult, source: install?.source ?? 'setup',
|
|
24
|
+
env, fetch: options.fetch, hosted: options.hosted,
|
|
25
|
+
});
|
|
26
|
+
return true;
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* The service's sender: every `intervalMs` it asks the sender to share what is final and unsent. At level off a tick reads
|
|
30
|
+
* one small file and does nothing else. The timer never keeps the process alive and a failed tick is dropped (the rows are
|
|
31
|
+
* still unsent, so the next tick tries again).
|
|
32
|
+
*/
|
|
33
|
+
exports.DEFAULT_SHARE_INTERVAL_MS = 60 * 60_000;
|
|
34
|
+
exports.MIN_SHARE_INTERVAL_MS = 60_000;
|
|
35
|
+
function shareIntervalMs(env = process.env) {
|
|
36
|
+
const raw = (env.RENOR_SHARING_INTERVAL_MIN ?? '').trim();
|
|
37
|
+
if (raw === '')
|
|
38
|
+
return exports.DEFAULT_SHARE_INTERVAL_MS;
|
|
39
|
+
const minutes = Number(raw);
|
|
40
|
+
if (!Number.isInteger(minutes) || minutes < 1 || minutes > 1440) {
|
|
41
|
+
throw new Error('RENOR_SHARING_INTERVAL_MIN must be a whole number of minutes between 1 and 1440');
|
|
42
|
+
}
|
|
43
|
+
return minutes * 60_000;
|
|
44
|
+
}
|
|
45
|
+
function startSharingLoop(options) {
|
|
46
|
+
const env = options.env ?? process.env;
|
|
47
|
+
const intervalMs = options.intervalMs ?? shareIntervalMs(env);
|
|
48
|
+
let running = false;
|
|
49
|
+
const tick = async () => {
|
|
50
|
+
if (running)
|
|
51
|
+
return;
|
|
52
|
+
running = true;
|
|
53
|
+
try {
|
|
54
|
+
if (await applyInstallOff(options))
|
|
55
|
+
options.log?.('[sharing] off: this install chose not to share, so this workspace was turned off');
|
|
56
|
+
await (0, send_1.settlePendingDelete)(options);
|
|
57
|
+
if ((0, state_1.effectiveLevel)(options.dir, env) === 'off')
|
|
58
|
+
return;
|
|
59
|
+
const result = await (0, send_1.shareNow)(options);
|
|
60
|
+
if (result.status === 'sent')
|
|
61
|
+
options.log?.(`[sharing] sent ${result.rows} row(s) at level ${result.level}`);
|
|
62
|
+
else if (result.status === 'failed')
|
|
63
|
+
options.log?.(`[sharing] not sent: ${result.reason ?? 'unknown'}; will retry`);
|
|
64
|
+
else if (result.status === 'paused' || result.status === 'stopped')
|
|
65
|
+
options.log?.(`[sharing] not sent: ${result.reason ?? 'unknown'}`);
|
|
66
|
+
}
|
|
67
|
+
catch (err) {
|
|
68
|
+
options.log?.(`[sharing] tick failed: ${err instanceof Error ? err.message : 'unknown'}`);
|
|
69
|
+
}
|
|
70
|
+
finally {
|
|
71
|
+
running = false;
|
|
72
|
+
}
|
|
73
|
+
};
|
|
74
|
+
const timer = setInterval(() => void tick(), intervalMs);
|
|
75
|
+
timer.unref();
|
|
76
|
+
// A tenant that sleeps when idle is woken by use, so the first tick runs soon after start instead of waiting a whole interval.
|
|
77
|
+
const first = setTimeout(() => void tick(), options.firstTickMs ?? 30_000);
|
|
78
|
+
first.unref();
|
|
79
|
+
return { stop: () => { clearInterval(timer); clearTimeout(first); }, tick };
|
|
80
|
+
}
|
|
@@ -0,0 +1,327 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.LABEL_WINDOW_MS = void 0;
|
|
4
|
+
exports.hourOf = hourOf;
|
|
5
|
+
exports.projectRows = projectRows;
|
|
6
|
+
const fields_1 = require("./fields");
|
|
7
|
+
/**
|
|
8
|
+
* The join, done inside the user's own folder: the learning log says what was served, saved, cited and retired; this turns
|
|
9
|
+
* it into finished, labelled rows. Only these rows can ever leave. They carry no key, no memory id, no query and no text
|
|
10
|
+
* (text only at `data`, from the example store), and every time is coarsened to the hour.
|
|
11
|
+
*
|
|
12
|
+
* A row is sent only once its label is final: the window (default 24 hours) after the event has closed. Until then the event
|
|
13
|
+
* waits, and the sender's watermark says how far it has got.
|
|
14
|
+
*/
|
|
15
|
+
exports.LABEL_WINDOW_MS = 24 * 3_600_000;
|
|
16
|
+
const asString = (value) => (typeof value === 'string' ? value : null);
|
|
17
|
+
const asNumber = (value) => (typeof value === 'number' && Number.isFinite(value) ? value : null);
|
|
18
|
+
const asBool = (value) => (value === 1 || value === true ? true : value === 0 || value === false ? false : null);
|
|
19
|
+
/** `2026-10-21T14`: the hour a row happened in, in UTC. */
|
|
20
|
+
function hourOf(ms) {
|
|
21
|
+
return new Date(ms).toISOString().slice(0, 13);
|
|
22
|
+
}
|
|
23
|
+
function delayBucket(ms) {
|
|
24
|
+
if (ms < 60_000)
|
|
25
|
+
return '<1m';
|
|
26
|
+
if (ms < 600_000)
|
|
27
|
+
return '<10m';
|
|
28
|
+
if (ms < 3_600_000)
|
|
29
|
+
return '<1h';
|
|
30
|
+
if (ms < 86_400_000)
|
|
31
|
+
return '<1d';
|
|
32
|
+
return '>=1d';
|
|
33
|
+
}
|
|
34
|
+
function lengthBucket(ms) {
|
|
35
|
+
if (ms < 60_000)
|
|
36
|
+
return '<1m';
|
|
37
|
+
if (ms < 600_000)
|
|
38
|
+
return '<10m';
|
|
39
|
+
if (ms < 3_600_000)
|
|
40
|
+
return '<1h';
|
|
41
|
+
if (ms < 21_600_000)
|
|
42
|
+
return '<6h';
|
|
43
|
+
return '>=6h';
|
|
44
|
+
}
|
|
45
|
+
function countBucket(n) {
|
|
46
|
+
if (n <= 0)
|
|
47
|
+
return '0';
|
|
48
|
+
if (n === 1)
|
|
49
|
+
return '1';
|
|
50
|
+
if (n <= 3)
|
|
51
|
+
return '2-3';
|
|
52
|
+
if (n <= 7)
|
|
53
|
+
return '4-7';
|
|
54
|
+
return '8+';
|
|
55
|
+
}
|
|
56
|
+
/** The smallest power of two at or above `tokens`: a size class, not a size. */
|
|
57
|
+
function tokenBucket(tokens) {
|
|
58
|
+
if (tokens === null || tokens < 0)
|
|
59
|
+
return null;
|
|
60
|
+
let bucket = 1;
|
|
61
|
+
while (bucket < tokens)
|
|
62
|
+
bucket *= 2;
|
|
63
|
+
return bucket;
|
|
64
|
+
}
|
|
65
|
+
const round = (value) => (value === null ? null : Math.round(value * 10_000) / 10_000);
|
|
66
|
+
/** Events about a memory, by its key, in time order. */
|
|
67
|
+
function indexEvents(tables) {
|
|
68
|
+
const byMemory = new Map();
|
|
69
|
+
const bySubject = new Map();
|
|
70
|
+
const add = (map, key, event) => {
|
|
71
|
+
if (key === null)
|
|
72
|
+
return;
|
|
73
|
+
const list = map.get(key);
|
|
74
|
+
if (list)
|
|
75
|
+
list.push(event);
|
|
76
|
+
else
|
|
77
|
+
map.set(key, [event]);
|
|
78
|
+
};
|
|
79
|
+
for (const op of tables.memory_ops) {
|
|
80
|
+
const at = asNumber(op.at);
|
|
81
|
+
const kind = op.op;
|
|
82
|
+
if (at === null)
|
|
83
|
+
continue;
|
|
84
|
+
const key = asString(op.memory_key);
|
|
85
|
+
if (kind === 'retrieve')
|
|
86
|
+
add(byMemory, key, { at, kind: 'retrieve' });
|
|
87
|
+
else if (kind === 'delete')
|
|
88
|
+
add(byMemory, key, { at, kind: 'delete' });
|
|
89
|
+
else if (kind === 'supersede') {
|
|
90
|
+
// A supersede changes the memory it replaces; it is also the save of the new value (its own key).
|
|
91
|
+
add(byMemory, asString(op.replaced_key), { at, kind: 'supersede' });
|
|
92
|
+
if (asString(op.replaced_key) !== key)
|
|
93
|
+
add(byMemory, key, { at, kind: 'supersede' });
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
for (const row of tables.feedback) {
|
|
97
|
+
const at = asNumber(row.at);
|
|
98
|
+
if (at === null)
|
|
99
|
+
continue;
|
|
100
|
+
add(byMemory, asString(row.memory_key), { at, kind: 'cite' });
|
|
101
|
+
add(bySubject, asString(row.subject_key), { at, kind: 'cite' });
|
|
102
|
+
}
|
|
103
|
+
for (const list of [...byMemory.values(), ...bySubject.values()])
|
|
104
|
+
list.sort((a, b) => a.at - b.at);
|
|
105
|
+
return { byMemory, bySubject };
|
|
106
|
+
}
|
|
107
|
+
function labelOf(lists, from, until, skipSupersedeAt = null) {
|
|
108
|
+
const label = { opened: false, cited: false, updated: false, retired: false, firstAt: null };
|
|
109
|
+
for (const list of lists) {
|
|
110
|
+
for (const event of list ?? []) {
|
|
111
|
+
if (event.at <= from || event.at > until)
|
|
112
|
+
continue;
|
|
113
|
+
if (skipSupersedeAt !== null && event.kind === 'supersede' && event.at === skipSupersedeAt)
|
|
114
|
+
continue;
|
|
115
|
+
if (event.kind === 'retrieve')
|
|
116
|
+
label.opened = true;
|
|
117
|
+
else if (event.kind === 'cite')
|
|
118
|
+
label.cited = true;
|
|
119
|
+
else if (event.kind === 'supersede')
|
|
120
|
+
label.updated = true;
|
|
121
|
+
else
|
|
122
|
+
label.retired = true;
|
|
123
|
+
label.firstAt = label.firstAt === null ? event.at : Math.min(label.firstAt, event.at);
|
|
124
|
+
}
|
|
125
|
+
}
|
|
126
|
+
return label;
|
|
127
|
+
}
|
|
128
|
+
/** A candidate the reply served (rank set). The log also keeps the ones the ranker scored and the reply did not serve: never shared. */
|
|
129
|
+
function servedRow(candidate) {
|
|
130
|
+
return asNumber(candidate.rank) !== null;
|
|
131
|
+
}
|
|
132
|
+
function retrievalRows(log, options, windowMs) {
|
|
133
|
+
const { tables } = log;
|
|
134
|
+
const events = indexEvents(tables);
|
|
135
|
+
const cutoff = options.now - windowMs;
|
|
136
|
+
const candidatesBy = new Map();
|
|
137
|
+
for (const candidate of tables.candidates) {
|
|
138
|
+
const id = asNumber(candidate.retrieval_id);
|
|
139
|
+
if (id === null || !servedRow(candidate))
|
|
140
|
+
continue;
|
|
141
|
+
const list = candidatesBy.get(id);
|
|
142
|
+
if (list)
|
|
143
|
+
list.push(candidate);
|
|
144
|
+
else
|
|
145
|
+
candidatesBy.set(id, [candidate]);
|
|
146
|
+
}
|
|
147
|
+
const rows = [];
|
|
148
|
+
const retrievals = [...tables.retrievals].sort((a, b) => (asNumber(a.at) ?? 0) - (asNumber(b.at) ?? 0) || (asNumber(a.id) ?? 0) - (asNumber(b.id) ?? 0));
|
|
149
|
+
for (const retrieval of retrievals) {
|
|
150
|
+
const at = asNumber(retrieval.at);
|
|
151
|
+
const id = asNumber(retrieval.id);
|
|
152
|
+
const tool = asString(retrieval.tool);
|
|
153
|
+
if (at === null || id === null || tool === null || !fields_1.RETRIEVAL_TOOL_NAMES.includes(tool))
|
|
154
|
+
continue;
|
|
155
|
+
if (at <= options.watermarks.retrieval || at > cutoff)
|
|
156
|
+
continue;
|
|
157
|
+
const queryKey = asString(retrieval.query_key);
|
|
158
|
+
const candidates = (candidatesBy.get(id) ?? []).slice(0, 200).map(candidate => {
|
|
159
|
+
const kind = asString(candidate.kind) ?? 'unkeyed';
|
|
160
|
+
const memoryKey = asString(candidate.memory_key);
|
|
161
|
+
const joinable = memoryKey !== null && kind !== 'unkeyed';
|
|
162
|
+
const label = joinable
|
|
163
|
+
? labelOf([events.byMemory.get(memoryKey), kind === 'fact' ? events.bySubject.get(asString(candidate.subject_key) ?? '') : undefined], at, at + windowMs)
|
|
164
|
+
: null;
|
|
165
|
+
const out = {
|
|
166
|
+
rank: asNumber(candidate.rank) ?? 0,
|
|
167
|
+
kind,
|
|
168
|
+
lane: asString(candidate.reason),
|
|
169
|
+
score: round(asNumber(candidate.score)),
|
|
170
|
+
matched: asBool(candidate.matched),
|
|
171
|
+
current: asBool(candidate.current),
|
|
172
|
+
opened: label === null ? null : label.opened,
|
|
173
|
+
cited: label === null ? null : label.cited,
|
|
174
|
+
updated: label === null ? null : label.updated,
|
|
175
|
+
retired: label === null ? null : label.retired,
|
|
176
|
+
delay_bucket: label === null || label.firstAt === null ? null : delayBucket(label.firstAt - at),
|
|
177
|
+
};
|
|
178
|
+
if (options.level === 'data')
|
|
179
|
+
out.text = memoryKey === null ? null : options.examples?.memory(memoryKey) ?? null;
|
|
180
|
+
return out;
|
|
181
|
+
});
|
|
182
|
+
const row = {
|
|
183
|
+
kind: 'retrieval-labelled/1',
|
|
184
|
+
hour: hourOf(at),
|
|
185
|
+
tool,
|
|
186
|
+
ranker: asString(retrieval.ranker) ?? 'baseline',
|
|
187
|
+
build: asString(retrieval.build),
|
|
188
|
+
model: (0, fields_1.modelIdentifier)(asString(retrieval.model)),
|
|
189
|
+
retrieval: asString(retrieval.retrieval),
|
|
190
|
+
served: asNumber(retrieval.served) ?? candidates.length,
|
|
191
|
+
reply_tokens_bucket: tokenBucket(asNumber(retrieval.reply_tokens)),
|
|
192
|
+
relevant: asBool(retrieval.relevant),
|
|
193
|
+
truncated: asBool(retrieval.truncated),
|
|
194
|
+
candidates,
|
|
195
|
+
};
|
|
196
|
+
if (options.level === 'data')
|
|
197
|
+
row.query = queryKey === null ? null : options.examples?.query(queryKey) ?? null;
|
|
198
|
+
rows.push({ kind: 'retrieval', at, row });
|
|
199
|
+
}
|
|
200
|
+
return rows;
|
|
201
|
+
}
|
|
202
|
+
function saveRows(log, options, windowMs) {
|
|
203
|
+
const { tables } = log;
|
|
204
|
+
const events = indexEvents(tables);
|
|
205
|
+
const cutoff = options.now - windowMs;
|
|
206
|
+
// How many times each memory was served after a given time: candidates by key, with the retrieval's time.
|
|
207
|
+
const retrievalAt = new Map();
|
|
208
|
+
for (const retrieval of tables.retrievals) {
|
|
209
|
+
const id = asNumber(retrieval.id);
|
|
210
|
+
const at = asNumber(retrieval.at);
|
|
211
|
+
if (id !== null && at !== null)
|
|
212
|
+
retrievalAt.set(id, at);
|
|
213
|
+
}
|
|
214
|
+
const servedBy = new Map();
|
|
215
|
+
for (const candidate of tables.candidates) {
|
|
216
|
+
const key = asString(candidate.memory_key);
|
|
217
|
+
const id = asNumber(candidate.retrieval_id);
|
|
218
|
+
const at = id === null ? undefined : retrievalAt.get(id);
|
|
219
|
+
if (key === null || at === undefined || !servedRow(candidate))
|
|
220
|
+
continue;
|
|
221
|
+
const list = servedBy.get(key);
|
|
222
|
+
if (list)
|
|
223
|
+
list.push(at);
|
|
224
|
+
else
|
|
225
|
+
servedBy.set(key, [at]);
|
|
226
|
+
}
|
|
227
|
+
const rows = [];
|
|
228
|
+
const ops = [...tables.memory_ops].sort((a, b) => (asNumber(a.at) ?? 0) - (asNumber(b.at) ?? 0) || (asNumber(a.id) ?? 0) - (asNumber(b.id) ?? 0));
|
|
229
|
+
for (const op of ops) {
|
|
230
|
+
const at = asNumber(op.at);
|
|
231
|
+
const tool = asString(op.tool);
|
|
232
|
+
const kind = asString(op.op);
|
|
233
|
+
if (at === null || tool === null || !fields_1.SAVE_TOOL_NAMES.includes(tool))
|
|
234
|
+
continue;
|
|
235
|
+
if (kind !== 'create' && kind !== 'supersede')
|
|
236
|
+
continue;
|
|
237
|
+
if (at <= options.watermarks.save || at > cutoff)
|
|
238
|
+
continue;
|
|
239
|
+
const memoryKey = asString(op.memory_key);
|
|
240
|
+
const item = asString(op.kind) ?? 'unkeyed';
|
|
241
|
+
const joinable = memoryKey !== null && item !== 'unkeyed';
|
|
242
|
+
const label = joinable
|
|
243
|
+
? labelOf([events.byMemory.get(memoryKey), item === 'fact' ? events.bySubject.get(asString(op.subject_key) ?? '') : undefined], at, at + windowMs, at)
|
|
244
|
+
: labelOf([], at, at + windowMs);
|
|
245
|
+
const reads = joinable ? (servedBy.get(memoryKey) ?? []).filter(time => time > at && time <= at + windowMs).length : 0;
|
|
246
|
+
const hasCites = tables.feedback.some(cite => cite.tool === tool && Math.abs((asNumber(cite.at) ?? Number.NaN) - at) <= 2000
|
|
247
|
+
&& cite.agent_key === op.agent_key && cite.session_key === op.session_key);
|
|
248
|
+
const row = {
|
|
249
|
+
kind: 'save-outcome/1',
|
|
250
|
+
hour: hourOf(at),
|
|
251
|
+
tool,
|
|
252
|
+
op: kind,
|
|
253
|
+
item,
|
|
254
|
+
has_cites: hasCites,
|
|
255
|
+
reads_bucket: countBucket(reads),
|
|
256
|
+
opened: label.opened,
|
|
257
|
+
cited: label.cited,
|
|
258
|
+
superseded: label.updated,
|
|
259
|
+
retired: label.retired,
|
|
260
|
+
};
|
|
261
|
+
if (options.level === 'data')
|
|
262
|
+
row.text = memoryKey === null ? null : options.examples?.memory(memoryKey) ?? null;
|
|
263
|
+
rows.push({ kind: 'save', at, row });
|
|
264
|
+
}
|
|
265
|
+
return rows;
|
|
266
|
+
}
|
|
267
|
+
function sessionRows(log, options, windowMs) {
|
|
268
|
+
const { tables } = log;
|
|
269
|
+
const cutoff = options.now - windowMs;
|
|
270
|
+
const sessions = new Map();
|
|
271
|
+
const touch = (key, at, tool, apply) => {
|
|
272
|
+
if (key === null || at === null || tool === null)
|
|
273
|
+
return;
|
|
274
|
+
let seen = sessions.get(key);
|
|
275
|
+
if (!seen) {
|
|
276
|
+
seen = { first: at, last: at, tool, reads: 0, saves: 0, empty: 0 };
|
|
277
|
+
sessions.set(key, seen);
|
|
278
|
+
}
|
|
279
|
+
if (at < seen.first) {
|
|
280
|
+
seen.first = at;
|
|
281
|
+
seen.tool = tool;
|
|
282
|
+
}
|
|
283
|
+
seen.last = Math.max(seen.last, at);
|
|
284
|
+
apply(seen);
|
|
285
|
+
};
|
|
286
|
+
for (const retrieval of tables.retrievals) {
|
|
287
|
+
touch(asString(retrieval.session_key), asNumber(retrieval.at), asString(retrieval.tool), seen => {
|
|
288
|
+
seen.reads += 1;
|
|
289
|
+
if ((asNumber(retrieval.served) ?? 0) === 0)
|
|
290
|
+
seen.empty += 1;
|
|
291
|
+
});
|
|
292
|
+
}
|
|
293
|
+
for (const op of tables.memory_ops) {
|
|
294
|
+
const tool = asString(op.tool);
|
|
295
|
+
touch(asString(op.session_key), asNumber(op.at), tool, seen => {
|
|
296
|
+
if (tool !== null && fields_1.SAVE_TOOL_NAMES.includes(tool) && (op.op === 'create' || op.op === 'supersede'))
|
|
297
|
+
seen.saves += 1;
|
|
298
|
+
});
|
|
299
|
+
}
|
|
300
|
+
const rows = [];
|
|
301
|
+
for (const seen of [...sessions.values()].sort((a, b) => a.last - b.last)) {
|
|
302
|
+
if (seen.last <= options.watermarks.session || seen.last > cutoff)
|
|
303
|
+
continue;
|
|
304
|
+
const firstCall = fields_1.RETRIEVAL_TOOL_NAMES.includes(seen.tool) || fields_1.SAVE_TOOL_NAMES.includes(seen.tool)
|
|
305
|
+
? seen.tool
|
|
306
|
+
: 'other';
|
|
307
|
+
rows.push({
|
|
308
|
+
kind: 'session',
|
|
309
|
+
at: seen.last,
|
|
310
|
+
row: {
|
|
311
|
+
kind: 'session-aggregate/1',
|
|
312
|
+
hour: hourOf(seen.first),
|
|
313
|
+
length_bucket: lengthBucket(seen.last - seen.first),
|
|
314
|
+
reads_bucket: countBucket(seen.reads),
|
|
315
|
+
saves_bucket: countBucket(seen.saves),
|
|
316
|
+
empty_reads_bucket: countBucket(seen.empty),
|
|
317
|
+
first_call: firstCall,
|
|
318
|
+
},
|
|
319
|
+
});
|
|
320
|
+
}
|
|
321
|
+
return rows;
|
|
322
|
+
}
|
|
323
|
+
/** The finished rows the log holds that are final and not yet sent, oldest first within each kind. */
|
|
324
|
+
function projectRows(log, options) {
|
|
325
|
+
const windowMs = options.windowMs ?? exports.LABEL_WINDOW_MS;
|
|
326
|
+
return [...retrievalRows(log, options, windowMs), ...saveRows(log, options, windowMs), ...sessionRows(log, options, windowMs)];
|
|
327
|
+
}
|