import { DESKTOP_EXPORT_FRAMEWORK_VERSION } from "../domain/desktop/appExport.js"; import type { DoctorHost, DoctorSkillState } from "./Doctor.js"; import type { DoctorCheck } from "../ports/DoctorProviderInspection.js"; import type { DesktopBuildCommand, DesktopBuildFacts, } from "../ports/DesktopBuildHost.js"; import { nodeCheck } from "./DoctorDiagnostics.js"; import { DESKTOP_BUILD_PROVIDER_ID } from "../domain/doctorProviderIds.js"; import type { DoctorScopeReport } from "./DoctorScope.js"; /** Free space agentenv's images need where Docker keeps them. */ export const DESKTOP_BUILD_MIN_FREE_BYTES = 20 * 1000 ** 3; /** The command that installs the agentenv-framework release bundles target. */ export const AGENTENV_INSTALL_COMMAND = `uv tool install agentenv-framework==${DESKTOP_EXPORT_FRAMEWORK_VERSION}`; /** What doctor already knows that the build checks reuse. */ export interface DesktopBuildContext { readonly host: Pick; readonly clients: readonly string[]; readonly skill: { readonly state: DoctorSkillState; readonly remediation: string | null; }; } const INFORMATIONAL = new Set([ `${DESKTOP_BUILD_PROVIDER_ID}-solve-endpoint`, `${DESKTOP_BUILD_PROVIDER_ID}-leftover-containers`, ]); /** Whether a desktop build check reports without deciding health. */ export const isDesktopBuildInformationalCheck = (name: string): boolean => INFORMATIONAL.has(name); const named = (name: string) => `${DESKTOP_BUILD_PROVIDER_ID}-${name}`; const result = ( name: string, ok: boolean, detail: string, outcome: { readonly classification: Exclude; readonly remediation: string; readonly details?: DoctorCheck["details"]; }, ): DoctorCheck => ({ name: named(name), ok, classification: ok ? "healthy" : outcome.classification, detail, ...(outcome.details === undefined ? {} : { details: outcome.details }), ...(ok ? {} : { remediation: outcome.remediation }), }); /** The desktop build checks a doctor scope selects, read through its host. */ export const selectedDesktopBuildChecks = async ( host: DoctorHost, scope: DoctorScopeReport, skill: DesktopBuildContext["skill"], ): Promise => scope.providers.includes(DESKTOP_BUILD_PROVIDER_ID) && host.desktopBuildFacts !== undefined ? desktopBuildChecks(await host.desktopBuildFacts(scope.clients), { host, clients: scope.clients, skill, }) : []; const setupCommand = (clients: readonly string[]): string => clients.length === 1 ? `rea setup --client ${clients[0]} --desktop-build` : "rea setup --client --desktop-build"; /** The desktop build checks, required first and informational last. */ export const desktopBuildChecks = ( facts: DesktopBuildFacts, context: DesktopBuildContext, ): readonly DoctorCheck[] => [ hostCheck(context.host), { ...nodeCheck(context.host), name: named("node") }, result("ps", facts.ps.found, facts.ps.detail, { classification: "missing_dependency", remediation: "Install procps, whose ps REA's process supervisor runs from /bin/ps or /usr/bin/ps: sudo apt install procps.", }), dockerCheck(facts.docker), daemonCheck(facts.daemon), diskCheck(facts.disk), agentEnvCheck(facts), archiveCheck(facts.archive, context.clients), registrationCheck(facts, context.clients), skillCheck(context.skill), solveEndpointCheck(facts.solveEndpoint), leftoverContainersCheck(facts.leftoverContainers), ]; const hostCheck = (host: DesktopBuildContext["host"]): DoctorCheck => result( "host", host.platform === "linux" && (host.architecture === "x64" || host.architecture === "arm64"), `${host.platform} ${host.architecture}`, { classification: "unsupported_host", remediation: "Builds run on a Linux host on amd64 or arm64 and target its own architecture; run REA on such a host.", }, ); const commandDetail = (command: DesktopBuildCommand, name: string): string => command.status === "found" ? `${command.path} (${command.source === "environment" ? name : "PATH"})` : command.status === "invalid" ? `${name}=${command.value} is not an absolute path to a program.` : `${name} is unset and none is on PATH.`; const dockerCheck = (docker: DesktopBuildCommand): DoctorCheck => result( "docker", docker.status === "found", commandDetail(docker, "REA_DOCKER_COMMAND"), { classification: docker.status === "invalid" ? "config_drift" : "missing_dependency", remediation: docker.status === "invalid" ? "Set REA_DOCKER_COMMAND to the absolute path of the Docker CLI, or unset it to use docker on PATH." : "Install Docker Engine: https://docs.docker.com/engine/install/", }, ); const daemonCheck = (daemon: DesktopBuildFacts["daemon"]): DoctorCheck => result( "docker-daemon", daemon.status === "reachable", daemon.status === "reachable" ? `Docker keeps its data in ${daemon.rootDirectory}.` : daemon.status === "unchecked" ? "Not checked without a Docker CLI." : daemon.detail, daemon.status === "unreachable" ? { classification: "runtime_failure", remediation: "Start Docker (sudo systemctl start docker), then rerun rea doctor --provider desktop_build.", } : { classification: "config_drift", remediation: "Let your user reach Docker without sudo: sudo usermod -aG docker $USER, then log out and in again.", }, ); const diskCheck = (disk: DesktopBuildFacts["disk"]): DoctorCheck => { const gb = (bytes: number) => `${(bytes / 1000 ** 3).toFixed(1)} GB`; return "error" in disk ? result("disk", false, `${disk.path}: ${disk.error}`, { classification: "unknown", remediation: `Check that ${disk.path} is readable, then rerun rea doctor --provider desktop_build.`, }) : result( "disk", disk.freeBytes >= DESKTOP_BUILD_MIN_FREE_BYTES, `${gb(disk.freeBytes)} free in ${disk.path}.`, { classification: "missing_dependency", remediation: `Free at least ${gb(DESKTOP_BUILD_MIN_FREE_BYTES)} in ${disk.path}, or move Docker's data root (data-root in /etc/docker/daemon.json) to a larger disk.`, details: { path: disk.path, free_bytes: disk.freeBytes }, }, ); }; const agentEnvCheck = (facts: DesktopBuildFacts): DoctorCheck => { const { agentEnv } = facts; const clients = facts.registrations.filter(({ registered }) => registered); if ( clients.some( ({ runner, unresolved }) => runner !== undefined || unresolved.includes("REA_AGENT_ENV_COMMAND"), ) ) { const rows = clients.map(({ client, runner, unresolved }) => ({ client, ...(runner ?? (unresolved.includes("REA_AGENT_ENV_COMMAND") ? { status: "unknown" as const } : agentEnv.status !== "found" ? { status: "invalid" as const } : agentEnv.version === undefined ? { status: "unknown" as const } : { status: agentEnv.version === DESKTOP_EXPORT_FRAMEWORK_VERSION ? ("current" as const) : ("stale" as const), version: agentEnv.version, })), })); const healthy = rows.every(({ status }) => status === "current"); return result( "agent-env", healthy, rows .map(({ client, status }) => `${client}'s runner is ${status}.`) .join(" "), { classification: rows.some(({ status }) => status === "unknown") ? "unknown" : "missing_dependency", remediation: `${AGENTENV_INSTALL_COMMAND}, or rea setup --desktop-build --install-agentenv.`, details: { expected_version: DESKTOP_EXPORT_FRAMEWORK_VERSION, clients: rows, }, }, ); } const pinned = agentEnv.version === DESKTOP_EXPORT_FRAMEWORK_VERSION; const detail = agentEnv.status !== "found" ? commandDetail(agentEnv, "REA_AGENT_ENV_COMMAND") : `${commandDetail(agentEnv, "REA_AGENT_ENV_COMMAND")} reports ${agentEnv.version === undefined ? "no version" : `agentenv-framework ${agentEnv.version}`}; bundles target ${DESKTOP_EXPORT_FRAMEWORK_VERSION}.`; return result("agent-env", agentEnv.status === "found" && pinned, detail, { classification: agentEnv.status === "invalid" ? "config_drift" : "missing_dependency", remediation: agentEnv.status === "invalid" ? `Set REA_AGENT_ENV_COMMAND to the absolute path of agent-env, or unset it to use agent-env on PATH. To install it: ${AGENTENV_INSTALL_COMMAND}` : `${AGENTENV_INSTALL_COMMAND}, or rea setup --desktop-build --install-agentenv.`, details: { expected_version: DESKTOP_EXPORT_FRAMEWORK_VERSION }, }); }; const archiveCheck = ( archive: DesktopBuildFacts["archive"], clients: readonly string[], ): DoctorCheck => result( "archive", archive.status === "current", archive.detail ?? (archive.status === "current" ? `${archive.path} holds this REA version.` : `${archive.path} is missing.`), { classification: archive.status === "unknown" ? "unknown" : "config_drift", remediation: archive.source === "environment" ? `Repack it with npm run pack:build-computer-runtime -- ${archive.path}, or unset REA_BUILD_COMPUTER_REA_ARCHIVE and run ${setupCommand(clients)}.` : `Run ${setupCommand(clients)} to pack it.`, details: { path: archive.path, source: archive.source }, }, ); const registrationCheck = ( facts: DesktopBuildFacts, clients: readonly string[], ): DoctorCheck => { const set = new Set(facts.environmentSettings); const gaps = facts.registrations.map( ({ client, registered, unrecorded, unresolved, differing = [], unchecked = [], runner, }) => ({ client, registered, missing: unrecorded.filter((name) => !set.has(name)), unresolved: [...unresolved], ...(differing.length === 0 ? {} : { differing: [...differing] }), ...(unchecked.length === 0 ? {} : { unchecked: [...unchecked] }), ...(runner === undefined ? {} : { runner }), }), ); const failing = gaps.filter( ({ registered, missing, differing, runner }) => !registered || missing.length > 0 || (differing ?? []).some( (name) => name !== "REA_AGENT_ENV_COMMAND" || runner?.status !== "current", ), ); const unknown = gaps.filter( ({ unresolved, unchecked }) => unresolved.length > 0 || (unchecked?.length ?? 0) > 0, ); const repair = failing[0]?.client ?? unknown[0]?.client; const remediation = failing.some( ({ differing }) => (differing?.length ?? 0) > 0, ) ? "Correct or remove the failed settings in the client's REA registration, then restart the client and run doctor again." : unknown.length > 0 ? "Check the unverified settings in the client's REA registration, then restart the client and run doctor again." : `Run ${setupCommand(repair === undefined ? clients : [repair])}, then restart the client.`; return result( "registration", gaps.length > 0 && failing.length === 0 && unknown.length === 0, gaps.length === 0 ? "No REA registration was found." : gaps.map(registrationDetail).join(" "), { classification: failing.length === 0 && gaps.length > 0 ? "unknown" : "config_drift", remediation, details: { registrations: gaps }, }, ); }; const registrationDetail = (gap: { readonly client: string; readonly registered: boolean; readonly missing: readonly string[]; readonly unresolved: readonly string[]; readonly differing?: readonly string[]; readonly unchecked?: readonly string[]; }): string => { if (!gap.registered) return `${gap.client} does not register REA.`; const details = [ ...(gap.missing.length === 0 ? [] : [ `${gap.client}'s registration does not record ${gap.missing.join(", ")}, and this environment does not set them.`, ]), ...(gap.unresolved.length === 0 ? [] : [`REA could not read ${gap.client}'s ${gap.unresolved.join(", ")}.`]), ...(gap.differing === undefined ? [] : [ `${gap.client}'s recorded ${gap.differing.join(", ")} failed verification.`, ]), ...(gap.unchecked === undefined ? [] : [ `REA could not verify ${gap.client}'s recorded ${gap.unchecked.join(", ")}.`, ]), ]; return details.length > 0 ? details.join(" ") : `${gap.client}'s registration records the build settings, or this environment sets them.`; }; const skillCheck = (skill: DesktopBuildContext["skill"]): DoctorCheck => result( "skill", skill.state === "aligned", `The installed REA skill, with its desktop-build reference, is ${skill.state}.`, { classification: skill.state === "unknown" ? "unknown" : "config_drift", remediation: skill.remediation ?? "Run rea setup --skill to update the REA skill.", }, ); const solveEndpointCheck = (where: string | null | undefined): DoctorCheck => result( "solve-endpoint", where !== undefined && where !== null, where === null ? "REA could not determine whether agentenv has a model endpoint configured." : where === undefined ? "No model endpoint is configured for solver runs." : `A model endpoint is configured in ${where}; its availability was not checked.`, { classification: where === null ? "unknown" : "missing_dependency", remediation: "For solver runs, export LITELLM_BASE_URL and LITELLM_API_KEY in the shell that starts the agent, or set base_url and api_key under [model] in .agentenv/config.toml.", }, ); const leftoverContainersCheck = ( containers: readonly string[] | undefined, ): DoctorCheck => result( "leftover-containers", containers === undefined || containers.length === 0, containers === undefined ? "Not checked without a reachable Docker daemon." : containers.length === 0 ? "No agentenv sandbox containers are left." : `${String(containers.length)} agentenv sandbox containers remain: ${containers.join(", ")}.`, { classification: "config_drift", remediation: `If no build is running, remove them: docker rm -f ${(containers ?? []).join(" ")}`, }, );