@memorax/memorax-code 0.1.0

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

@@ -0,0 +1,567 @@
+import { randomBytes } from "node:crypto";
+import { spawn } from "node:child_process";
+import { closeSync, existsSync, openSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { BackendConnectionAuthorityError, DEFAULT_BACKEND_URL, resolveBackendConnection, writeBackendConnectionAuthority, } from "../../memorax-code-adapter-common/src/backend-connection.mjs";
+import { ensurePrivateDirectory, } from "../../memorax-code-adapter-common/src/runtime-record.mjs";
+import { backendEnv, parseBooleanEnv } from "./backend-env.js";
+import { isProcessAlive, managedServiceCommandLine, probeProcessCommandLine, terminateProcessTree, } from "./backend-process.js";
+import { clearBackendServiceState } from "./backend-service-cleanup.js";
+import { readBackendServiceRecordAtPath, readBackendServiceStateAtPath, writeBackendServiceStateAtPath, } from "./backend-service-record.js";
+import { assertBackendTokenPersistenceEligible } from "./backend-token-record.js";
+import { clearBackendShutdownRequest, writeBackendShutdownRequest, } from "./backend-shutdown-request.js";
+import { runtimeRecordDurabilityWarning, runtimeRecordErrorFields, runtimeRecordServiceFailure, withRuntimeRecordWarnings, } from "./backend-service-result.js";
+import { persistBackendToken, readBackendToken, writeBackendToken, } from "./backend-service-token.js";
+import { backendServiceHome } from "./backend-lifecycle-lock.js";
+import { isLoopbackHost } from "./backend-state.js";
+import { withLoopbackProxyBypass } from "./proxy-env.js";
+export { BACKEND_SERVICE_RECORD_VERSION, BackendServiceStateError, } from "./backend-service-record.js";
+export { isProcessAlive, terminateProcessTree } from "./backend-process.js";
+export { readBackendToken, writeBackendToken };
+function serviceDir(options) {
+    return join(backendServiceHome(options), "runtime", "backend");
+}
+function pidPath(options) { return join(serviceDir(options), "backend.pid.json"); }
+function logPath(options) {
+    const configured = backendEnv("LOG");
+    if (configured)
+        return configured;
+    return join(serviceDir(options), "backend.log");
+}
+export function readBackendServiceRecordState(options = {}) {
+    return readBackendServiceRecordAtPath(pidPath(options));
+}
+export function readBackendServiceState(options = {}) {
+    return readBackendServiceStateAtPath(pidPath(options));
+}
+export function backendServiceEndpoint(options = {}) {
+    const memoraxCodeHome = backendServiceHome(options);
+    let configured;
+    try {
+        configured = resolveBackendConnection({
+            memoraxCodeHome,
+            env: { ...process.env, MEMORAX_CODE_BACKEND_URL: undefined },
+        });
+    }
+    catch (error) {
+        const hasExplicitBind = options.host !== undefined || options.port !== undefined;
+        if (!(error instanceof BackendConnectionAuthorityError) || !hasExplicitBind)
+            throw error;
+        configured = resolveBackendConnection({
+            memoraxCodeHome,
+            backendUrl: DEFAULT_BACKEND_URL,
+            env: {},
+        });
+    }
+    const host = options.host ?? configured.host;
+    const port = options.port ?? configured.port;
+    const formattedHost = host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
+    const url = `http://${formattedHost}:${port}`;
+    const connection = resolveBackendConnection({
+        memoraxCodeHome,
+        backendUrl: url,
+        backendToken: options.authToken,
+    });
+    return {
+        host,
+        port,
+        url,
+        ...(connection.token ? { authToken: connection.token } : {}),
+        ...(connection.tokenSource !== "none" ? { authTokenSource: connection.tokenSource } : {}),
+    };
+}
+export function preflightBackendServiceStart(options = {}) {
+    const endpoint = backendServiceEndpoint(options);
+    const token = backendServiceTokenCandidate(options, endpoint);
+    if (token)
+        assertBackendTokenPersistenceEligible(backendServiceHome(options));
+    return endpoint;
+}
+export async function startBackendService(options = {}, runtime = {}) {
+    let endpoint;
+    try {
+        endpoint = backendServiceEndpoint(options);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            action: "start",
+            error: error instanceof Error ? error.message : String(error),
+            ...runtimeRecordErrorFields(error),
+        };
+    }
+    const processAlive = runtime.isProcessAlive ?? isProcessAlive;
+    let existing;
+    try {
+        existing = readBackendServiceState(options);
+    }
+    catch (error) {
+        return runtimeRecordServiceFailure("start", error);
+    }
+    let token;
+    try {
+        token = resolveBackendServiceToken(options, endpoint);
+    }
+    catch (error) {
+        return runtimeRecordServiceFailure("start", error);
+    }
+    const { host, port, url } = endpoint;
+    if (existing && processAlive(existing.pid)) {
+        const ownership = await readBackendOwnership(existing, options.timeoutMs ?? 5000, backendServiceHome(options), runtime);
+        if (canReportRunning(ownership)) {
+            return { ok: true, action: "start", alreadyRunning: true, state: existing };
+        }
+        if (processAlive(existing.pid)) {
+            return {
+                ok: false,
+                action: "start",
+                state: existing,
+                error: `refusing to replace unverified process ${existing.pid}; ${describeOwnershipFailure(ownership)}; remove stale Backend state after confirming process ownership`,
+            };
+        }
+    }
+    if (existing) {
+        const cleanup = clearBackendServiceState(pidPath(options), existing, "start");
+        if (cleanup)
+            return cleanup;
+    }
+    clearBackendShutdownRequest(backendServiceHome(options));
+    ensurePrivateDirectory(serviceDir(options), { durableBoundary: backendServiceHome(options) });
+    const logs = logPath(options);
+    const outFd = openSync(logs, "a");
+    const errFd = openSync(logs, "a");
+    const serverPath = fileURLToPath(new URL("./service-entrypoint.js", import.meta.url));
+    const instanceId = randomBytes(24).toString("base64url");
+    let child;
+    try {
+        child = (runtime.spawnProcess ?? spawn)(process.execPath, [serverPath, "--memorax-code-backend-instance", instanceId], {
+            detached: true,
+            env: withLoopbackProxyBypass({
+                ...process.env,
+                MEMORAX_CODE_HOME: backendServiceHome(options),
+                MEMORAX_CODE_BACKEND_HOST: host,
+                MEMORAX_CODE_BACKEND_PORT: String(port),
+                MEMORAX_CODE_BACKEND_INSTANCE_ID: instanceId,
+                ...(options.claudeProjectsRoot === false
+                    ? { MEMORAX_CODE_MEMORY_VIEWER_CLAUDE_PROJECTS_ROOT: "disabled" }
+                    : typeof options.claudeProjectsRoot === "string" && options.claudeProjectsRoot.trim()
+                        ? { MEMORAX_CODE_MEMORY_VIEWER_CLAUDE_PROJECTS_ROOT: resolve(options.claudeProjectsRoot.trim()) }
+                        : {}),
+                ...(token ? { MEMORAX_CODE_BACKEND_TOKEN: token } : {}),
+            }, url),
+            stdio: ["ignore", outFd, errFd],
+        });
+    }
+    catch (error) {
+        closeSync(outFd);
+        closeSync(errFd);
+        return {
+            ok: false,
+            action: "start",
+            logPath: logs,
+            error: `failed to spawn Backend process: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    closeSync(outFd);
+    closeSync(errFd);
+    const spawnError = await waitForSpawn(child);
+    const childPid = child.pid;
+    if (spawnError || !Number.isSafeInteger(childPid) || (childPid ?? 0) <= 0) {
+        return {
+            ok: false,
+            action: "start",
+            logPath: logs,
+            error: spawnError
+                ? `failed to spawn Backend process: ${spawnError.message}`
+                : "failed to spawn Backend process: child PID is unavailable",
+        };
+    }
+    child.unref();
+    const state = {
+        pid: childPid,
+        instanceId,
+        host,
+        port,
+        url,
+        logPath: logs,
+        startedAt: new Date().toISOString(),
+    };
+    const durabilityWarnings = [];
+    try {
+        const written = writeBackendServiceStateAtPath(pidPath(options), state, backendServiceHome(options), runtime.recordWriteRuntime);
+        const warning = runtimeRecordDurabilityWarning("pid", written);
+        if (warning)
+            durabilityWarnings.push(warning);
+    }
+    catch (error) {
+        const terminated = (runtime.terminateProcessTree ?? terminateProcessTree)(state.pid);
+        if (terminated) {
+            await waitUntilStopped(state.pid, options.timeoutMs ?? 5000, processAlive);
+        }
+        return {
+            ok: false,
+            action: "start",
+            state,
+            error: `failed to persist Backend service state: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    const healthy = await waitForHealth(url, options.timeoutMs ?? 5000, instanceId, backendServiceHome(options), runtime);
+    if (!healthy) {
+        const terminated = (runtime.terminateProcessTree ?? terminateProcessTree)(state.pid);
+        if (terminated) {
+            await waitUntilStopped(state.pid, options.timeoutMs ?? 5000, processAlive);
+        }
+        if (terminated && !processAlive(state.pid)) {
+            const cleanup = clearBackendServiceState(pidPath(options), state, "start", `backend did not become healthy at ${url}; process stopped`);
+            if (cleanup)
+                return cleanup;
+            return {
+                ok: false,
+                action: "start",
+                state,
+                error: `backend did not become healthy at ${url}`,
+            };
+        }
+        return {
+            ok: false,
+            action: "start",
+            state,
+            error: `backend did not become healthy at ${url}; cleanup failed and PID state was retained`,
+        };
+    }
+    try {
+        const activeTokenRecord = token
+            ? persistBackendToken(options, token, runtime.recordWriteRuntime)
+            : undefined;
+        const tokenWarning = runtimeRecordDurabilityWarning("token", activeTokenRecord?.persistence);
+        if (tokenWarning)
+            durabilityWarnings.push(tokenWarning);
+        const connectionWrite = writeBackendConnectionAuthority({
+            memoraxCodeHome: backendServiceHome(options),
+            url,
+            ...(activeTokenRecord ? { tokenPath: activeTokenRecord.tokenPath } : {}),
+        }, runtime.recordWriteRuntime);
+        const connectionWarning = runtimeRecordDurabilityWarning("connection", connectionWrite);
+        if (connectionWarning)
+            durabilityWarnings.push(connectionWarning);
+    }
+    catch (error) {
+        const terminated = (runtime.terminateProcessTree ?? terminateProcessTree)(state.pid);
+        if (terminated) {
+            await waitUntilStopped(state.pid, options.timeoutMs ?? 5000, processAlive);
+        }
+        if (terminated && !processAlive(state.pid)) {
+            const cleanup = clearBackendServiceState(pidPath(options), state, "start", `failed to persist Backend connection authority: ${error instanceof Error ? error.message : String(error)}; process stopped`);
+            if (cleanup)
+                return cleanup;
+        }
+        return {
+            ok: false,
+            action: "start",
+            state,
+            error: `failed to persist Backend connection authority: ${error instanceof Error ? error.message : String(error)}`,
+            ...runtimeRecordErrorFields(error),
+        };
+    }
+    return withRuntimeRecordWarnings({ ok: true, action: "start", state }, durabilityWarnings);
+}
+function resolveBackendServiceToken(options, endpoint) {
+    const loopback = isLoopbackHost(endpoint.host);
+    const serverMode = backendEnv("MODE") === "server";
+    const allowExternalAccess = parseBooleanEnv(backendEnv("ALLOW_EXTERNAL")) ?? serverMode;
+    if (!loopback && !allowExternalAccess) {
+        throw new Error(`external Backend host "${endpoint.host}" is disabled; set MEMORAX_CODE_BACKEND_ALLOW_EXTERNAL=1 and configure MEMORAX_CODE_BACKEND_TOKEN to opt in`);
+    }
+    const token = backendServiceTokenCandidate(options, endpoint);
+    if ((!loopback || serverMode) && !token) {
+        throw new Error("MEMORAX_CODE_BACKEND_TOKEN is required for server mode or external Backend access");
+    }
+    if (token)
+        assertBackendTokenPersistenceEligible(backendServiceHome(options));
+    return token;
+}
+function backendServiceTokenCandidate(options, endpoint) {
+    const loopback = isLoopbackHost(endpoint.host);
+    const loopbackAuth = parseBooleanEnv(backendEnv("LOOPBACK_AUTH"));
+    const serverMode = backendEnv("MODE") === "server";
+    const needsStoredToken = endpoint.authToken === undefined
+        && (!loopback || loopbackAuth === true || serverMode);
+    const tokenFromFile = needsStoredToken ? readBackendToken(options)?.token : undefined;
+    const configuredToken = loopback
+        && loopbackAuth === false
+        && endpoint.authTokenSource === "authority-file"
+        ? undefined
+        : endpoint.authToken;
+    const token = configuredToken
+        ?? (loopback && loopbackAuth !== true ? undefined : tokenFromFile);
+    return token;
+}
+export async function stopBackendService(options = {}, runtime = {}) {
+    const processAlive = runtime.isProcessAlive ?? isProcessAlive;
+    let state;
+    try {
+        state = readBackendServiceState(options);
+    }
+    catch (error) {
+        return runtimeRecordServiceFailure("stop", error);
+    }
+    if (!state)
+        return { ok: true, action: "stop", alreadyRunning: false };
+    if (processAlive(state.pid)) {
+        const timeoutMs = options.timeoutMs ?? 5000;
+        const windowsInstanceId = (runtime.platform ?? process.platform) === "win32"
+            ? state.instanceId
+            : undefined;
+        if (windowsInstanceId) {
+            try {
+                writeBackendShutdownRequest(backendServiceHome(options), {
+                    pid: state.pid,
+                    instanceId: windowsInstanceId,
+                });
+                await waitUntilStopped(state.pid, timeoutMs, processAlive);
+            }
+            catch {
+                // A verified process may still be force-stopped below when the private
+                // request file cannot be written.
+            }
+            finally {
+                clearBackendShutdownRequest(backendServiceHome(options));
+            }
+        }
+        if (processAlive(state.pid)) {
+            const ownership = await readBackendOwnership(state, timeoutMs, backendServiceHome(options), runtime);
+            if (processAlive(state.pid)) {
+                if (!canForceStop(ownership)) {
+                    const refusal = windowsInstanceId
+                        ? `refusing to force-stop process ${state.pid}`
+                        : `refusing to stop unverified process ${state.pid}`;
+                    return {
+                        ok: false,
+                        action: "stop",
+                        state,
+                        error: `${refusal}; ${describeOwnershipFailure(ownership)}`,
+                    };
+                }
+                if (!(runtime.terminateProcessTree ?? terminateProcessTree)(state.pid)) {
+                    return {
+                        ok: false,
+                        action: "stop",
+                        state,
+                        error: `failed to terminate verified Backend process ${state.pid}`,
+                    };
+                }
+                await waitUntilStopped(state.pid, timeoutMs, processAlive);
+                if (processAlive(state.pid)) {
+                    return { ok: false, action: "stop", state, error: `backend process ${state.pid} did not stop` };
+                }
+            }
+        }
+    }
+    clearBackendShutdownRequest(backendServiceHome(options));
+    const cleanup = clearBackendServiceState(pidPath(options), state, "stop", "Backend process stopped");
+    if (cleanup)
+        return cleanup;
+    return { ok: true, action: "stop", state };
+}
+export async function restartBackendService(options = {}, runtime = {}) {
+    const stopped = await stopBackendService(options, runtime);
+    if (!stopped.ok)
+        return { ...stopped, action: "restart" };
+    const started = await startBackendService(options, runtime);
+    return { ...started, action: "restart" };
+}
+export function backendServiceLogs(options = {}, bytes = 12000) {
+    const path = logPath(options);
+    if (!existsSync(path))
+        return { ok: false, action: "logs", logPath: path, error: "log file does not exist" };
+    const text = readFileSync(path, "utf8");
+    return { ok: true, action: "logs", logPath: path, text: text.slice(Math.max(0, text.length - bytes)) };
+}
+async function waitForHealth(url, timeoutMs, instanceId, expectedSessionHome, runtime) {
+    const budgetMs = Number.isFinite(timeoutMs) ? Math.max(0, Math.trunc(timeoutMs)) : 0;
+    const deadline = Date.now() + budgetMs;
+    while (Date.now() < deadline) {
+        const remainingMs = deadline - Date.now();
+        try {
+            const health = await readHealthWithTimeout(new URL("/health", url), remainingMs, runtime.fetch);
+            if (health.ok
+                && health.body.ok === true
+                && health.body.service === "memorax-code-backend"
+                && health.body.instanceId === instanceId
+                && typeof health.body.state?.sessionHome === "string"
+                && resolve(health.body.state.sessionHome) === resolve(expectedSessionHome))
+                return true;
+        }
+        catch {
+            // Retry until timeout; the child process may still be starting.
+        }
+        const retryBudgetMs = deadline - Date.now();
+        if (retryBudgetMs > 0)
+            await sleep(Math.min(100, retryBudgetMs));
+    }
+    return false;
+}
+async function readBackendOwnership(state, timeoutMs, expectedSessionHome, runtime) {
+    if (!isTrustedServiceState(state))
+        return { status: "invalid_state" };
+    let health = "inconclusive";
+    if (isLoopbackHealthUrl(state.url)) {
+        try {
+            const result = await readHealthWithTimeout(new URL("/health", state.url), timeoutMs, runtime.fetch);
+            if (result.ok) {
+                health = result.body.ok === true
+                    && result.body.service === "memorax-code-backend"
+                    && result.body.instanceId === state.instanceId
+                    && typeof result.body.state?.sessionHome === "string"
+                    && resolve(result.body.state.sessionHome) === resolve(expectedSessionHome)
+                    ? "matched"
+                    : "conflicting";
+            }
+        }
+        catch {
+            // Process evidence can still prove ownership for a hung Backend.
+        }
+    }
+    if (health === "conflicting") {
+        return {
+            status: "evaluated",
+            health,
+            process: { status: "not_probed" },
+        };
+    }
+    // Read the process marker after the bounded health probe so PID reuse while
+    // awaiting health cannot authorize the following synchronous taskkill path.
+    const probe = runtime.probeProcessCommandLine
+        ? runtime.probeProcessCommandLine(state.pid)
+        : runtime.platform
+            ? probeProcessCommandLine(state.pid, { platform: runtime.platform })
+            : probeProcessCommandLine(state.pid);
+    let processEvidence;
+    if (probe.status === "ok") {
+        processEvidence = managedServiceCommandLine(probe.commandLine, state.instanceId)
+            ? { status: "matched" }
+            : { status: "mismatched" };
+    }
+    else if (probe.status === "not_found") {
+        processEvidence = { status: "not_found" };
+    }
+    else {
+        processEvidence = { status: "inconclusive", probe };
+    }
+    return {
+        status: "evaluated",
+        health,
+        process: processEvidence,
+    };
+}
+function canReportRunning(ownership) {
+    if (ownership.status !== "evaluated")
+        return false;
+    if (ownership.health === "conflicting"
+        || ownership.process.status === "mismatched"
+        || ownership.process.status === "not_found")
+        return false;
+    return ownership.health === "matched" || ownership.process.status === "matched";
+}
+function canForceStop(ownership) {
+    return ownership.status === "evaluated"
+        && ownership.health !== "conflicting"
+        && ownership.process.status === "matched";
+}
+function describeOwnershipFailure(ownership) {
+    if (ownership.status === "invalid_state") {
+        return "Backend service state is not trusted";
+    }
+    if (ownership.health === "conflicting") {
+        return "Backend health identity conflicts with the recorded instance";
+    }
+    if (ownership.process.status === "mismatched") {
+        return "process command identity does not match the recorded Backend instance";
+    }
+    if (ownership.process.status === "not_found") {
+        return "the recorded process was not found by the ownership probe";
+    }
+    if (ownership.process.status === "inconclusive") {
+        return describeInconclusiveProcessProbe(ownership.process.probe);
+    }
+    return "Backend ownership could not be established";
+}
+function describeInconclusiveProcessProbe(probe) {
+    if (probe.reason === "timeout") {
+        return `ownership probe timed out after ${probe.timeoutMs}ms`;
+    }
+    const details = [
+        probe.reason,
+        probe.code ? `code ${probe.code}` : undefined,
+        typeof probe.exitCode === "number" ? `exit code ${probe.exitCode}` : undefined,
+        probe.signal ? `signal ${probe.signal}` : undefined,
+    ].filter((value) => value !== undefined);
+    return `ownership probe was inconclusive (${details.join(", ")})`;
+}
+function isTrustedServiceState(state) {
+    if (!Number.isSafeInteger(state.pid) || state.pid <= 0)
+        return false;
+    if (!Number.isSafeInteger(state.port) || state.port <= 0 || state.port > 65535)
+        return false;
+    try {
+        const url = new URL(state.url);
+        return url.protocol === "http:" && Number(url.port || "80") === state.port;
+    }
+    catch {
+        return false;
+    }
+}
+function isLoopbackHealthUrl(url) {
+    try {
+        const parsed = new URL(url);
+        return parsed.protocol === "http:" && isLoopbackHost(parsed.hostname);
+    }
+    catch {
+        return false;
+    }
+}
+function waitForSpawn(child) {
+    return new Promise((resolveSpawn) => {
+        let settled = false;
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            resolveSpawn(error);
+        };
+        child.once("error", finish);
+        child.once("spawn", () => finish());
+    });
+}
+async function readHealthWithTimeout(url, timeoutMs, fetchImpl = fetch) {
+    const controller = new AbortController();
+    const boundedTimeoutMs = Math.max(1, Math.min(timeoutMs, 1000));
+    const timeout = setTimeout(() => controller.abort(), boundedTimeoutMs);
+    try {
+        const response = await fetchImpl(url, {
+            headers: { connection: "close" },
+            signal: controller.signal,
+        });
+        if (!response.ok)
+            return { ok: false, body: {} };
+        return {
+            ok: true,
+            body: await response.json(),
+        };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+async function waitUntilStopped(pid, timeoutMs, processAlive = isProcessAlive) {
+    const started = Date.now();
+    while (Date.now() - started < timeoutMs) {
+        if (!processAlive(pid))
+            return;
+        await sleep(100);
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/lib/memorax-code-backend/dist/trace-config.js

@@ -0,0 +1,112 @@
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { loadMemoraxCodeConfig } from "./memorax-code-config.js";
+import { isTraceClient } from "./trace-context.js";
+export const TRACE_CLIENTS = ["codex", "claude"];
+export const CODEX_TRACE_DEFAULT_CONFIG = {
+    enabled: true,
+    captureContent: true,
+    retentionDays: 7,
+    maxEventChars: 20_000,
+    maxFileBytes: 52_428_800,
+};
+export const CLAUDE_TRACE_DEFAULT_CONFIG = {
+    enabled: true,
+    captureContent: true,
+    retentionDays: 7,
+    maxEventChars: 20_000,
+    maxFileBytes: 52_428_800,
+};
+export const TRACE_CLEANUP_DEBOUNCE_MS = 60 * 60 * 1000;
+export const TRACE_CURRENT_TURN_TTL_MS = 30 * 60 * 1000;
+export const CODEX_TRACE_CLEANUP_DEBOUNCE_MS = TRACE_CLEANUP_DEBOUNCE_MS;
+export const CODEX_TRACE_CURRENT_TURN_TTL_MS = TRACE_CURRENT_TURN_TTL_MS;
+const WINDOWS_RESERVED_PATH_SEGMENT = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i;
+const WINDOWS_REWRITTEN_LABEL_MAX_CHARS = 48;
+export function codexTraceConfigFromEnv(env = process.env, fileConfig) {
+    return clientTraceConfigFromEnv("codex", env, fileConfig);
+}
+export function claudeTraceConfigFromEnv(env = process.env, fileConfig) {
+    return clientTraceConfigFromEnv("claude", env, fileConfig);
+}
+export function clientTraceConfigFromEnv(client, env = process.env, fileConfig) {
+    assertTraceClient(client);
+    const config = fileConfig ?? loadMemoraxCodeConfig(memoraxCodeHomeForTrace(env), { warn: () => undefined });
+    const section = config.trace?.[client];
+    const defaults = client === "claude" ? CLAUDE_TRACE_DEFAULT_CONFIG : CODEX_TRACE_DEFAULT_CONFIG;
+    const prefix = client === "claude" ? "MEMORAX_CODE_CLAUDE_TRACE" : "MEMORAX_CODE_CODEX_TRACE";
+    return {
+        enabled: booleanValue(env[`${prefix}_ENABLED`], section?.enabled ?? defaults.enabled),
+        captureContent: booleanValue(env[`${prefix}_CAPTURE_CONTENT`], section?.capture_content ?? defaults.captureContent),
+        retentionDays: positiveInteger(env[`${prefix}_RETENTION_DAYS`] ?? section?.retention_days, defaults.retentionDays),
+        maxEventChars: positiveInteger(env[`${prefix}_MAX_EVENT_CHARS`] ?? section?.max_event_chars, defaults.maxEventChars),
+        maxFileBytes: positiveInteger(env[`${prefix}_MAX_FILE_BYTES`] ?? section?.max_file_bytes, defaults.maxFileBytes),
+    };
+}
+export function memoraxCodeHomeForTrace(env = process.env) {
+    return env.MEMORAX_CODE_HOME?.trim() || join(homedir(), ".memorax-code");
+}
+export function tracePaths(memoraxCodeHome = memoraxCodeHomeForTrace(process.env)) {
+    return clientTracePaths("codex", memoraxCodeHome);
+}
+export function claudeTracePaths(memoraxCodeHome = memoraxCodeHomeForTrace(process.env)) {
+    return clientTracePaths("claude", memoraxCodeHome);
+}
+export function clientTracePaths(client, memoraxCodeHome = memoraxCodeHomeForTrace(process.env)) {
+    assertTraceClient(client);
+    const root = join(memoraxCodeHome, "debug", "traces", client);
+    const sessionsRoot = join(root, "sessions");
+    const sessionDir = (sessionId) => join(sessionsRoot, sanitizeTracePathSegment(sessionId));
+    return {
+        root,
+        currentTurnPath: join(root, ".current-turn.json"),
+        sessionsRoot,
+        sessionDir,
+        sessionCurrentTurnPath: (sessionId) => join(sessionDir(sessionId), ".current-turn.json"),
+        traceJson: (sessionId) => join(sessionDir(sessionId), "trace.json"),
+        eventsJsonl: (sessionId) => join(sessionDir(sessionId), "events.jsonl"),
+    };
+}
+export function sanitizeTracePathSegment(value, platform = process.platform) {
+    const raw = value.trim();
+    const normalized = raw.replace(/[^a-zA-Z0-9._-]+/g, "_").replace(/^_+|_+$/g, "");
+    const segment = !normalized || normalized === "." || normalized === ".." ? "session" : normalized;
+    if (platform !== "win32")
+        return segment;
+    const withoutTrailingDotsOrSpaces = segment.replace(/[. ]+$/g, "");
+    if (withoutTrailingDotsOrSpaces === segment
+        && !WINDOWS_RESERVED_PATH_SEGMENT.test(segment)) {
+        return segment;
+    }
+    const label = (withoutTrailingDotsOrSpaces || "session").slice(0, WINDOWS_REWRITTEN_LABEL_MAX_CHARS);
+    const hash = createHash("sha256").update(raw).digest("hex").slice(0, 12);
+    return `_win_${label}-${hash}`;
+}
+function booleanValue(value, fallback) {
+    if (typeof value === "boolean")
+        return value;
+    if (typeof value !== "string")
+        return fallback;
+    const normalized = value.trim().toLowerCase();
+    if (["1", "true", "yes", "on"].includes(normalized))
+        return true;
+    if (["0", "false", "no", "off"].includes(normalized))
+        return false;
+    return fallback;
+}
+function positiveInteger(value, fallback) {
+    if (typeof value === "number" && Number.isSafeInteger(value) && value > 0)
+        return value;
+    if (typeof value !== "string")
+        return fallback;
+    const normalized = value.trim().replaceAll("_", "");
+    if (!/^[1-9]\d*$/.test(normalized))
+        return fallback;
+    const parsed = Number(normalized);
+    return Number.isSafeInteger(parsed) ? parsed : fallback;
+}
+function assertTraceClient(client) {
+    if (!isTraceClient(client))
+        throw new TypeError("Unsupported trace client");
+}