@memorax/memorax-code 0.1.0

package/lib/memorax-code-backend/dist/server-health.js

@@ -0,0 +1,16 @@
+import { json } from "./server-json.js";
+export function handleHealthRequest(state, res) {
+    return json(res, 200, {
+        ok: true,
+        service: "memorax-code-backend",
+        instanceId: process.env.MEMORAX_CODE_BACKEND_INSTANCE_ID,
+        authRequired: Boolean(state.authToken),
+        security: {
+            mode: state.security.mode,
+            allowExternalAccess: state.security.allowExternalAccess,
+        },
+        state: {
+            sessionHome: state.sessionHome,
+        },
+    });
+}

package/lib/memorax-code-backend/dist/server-http.js

@@ -0,0 +1,110 @@
+import { backendEnv } from "./backend-env.js";
+const DEFAULT_MAX_JSON_BODY_BYTES = 16 * 1024 * 1024;
+const MEMORY_VIEWER_SESSION_COOKIE = "memorax_code_memory_viewer_session";
+export class HttpRequestError extends Error {
+    statusCode;
+    constructor(statusCode, message) {
+        super(message);
+        this.statusCode = statusCode;
+        this.name = "HttpRequestError";
+    }
+}
+function maxJsonBodyBytes() {
+    const configured = Number(backendEnv("MAX_JSON_BODY_BYTES"));
+    if (Number.isFinite(configured) && configured > 0)
+        return Math.floor(configured);
+    return DEFAULT_MAX_JSON_BODY_BYTES;
+}
+export async function readJson(req, maxBytes = maxJsonBodyBytes()) {
+    const rawContentEncoding = Array.isArray(req.headers["content-encoding"])
+        ? req.headers["content-encoding"].join(",")
+        : req.headers["content-encoding"];
+    const unsupportedEncoding = (rawContentEncoding ?? "identity")
+        .split(",")
+        .map((encoding) => encoding.trim().toLowerCase())
+        .find((encoding) => encoding && encoding !== "identity");
+    if (unsupportedEncoding) {
+        throw new HttpRequestError(415, `unsupported content-encoding: ${unsupportedEncoding}`);
+    }
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        const buffer = Buffer.from(chunk);
+        size += buffer.byteLength;
+        if (size > maxBytes) {
+            throw new HttpRequestError(413, `request body exceeds ${maxBytes} bytes`);
+        }
+        chunks.push(buffer);
+    }
+    const text = Buffer.concat(chunks).toString("utf8");
+    try {
+        return text ? JSON.parse(text) : {};
+    }
+    catch (error) {
+        if (error instanceof SyntaxError) {
+            throw new HttpRequestError(400, "request body must be valid JSON");
+        }
+        throw error;
+    }
+}
+export function authorized(state, req, url) {
+    if (!state.authToken)
+        return true;
+    const authorization = req.headers.authorization;
+    const bearer = authorization?.startsWith("Bearer ") ? authorization.slice("Bearer ".length) : undefined;
+    const headerToken = req.headers["x-memorax-code-backend-token"];
+    const token = bearer
+        ?? (typeof headerToken === "string" ? headerToken : undefined)
+        ?? url.searchParams.get("token")
+        ?? undefined;
+    if (token === state.authToken)
+        return true;
+    if (url.pathname === "/memory-viewer"
+        || url.pathname.startsWith("/memory-viewer/")) {
+        const viewerCookie = cookieValue(req.headers.cookie, MEMORY_VIEWER_SESSION_COOKIE);
+        if (viewerCookie === state.authToken)
+            return true;
+    }
+    return false;
+}
+export function memoryViewerSessionCookieHeader(state, req, url) {
+    if (!state.authToken
+        || req.method !== "GET"
+        || url.pathname !== "/memory-viewer")
+        return undefined;
+    const supplied = url.searchParams.get("token");
+    const authorization = req.headers.authorization;
+    const bearer = authorization?.startsWith("Bearer ") ? authorization.slice("Bearer ".length) : undefined;
+    if (supplied !== state.authToken && bearer !== state.authToken)
+        return undefined;
+    const secure = Boolean(req.socket?.encrypted);
+    return `${MEMORY_VIEWER_SESSION_COOKIE}=${encodeURIComponent(state.authToken)}; HttpOnly; SameSite=Strict; Path=/memory-viewer${secure ? "; Secure" : ""}`;
+}
+function cookieValue(header, name) {
+    if (!header)
+        return undefined;
+    for (const part of header.split(";")) {
+        const [rawName, ...rawValue] = part.trim().split("=");
+        if (rawName !== name)
+            continue;
+        try {
+            return decodeURIComponent(rawValue.join("="));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+export function statusCodeFromError(error) {
+    if (error instanceof HttpRequestError)
+        return error.statusCode;
+    return error instanceof Error && "statusCode" in error && typeof error.statusCode === "number"
+        ? error.statusCode
+        : 500;
+}
+export function publicErrorMessage(error) {
+    return error instanceof HttpRequestError
+        ? error.message
+        : "internal server error";
+}

package/lib/memorax-code-backend/dist/server-json.js

@@ -0,0 +1,4 @@
+export function json(res, status, body) {
+    res.writeHead(status, { "content-type": "application/json" });
+    res.end(JSON.stringify(body));
+}

package/lib/memorax-code-backend/dist/server-memory-hook.js

@@ -0,0 +1,32 @@
+import { parseTurnStartCommand, parseWritebackCommand, } from "./memory-hook-command.js";
+import { readJson } from "./server-http.js";
+import { json } from "./server-json.js";
+export async function handleMemoryHookRequest(dependencies, url, req, res) {
+    if (req.method !== "POST")
+        return false;
+    if (url.pathname !== "/memory/turn-start"
+        && url.pathname !== "/memory/skill-reminder"
+        && url.pathname !== "/memory/writeback")
+        return false;
+    const body = await readJson(req);
+    if (url.pathname === "/memory/skill-reminder") {
+        json(res, 200, await dependencies.memoryReminderTraceRecorder.recordSkillReminder(body));
+        return true;
+    }
+    if (url.pathname === "/memory/turn-start") {
+        const parsed = parseTurnStartCommand(body);
+        if (!parsed.ok) {
+            json(res, 400, { ok: false, error: parsed.error });
+            return true;
+        }
+        json(res, 200, await dependencies.memoryService.recordTurnStart(parsed.command));
+        return true;
+    }
+    const parsed = parseWritebackCommand(body);
+    if (!parsed.ok) {
+        json(res, 400, { ok: false, error: parsed.error });
+        return true;
+    }
+    json(res, 200, await dependencies.memoryService.writebackTurn(parsed.command));
+    return true;
+}

package/lib/memorax-code-backend/dist/server-memory-viewer.js

@@ -0,0 +1,135 @@
+import { createHash } from "node:crypto";
+import { isMemoryProjectId, UNCLASSIFIED_PROJECT_ID } from "./memory-project.js";
+import { MEMORAX_LOGO_DATA_URL } from "./memory-viewer-logo.js";
+import { memoryViewerUserHtml } from "./memory-viewer-user-html.js";
+import { projectMemoryViewerUserData } from "./memory-viewer-user-projection.js";
+import { listMemoryViewerDataWithHistory, } from "./memory-viewer-store.js";
+import { repoMemoryReadinessForProject, } from "./repo-memory-readiness.js";
+import { json } from "./server-json.js";
+import { memoraxCodeHomeForTrace } from "./trace-config.js";
+const MEMORY_VIEWER_SESSION_ACTIVITY_WINDOW_MS = 72 * 60 * 60 * 1_000;
+const MEMORY_VIEWER_ACTIVITY_CUTOFF_GRANULARITY_MS = 60_000;
+const MEMORY_VIEWER_LOGO = Buffer.from(MEMORAX_LOGO_DATA_URL.slice(MEMORAX_LOGO_DATA_URL.indexOf(",") + 1), "base64");
+export async function handleMemoryViewerRequest(url, req, res, options = {}) {
+    if (req.method === "GET" && url.pathname === "/memory-viewer") {
+        if (!memoryViewerUserClient(url)) {
+            json(res, 400, { ok: false, error: "client must be codex or claude-code" });
+            return true;
+        }
+        res.writeHead(200, {
+            "content-type": "text/html; charset=utf-8",
+            "cache-control": "no-store",
+            "content-security-policy": "default-src 'self'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; connect-src 'self'; img-src 'self' data:; base-uri 'none'; frame-ancestors 'none'",
+            "referrer-policy": "no-referrer",
+            "x-content-type-options": "nosniff",
+            ...(options.sessionCookie ? { "set-cookie": options.sessionCookie } : {}),
+        });
+        res.end(memoryViewerUserHtml());
+        return true;
+    }
+    if (req.method === "GET" && url.pathname === "/memory-viewer/logo") {
+        res.writeHead(200, {
+            "content-type": "image/png",
+            "cache-control": "private, max-age=86400",
+            "x-content-type-options": "nosniff",
+        });
+        res.end(MEMORY_VIEWER_LOGO);
+        return true;
+    }
+    if (req.method !== "GET" || url.pathname !== "/memory-viewer/api/summary") {
+        return false;
+    }
+    const memoraxCodeHome = viewerMemoraxCodeHome(options);
+    const selectedClient = memoryViewerUserClient(url);
+    if (!selectedClient) {
+        json(res, 400, { ok: false, error: "client must be codex or claude-code" });
+        return true;
+    }
+    const requestedProject = projectFilter(url);
+    const activeSessionSince = memoryViewerActivityCutoff(options.now?.() ?? Date.now());
+    const viewerData = await listMemoryViewerDataWithHistory(memoraxCodeHome, {
+        client: selectedClient.traceClient,
+        includePendingWritebacks: true,
+        activeSessionSince,
+        includeUserProjection: true,
+        ...(requestedProject.projectId ? { projectId: requestedProject.projectId } : {}),
+        ...(requestedProject.reject ? { rejectProjectFilter: true } : {}),
+    }, { claudeProjectsRoot: options.claudeProjectsRoot });
+    const projection = viewerData.userProjection
+        ?? projectMemoryViewerUserData(viewerData.events);
+    const readiness = options.repoMemoryReadiness ?? repoMemoryReadinessForProject;
+    const projects = await Promise.all(activeMemoryViewerProjects(viewerData.activityProjects, viewerData.activityProjectSessions, activeSessionSince).map(async (project) => ({
+        projectId: project.projectId,
+        projectLabel: project.projectLabel,
+        repoMemory: await readiness(project.projectId, memoraxCodeHome),
+    })));
+    conditionalViewerJson(req, res, {
+        ok: true,
+        selectedClient: selectedClient.publicClient,
+        availableClients: ["codex", "claude-code"],
+        summary: projection.summary,
+        activities: projection.activities.slice(0, 100),
+        projects,
+        ...(viewerData.selectedProjectId ? { selectedProjectId: viewerData.selectedProjectId } : {}),
+        ...(viewerData.projectFilterStatus ? { projectFilterStatus: viewerData.projectFilterStatus } : {}),
+    });
+    return true;
+}
+function viewerMemoraxCodeHome(options) {
+    return options.memoraxCodeHome
+        ?? (options.env?.MEMORAX_CODE_HOME?.trim() || memoraxCodeHomeForTrace(options.env));
+}
+function memoryViewerUserClient(url) {
+    const value = url.searchParams.get("client");
+    const traceClient = value === null ? "codex" : traceClientFromPublicValue(value.trim().toLowerCase());
+    return traceClient
+        ? { traceClient, publicClient: traceClient === "claude" ? "claude-code" : "codex" }
+        : undefined;
+}
+function traceClientFromPublicValue(value) {
+    if (value === "codex")
+        return "codex";
+    return value === "claude" || value === "claude-code" || value === "cc"
+        ? "claude"
+        : undefined;
+}
+function activeMemoryViewerProjects(projects, projectSessions, activeSessionSince) {
+    const activeProjectIds = new Set(projectSessions
+        .filter((entry) => {
+        const lastSeenAt = Date.parse(entry.lastSeenAt);
+        return Number.isFinite(lastSeenAt) && lastSeenAt >= activeSessionSince;
+    })
+        .map((entry) => entry.projectId));
+    return projects.filter((entry) => activeProjectIds.has(entry.projectId));
+}
+function memoryViewerActivityCutoff(now) {
+    const safeNow = Number.isFinite(now) ? now : Date.now();
+    return Math.floor(safeNow / MEMORY_VIEWER_ACTIVITY_CUTOFF_GRANULARITY_MS)
+        * MEMORY_VIEWER_ACTIVITY_CUTOFF_GRANULARITY_MS
+        - MEMORY_VIEWER_SESSION_ACTIVITY_WINDOW_MS;
+}
+function conditionalViewerJson(req, res, body) {
+    const payload = JSON.stringify(body);
+    const etag = `"${createHash("sha256").update(payload).digest("base64url")}"`;
+    const headers = {
+        "cache-control": "private, no-cache",
+        etag,
+    };
+    if (req.headers["if-none-match"] === etag) {
+        res.writeHead(304, headers);
+        res.end();
+        return;
+    }
+    res.writeHead(200, { ...headers, "content-type": "application/json" });
+    res.end(payload);
+}
+function projectFilter(url) {
+    const rawProjectId = url.searchParams.get("projectId");
+    const projectId = (rawProjectId ?? "").trim();
+    if (projectId === UNCLASSIFIED_PROJECT_ID || isMemoryProjectId(projectId)) {
+        return { projectId };
+    }
+    if (rawProjectId !== null && projectId)
+        return { reject: true };
+    return {};
+}

package/lib/memorax-code-backend/dist/server-observability.js

@@ -0,0 +1,102 @@
+import { randomUUID } from "node:crypto";
+import { backendDebug } from "./debug-log.js";
+import { TRACE_CLIENTS, clientTraceConfigFromEnv, } from "./trace-config.js";
+import { recordTraceEvent } from "./trace-store.js";
+import { memoryViewerObservabilityHook } from "./memory-viewer-observability.js";
+export function createBackendMemoryObservability(memoraxCodeHome, existingHook, env = process.env, additionalDefaultHooks = []) {
+    if (existingHook)
+        return existingHook;
+    const effectiveEnv = { ...env, MEMORAX_CODE_HOME: memoraxCodeHome };
+    return composeMemoryObservabilityHooks([
+        ...additionalDefaultHooks,
+        memoryViewerObservabilityHook(),
+        sessionTraceObservabilityHook(memoraxCodeHome, effectiveEnv),
+    ]);
+}
+export function composeMemoryObservabilityHooks(hooks) {
+    const active = hooks.filter((hook) => Boolean(hook?.recordEvent));
+    if (active.length === 0)
+        return undefined;
+    return {
+        recordEvent(event) {
+            const correlatedEvent = event.eventId
+                ? event
+                : { ...event, eventId: `memory-observability-${randomUUID()}` };
+            for (const [sinkIndex, hook] of active.entries()) {
+                try {
+                    hook.recordEvent?.(correlatedEvent);
+                }
+                catch (error) {
+                    backendDebug("memory_observability.sink_failed", {
+                        sinkIndex,
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            }
+        },
+        async drain() {
+            await Promise.all(active.map(async (hook, sinkIndex) => {
+                try {
+                    await hook.drain?.();
+                }
+                catch (error) {
+                    backendDebug("memory_observability.drain_failed", {
+                        sinkIndex,
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            }));
+        },
+    };
+}
+function sessionTraceObservabilityHook(memoraxCodeHome, env) {
+    const enabledClients = new Set(TRACE_CLIENTS.filter((client) => clientTraceConfigFromEnv(client, env).enabled));
+    if (enabledClients.size === 0)
+        return undefined;
+    const pending = new Set();
+    return {
+        recordEvent(event) {
+            const client = event.traceContext?.client;
+            if (!client || !enabledClients.has(client))
+                return;
+            const config = clientTraceConfigFromEnv(client, env);
+            if (!config.enabled)
+                return;
+            const write = recordTraceEvent({
+                memoraxCodeHome,
+                env,
+                config,
+                traceContext: event.traceContext,
+                eventId: event.eventId,
+                type: sessionTraceEventType(event),
+                source: event.source,
+                operation: event.operation,
+                ok: event.ok,
+                relatedTurns: event.relatedTurns,
+                request: event.request,
+                response: event.response,
+                error: event.error,
+            }).catch((error) => {
+                backendDebug(`${client}_trace.write_failed`, {
+                    label: "memory_observability",
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }).finally(() => {
+                pending.delete(write);
+            });
+            pending.add(write);
+        },
+        async drain() {
+            await Promise.allSettled([...pending]);
+        },
+    };
+}
+function sessionTraceEventType(event) {
+    if (event.source === "memory_cli" && event.operation === "writeback")
+        return "memory_cli_add";
+    if (event.source === "memory_cli")
+        return "memory_cli_search";
+    if (event.operation === "writeback")
+        return "memory_writeback";
+    return "memory_retrieve";
+}

package/lib/memorax-code-backend/dist/server.js

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+import { createServer, } from "node:http";
+import { isMainEntrypoint } from "./entrypoint.js";
+import { backendDebug } from "./debug-log.js";
+import { createMemoryReminderTraceRecorder } from "./memory-reminder-trace-recorder.js";
+import { handleMemoryViewerRequest } from "./server-memory-viewer.js";
+import { handleMemoryHookRequest } from "./server-memory-hook.js";
+import { createBackendMemoryObservability } from "./server-observability.js";
+import { createMemoryService } from "./memory-service.js";
+import { handleHealthRequest } from "./server-health.js";
+import { authorized, memoryViewerSessionCookieHeader, publicErrorMessage, statusCodeFromError } from "./server-http.js";
+import { json } from "./server-json.js";
+import { createBackendState } from "./backend-state.js";
+import { TRACE_CLIENTS } from "./trace-config.js";
+import { pruneExpiredTraceSessionsForClient } from "./trace-store.js";
+import { startMemoryWritebackReconciler } from "./memory-writeback-reconciler.js";
+import { createMemoryWritebackTaskProjection } from "./memory-writeback-task-projection.js";
+import { readActiveManagedClients } from "./active-client-selection.js";
+const DEFAULT_BACKEND_SHUTDOWN_TIMEOUT_MS = 4_000;
+export function createBackendServer(state = createBackendState(), options = {}) {
+    const memoryEnv = { ...process.env, MEMORAX_CODE_HOME: state.sessionHome };
+    const memoryWritebackTaskProjections = TRACE_CLIENTS.map((client) => createMemoryWritebackTaskProjection({
+        memoraxCodeHome: state.sessionHome,
+        client,
+    }));
+    const memoryObservability = createBackendMemoryObservability(state.sessionHome, options.memoryObservability, memoryEnv, memoryWritebackTaskProjections.map((projection) => projection.observabilityHook));
+    const memoryService = createMemoryService({
+        diagnosticLogger: backendDebug,
+        env: memoryEnv,
+        memoraxCodeHome: state.sessionHome,
+        memoryObservability,
+    });
+    const memoryHookDependencies = {
+        memoryService,
+        memoryReminderTraceRecorder: createMemoryReminderTraceRecorder({
+            diagnosticLogger: backendDebug,
+            env: memoryEnv,
+            memoraxCodeHome: state.sessionHome,
+        }),
+    };
+    for (const client of TRACE_CLIENTS) {
+        void pruneExpiredTraceSessionsForClient({
+            client,
+            memoraxCodeHome: state.sessionHome,
+        }).catch((error) => {
+            backendDebug(`${client}_trace.retention_cleanup_failed`, {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        });
+    }
+    const memoryWritebackReconcilers = memoryWritebackTaskProjections.map((taskProjection) => (startMemoryWritebackReconciler({
+        memoraxCodeHome: state.sessionHome,
+        env: memoryEnv,
+        taskProjection,
+    })));
+    const handleRequest = async (req, res) => {
+        const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "127.0.0.1"}`);
+        backendDebug("http.request", {
+            method: req.method,
+            path: url.pathname,
+        });
+        try {
+            if (req.method === "GET" && url.pathname === "/health")
+                return handleHealthRequest(state, res);
+            if (!authorized(state, req, url))
+                return json(res, 401, { ok: false, error: "unauthorized" });
+            if (url.pathname === "/memory-viewer"
+                || url.pathname.startsWith("/memory-viewer/")) {
+                if (await handleMemoryViewerRequest(url, req, res, {
+                    memoraxCodeHome: state.sessionHome,
+                    claudeProjectsRoot: readActiveManagedClients(state.sessionHome)?.claude === true
+                        ? state.claudeProjectsRoot
+                        : false,
+                    sessionCookie: memoryViewerSessionCookieHeader(state, req, url),
+                }))
+                    return;
+            }
+            if (await handleMemoryHookRequest(memoryHookDependencies, url, req, res))
+                return;
+            return json(res, 404, { ok: false, error: "not found" });
+        }
+        catch (error) {
+            const status = statusCodeFromError(error);
+            const publicMessage = publicErrorMessage(error);
+            if (status >= 500)
+                console.error("request failed", error);
+            if (res.headersSent) {
+                return res.end();
+            }
+            return json(res, status, { ok: false, error: publicMessage });
+        }
+    };
+    const activeRequests = new Set();
+    const server = createServer((req, res) => {
+        const request = handleRequest(req, res);
+        activeRequests.add(request);
+        void request.then(() => activeRequests.delete(request), () => activeRequests.delete(request));
+    });
+    return attachBackendShutdown(server, {
+        activeRequests,
+        memoryObservability,
+        memoryService,
+        memoryWritebackReconcilers,
+        timeoutMs: positiveShutdownTimeout(options.shutdownTimeoutMs),
+    });
+}
+function attachBackendShutdown(server, resources) {
+    const closeHttpServer = server.close.bind(server);
+    const backendServer = server;
+    let shutdownPromise;
+    backendServer.shutdown = () => {
+        shutdownPromise ??= shutdownBackend(backendServer, closeHttpServer, resources);
+        return shutdownPromise;
+    };
+    backendServer.close = ((callback) => {
+        void backendServer.shutdown().then(() => callback?.(), (error) => callback?.(error instanceof Error ? error : new Error(String(error))));
+        return backendServer;
+    });
+    return backendServer;
+}
+async function shutdownBackend(server, closeHttpServer, resources) {
+    const deadline = Date.now() + resources.timeoutMs;
+    const reconcilerDrain = settleShutdownWork("memory_writeback_reconcilers", Promise.all(resources.memoryWritebackReconcilers.map((reconciler) => reconciler.close())));
+    try {
+        await waitForShutdownPhase("http_server", closeBackendHttpServer(server, closeHttpServer, resources.timeoutMs), deadline);
+        await waitForShutdownPhase("http_requests", waitForActiveRequests(resources.activeRequests), deadline);
+        if (Date.now() < deadline) {
+            await waitForShutdownPhase("memory_service", settleShutdownWork("memory_service", resources.memoryService.drain()), deadline);
+        }
+        if (Date.now() < deadline && resources.memoryObservability?.drain) {
+            await waitForShutdownPhase("memory_observability", settleShutdownWork("memory_observability", resources.memoryObservability.drain()), deadline);
+        }
+        await waitForShutdownPhase("background_work", reconcilerDrain, deadline);
+    }
+    finally {
+        resources.memoryService.close();
+    }
+}
+function closeBackendHttpServer(server, closeHttpServer, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const forceTimer = setTimeout(() => {
+            backendDebug("shutdown.http_connections_forced", { timeoutMs });
+            try {
+                server.closeAllConnections();
+            }
+            catch (error) {
+                backendDebug("shutdown.http_connections_force_failed", {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }, timeoutMs);
+        const done = (error) => {
+            clearTimeout(forceTimer);
+            if (error && error.code !== "ERR_SERVER_NOT_RUNNING") {
+                reject(error);
+                return;
+            }
+            resolve();
+        };
+        try {
+            closeHttpServer(done);
+            server.closeIdleConnections();
+        }
+        catch (error) {
+            done(error instanceof Error ? error : new Error(String(error)));
+        }
+    });
+}
+async function waitForActiveRequests(activeRequests) {
+    while (activeRequests.size > 0) {
+        await Promise.allSettled([...activeRequests]);
+    }
+}
+async function waitForShutdownPhase(phase, work, deadline) {
+    const remainingMs = deadline - Date.now();
+    if (remainingMs <= 0) {
+        backendDebug("shutdown.phase_timed_out", { phase, remainingMs: 0 });
+        return false;
+    }
+    let timer;
+    const result = await Promise.race([
+        work.then(() => ({ completed: true }), (error) => ({ completed: true, error })),
+        new Promise((resolve) => {
+            timer = setTimeout(() => resolve({ completed: false }), remainingMs);
+        }),
+    ]);
+    if (timer)
+        clearTimeout(timer);
+    if (!result.completed) {
+        backendDebug("shutdown.phase_timed_out", { phase, remainingMs });
+        return false;
+    }
+    if ("error" in result)
+        throw result.error;
+    return true;
+}
+async function settleShutdownWork(label, work) {
+    try {
+        await work;
+    }
+    catch (error) {
+        backendDebug("shutdown.work_failed", {
+            label,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+function positiveShutdownTimeout(value) {
+    if (typeof value === "number" && Number.isSafeInteger(value) && value > 0)
+        return value;
+    return DEFAULT_BACKEND_SHUTDOWN_TIMEOUT_MS;
+}
+if (isMainEntrypoint(import.meta.url)) {
+    import("./server-cli.js")
+        .then(({ runBackendCli }) => runBackendCli(process.argv))
+        .catch((error) => {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    });
+}

package/lib/memorax-code-backend/dist/service-entrypoint.js

@@ -0,0 +1,10 @@
+import { runBackendCli } from "./server-cli.js";
+const markerIndex = process.argv.indexOf("--memorax-code-backend-instance");
+const instanceId = markerIndex >= 0 ? process.argv[markerIndex + 1] : undefined;
+if (!instanceId
+    || instanceId !== process.env.MEMORAX_CODE_BACKEND_INSTANCE_ID
+    || !/^[A-Za-z0-9_-]+$/.test(instanceId)) {
+    console.error("invalid MemoraX Code Backend service instance marker");
+    process.exit(1);
+}
+runBackendCli([process.execPath, "memorax-code-backend"]);