renor-engine 0.0.0-stage → 1.0.0

package/dist/mvp/compileCache.js

@@ -0,0 +1,249 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compileCacheOverlap = compileCacheOverlap;
+exports.releaseSeedDir = releaseSeedDir;
+exports.enableWorkspaceCompileCache = enableWorkspaceCompileCache;
+exports.activeCompileCacheDir = activeCompileCacheDir;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_module_1 = __importDefault(require("node:module"));
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * This workspace's own Node compile cache, enabled before anything heavy loads.
+ *
+ * WHY IT IS HERE AND NOT IN cli.ts: cli.ts's own imports are resolved before any
+ * statement in it runs, so a call there would enable the cache AFTER the modules
+ * that dominate a cold start had already been compiled. This module is imported
+ * first for its side effect, and nothing heavy is imported above it.
+ *
+ * WHY IT IS PER WORKSPACE: the cache is a write. Two workspaces sharing one
+ * directory would be one workspace's engine creating files another workspace's
+ * engine owns, which on a host where each workspace runs as its own OS account is
+ * a cross-tenant write channel. The directory therefore comes from
+ * MVP_COMPILE_CACHE_DIR, which provision-renor-tenant.sh derives per workspace
+ * (`/var/lib/renor/<slug>/cache/compile`) rather than from a shared value. With the
+ * variable unset there is NO cache: nothing is derived from MVP_MEMORY_DIR.
+ *
+ * WHY IT IS NEVER IN A DATA TREE: a cache directory that overlaps the memory,
+ * history or auth trees is neither created nor enabled here (Node writes its
+ * entries at exit, so enabling first would leave them behind even though
+ * loadMvpConfig then refuses the start), because those trees are indexed,
+ * exported, or hold client secrets.
+ *
+ * WHY A FAILURE IS NOT FATAL: this is a speed optimisation, not a correctness
+ * input. Node's own contract for enableCompileCache is to report rather than
+ * throw, and the engine must start on a read-only or unwritable cache dir, on a
+ * Node build without compile-cache support, and with NODE_DISABLE_COMPILE_CACHE=1.
+ * A refusal is reported once, on stderr, and startup continues — measurably
+ * slower on some hosts, never wrong.
+ */
+/** Reported once per process, and only when the cache was not enabled. */
+let reported = false;
+/**
+ * Why `dir` may not be a compile cache, or null when it may.
+ *
+ * ONE implementation, used twice: here, BEFORE the directory is created and the cache enabled
+ * (a refused start must leave nothing behind in a data tree: Node writes its entries at process
+ * exit, including the exit after a refusal), and by loadMvpConfig, which turns it into the
+ * startup refusal. Dependency-free on purpose: this module runs before anything heavy loads.
+ */
+function compileCacheOverlap(dir, trees) {
+    const inside = (a, b) => a !== b && b.startsWith(a + node_path_1.default.sep);
+    const overlapsEither = (a, b) => a === b || inside(a, b) || inside(b, a);
+    const labelled = [
+        ['the fact memory directory (MVP_MEMORY_DIR)', trees.memoryDir],
+        ['the promoted history directory (MVP_HISTORY_DIR)', trees.historyDir],
+        ['the OAuth client registry (MVP_AUTH_STATE_PATH)', trees.authStatePath],
+    ];
+    for (const [label, tree] of labelled) {
+        if (tree && overlapsEither(dir, tree)) {
+            return `MVP_COMPILE_CACHE_DIR (${dir}) must not be equal to, contain, or sit inside ${label}. `
+                + 'It is a rebuildable cache of compiled code, not user data, and a cache inside a data tree '
+                + 'would be indexed, exported, or shipped with the workspace.';
+        }
+    }
+    return null;
+}
+function resolvedEnvPath(name) {
+    const raw = (process.env[name] ?? '').trim();
+    return raw === '' ? null : node_path_1.default.resolve(raw);
+}
+/**
+ * Why an EXISTING cache directory may not be used, or null. A cache is loaded as code, so it
+ * must be a real directory (not a symlink) that only this process's user can write: a
+ * group- or world-writable one lets another account plant what this engine compiles from.
+ */
+function unsafeExistingDir(dir) {
+    let st;
+    try {
+        st = node_fs_1.default.lstatSync(dir);
+    }
+    catch (err) {
+        return `cannot inspect ${dir} (${err.code ?? 'error'})`;
+    }
+    if (st.isSymbolicLink())
+        return `${dir} is a symlink`;
+    if (!st.isDirectory())
+        return `${dir} is not a directory`;
+    if ((st.mode & 0o022) !== 0) {
+        return `${dir} is writable by group or others (mode ${(st.mode & 0o777).toString(8)})`;
+    }
+    if (typeof process.geteuid === 'function' && st.uid !== process.geteuid()) {
+        return `${dir} is owned by another user (uid ${st.uid})`;
+    }
+    return null;
+}
+function declined(reason) {
+    if (!reported) {
+        reported = true;
+        console.error(`[mvp] compile cache not enabled (${reason}); the engine starts normally without it`);
+    }
+    return { enabled: false, directory: null, reason, seeded: 0 };
+}
+/**
+ * The release's compile-cache seed, copied into this workspace's own (empty) cache.
+ *
+ * WHY: Node keys a cache entry by the file's path, so every release path starts a workspace's cache empty
+ * (provision-renor-tenant.sh empties it when the pin moves), and the first wake after each release compiled the whole
+ * module graph again: about 400 ms of CPU on the harness's small workspace, which a hosted unit's CPUQuota stretches to
+ * about twice that in wall time. deploy-remote.sh runs `dist/mvp/compileSeed.js` once per release, at the release's final
+ * path, into `<release>/.compile-seed`; the engine copies those entries into the cache it owns when that cache is empty.
+ *
+ * WHY A COPY AND NOT A SHARED CACHE: the per-workspace cache above is one account's own write. Pointing every workspace at
+ * the release's directory would make it a shared one (or a read of one whose owner is another account). The copy keeps the
+ * invariant: the engine only ever loads code from a directory it owns, which only it can write, and that the seed
+ * filled before the first start.
+ *
+ * WHAT IS TRUSTED: only a seed directory that root (or this very account) owns and no group or other can write, holding
+ * regular files, in the sub-directory Node names for this Node build and V8 flags (it ends in the owner's uid; the build
+ * account's uid is not this workspace's, so the name is compared without it). Anything else is not read. A failure is
+ * never fatal: the cache fills as it always did.
+ */
+const SEED_ENTRY = /^[0-9a-f]{8}$/;
+const MAX_SEED_ENTRIES = 4096;
+const MAX_SEED_ENTRY_BYTES = 32 * 1024 * 1024;
+/** The directory deploy-remote.sh seeds for the release this code runs from, unless MVP_COMPILE_SEED_DIR names another. */
+function releaseSeedDir() {
+    const explicit = resolvedEnvPath('MVP_COMPILE_SEED_DIR');
+    return explicit ?? node_path_1.default.resolve(__dirname, '..', '..', '.compile-seed');
+}
+function trustedSeedDir(dir) {
+    let st;
+    try {
+        st = node_fs_1.default.lstatSync(dir);
+    }
+    catch {
+        return false;
+    }
+    if (!st.isDirectory() || st.isSymbolicLink() || (st.mode & 0o022) !== 0)
+        return false;
+    const me = typeof process.geteuid === 'function' ? process.geteuid() : st.uid;
+    return st.uid === 0 || st.uid === me;
+}
+/** `v22.23.2-x64-9de703df-1000` -> `v22.23.2-x64-9de703df`: Node's cache sub-directory without the uid it ends in. */
+function withoutUid(name) {
+    const m = /^(v[0-9][\w.]*-[\w]+-[0-9a-f]+)-\d+$/.exec(name);
+    return m ? m[1] : null;
+}
+/**
+ * Copy the seed into `target` (the versioned directory Node is using) when it holds no entries. Returns how many entries
+ * were copied. An entry that is half written (a start killed during the copy) is rejected by Node's own checksum and compiled again.
+ */
+function seedFromRelease(target) {
+    try {
+        const seedRoot = releaseSeedDir();
+        if (!trustedSeedDir(seedRoot))
+            return 0;
+        const want = withoutUid(node_path_1.default.basename(target));
+        if (want === null)
+            return 0;
+        const sub = node_fs_1.default.readdirSync(seedRoot).find(name => withoutUid(name) === want);
+        if (sub === undefined)
+            return 0;
+        const from = node_path_1.default.join(seedRoot, sub);
+        if (!trustedSeedDir(from))
+            return 0;
+        node_fs_1.default.mkdirSync(target, { recursive: true, mode: 0o700 });
+        if (node_fs_1.default.readdirSync(target).length > 0)
+            return 0; // this workspace already has its own entries: never mix
+        let copied = 0;
+        for (const entry of node_fs_1.default.readdirSync(from, { withFileTypes: true })) {
+            if (!entry.isFile() || !SEED_ENTRY.test(entry.name))
+                continue;
+            if (copied >= MAX_SEED_ENTRIES)
+                break;
+            const src = node_path_1.default.join(from, entry.name);
+            if (node_fs_1.default.statSync(src).size > MAX_SEED_ENTRY_BYTES)
+                continue;
+            // Straight to the final name: Node checks each entry's size and checksum before it uses one and compiles again when
+            // they do not match, so an entry a killed start left half written costs a compile, never a wrong result. A temporary
+            // name and a rename would add 30 ms of syscalls for 588 entries.
+            node_fs_1.default.copyFileSync(src, node_path_1.default.join(target, entry.name), node_fs_1.default.constants.COPYFILE_EXCL);
+            copied++;
+        }
+        return copied;
+    }
+    catch {
+        return 0; // a speed optimisation: whatever went wrong, the engine starts and fills its cache as it always did
+    }
+}
+/**
+ * Enable the cache and report what Node decided. Safe to call more than once;
+ * Node returns ALREADY_ENABLED and the first directory wins.
+ *
+ * Only an EXPLICIT MVP_COMPILE_CACHE_DIR enables a cache. There is deliberately no derived
+ * default: a directory worked out from MVP_MEMORY_DIR can land in a shared place (a memory
+ * directory of /tmp/x derives /tmp/cache/compile), and a shared compile cache is a cross-user
+ * write. The provisioner names a per-workspace directory in every env file it writes.
+ */
+function enableWorkspaceCompileCache() {
+    const explicit = resolvedEnvPath('MVP_COMPILE_CACHE_DIR');
+    if (explicit === null) {
+        return { enabled: false, directory: null, reason: 'MVP_COMPILE_CACHE_DIR is not set', seeded: 0 };
+    }
+    // BEFORE mkdir and before enabling: a directory inside a data tree is skipped, never created.
+    // loadMvpConfig still refuses the start with the full message afterwards.
+    const overlap = compileCacheOverlap(explicit, {
+        memoryDir: resolvedEnvPath('MVP_MEMORY_DIR'),
+        historyDir: resolvedEnvPath('MVP_HISTORY_DIR'),
+        authStatePath: resolvedEnvPath('MVP_AUTH_STATE_PATH'),
+    });
+    if (overlap !== null) {
+        return { enabled: false, directory: null, reason: 'MVP_COMPILE_CACHE_DIR overlaps a data tree; no cache written', seeded: 0 };
+    }
+    if (typeof node_module_1.default.enableCompileCache !== 'function') {
+        return declined('this Node build has no module.enableCompileCache');
+    }
+    // Create it here rather than trusting it to exist: the engine is the thing that writes into
+    // it, and a 0700 directory it owns is the narrowest grant that lets it. mkdir with recursive
+    // ignores EEXIST, so this is idempotent. A failure is not fatal: the checks below report it.
+    try {
+        node_fs_1.default.mkdirSync(explicit, { recursive: true, mode: 0o700 });
+    }
+    catch {
+        // Reported through the checks below; nothing to add here.
+    }
+    const unsafe = unsafeExistingDir(explicit);
+    if (unsafe !== null)
+        return declined(unsafe);
+    const result = node_module_1.default.enableCompileCache(explicit);
+    const accepted = result.status === node_module_1.default.constants.compileCacheStatus.ENABLED
+        || result.status === node_module_1.default.constants.compileCacheStatus.ALREADY_ENABLED;
+    if (!accepted) {
+        return declined(result.status === node_module_1.default.constants.compileCacheStatus.DISABLED
+            ? 'disabled by NODE_DISABLE_COMPILE_CACHE'
+            : result.message ?? `status ${result.status}`);
+    }
+    const directory = result.directory ?? explicit;
+    return { enabled: true, directory, reason: null, seeded: seedFromRelease(node_module_1.default.getCompileCacheDir() ?? directory) };
+}
+/**
+ * The directory this process is actually using, or undefined when no cache is
+ * enabled. Read from Node rather than recomputed, so it reports the truth even
+ * when NODE_COMPILE_CACHE was set in the environment and won.
+ */
+function activeCompileCacheDir() {
+    return node_module_1.default.getCompileCacheDir();
+}

