renor-engine 0.0.0-stage → 1.1.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.
Files changed (194) hide show
  1. package/LICENSE +202 -0
  2. package/NOTICE +75 -0
  3. package/README.md +105 -2
  4. package/dist/.tsbuildinfo +1 -0
  5. package/dist/BUILD.json +6 -0
  6. package/dist/api/apiAuth.js +43 -0
  7. package/dist/api/server.js +174 -0
  8. package/dist/buildIdentity.js +149 -0
  9. package/dist/callPhases.js +82 -0
  10. package/dist/cli-extractors.js +46 -0
  11. package/dist/cli.js +500 -0
  12. package/dist/config.js +65 -0
  13. package/dist/context/composer.js +320 -0
  14. package/dist/context/readHonesty.js +478 -0
  15. package/dist/context/rowStore.js +238 -0
  16. package/dist/conversation/formatter.js +81 -0
  17. package/dist/conversation/parser.js +193 -0
  18. package/dist/conversation/types.js +2 -0
  19. package/dist/conversation/writer.js +42 -0
  20. package/dist/db/client.js +149 -0
  21. package/dist/db/handoffTable.js +31 -0
  22. package/dist/db/indexSalvage.js +101 -0
  23. package/dist/db/migrations.js +670 -0
  24. package/dist/db/readCache.js +109 -0
  25. package/dist/db/schema.js +5 -0
  26. package/dist/db/sqlite.js +396 -0
  27. package/dist/db/statements.js +89 -0
  28. package/dist/digests/digestCache.js +146 -0
  29. package/dist/digests/digests.js +597 -0
  30. package/dist/digests/worker.js +350 -0
  31. package/dist/embeddings/caching.js +337 -0
  32. package/dist/embeddings/coalescing.js +177 -0
  33. package/dist/embeddings/interactive.js +103 -0
  34. package/dist/embeddings/local.js +70 -0
  35. package/dist/embeddings/openai.js +106 -0
  36. package/dist/embeddings/rebuild.js +166 -0
  37. package/dist/embeddings/simdScan.js +260 -0
  38. package/dist/embeddings/space.js +21 -0
  39. package/dist/embeddings/types.js +14 -0
  40. package/dist/embeddings/vectorIndex.js +674 -0
  41. package/dist/embeddings/vertex.js +334 -0
  42. package/dist/eval/artifacts.js +42 -0
  43. package/dist/eval/cacheReport.js +146 -0
  44. package/dist/eval/comparison.js +182 -0
  45. package/dist/eval/context700-candidate.js +145 -0
  46. package/dist/eval/evalCache.js +568 -0
  47. package/dist/eval/hashEmbedding.js +35 -0
  48. package/dist/eval/indexSnapshots.js +548 -0
  49. package/dist/eval/longmemeval.js +56 -0
  50. package/dist/eval/metrics.js +181 -0
  51. package/dist/eval/pageDump.js +67 -0
  52. package/dist/eval/renorbenchBaseline.js +486 -0
  53. package/dist/eval/renorbenchDocuments.js +134 -0
  54. package/dist/eval/renorbenchProduct.js +182 -0
  55. package/dist/eval/runLedger.js +279 -0
  56. package/dist/eval/runManifest.js +485 -0
  57. package/dist/eval/scoring.js +197 -0
  58. package/dist/eval/textTokens.js +17 -0
  59. package/dist/evidence/attach.js +264 -0
  60. package/dist/evidence/background.js +147 -0
  61. package/dist/evidence/evidenceCache.js +182 -0
  62. package/dist/evidence/gate.js +37 -0
  63. package/dist/evidence/keyPool.js +85 -0
  64. package/dist/evidence/ollamaChat.js +84 -0
  65. package/dist/evidence/optin.js +165 -0
  66. package/dist/evidence/options.js +151 -0
  67. package/dist/evidence/secondPass.js +294 -0
  68. package/dist/extraction/classifyCapture.js +34 -0
  69. package/dist/extraction/decision-model.js +174 -0
  70. package/dist/extraction/eventExtractor.js +113 -0
  71. package/dist/extraction/extractionClient.js +122 -0
  72. package/dist/extraction/factExtractor.js +46 -0
  73. package/dist/extraction/factsWritePath.js +179 -0
  74. package/dist/extraction/preferenceExtractor.js +150 -0
  75. package/dist/extraction/secretGuard.js +176 -0
  76. package/dist/extraction/secretScanner.js +665 -0
  77. package/dist/extraction/typedFacts.js +224 -0
  78. package/dist/extraction/writePathAdjudication.js +110 -0
  79. package/dist/importing/apply.js +672 -0
  80. package/dist/importing/bundle-write.js +80 -0
  81. package/dist/importing/cli.js +408 -0
  82. package/dist/importing/existing.js +51 -0
  83. package/dist/importing/facts.js +121 -0
  84. package/dist/importing/forgetImported.js +79 -0
  85. package/dist/importing/hosted.js +467 -0
  86. package/dist/importing/journalLog.js +96 -0
  87. package/dist/importing/markdown.js +98 -0
  88. package/dist/importing/plan.js +201 -0
  89. package/dist/importing/secretScreen.js +113 -0
  90. package/dist/importing/serialize.js +188 -0
  91. package/dist/importing/source.js +463 -0
  92. package/dist/importing/types.js +6 -0
  93. package/dist/indexer/chunker.js +319 -0
  94. package/dist/indexer/dailyEntries.js +63 -0
  95. package/dist/indexer/hasher.js +10 -0
  96. package/dist/indexer/laneRuns.js +48 -0
  97. package/dist/indexer/o200k.js +481 -0
  98. package/dist/indexer/o200k.json +8 -0
  99. package/dist/indexer/outsideRoot.js +77 -0
  100. package/dist/indexer/parser.js +170 -0
  101. package/dist/indexer/pipeline.js +988 -0
  102. package/dist/indexer/staleness.js +201 -0
  103. package/dist/indexer/tokenizer.js +77 -0
  104. package/dist/indexer/walker.js +170 -0
  105. package/dist/mcp/hive.js +88 -0
  106. package/dist/mcp/requestErrors.js +47 -0
  107. package/dist/mcp/server.js +426 -0
  108. package/dist/memory/agentLease.js +43 -0
  109. package/dist/memory/confinedWrite.js +315 -0
  110. package/dist/memory/controls.js +73 -0
  111. package/dist/memory/dailyNote.js +265 -0
  112. package/dist/memory/durableAppend.js +57 -0
  113. package/dist/memory/factConflicts.js +203 -0
  114. package/dist/memory/factTerms.js +321 -0
  115. package/dist/memory/handoff.js +363 -0
  116. package/dist/memory/hiveNameHeader.cjs +10 -0
  117. package/dist/memory/inventory.js +55 -0
  118. package/dist/memory/invisibleText.js +20 -0
  119. package/dist/memory/lifecycle.js +1991 -0
  120. package/dist/memory/limits.js +13 -0
  121. package/dist/memory/requests.js +183 -0
  122. package/dist/memory/sourceName.js +276 -0
  123. package/dist/memory/statusFacts.js +61 -0
  124. package/dist/memory/whatsNew.js +158 -0
  125. package/dist/memory/writer.js +175 -0
  126. package/dist/memory/writerConflicts.js +85 -0
  127. package/dist/memorymap/memoryMap.js +1594 -0
  128. package/dist/memorymap/replacedJournal.js +58 -0
  129. package/dist/memorymap/replacements.js +410 -0
  130. package/dist/mvp/activity.js +86 -0
  131. package/dist/mvp/agentMemory.js +1800 -0
  132. package/dist/mvp/answerCheck.js +211 -0
  133. package/dist/mvp/auth.js +531 -0
  134. package/dist/mvp/cli.js +75 -0
  135. package/dist/mvp/client-store.js +462 -0
  136. package/dist/mvp/compileCache.js +242 -0
  137. package/dist/mvp/compileSeed.js +33 -0
  138. package/dist/mvp/config.js +288 -0
  139. package/dist/mvp/connectionStatus.js +80 -0
  140. package/dist/mvp/contextDistinct.js +53 -0
  141. package/dist/mvp/contextProfile.js +87 -0
  142. package/dist/mvp/contextRelevance.js +413 -0
  143. package/dist/mvp/directorySurface.js +68 -0
  144. package/dist/mvp/engine.js +1078 -0
  145. package/dist/mvp/exportAll.js +374 -0
  146. package/dist/mvp/factLanePack.js +77 -0
  147. package/dist/mvp/factMarkers.js +65 -0
  148. package/dist/mvp/factsLane.js +203 -0
  149. package/dist/mvp/hiddenSpans.js +585 -0
  150. package/dist/mvp/history.js +414 -0
  151. package/dist/mvp/hitDates.js +31 -0
  152. package/dist/mvp/hitFloor.js +36 -0
  153. package/dist/mvp/identity.js +18 -0
  154. package/dist/mvp/idle.js +113 -0
  155. package/dist/mvp/log.js +118 -0
  156. package/dist/mvp/memoryDir.js +98 -0
  157. package/dist/mvp/posthogMcp.js +210 -0
  158. package/dist/mvp/readScope.js +104 -0
  159. package/dist/mvp/readUsefulness.js +222 -0
  160. package/dist/mvp/sanitize.js +48 -0
  161. package/dist/mvp/schemaRejections.js +91 -0
  162. package/dist/mvp/scope.js +127 -0
  163. package/dist/mvp/server.js +2604 -0
  164. package/dist/mvp/serverCard.js +38 -0
  165. package/dist/mvp/storedSize.js +139 -0
  166. package/dist/mvp/telemetry.js +474 -0
  167. package/dist/net/poolFetch.js +174 -0
  168. package/dist/recall/actionRecall.js +282 -0
  169. package/dist/recall/autoRecall.js +447 -0
  170. package/dist/recall/searchRecall.js +189 -0
  171. package/dist/retrieval/adviceLines.js +195 -0
  172. package/dist/retrieval/adviceQuestion.js +44 -0
  173. package/dist/retrieval/conversationShape.js +44 -0
  174. package/dist/retrieval/dailyEntryTime.js +55 -0
  175. package/dist/retrieval/entityLookup.js +162 -0
  176. package/dist/retrieval/factsFirst.js +188 -0
  177. package/dist/retrieval/keyword.js +84 -0
  178. package/dist/retrieval/ledgerEventTime.js +51 -0
  179. package/dist/retrieval/ledgerLiveness.js +83 -0
  180. package/dist/retrieval/ledgerPresentation.js +161 -0
  181. package/dist/retrieval/noteIdentity.js +57 -0
  182. package/dist/retrieval/orchestrator.js +1171 -0
  183. package/dist/retrieval/plainWording.js +236 -0
  184. package/dist/retrieval/queryHelpers.js +142 -0
  185. package/dist/retrieval/questionSpan.js +475 -0
  186. package/dist/retrieval/readerEvents.js +690 -0
  187. package/dist/retrieval/readerLayout.js +422 -0
  188. package/dist/retrieval/relativeTimeHints.js +113 -0
  189. package/dist/retrieval/semantic.js +67 -0
  190. package/dist/router/routerCache.js +106 -0
  191. package/dist/router/sessionRouter.js +726 -0
  192. package/dist/toolRefusal.js +120 -0
  193. package/dist/watcher/watcher.js +77 -0
  194. package/package.json +118 -4
