@memorax/memorax-code 0.1.0

package/lib/memorax-code-backend/dist/automatic-memory-writeback.js

@@ -0,0 +1,297 @@
+import { createHash } from "node:crypto";
+import { createMemoryWritebackBufferRuntime, } from "./memory-writeback-buffer.js";
+import { memoryWritebackAddParts, } from "./memory-writeback-chunk.js";
+import { invokeMemoraxMemoryProvider, } from "./memorax-adapter.js";
+import { memoryWritebackBufferEnabled, memoryWritebackEnabled, memoryWritebackMaxMessageChars, } from "./memorax-config.js";
+const WRITEBACK_DEDUPE_TTL_MS = 5 * 60 * 1000;
+const WRITEBACK_DEDUPE_MAX = 1024;
+const AUTOMATIC_MEMORY_WRITEBACK_MAX_ATTEMPTS = 2;
+const AUTOMATIC_MEMORY_WRITEBACK_RETRY_DELAY_MS = 100;
+const AUTOMATIC_MEMORY_WRITEBACK_MAX_RETRY_DELAY_MS = 5_000;
+export function createAutomaticMemoryWritebackRuntime(options = {}) {
+    const state = {
+        diagnosticLogger: options.diagnosticLogger ?? (() => { }),
+        pendingWritebacks: new Map(),
+        writebackBuffer: createMemoryWritebackBufferRuntime(),
+        accepting: true,
+        inFlight: new Set(),
+    };
+    return {
+        enqueue(options) {
+            return enqueueAutomaticMemoryWritebackForRuntime(state, options);
+        },
+        drain() {
+            if (state.drainPromise)
+                return state.drainPromise;
+            state.accepting = false;
+            state.writebackBuffer.flushAll("shutdown");
+            state.drainPromise = Promise.allSettled([...state.inFlight]).then(() => undefined);
+            return state.drainPromise;
+        },
+        close() {
+            state.accepting = false;
+            state.writebackBuffer.close();
+            state.pendingWritebacks.clear();
+        },
+    };
+}
+function enqueueAutomaticMemoryWritebackForRuntime(state, options) {
+    if (!state.accepting) {
+        state.diagnosticLogger("memory.automatic_writeback", {
+            scheduled: false,
+            skipReason: "runtime_closed",
+            sessionKey: options.sessionKey,
+        });
+        return { accepted: false, reason: "runtime_closed" };
+    }
+    try {
+        const decision = automaticMemoryWritebackDecision(state, options);
+        if (!decision.write) {
+            state.diagnosticLogger("memory.automatic_writeback", {
+                scheduled: false,
+                skipReason: decision.skipReason,
+                sessionKey: options.sessionKey,
+            });
+            return decision.skipReason === "duplicate_pending"
+                ? { accepted: true }
+                : { accepted: false, reason: decision.skipReason };
+        }
+        if (memoryWritebackBufferEnabled(options.env ?? process.env)) {
+            state.writebackBuffer.enqueue(decision, options, {
+                debug: state.diagnosticLogger,
+                flush: (bufferedDecision, bufferedOptions) => flushAutomaticMemoryWritebackBuffer(state, bufferedDecision, bufferedOptions),
+                hasPendingWriteback: (idempotencyKey) => hasPendingWriteback(state, idempotencyKey),
+                reservePendingWritebacks: (idempotencyKeys) => reservePendingWritebacks(state, idempotencyKeys),
+                hashText,
+            });
+            return { accepted: true };
+        }
+        reservePendingWriteback(state, decision.idempotencyKey);
+        state.diagnosticLogger("memory.automatic_writeback", {
+            scheduled: true,
+            sessionKey: options.sessionKey,
+            idempotencyKey: decision.idempotencyKey,
+            messageCount: decision.messages.length,
+            userChars: decision.messages[0]?.content.length ?? 0,
+            assistantChars: decision.messages[1]?.content.length ?? 0,
+        });
+        trackAutomaticMemoryWriteback(state, enqueueAutomaticMemoryWritebackAsync(state, decision, options));
+        return { accepted: true };
+    }
+    catch (error) {
+        state.diagnosticLogger("memory.automatic_writeback", {
+            scheduled: false,
+            skipReason: "decision_error",
+            sessionKey: options.sessionKey,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return { accepted: false, reason: "decision_error" };
+    }
+}
+function automaticMemoryWritebackDecision(state, options) {
+    const env = options.env ?? process.env;
+    if (!memoryWritebackEnabled(env))
+        return { write: false, skipReason: "disabled" };
+    if (!options.sessionKey?.trim())
+        return { write: false, skipReason: "session_missing" };
+    if (!options.repositoryScope) {
+        return {
+            write: false,
+            skipReason: options.repositoryScopeReason
+                ?? (options.repositoryScopeError ? "workspace_scope_unavailable" : "workspace_scope_missing"),
+        };
+    }
+    const sessionKey = options.sessionKey.trim();
+    const maxMessageChars = memoryWritebackMaxMessageChars(env);
+    const userText = limitMessageContent(options.userText?.trim() ?? "", maxMessageChars, {
+        role: "user",
+        sessionKey,
+    }, state.diagnosticLogger);
+    const assistantText = limitMessageContent(options.assistantText?.trim() ?? "", maxMessageChars, {
+        role: "assistant",
+        sessionKey,
+    }, state.diagnosticLogger);
+    if (!userText)
+        return { write: false, skipReason: "user_prompt_empty" };
+    if (!assistantText)
+        return { write: false, skipReason: "assistant_text_empty" };
+    const idempotencyKey = `automatic:${options.client}:${hashText(options.repositoryScope.effectiveUserId)}:${sessionKey}:${hashText(userText)}:${hashText(assistantText)}`;
+    if (hasPendingWriteback(state, idempotencyKey))
+        return { write: false, skipReason: "duplicate_pending" };
+    return {
+        write: true,
+        client: options.client,
+        sessionKey,
+        idempotencyKey,
+        messages: [
+            { role: "user", content: userText },
+            { role: "assistant", content: assistantText },
+        ],
+    };
+}
+async function enqueueAutomaticMemoryWritebackAsync(state, decision, options) {
+    try {
+        const parts = memoryWritebackAddParts(decision, options.env ?? process.env);
+        for (const [index, part] of parts.entries()) {
+            for (let attempt = 1; attempt <= AUTOMATIC_MEMORY_WRITEBACK_MAX_ATTEMPTS; attempt += 1) {
+                const response = await invokeMemoraxMemoryProvider({
+                    sessionId: decision.sessionKey,
+                    prompt: part.messages.find((message) => message.role === "user")?.content ?? "",
+                }, {
+                    provider_family: "memory",
+                    provider_id: "memory.memorax",
+                    transport: "external_http",
+                    slot: "state_context",
+                    operation: "writeback",
+                    dispatch: "async_best_effort",
+                    context: {
+                        idempotencyKey: part.idempotencyKey,
+                        messages: part.messages,
+                        contentType: "code",
+                        mode: "default",
+                        ...(part.chunk ? { chunk: part.chunk } : {}),
+                    },
+                }, {
+                    env: options.env,
+                    fetchImpl: options.fetchImpl,
+                    observability: options.memoryObservability,
+                    observabilitySource: options.memoryObservabilitySource ?? "automatic_writeback",
+                    relatedTurns: options.relatedTurns,
+                    repositoryScope: options.repositoryScope,
+                    traceContext: options.traceContext,
+                    diagnosticLogger: state.diagnosticLogger,
+                    writebackAttempt: {
+                        attempt,
+                        maxAttempts: AUTOMATIC_MEMORY_WRITEBACK_MAX_ATTEMPTS,
+                    },
+                });
+                const retryDelayMs = !response.ok && attempt < AUTOMATIC_MEMORY_WRITEBACK_MAX_ATTEMPTS
+                    ? automaticMemoryWritebackRetryDelayMs(response, attempt)
+                    : undefined;
+                const retrying = retryDelayMs !== undefined;
+                state.diagnosticLogger("memory.automatic_writeback", {
+                    scheduled: true,
+                    accepted: response.ok,
+                    sessionKey: decision.sessionKey,
+                    idempotencyKey: part.idempotencyKey,
+                    parentIdempotencyKey: part.idempotencyKey === decision.idempotencyKey ? undefined : decision.idempotencyKey,
+                    flushReason: decision.flushReason,
+                    turnCount: decision.turnCount,
+                    partIndex: parts.length > 1 ? index : undefined,
+                    partCount: parts.length > 1 ? parts.length : undefined,
+                    attempt,
+                    maxAttempts: AUTOMATIC_MEMORY_WRITEBACK_MAX_ATTEMPTS,
+                    retrying,
+                    retryDelayMs,
+                    dispatchReceipt: response.ok ? response.result.dispatch_receipt ?? null : undefined,
+                    error: response.ok ? undefined : response.error,
+                    errorKind: response.ok ? undefined : response.errorKind,
+                    httpStatus: response.ok ? undefined : response.httpStatus,
+                });
+                if (response.ok)
+                    break;
+                if (!retrying) {
+                    releasePendingWritebacks(state, [decision.idempotencyKey, ...(decision.dedupeKeys ?? [])]);
+                    return;
+                }
+                await delayAutomaticMemoryWritebackRetry(retryDelayMs);
+            }
+        }
+    }
+    catch (error) {
+        releasePendingWritebacks(state, [decision.idempotencyKey, ...(decision.dedupeKeys ?? [])]);
+        state.diagnosticLogger("memory.automatic_writeback", {
+            scheduled: true,
+            accepted: false,
+            sessionKey: decision.sessionKey,
+            idempotencyKey: decision.idempotencyKey,
+            flushReason: decision.flushReason,
+            turnCount: decision.turnCount,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+function flushAutomaticMemoryWritebackBuffer(state, decision, options) {
+    trackAutomaticMemoryWriteback(state, enqueueAutomaticMemoryWritebackAsync(state, decision, {
+        client: decision.client,
+        sessionKey: options.sessionKey,
+        env: options.env,
+        fetchImpl: options.fetchImpl,
+        memoryObservability: options.memoryObservability,
+        memoryObservabilitySource: options.memoryObservabilitySource,
+        relatedTurns: options.relatedTurns,
+        repositoryScope: options.repositoryScope,
+        traceContext: options.traceContext,
+    }));
+}
+function trackAutomaticMemoryWriteback(state, writeback) {
+    state.inFlight.add(writeback);
+    void writeback.then(() => state.inFlight.delete(writeback), () => state.inFlight.delete(writeback));
+}
+function hasPendingWriteback(state, idempotencyKey) {
+    prunePendingWritebacks(state);
+    return state.pendingWritebacks.has(idempotencyKey);
+}
+function reservePendingWriteback(state, idempotencyKey) {
+    reservePendingWritebacks(state, [idempotencyKey]);
+}
+function reservePendingWritebacks(state, idempotencyKeys) {
+    prunePendingWritebacks(state);
+    const expiresAt = Date.now() + WRITEBACK_DEDUPE_TTL_MS;
+    for (const idempotencyKey of idempotencyKeys) {
+        state.pendingWritebacks.set(idempotencyKey, expiresAt);
+    }
+    while (state.pendingWritebacks.size > WRITEBACK_DEDUPE_MAX) {
+        const oldest = state.pendingWritebacks.keys().next().value;
+        if (typeof oldest !== "string")
+            break;
+        state.pendingWritebacks.delete(oldest);
+    }
+}
+function releasePendingWriteback(state, idempotencyKey) {
+    state.pendingWritebacks.delete(idempotencyKey);
+}
+function releasePendingWritebacks(state, idempotencyKeys) {
+    for (const idempotencyKey of idempotencyKeys)
+        releasePendingWriteback(state, idempotencyKey);
+}
+function prunePendingWritebacks(state, now = Date.now()) {
+    for (const [key, expiresAt] of state.pendingWritebacks.entries()) {
+        if (expiresAt <= now)
+            state.pendingWritebacks.delete(key);
+    }
+}
+function limitMessageContent(content, maxChars, fields, diagnosticLogger = () => { }) {
+    if (content.length <= maxChars)
+        return content;
+    const kept = content.slice(0, maxChars).trim();
+    diagnosticLogger("memory.automatic_writeback.truncated", {
+        sessionKey: fields?.sessionKey,
+        role: fields?.role,
+        originalChars: content.length,
+        keptChars: kept.length,
+        maxChars,
+    });
+    return kept;
+}
+function hashText(text) {
+    return createHash("sha256").update(text).digest("hex").slice(0, 16);
+}
+function automaticMemoryWritebackRetryDelayMs(failure, attempt) {
+    if (!isRetryableAutomaticMemoryWritebackFailure(failure))
+        return undefined;
+    const requestedDelayMs = failure.retryAfterMs ?? AUTOMATIC_MEMORY_WRITEBACK_RETRY_DELAY_MS * attempt;
+    return Math.min(AUTOMATIC_MEMORY_WRITEBACK_MAX_RETRY_DELAY_MS, Math.max(0, requestedDelayMs));
+}
+function isRetryableAutomaticMemoryWritebackFailure(failure) {
+    if (failure.errorKind === "timeout" || failure.errorKind === "transport")
+        return true;
+    if (failure.errorKind !== "http" || failure.httpStatus === undefined)
+        return false;
+    return failure.httpStatus === 408
+        || failure.httpStatus === 429
+        || failure.httpStatus >= 500;
+}
+async function delayAutomaticMemoryWritebackRetry(delayMs) {
+    await new Promise((resolve) => setTimeout(resolve, delayMs));
+}

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

@@ -0,0 +1,13 @@
+export function backendEnv(suffix, env = process.env) {
+    return env[`MEMORAX_CODE_BACKEND_${suffix}`];
+}
+export function parseBooleanEnv(value) {
+    if (value === undefined)
+        return undefined;
+    const normalized = value.trim().toLowerCase();
+    if (["1", "true", "yes", "on", "enabled"].includes(normalized))
+        return true;
+    if (["0", "false", "no", "off", "disabled"].includes(normalized))
+        return false;
+    return undefined;
+}

package/lib/memorax-code-backend/dist/backend-lifecycle-lock.js

@@ -0,0 +1,42 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { withJsonFileLockAsync } from "../../memorax-code-adapter-common/src/config-utils.mjs";
+const BACKEND_LIFECYCLE_LOCK_TIMEOUT_MS = 25000;
+const BACKEND_LIFECYCLE_LOCK_STALE_MS = 5000;
+const BACKEND_LIFECYCLE_LOCK_RETRY_MS = 20;
+export class BackendLifecycleLockError extends Error {
+    code = "BACKEND_LIFECYCLE_LOCK_TIMEOUT";
+    lockPath;
+    constructor(lockPath) {
+        super(`timed out waiting for Backend lifecycle authority lock: ${lockPath}`);
+        this.name = "BackendLifecycleLockError";
+        this.lockPath = lockPath;
+    }
+}
+export function backendServiceHome(options = {}) {
+    return options.home ?? process.env.MEMORAX_CODE_HOME ?? join(homedir(), ".memorax-code");
+}
+export function backendLifecycleLockTarget(options = {}) {
+    return join(backendServiceHome(options), "runtime", "backend", "backend.lifecycle");
+}
+export async function withBackendLifecycleLock(options, operation) {
+    const target = backendLifecycleLockTarget(options);
+    try {
+        return await withJsonFileLockAsync(target, operation, {
+            timeoutMs: BACKEND_LIFECYCLE_LOCK_TIMEOUT_MS,
+            staleMs: BACKEND_LIFECYCLE_LOCK_STALE_MS,
+            retryMs: BACKEND_LIFECYCLE_LOCK_RETRY_MS,
+        });
+    }
+    catch (error) {
+        if (errorCode(error) === "JSON_FILE_LOCK_TIMEOUT") {
+            throw new BackendLifecycleLockError(`${target}.lock`);
+        }
+        throw error;
+    }
+}
+function errorCode(error) {
+    return typeof error === "object" && error !== null && "code" in error
+        ? error.code
+        : undefined;
+}

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

@@ -0,0 +1,147 @@
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
+const POSIX_PROCESS_PROBE_TIMEOUT_MS = 2_000;
+const WINDOWS_PROCESS_PROBE_TIMEOUT_MS = 10_000;
+const PROCESS_TERMINATION_TIMEOUT_MS = 5_000;
+export function isProcessAlive(pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function terminateProcessTree(pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return false;
+    if (!isProcessAlive(pid))
+        return true;
+    if (process.platform === "win32") {
+        const taskkill = process.env.SystemRoot
+            ? join(process.env.SystemRoot, "System32", "taskkill.exe")
+            : undefined;
+        if (!taskkill)
+            return false;
+        return spawnSync(taskkill, ["/PID", String(pid), "/T", "/F"], {
+            stdio: "ignore",
+            windowsHide: true,
+            timeout: PROCESS_TERMINATION_TIMEOUT_MS,
+            killSignal: "SIGKILL",
+        }).status === 0;
+    }
+    try {
+        process.kill(pid, "SIGTERM");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function probeProcessCommandLine(pid, runtime = {}) {
+    const platform = runtime.platform ?? process.platform;
+    const timeoutMs = platform === "win32"
+        ? WINDOWS_PROCESS_PROBE_TIMEOUT_MS
+        : POSIX_PROCESS_PROBE_TIMEOUT_MS;
+    if (!Number.isSafeInteger(pid) || pid <= 0) {
+        return { status: "inconclusive", reason: "invalid_pid", timeoutMs };
+    }
+    const run = runtime.spawnSync ?? runProbeCommand;
+    let command;
+    let args;
+    const options = {
+        encoding: "utf8",
+        timeout: timeoutMs,
+        killSignal: "SIGKILL",
+    };
+    if (platform === "win32") {
+        const systemRoot = (runtime.env ?? process.env).SystemRoot;
+        const powershell = systemRoot
+            ? join(systemRoot, "System32", "WindowsPowerShell", "v1.0", "powershell.exe")
+            : undefined;
+        if (!powershell) {
+            return { status: "inconclusive", reason: "powershell_unavailable", timeoutMs };
+        }
+        command = powershell;
+        args = [
+            "-NoProfile",
+            "-NonInteractive",
+            "-Command",
+            `(Get-CimInstance Win32_Process -Filter 'ProcessId = ${pid}').CommandLine`,
+        ];
+        options.windowsHide = true;
+    }
+    else {
+        command = "ps";
+        args = ["-p", String(pid), "-o", "command="];
+    }
+    let result;
+    try {
+        result = run(command, args, options);
+    }
+    catch (error) {
+        const code = error instanceof Error
+            ? error.code
+            : undefined;
+        return {
+            status: "inconclusive",
+            reason: "spawn_error",
+            timeoutMs,
+            ...(code ? { code } : {}),
+        };
+    }
+    if (result.error?.code === "ETIMEDOUT") {
+        return {
+            status: "inconclusive",
+            reason: "timeout",
+            timeoutMs,
+            code: "ETIMEDOUT",
+            ...(result.signal ? { signal: result.signal } : {}),
+        };
+    }
+    if (result.error) {
+        return {
+            status: "inconclusive",
+            reason: "spawn_error",
+            timeoutMs,
+            ...(result.error.code ? { code: result.error.code } : {}),
+        };
+    }
+    if (result.signal) {
+        return {
+            status: "inconclusive",
+            reason: "terminated",
+            timeoutMs,
+            signal: result.signal,
+        };
+    }
+    if (result.status !== 0) {
+        return {
+            status: "inconclusive",
+            reason: "nonzero_exit",
+            timeoutMs,
+            ...(typeof result.status === "number" ? { exitCode: result.status } : {}),
+        };
+    }
+    const commandLine = result.stdout.trim();
+    return commandLine
+        ? { status: "ok", commandLine }
+        : { status: "not_found" };
+}
+export function managedServiceCommandLine(commandLine, instanceId) {
+    const marker = commandLine.match(/(?:^|\s)--memorax-code-backend-instance(?:=|\s+)([A-Za-z0-9_-]+)(?:\s|$)/)?.[1];
+    return marker === instanceId
+        && /(?:^|[\\/\s"'])node(?:\.exe)?(?:["']?\s)/i.test(commandLine)
+        && /[\\/]memorax-code-backend[\\/]dist[\\/]service-entrypoint\.js(?:["']?(?:\s|$))/i.test(commandLine);
+}
+function runProbeCommand(command, args, options) {
+    const result = spawnSync(command, args, options);
+    return {
+        ...(result.error ? { error: result.error } : {}),
+        signal: result.signal,
+        status: result.status,
+        stdout: result.stdout,
+    };
+}

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

@@ -0,0 +1,18 @@
+import { removeBackendServiceStateIfOwnedAtPath, } from "./backend-service-record.js";
+export function clearBackendServiceState(path, state, action, prefix = "failed to clear Backend service state") {
+    const result = removeBackendServiceStateIfOwnedAtPath(path, state);
+    if (result.disposition === "removed"
+        || (result.disposition === "not_owned" && result.reason === "absent")) {
+        return undefined;
+    }
+    const detail = result.disposition === "io_failed"
+        ? result.error
+        : "the PID authority was replaced while cleanup was in progress";
+    return {
+        ok: false,
+        action,
+        state,
+        errorCode: "BACKEND_SERVICE_STATE_CLEANUP_FAILED",
+        error: `${prefix}; ${detail}`,
+    };
+}