package/dist/mvp/compileSeed.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// Fills a compile-cache directory for THIS release, for deploy-remote.sh to run once at the release's final path:
+//
+//   MVP_COMPILE_CACHE_DIR=<release>/.compile-seed node <release>/dist/mvp/compileSeed.js
+//
+// It does what cli.ts does before it serves: enables the cache first, then loads the modules the engine loads at start (the
+// config, the server and everything under it, telemetry, the PostHog glue), and exits 0, which is when Node writes its entries.
+// It starts no server, reads no workspace and needs no environment beyond the cache directory. The engine copies the result into
+// each workspace's own cache on its first start of the release (compileCache.ts, seedFromRelease).
+const compileCache_1 = require("./compileCache");
+const report = (0, compileCache_1.enableWorkspaceCompileCache)();
+try {
+    if (!report.enabled) {
+        console.error(`[compile-seed] not seeding: ${report.reason}`);
+        process.exit(2);
+    }
+    // Plain requires, after the cache is on, for the same reason cli.ts enables it first: these are the heavy modules.
+    for (const module of ['./config', './server', './telemetry', './posthogMcp'])
+        require(module);
+    console.log(`[compile-seed] loaded the startup modules into ${report.directory}`);
+    process.exit(0);
+}
+catch (err) {
+    console.error('[compile-seed] failed:', err instanceof Error ? err.message : err);
+    process.exit(1);
+}