@@ -0,0 +1,174 @@
1
+ "use strict";
2
+ var __importDefault = (this && this.__importDefault) || function (mod) {
3
+ return (mod && mod.__esModule) ? mod : { "default": mod };
4
+ };
5
+ Object.defineProperty(exports, "__esModule", { value: true });
6
+ exports.createServer = createServer;
7
+ const express_1 = __importDefault(require("express"));
8
+ const hostHeaderValidation_js_1 = require("@modelcontextprotocol/sdk/server/middleware/hostHeaderValidation.js");
9
+ const apiAuth_1 = require("./apiAuth");
10
+ const orchestrator_1 = require("../retrieval/orchestrator");
11
+ const ledgerPresentation_1 = require("../retrieval/ledgerPresentation");
12
+ const entityLookup_1 = require("../retrieval/entityLookup");
13
+ const writer_1 = require("../memory/writer");
14
+ const lifecycle_1 = require("../memory/lifecycle");
15
+ const attach_1 = require("../evidence/attach");
16
+ const options_1 = require("../evidence/options");
17
+ const composer_1 = require("../context/composer");
18
+ const readHonesty_1 = require("../context/readHonesty");
19
+ const buildIdentity_1 = require("../buildIdentity");
20
+ const log_1 = require("../mvp/log");
21
+ const log = (0, log_1.createLogger)('engine');
22
+ function createServer(db, vectorIndex, provider, vaultPath, priorityPaths, memoryDir, ledgerPath, options) {
23
+ // Fail closed: there is no unauthenticated way to build this server.
24
+ const apiToken = options?.apiToken?.trim();
25
+ if (!apiToken)
26
+ throw new Error('createServer needs options.apiToken: the HTTP API does not run without a bearer token');
27
+ const app = (0, express_1.default)();
28
+ // DNS-rebinding guard first: a page that rebinds its own domain to 127.0.0.1 sends its own Host, and is refused
29
+ // before any route (or the token check) runs. Then the credential every other local user lacks.
30
+ app.use((0, hostHeaderValidation_js_1.hostHeaderValidation)(apiAuth_1.LOCAL_API_HOSTNAMES));
31
+ app.use((0, apiAuth_1.bearerTokenGuard)(apiToken));
32
+ app.use(express_1.default.json());
33
+ // Resolve the optional evidence path once per server, not once per request.
34
+ // This avoids opening a new SQLite evidence-cache connection on every search.
35
+ const productEvidenceEnabled = (0, attach_1.searchEvidenceEnabled)();
36
+ const productEvidenceOptions = productEvidenceEnabled
37
+ ? (0, options_1.resolveEvidenceToolOptions)({ dbPath: db.name })
38
+ : null;
39
+ const productEvidenceExtractor = productEvidenceOptions
40
+ ? (0, options_1.createEvidenceExtractor)(productEvidenceOptions)
41
+ : null;
42
+ // C0 shared composer (ADR-0003 §5): opt-in via RENOR_STRUCTURED_CONTEXT,
43
+ // default OFF — when off, responses are byte-identical to the pre-C0 contract.
44
+ const structuredOn = (0, composer_1.structuredContextEnabled)();
45
+ // Relative to the vault root — remember() joins it onto vaultPath.
46
+ const config_ledgerPath = ledgerPath ?? lifecycle_1.DEFAULT_LEDGER_REL;
47
+ // The ledger is the engine's own record, not a memory: this route returns neither its header nor the markup of its records.
48
+ const isLedger = (0, ledgerPresentation_1.ledgerNoteMatcher)({ memoryDir: vaultPath, ledgerRelPath: config_ledgerPath });
49
+ // Build/deploy identity: which source commit is this process running? Written
50
+ // at build time by scripts/ci/stamp-build.mjs and read through the shared,
51
+ // non-throwing helper (src/buildIdentity.ts) that the MVP's GET /version also
52
+ // uses. Deploy drift must be observable; the manifest never throws.
53
+ app.get('/api/health', (_req, res) => {
54
+ res.json({ ok: true, name: 'renor', version: buildIdentity_1.ENGINE_VERSION, ...(0, buildIdentity_1.readBuildIdentity)() });
55
+ });
56
+ app.post('/retrieve-context', async (req, res) => {
57
+ const { query, topK: rawTopK = 20 } = req.body;
58
+ if (!query)
59
+ return void res.status(400).json({ error: 'query required' });
60
+ const topK = Math.min(100, Math.max(1, Math.floor(Number(rawTopK) || 20)));
61
+ // LANE 3 read-time honesty (RENOR_READ_HONESTY, default OFF): provenance +
62
+ // contradiction + abstention alongside the unchanged hits array.
63
+ const readHonesty = (hits) => (0, readHonesty_1.readHonestyEnabled)()
64
+ ? {
65
+ readHonesty: (0, readHonesty_1.readHonestyForItems)({
66
+ db, query, items: hits, ledgerRelPath: config_ledgerPath,
67
+ }),
68
+ }
69
+ : {};
70
+ try {
71
+ const retrieved = await (0, orchestrator_1.retrieveContext)(db, vectorIndex, provider, query, topK, priorityPaths, {}, { isLedgerNote: isLedger });
72
+ if (!productEvidenceEnabled || !productEvidenceOptions) {
73
+ // Preserve the pre-evidence response contract exactly when the feature is off.
74
+ const plain = (0, ledgerPresentation_1.presentLedgerEvents)(retrieved.hits, isLedger);
75
+ return void res.json({
76
+ query: retrieved.query,
77
+ hits: plain,
78
+ ...(structuredOn
79
+ ? { composedContext: (0, composer_1.composeQueryContextFromDb)(db, { query: retrieved.query, hits: plain }) }
80
+ : {}),
81
+ ...readHonesty(plain),
82
+ });
83
+ }
84
+ const attached = await (0, attach_1.attachSearchEvidence)({
85
+ query,
86
+ hits: retrieved.hits,
87
+ vaultPath,
88
+ options: productEvidenceOptions,
89
+ extractor: productEvidenceExtractor,
90
+ enabled: true,
91
+ });
92
+ // The evidence pass read the sources as stored; what the caller is shown is what the user said.
93
+ const shown = (0, ledgerPresentation_1.presentLedgerEvents)(attached.hits, isLedger);
94
+ res.json({
95
+ query: retrieved.query,
96
+ hits: shown,
97
+ evidence: attached.evidence,
98
+ ...(structuredOn
99
+ ? { composedContext: (0, composer_1.composeQueryContextFromDb)(db, { query: retrieved.query, hits: shown.filter((h) => h.notePath !== attach_1.EVIDENCE_HIT_PATH), evidence: attached.evidence }) }
100
+ : {}),
101
+ ...readHonesty(shown),
102
+ });
103
+ }
104
+ catch (e) {
105
+ res.status(500).json({ error: e instanceof Error ? e.message : String(e) });
106
+ }
107
+ });
108
+ app.get('/entity/:name', (req, res) => {
109
+ const entity = (0, entityLookup_1.lookupEntity)(db, req.params.name);
110
+ if (!entity)
111
+ return void res.status(404).json({ error: 'not found' });
112
+ res.json(entity);
113
+ });
114
+ app.get('/facts/:entityId', (req, res) => {
115
+ // Current-only by default (temporal-memory contract): superseded facts carry
116
+ // valid_to and are opt-in via history/asOf endpoints, never the ID route.
117
+ const rows = db.prepare('SELECT * FROM facts WHERE subject_entity_id = ? AND valid_to IS NULL ORDER BY updated_at DESC').all(Number(req.params.entityId));
118
+ res.json(rows);
119
+ });
120
+ app.post('/memory/daily', async (req, res) => {
121
+ const { date, text, source = 'api' } = req.body;
122
+ if (!date || !text)
123
+ return void res.status(400).json({ error: 'date and text required' });
124
+ try {
125
+ await (0, writer_1.appendDailyMemory)(vaultPath, date, { text, source }, memoryDir);
126
+ res.json({ ok: true });
127
+ }
128
+ catch (e) {
129
+ res.status(500).json({ error: e instanceof Error ? e.message : String(e) });
130
+ }
131
+ });
132
+ // Lifecycle-backed durable memory (ledger-first, supersedes, idempotent, returns receipt).
133
+ app.post('/memory/fact', async (req, res) => {
134
+ const { subject, predicate, object, source } = req.body;
135
+ if (!subject || !predicate || !object)
136
+ return void res.status(400).json({ error: 'subject, predicate, object required' });
137
+ try {
138
+ res.json(await (0, lifecycle_1.remember)(db, vaultPath, config_ledgerPath, { subject, predicate, object, source }));
139
+ }
140
+ catch (e) {
141
+ // A rejected lifecycle FIELD is the caller's mistake, not an engine fault: remember()
142
+ // validates every field before touching the ledger, so this is a bad request and must
143
+ // answer 4xx. Answering 500 made a client-side type bug (a non-string `object`) look like
144
+ // a server outage. Engine faults — unreadable ledger, reused event id, clock regression,
145
+ // an escaping ledger path — still throw plain Errors and stay 500.
146
+ if (e instanceof lifecycle_1.LifecycleInputError)
147
+ return void res.status(400).json({ error: e.message });
148
+ res.status(500).json({ error: e instanceof Error ? e.message : String(e) });
149
+ }
150
+ });
151
+ // Facts by entity NAME (agents don't know DB ids). ?asOf=ISO&history=1
152
+ app.get('/facts-for/:name', (req, res) => {
153
+ try {
154
+ res.json((0, lifecycle_1.factsFor)(db, req.params.name, {
155
+ asOf: req.query.asOf,
156
+ includeHistory: req.query.history === '1' || req.query.history === 'true',
157
+ }));
158
+ }
159
+ catch (e) {
160
+ res.status(500).json({ error: e instanceof Error ? e.message : String(e) });
161
+ }
162
+ });
163
+ // One generic answer for anything a route did not handle: Express's own error page names the absolute path of the
164
+ // file that threw. The cause stays in this process's log.
165
+ app.use((err, _req, res, next) => {
166
+ if (res.headersSent)
167
+ return next(err);
168
+ const status = typeof err?.status === 'number' && Number.isInteger(err.status) && err.status >= 400 && err.status < 500 ? err.status : 500;
169
+ if (status >= 500)
170
+ log.error('serve_request_failed', { status }, err);
171
+ res.status(status).json({ error: status >= 500 ? 'internal error' : 'bad request' });
172
+ });
173
+ return app;
174
+ }
@@ -0,0 +1,149 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.BUILD_MANIFEST_PATH = exports.ENGINE_VERSION = exports.MAX_BUILD_MANIFEST_BYTES = void 0;
4
+ exports.readBuildIdentity = readBuildIdentity;
5
+ const node_fs_1 = require("node:fs");
6
+ const node_path_1 = require("node:path");
7
+ const UNKNOWN_BUILD_IDENTITY = Object.freeze({
8
+ commit: 'unknown',
9
+ branch: 'unknown',
10
+ dirty: null,
11
+ builtAt: null,
12
+ });
13
+ /**
14
+ * Manifest size gate. A stamp written by scripts/ci/stamp-build.mjs is ~200
15
+ * bytes, so anything in the KiB range is not a build stamp this project wrote.
16
+ * Refusing it by size (before the contents are even parsed) bounds the work and
17
+ * the memory the reader can be forced into, and keeps a giant file from ever
18
+ * becoming the input to a response.
19
+ */
20
+ exports.MAX_BUILD_MANIFEST_BYTES = 4096;
21
+ /** A git revision id as printed by `git rev-parse HEAD`, shortened or full. */
22
+ const COMMIT_PATTERN = /^[0-9a-fA-F]{7,40}$/;
23
+ /**
24
+ * ISO-8601 instant: calendar date, time to the second, optional fractional
25
+ * seconds, and either `Z` or a numeric offset — the shapes `Date#toISOString`
26
+ * and ordinary ISO producers emit. Anything else (partial dates, prose,
27
+ * dates with embedded whitespace) is not a build timestamp.
28
+ */
29
+ const BUILT_AT_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,6})?(?:Z|[+-]\d{2}:\d{2})$/;
30
+ /** Longest ISO instant worth accepting (offset + 6 fractional digits). */
31
+ const MAX_BUILT_AT_LENGTH = 35;
32
+ /** Git ref names are ASCII: letters, digits, `.`, `_`, `-` and `/` separators. */
33
+ const BRANCH_PATTERN = /^[A-Za-z0-9._/-]+$/;
34
+ /** git's own per-ref-component cap is 255 bytes; nothing legitimate is longer. */
35
+ const MAX_BRANCH_LENGTH = 255;
36
+ /** The engine package root: nearest ancestor of this module holding package.json. */
37
+ function resolveEngineRoot() {
38
+ let dir = __dirname;
39
+ for (let up = 0; up < 3; up += 1) {
40
+ if ((0, node_fs_1.existsSync)((0, node_path_1.join)(dir, 'package.json')))
41
+ return dir;
42
+ const parent = (0, node_path_1.dirname)(dir);
43
+ if (parent === dir)
44
+ break;
45
+ dir = parent;
46
+ }
47
+ return null;
48
+ }
49
+ /**
50
+ * The engine package's version, read from its package.json. Every surface that announces a version (the MCP
51
+ * initialize reply, GET /api/health, `renor --version`) takes it from here, so none can drift from the package.
52
+ * "unknown" when the file cannot be read or holds no semver-shaped version, never a guess.
53
+ */
54
+ exports.ENGINE_VERSION = (() => {
55
+ const root = resolveEngineRoot();
56
+ if (!root)
57
+ return 'unknown';
58
+ try {
59
+ const version = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(root, 'package.json'), 'utf8')).version;
60
+ return typeof version === 'string' && /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version) ? version : 'unknown';
61
+ }
62
+ catch {
63
+ return 'unknown';
64
+ }
65
+ })();
66
+ /**
67
+ * Absolute path of the stamped manifest, or null when the package root cannot
68
+ * be located (then identity is simply unknown — never a guess).
69
+ *
70
+ * Resolved from the package root rather than a fixed relative hop because the
71
+ * two layouts differ: a compiled deployment loads this module from dist/ while
72
+ * a source run (tsx: `npm run mvp`, `renor serve`) loads it from src/, and both
73
+ * must find <engine>/dist/BUILD.json.
74
+ */
75
+ exports.BUILD_MANIFEST_PATH = (() => {
76
+ const root = resolveEngineRoot();
77
+ return root === null ? null : (0, node_path_1.join)(root, 'dist', 'BUILD.json');
78
+ })();
79
+ /** Hex revision id, or the unknown placeholder. */
80
+ function validatedCommit(value) {
81
+ return typeof value === 'string' && COMMIT_PATTERN.test(value)
82
+ ? value
83
+ : UNKNOWN_BUILD_IDENTITY.commit;
84
+ }
85
+ /**
86
+ * Plausible git ref name, or the unknown placeholder. Enforces the
87
+ * `git check-ref-format` rules a charset check alone would miss (`..`, `@{`,
88
+ * leading dot, `.lock` suffix, empty component), so a filesystem path, a tenant
89
+ * slug, a URL or a ref-shaped injection cannot pass as a branch.
90
+ */
91
+ function validatedBranch(value) {
92
+ const unknown = UNKNOWN_BUILD_IDENTITY.branch;
93
+ if (typeof value !== 'string' || value.length > MAX_BRANCH_LENGTH)
94
+ return unknown;
95
+ if (!BRANCH_PATTERN.test(value))
96
+ return unknown;
97
+ if (value.includes('..') || value.includes('@{'))
98
+ return unknown;
99
+ for (const component of value.split('/')) {
100
+ if (component === '' || component.startsWith('.'))
101
+ return unknown;
102
+ if (component.endsWith('.lock'))
103
+ return unknown;
104
+ }
105
+ return value;
106
+ }
107
+ /** Parsable ISO-8601 instant, or null. */
108
+ function validatedBuiltAt(value) {
109
+ if (typeof value !== 'string' || value.length > MAX_BUILT_AT_LENGTH)
110
+ return null;
111
+ if (!BUILT_AT_PATTERN.test(value))
112
+ return null;
113
+ return Number.isFinite(Date.parse(value)) ? value : null;
114
+ }
115
+ /**
116
+ * Reads the build manifest. Returns the unknown identity — never throws — when
117
+ * the manifest is absent, unreadable, oversized, not JSON, not an object, or
118
+ * carries a value that fails its field's shape check.
119
+ */
120
+ function readBuildIdentity(manifestPath = exports.BUILD_MANIFEST_PATH) {
121
+ if (manifestPath === null)
122
+ return { ...UNKNOWN_BUILD_IDENTITY };
123
+ let raw;
124
+ try {
125
+ if ((0, node_fs_1.statSync)(manifestPath).size > exports.MAX_BUILD_MANIFEST_BYTES) {
126
+ return { ...UNKNOWN_BUILD_IDENTITY }; // not a stamp we wrote
127
+ }
128
+ raw = (0, node_fs_1.readFileSync)(manifestPath, 'utf8');
129
+ }
130
+ catch {
131
+ return { ...UNKNOWN_BUILD_IDENTITY }; // pre-stamp / snapshot deployment
132
+ }
133
+ try {
134
+ const parsed = JSON.parse(raw);
135
+ if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
136
+ return { ...UNKNOWN_BUILD_IDENTITY };
137
+ }
138
+ const manifest = parsed;
139
+ return {
140
+ commit: validatedCommit(manifest.commit),
141
+ branch: validatedBranch(manifest.branch),
142
+ dirty: typeof manifest.dirty === 'boolean' ? manifest.dirty : null,
143
+ builtAt: validatedBuiltAt(manifest.builtAt),
144
+ };
145
+ }
146
+ catch {
147
+ return { ...UNKNOWN_BUILD_IDENTITY };
148
+ }
149
+ }
@@ -0,0 +1,82 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.CallPhases = exports.PHASE_NAMES = void 0;
4
+ exports.isPhasedTool = isPhasedTool;
5
+ exports.recordPhase = recordPhase;
6
+ exports.recordedPhase = recordedPhase;
7
+ exports.markRetrieved = markRetrieved;
8
+ const node_async_hooks_1 = require("node:async_hooks");
9
+ /**
10
+ * Where the time of one read call went, for the engine's log (telemetry.ts `phases` on a `get_context` or `search_memory` line).
11
+ * Milliseconds, a number per phase and nothing else: no text of the call, its query or its result ever goes through here.
12
+ *
13
+ * embed the embedding provider's whole call for the query (token, requests, waits between retries); absent when the
14
+ * query's vector came from the query cache, so a missing `embed` says that no call to the service was made
15
+ * token of embed: waiting for an access token (about 0 when one was in hand)
16
+ * connect of embed: opening a connection to the service (TCP, TLS, address lookup); absent when a connection was reused
17
+ * call of embed: the requests themselves once connected (send, the service's own time, receive)
18
+ * retrieve the matches and facts: from the start of the call to the point they are in hand, less embed
19
+ * reply the answer built from them: from that point to the end of the call
20
+ *
21
+ * A call's phases are collected in an `AsyncLocalStorage` scope that the tool wrapper opens (server.ts), so the provider that
22
+ * measures the embedding needs no argument for it, and a call made outside a scope (a CLI, an eval, a test) records nothing.
23
+ * Requests made together add up, so the phases of such a call can sum to more than its wall time.
24
+ */
25
+ exports.PHASE_NAMES = ['embed', 'token', 'connect', 'call', 'retrieve', 'reply'];
26
+ /** The tools that report their phases: the two reads whose latency the product is judged on. */
27
+ const PHASED_TOOLS = ['get_context', 'search_memory'];
28
+ function isPhasedTool(tool) {
29
+ return PHASED_TOOLS.includes(tool);
30
+ }
31
+ const scope = new node_async_hooks_1.AsyncLocalStorage();
32
+ class CallPhases {
33
+ totals = new Map();
34
+ startedAt = performance.now();
35
+ retrievedAt;
36
+ embedAtRetrieved = 0;
37
+ /** Runs `work` with this as the call whose phases are recorded. */
38
+ run(work) {
39
+ return scope.run(this, work);
40
+ }
41
+ add(phase, ms) {
42
+ if (Number.isFinite(ms) && ms >= 0)
43
+ this.totals.set(phase, (this.totals.get(phase) ?? 0) + ms);
44
+ }
45
+ total(phase) {
46
+ return this.totals.get(phase) ?? 0;
47
+ }
48
+ /** The matches and facts are in hand: what is left of the call is the answer being built. The first mark counts. */
49
+ markRetrieved() {
50
+ if (this.retrievedAt !== undefined)
51
+ return;
52
+ this.retrievedAt = performance.now();
53
+ this.embedAtRetrieved = this.total('embed');
54
+ }
55
+ /** What the call recorded, rounded to a tenth of a millisecond; `retrieve` and `reply` only for a call that reached the mark. */
56
+ report() {
57
+ const out = {};
58
+ for (const [phase, ms] of this.totals)
59
+ out[phase] = ms;
60
+ if (this.retrievedAt !== undefined) {
61
+ out.retrieve = Math.max(0, this.retrievedAt - this.startedAt - this.embedAtRetrieved);
62
+ out.reply = Math.max(0, performance.now() - this.retrievedAt);
63
+ }
64
+ for (const phase of exports.PHASE_NAMES)
65
+ if (out[phase] !== undefined)
66
+ out[phase] = Math.round(out[phase] * 10) / 10;
67
+ return out;
68
+ }
69
+ }
70
+ exports.CallPhases = CallPhases;
71
+ /** Adds to the current call's phase, if a call is being recorded. */
72
+ function recordPhase(phase, ms) {
73
+ scope.getStore()?.add(phase, ms);
74
+ }
75
+ /** What the current call has recorded so far for a phase (0 when no call is being recorded). */
76
+ function recordedPhase(phase) {
77
+ return scope.getStore()?.total(phase) ?? 0;
78
+ }
79
+ /** The matches and facts of the current call are in hand (see CallPhases.markRetrieved). */
80
+ function markRetrieved() {
81
+ scope.getStore()?.markRetrieved();
82
+ }
@@ -0,0 +1,46 @@
1
+ "use strict";
2
+ var __importDefault = (this && this.__importDefault) || function (mod) {
3
+ return (mod && mod.__esModule) ? mod : { "default": mod };
4
+ };
5
+ Object.defineProperty(exports, "__esModule", { value: true });
6
+ exports.buildWritePathExtractors = buildWritePathExtractors;
7
+ const openai_1 = __importDefault(require("openai"));
8
+ const factExtractor_1 = require("./extraction/factExtractor");
9
+ const extractionClient_1 = require("./extraction/extractionClient");
10
+ const typedFacts_1 = require("./extraction/typedFacts");
11
+ const eventExtractor_1 = require("./extraction/eventExtractor");
12
+ const preferenceExtractor_1 = require("./extraction/preferenceExtractor");
13
+ /**
14
+ * Structured-row lanes use only a named extractor provider. A bare
15
+ * OPENAI_API_KEY does not arm them. LLM_EXTRACTION is the older fact path:
16
+ * when that flag is on and no named provider exists, it keeps the OpenAI
17
+ * client main already built from that key.
18
+ *
19
+ * The legacy fact path asks for `FACTS_MODEL` only when the resolved provider is
20
+ * one of the extractor-specific providers. On the generic OPENAI_API_KEY +
21
+ * OPENAI_BASE_URL fallback it keeps the fact extractor's own `gpt-4o-mini`
22
+ * default, which is the model `main` sent there. See
23
+ * `isExtractorSpecificProvider`.
24
+ */
25
+ function buildWritePathExtractors(config, env = process.env) {
26
+ const resolved = (0, extractionClient_1.openExtractorClient)(typedFacts_1.FACTS_MODEL, env);
27
+ const extractorClient = resolved?.client ?? null;
28
+ const legacyFactClient = config.llmExtraction && !extractorClient && config.openaiApiKey
29
+ ? new openai_1.default({ apiKey: config.openaiApiKey })
30
+ : null;
31
+ const factClient = (extractorClient ?? legacyFactClient);
32
+ return {
33
+ factExtractor: config.llmExtraction && factClient
34
+ ? (title, body) => (0, factExtractor_1.extractFacts)(factClient, title, body, (0, extractionClient_1.isExtractorSpecificProvider)(resolved?.config ?? null) ? typedFacts_1.FACTS_MODEL : 'gpt-4o-mini')
35
+ : undefined,
36
+ numericFactExtractor: (0, typedFacts_1.typedFactsEnabled)(env) && extractorClient
37
+ ? (title, body) => (0, typedFacts_1.extractNumericFacts)(extractorClient, title, body)
38
+ : undefined,
39
+ eventExtractor: (0, eventExtractor_1.chronicleEnabled)(env) && extractorClient
40
+ ? (title, body) => (0, eventExtractor_1.extractEvents)(extractorClient, title, body)
41
+ : undefined,
42
+ preferenceExtractor: (0, preferenceExtractor_1.prefsEnabled)(env) && extractorClient
43
+ ? (title, body) => (0, preferenceExtractor_1.extractPreferences)(extractorClient, title, body)
44
+ : undefined,
45
+ };
46
+ }