package/dist/mvp/config.js

@@ -0,0 +1,288 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_LEDGER_REL = void 0;
+exports.loadMvpConfig = loadMvpConfig;
+const path_1 = __importDefault(require("path"));
+const compileCache_1 = require("./compileCache");
+exports.DEFAULT_LEDGER_REL = 'System/Memory Events Ledger.md';
+/** Values printed in the documentation (and the commonest guesses): anyone who has read the README can sign in with them. */
+const KNOWN_WEAK_OWNER_PASSWORDS = new Set([
+    'replace-this-password', 'choose-a-long-secret', '<owner-secret>', 'owner-secret', 'your-password-here',
+    'password', 'password1', 'password123', '12345678', '123456789', 'qwertyui', 'qwerty123', 'changeme', 'change-me', 'letmein1',
+]);
+function weakOwnerPasswordReason(password) {
+    const lower = password.toLowerCase();
+    if (KNOWN_WEAK_OWNER_PASSWORDS.has(lower))
+        return 'it is an example value from the documentation or a very common password';
+    if (new Set(lower).size === 1)
+        return 'it is one character repeated';
+    return null;
+}
+function requiredEnv(name, hint) {
+    const value = process.env[name];
+    if (!value || value.trim() === '') {
+        throw new Error(`Missing required configuration ${name}: ${hint}`);
+    }
+    return value.trim();
+}
+/**
+ * Where this workspace keeps its Node compile cache.
+ *
+ * Three properties, each a correctness property rather than taste:
+ *
+ *  - INSIDE this workspace's own state tree, named explicitly: provision-renor-tenant.sh writes
+ *    `/var/lib/renor/<slug>/cache/compile` into every env file, and that whole tree is the unit's
+ *    only ReadWritePaths entry. There is NO derived default (null when unset): a path worked out
+ *    from the memory directory can land in a shared place such as /tmp/cache/compile.
+ *  - NEVER inside a data tree. The memory directory is indexed and exported, the history directory
+ *    is promoted transcripts, and the auth path holds client secrets; Node's compiled-code blobs
+ *    belong in none of them. Overlap in EITHER direction throws.
+ *  - NEVER shared. Overlap is checked against THIS workspace's trees, but a path pointing into a
+ *    sibling workspace is not detectable from inside this process — so the provisioner derives
+ *    the path per workspace instead of reading a shared configuration value, and refuses an env
+ *    file that names anything else.
+ */
+function resolveCompileCacheDir(memoryDir, historyDir, authStatePath) {
+    const raw = (process.env.MVP_COMPILE_CACHE_DIR ?? '').trim();
+    if (raw === '')
+        return null;
+    const dir = path_1.default.resolve(raw);
+    const refusal = (0, compileCache_1.compileCacheOverlap)(dir, { memoryDir, historyDir, authStatePath });
+    if (refusal !== null)
+        throw new Error(refusal);
+    return dir;
+}
+function loadMvpConfig() {
+    const memoryDir = requiredEnv('MVP_MEMORY_DIR', 'dedicated owner memory directory for this product (create a NEW folder, e.g. ~/memory-company-data)');
+    const port = Number(process.env.MVP_PORT ?? 3471);
+    if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+        throw new Error('MVP_PORT must be an integer between 1 and 65535');
+    }
+    const baseUrlRaw = requiredEnv('MVP_BASE_URL', 'the externally reachable base URL of this service, e.g. http://localhost:3471 for local tests or your public https URL for ChatGPT');
+    let baseUrl;
+    try {
+        baseUrl = new URL(baseUrlRaw);
+    }
+    catch {
+        throw new Error(`MVP_BASE_URL is not a valid URL: ${baseUrlRaw}`);
+    }
+    if (baseUrl.hash || baseUrl.search) {
+        throw new Error('MVP_BASE_URL must not contain a query or fragment');
+    }
+    // Owner identity: the ONLY account that can complete authorization.
+    const ownerEmail = requiredEnv('MVP_OWNER_EMAIL', 'the single owner login email; no other identity may authorize').toLowerCase();
+    const ownerPassword = requiredEnv('MVP_OWNER_PASSWORD', 'the owner login secret (env-only; never commit it to Git or write it into the memory directory)');
+    if (ownerPassword.length < 8) {
+        throw new Error('MVP_OWNER_PASSWORD must be at least 8 characters');
+    }
+    // The README's example is public: anyone who can reach the login page signs in with it, so refuse to start on it.
+    const weakReason = weakOwnerPasswordReason(ownerPassword);
+    if (weakReason) {
+        throw new Error(`MVP_OWNER_PASSWORD is too weak: ${weakReason}. Choose your own secret, for example: export MVP_OWNER_PASSWORD="$(openssl rand -base64 18)"`);
+    }
+    const accessTokenTtlSeconds = Number(process.env.MVP_ACCESS_TOKEN_TTL_SECONDS ?? 3600);
+    if (!Number.isFinite(accessTokenTtlSeconds) || accessTokenTtlSeconds < 60) {
+        throw new Error('MVP_ACCESS_TOKEN_TTL_SECONDS must be at least 60');
+    }
+    // AUTH-B1: exact callback-URI allowlist for DCR. Deny by default: unset or
+    // empty means NO client may register until the owner names exact callbacks.
+    const allowedCallbackUris = (process.env.MVP_ALLOWED_CALLBACK_URIS ?? '')
+        .split(',').map(s => s.trim()).filter(Boolean);
+    for (const uri of allowedCallbackUris) {
+        try {
+            new URL(uri);
+        }
+        catch {
+            throw new Error(`MVP_ALLOWED_CALLBACK_URIS contains an invalid URL: ${uri}`);
+        }
+        if (/[\s]/.test(uri)) {
+            throw new Error('MVP_ALLOWED_CALLBACK_URIS entries must be exact URIs without whitespace');
+        }
+    }
+    // AUTH-B3: bounded failed-login limiter knobs (operator-tunable, sane defaults).
+    const loginMaxFailures = Number(process.env.MVP_LOGIN_MAX_FAILURES ?? 5);
+    if (!Number.isInteger(loginMaxFailures) || loginMaxFailures < 1 || loginMaxFailures > 100) {
+        throw new Error('MVP_LOGIN_MAX_FAILURES must be an integer between 1 and 100');
+    }
+    const loginLockoutMs = Number(process.env.MVP_LOGIN_LOCKOUT_MS ?? 30_000);
+    if (!Number.isInteger(loginLockoutMs) || loginLockoutMs < 1 || loginLockoutMs > 3_600_000) {
+        throw new Error('MVP_LOGIN_LOCKOUT_MS must be an integer between 1 and 3600000');
+    }
+    const memoryDirResolved = path_1.default.resolve(memoryDir);
+    // CLIENT-PERSISTENCE: explicit private OAuth client-registry path. The
+    // registry holds registered client metadata (incl. client secrets), so it
+    // must live outside the memory and history trees in both directions.
+    const authStatePathRaw = requiredEnv('MVP_AUTH_STATE_PATH', 'private path of the persistent OAuth client registry, e.g. /path/to/private-runtime/auth/clients.json '
+        + '(file inside a NEW owner-only 0700 directory OUTSIDE the memory/history/export directories; never in Git)');
+    const authStatePath = path_1.default.resolve(authStatePathRaw);
+    // SSE-CHATGPT: transport mode. Default stays JSON (stateless) — the exact
+    // behavior every existing test pins. 'false'/'0' opts into SSE responses.
+    const gatewaySecret = (process.env.MVP_GATEWAY_SECRET ?? '').trim();
+    const mcpJsonRaw = (process.env.MVP_MCP_JSON ?? 'true').trim().toLowerCase();
+    if (mcpJsonRaw !== 'true' && mcpJsonRaw !== 'false' && mcpJsonRaw !== '1' && mcpJsonRaw !== '0') {
+        throw new Error('MVP_MCP_JSON must be true or false');
+    }
+    const mcpJsonResponse = mcpJsonRaw === 'true' || mcpJsonRaw === '1';
+    const mcpMaxSessions = Number(process.env.MVP_MCP_MAX_SESSIONS ?? 100);
+    // Each retained session holds a full MCP server (about 0.3 MB measured), so the ceiling is 1,000: 10,000 would
+    // extrapolate to roughly 3 GB of heap, past Node's default limit.
+    if (!Number.isInteger(mcpMaxSessions) || mcpMaxSessions < 1) {
+        throw new Error('MVP_MCP_MAX_SESSIONS must be an integer of at least 1');
+    }
+    if (mcpMaxSessions > 1_000) {
+        throw new Error(`MVP_MCP_MAX_SESSIONS is ${mcpMaxSessions}; the largest accepted value is 1000 (each session costs about 0.3 MB of heap)`);
+    }
+    const mcpSessionTtlMs = Number(process.env.MVP_MCP_SESSION_TTL_MS ?? 3_600_000);
+    if (!Number.isInteger(mcpSessionTtlMs) || mcpSessionTtlMs < 1_000 || mcpSessionTtlMs > 86_400_000) {
+        throw new Error('MVP_MCP_SESSION_TTL_MS must be an integer between 1000 and 86400000');
+    }
+    const embeddingRaw = (process.env.MVP_EMBEDDING_PROVIDER ?? process.env.EMBEDDING_PROVIDER ?? 'none').trim().toLowerCase();
+    if (embeddingRaw !== 'none' && embeddingRaw !== 'local' && embeddingRaw !== 'openai' && embeddingRaw !== 'vertex') {
+        throw new Error('MVP_EMBEDDING_PROVIDER must be none, local, openai, or vertex');
+    }
+    const embeddingProvider = embeddingRaw;
+    let embeddingApiKey;
+    let embeddingModel;
+    let embeddingBaseURL;
+    let embeddingDims;
+    let vertexKeyFile;
+    let vertexProject;
+    let vertexLocation;
+    if (embeddingProvider === 'openai') {
+        const key = (process.env.MVP_EMBEDDING_API_KEY ?? process.env.OPENAI_API_KEY ?? '').trim();
+        if (!key)
+            throw new Error('MVP_EMBEDDING_API_KEY (or OPENAI_API_KEY) is required when MVP_EMBEDDING_PROVIDER=openai');
+        embeddingApiKey = key;
+        embeddingModel = (process.env.MVP_EMBEDDING_MODEL ?? process.env.EMBEDDING_MODEL ?? 'voyage-4-large').trim();
+        embeddingBaseURL = (process.env.MVP_EMBEDDING_BASE_URL ?? process.env.EMBEDDING_BASE_URL ?? 'https://api.voyageai.com/v1').trim();
+        const dimsRaw = process.env.MVP_EMBEDDING_DIMS ?? process.env.EMBEDDING_DIMS ?? '1024';
+        embeddingDims = Number(dimsRaw);
+        if (!Number.isInteger(embeddingDims) || embeddingDims < 8 || embeddingDims > 8192) {
+            throw new Error('MVP_EMBEDDING_DIMS must be an integer between 8 and 8192');
+        }
+    }
+    else if (embeddingProvider === 'vertex') {
+        const keyFile = (process.env.MVP_VERTEX_KEY_FILE
+            ?? process.env.GOOGLE_APPLICATION_CREDENTIALS
+            ?? process.env.RENOR_EVAL_VERTEX_KEY_FILE
+            ?? '').trim();
+        if (!keyFile) {
+            throw new Error('MVP_VERTEX_KEY_FILE (or GOOGLE_APPLICATION_CREDENTIALS) is required when MVP_EMBEDDING_PROVIDER=vertex');
+        }
+        vertexKeyFile = path_1.default.resolve(keyFile);
+        vertexProject = (process.env.MVP_VERTEX_PROJECT
+            ?? process.env.RENOR_EVAL_VERTEX_PROJECT
+            ?? '').trim();
+        if (!/^[a-z0-9-]+$/.test(vertexProject)) {
+            throw new Error('MVP_VERTEX_PROJECT (or RENOR_EVAL_VERTEX_PROJECT) is required when MVP_EMBEDDING_PROVIDER=vertex');
+        }
+        vertexLocation = (process.env.MVP_VERTEX_LOCATION
+            ?? process.env.RENOR_EVAL_VERTEX_LOCATION
+            ?? '').trim();
+        if (!vertexLocation) {
+            throw new Error('MVP_VERTEX_LOCATION (or RENOR_EVAL_VERTEX_LOCATION) is required when MVP_EMBEDDING_PROVIDER=vertex');
+        }
+        if (!/^[a-z0-9-]+$/.test(vertexLocation)) {
+            throw new Error('MVP_VERTEX_LOCATION must be a valid GCP location like europe-west4');
+        }
+        embeddingModel = (process.env.MVP_EMBEDDING_MODEL ?? process.env.EMBEDDING_MODEL ?? process.env.RENOR_EVAL_MODEL ?? 'gemini-embedding-001').trim();
+        const dimsRaw = process.env.MVP_EMBEDDING_DIMS ?? process.env.EMBEDDING_DIMS ?? process.env.RENOR_EVAL_EMBEDDING_DIMS ?? '768';
+        embeddingDims = Number(dimsRaw);
+        if (!Number.isInteger(embeddingDims) || ![768, 1536, 3072].includes(embeddingDims)) {
+            throw new Error('MVP_EMBEDDING_DIMS for vertex must be 768, 1536, or 3072');
+        }
+    }
+    else if (embeddingProvider === 'local') {
+        embeddingModel = (process.env.MVP_EMBEDDING_MODEL ?? process.env.EMBEDDING_MODEL ?? 'Xenova/multilingual-e5-base').trim();
+        const dimsRaw = process.env.MVP_EMBEDDING_DIMS ?? process.env.EMBEDDING_DIMS;
+        if (dimsRaw) {
+            embeddingDims = Number(dimsRaw);
+            if (!Number.isInteger(embeddingDims) || embeddingDims < 8 || embeddingDims > 8192) {
+                throw new Error('MVP_EMBEDDING_DIMS must be an integer between 8 and 8192');
+            }
+        }
+    }
+    let explicitDbPath = null;
+    const rawDb = process.env.MVP_DB_PATH;
+    if (rawDb && rawDb.trim() !== '') {
+        explicitDbPath = path_1.default.resolve(rawDb.trim());
+        if (explicitDbPath.endsWith('.md')) {
+            throw new Error('MVP_DB_PATH must not be a Markdown file');
+        }
+    }
+    // On-demand (RENOR_ON_DEMAND): the one switch, off unless explicitly on. Only enable it
+    // for a workspace whose clients reach it through the gateway, with the gateway's own
+    // RENOR_ON_DEMAND on: nothing else starts a sleeping engine.
+    const onDemandRaw = (process.env.RENOR_ON_DEMAND ?? '').trim().toLowerCase();
+    if (!['', '0', 'false', '1', 'true'].includes(onDemandRaw)) {
+        throw new Error('RENOR_ON_DEMAND must be 1/true or 0/false');
+    }
+    let idleExitMs = null;
+    if (onDemandRaw === '1' || onDemandRaw === 'true') {
+        const idleSeconds = Number(process.env.RENOR_ON_DEMAND_IDLE_SECONDS ?? 600);
+        if (!Number.isInteger(idleSeconds) || idleSeconds < 1 || idleSeconds > 86_400) {
+            throw new Error('RENOR_ON_DEMAND_IDLE_SECONDS must be an integer between 1 and 86400');
+        }
+        idleExitMs = idleSeconds * 1000;
+    }
+    const overlaps = (a, b) => a === b || a.startsWith(b + path_1.default.sep);
+    if (overlaps(authStatePath, memoryDirResolved)) {
+        throw new Error('MVP_AUTH_STATE_PATH must not be inside the fact memory directory (MVP_MEMORY_DIR)');
+    }
+    if (authStatePath.endsWith('.md')) {
+        throw new Error('MVP_AUTH_STATE_PATH must not be a Markdown file');
+    }
+    // Promoted-history directory: optional, explicit, and strictly disjoint
+    // from the fact memory directory (no overlap in either direction).
+    let historyDir = null;
+    const rawHistoryDir = process.env.MVP_HISTORY_DIR;
+    if (rawHistoryDir && rawHistoryDir.trim() !== '') {
+        historyDir = path_1.default.resolve(rawHistoryDir.trim());
+        const inside = (a, b) => a !== b && b.startsWith(a + path_1.default.sep);
+        if (historyDir === memoryDirResolved
+            || inside(historyDir, memoryDirResolved)
+            || inside(memoryDirResolved, historyDir)) {
+            throw new Error('MVP_HISTORY_DIR must not be equal to or overlap the fact memory directory (MVP_MEMORY_DIR)');
+        }
+        if (overlaps(authStatePath, historyDir) || overlaps(historyDir, authStatePath)) {
+            throw new Error('MVP_AUTH_STATE_PATH must not be equal to or overlap the promoted history directory (MVP_HISTORY_DIR)');
+        }
+    }
+    // This workspace's own compile cache. A wrong location is REFUSED, not repaired: silently
+    // relocating it would hide the misconfiguration that, in a shared directory, is precisely the
+    // cross-tenant write this exists to prevent.
+    const compileCacheDir = resolveCompileCacheDir(memoryDirResolved, historyDir, authStatePath);
+    return {
+        memoryDir: memoryDirResolved,
+        dbPath: explicitDbPath ?? path_1.default.join(path_1.default.resolve(memoryDir), '.memory-index', 'index.db'),
+        ledgerRelPath: process.env.MVP_LEDGER_REL ?? exports.DEFAULT_LEDGER_REL,
+        baseUrl,
+        port,
+        ownerEmail,
+        ownerPassword,
+        accessTokenTtlSeconds,
+        gatewaySecret,
+        allowedCallbackUris,
+        loginMaxFailures,
+        loginLockoutMs,
+        historyDir,
+        authStatePath,
+        mcpJsonResponse,
+        mcpMaxSessions,
+        mcpSessionTtlMs,
+        embeddingProvider,
+        embeddingApiKey,
+        embeddingModel,
+        embeddingBaseURL,
+        embeddingDims,
+        vertexKeyFile,
+        vertexProject,
+        vertexLocation,
+        explicitDbPath,
+        idleExitMs,
+        compileCacheDir,
+    };
+}

package/dist/mvp/connectionStatus.js

@@ -0,0 +1,80 @@
+"use strict";
+/**
+ * Which Renor an agent is talking to, said once and whenever something is wrong.
+ *
+ * Agents could not tell that they were connected to the wrong server, or that a connection had silently dropped:
+ * absence was silent. So the first tool reply of an MCP session carries one short status block, and so does every
+ * error a tool returns, with a sentence on how to reconnect. A later successful reply of the same session carries
+ * nothing, so the status costs a few dozen tokens once per session, not a line on every reply.
+ *
+ * The status is an extra trailing text block on the reply. The block a tool always returned is untouched, so
+ * nothing that reads a reply by its first block changes.
+ *
+ * It is on only for a hosted workspace (the provisioner writes MVP_INSTANCE_ID, the workspace's slug, into every
+ * tenant's environment); an engine run any other way answers as it always did.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConnectionAnnouncer = exports.HOSTED_MCP_URL = void 0;
+exports.connectionStatusFromEnv = connectionStatusFromEnv;
+exports.connectionStatusBlock = connectionStatusBlock;
+/** The one public MCP URL every hosted workspace is reached through (the gateway routes it to the workspace). */
+exports.HOSTED_MCP_URL = 'https://mcp.renor.cloud/mcp';
+/**
+ * The status of the hosted workspace this process serves, or null when it is not one (no MVP_INSTANCE_ID, or
+ * RENOR_CONNECTION_STATUS=0, the way to switch it off).
+ */
+function connectionStatusFromEnv(env) {
+    if ((env.RENOR_CONNECTION_STATUS ?? '').trim() === '0')
+        return null;
+    const workspace = (env.MVP_INSTANCE_ID ?? '').trim().toLowerCase();
+    // The slug shape the control plane issues; anything else is not a hosted workspace's name.
+    if (!/^[a-z0-9][a-z0-9_-]{0,63}$/.test(workspace))
+        return null;
+    return { workspace, url: exports.HOSTED_MCP_URL };
+}
+/** What an agent is told on its first reply: where it is, and what to do if that is not where it expected to be. */
+function firstSentence(status) {
+    return `Connected to Renor's hosted workspace "${status.workspace}" at ${status.url}; if that is not the workspace you expect, tell the user.`;
+}
+/** What an agent is told on an error: where it is, and how to connect again. */
+function errorSentence(status) {
+    return `Renor hosted workspace "${status.workspace}" at ${status.url}. If Renor stops answering or refuses you, reconnect: sign in again through your client's MCP settings for ${status.url}.`;
+}
+/** The one-line text block: a stable machine-readable field, and one short sentence. */
+function connectionStatusBlock(status, kind) {
+    const message = kind === 'first' ? firstSentence(status) : errorSentence(status);
+    return {
+        type: 'text',
+        text: JSON.stringify({ renor_connection: { hosted: true, workspace: status.workspace, url: status.url }, message }),
+    };
+}
+/**
+ * Decides, per MCP session, which replies carry the status. One of these per session server: the first tool reply
+ * takes the announcement (a session that has none to announce, because it has no session to begin, never does), and
+ * an error always carries it.
+ */
+class ConnectionAnnouncer {
+    status;
+    announced;
+    constructor(status, announceFirst) {
+        this.status = status;
+        this.announced = !announceFirst;
+    }
+    /** The reply, with the status block appended where it belongs, or the reply itself where it does not. */
+    decorate(result, first) {
+        if (this.status === null || !Array.isArray(result?.content))
+            return result;
+        const error = result.isError === true;
+        if (!error && !first)
+            return result;
+        return { ...result, content: [...result.content, connectionStatusBlock(this.status, error ? 'error' : 'first')] };
+    }
+    /** Called when a tool call starts: true for exactly one call in the session, the first. */
+    takeFirst() {
+        if (this.announced)
+            return false;
+        this.announced = true;
+        return true;
+    }
+}
+exports.ConnectionAnnouncer = ConnectionAnnouncer;