Files
reverse-engineering-anything/src/desktop/DesktopBuildDoctorFacts.ts
T
morluto 47461fddab fix(desktop): share launch syntax, replay paths, and runtime admission (#12153)
* refactor(desktop): share launch syntax with the offline installer

Refs #12119 and #12120.

* fix(desktop): share build archive readiness admission

Refs #12144

* fix(desktop): honor env unset launch operands

* fix(desktop): retain unknown state home after env removal

* fix(desktop): share captured state replay paths

* fix(desktop): keep traversing launches aligned with retained seeds

* fix(desktop): preserve scalars in traversing launches

* fix(desktop): admit traversing arguments before replay
2026-11-19 03:36:56 +00:00

628 lines
20 KiB
TypeScript

import { constants } from "node:fs";
import { access, stat, statfs } from "node:fs/promises";
import { dirname, isAbsolute } from "node:path";
import { z } from "zod";
import type {
DesktopBuildCommand,
DesktopBuildFacts,
DesktopBuildFactsInput,
} from "../ports/DesktopBuildHost.js";
import {
AnalysisCancelledError,
cancelledBy,
carriedReason,
} from "../domain/analysisErrorCore.js";
import { safeParseJson } from "../domain/safeJson.js";
import {
readRegularFileText,
RetainedRegularFileCleanupFailure,
} from "../process/RegularFileRead.js";
import { DESKTOP_EXPORT_FRAMEWORK_VERSION } from "../domain/desktop/appExport.js";
import { PYTHON_BUILD_ARCHIVE_PROBE } from "../domain/desktop/appBuildArchive.js";
import { PRODUCT_IDENTITY } from "../identity.js";
import { execFileOutputFailure } from "../process/ExecFileOutput.js";
import { describeSystemPs, resolveSystemPs } from "../process/systemPs.js";
import { agentEnvInterpreter } from "./AgentEnvComputerHelper.js";
import {
ArtifactFileCleanupFailure,
AnalysisCleanupLeaseGroup,
type AnalysisCleanupLease,
} from "../resources/index.js";
import { ProviderCleanupError } from "../domain/providerCleanupError.js";
import {
agentEnvReportedVersion,
defaultBuildComputerArchive,
programOnPath,
resolveBuildComputerProgram,
type BuildComputerSetting,
} from "./BuildComputerEnvironment.js";
import { BUILD_COMPUTER_SETTINGS } from "../domain/desktop/buildComputerSettings.js";
import { errorMessage } from "../kernel/errorMessage.js";
const DEFAULT_DOCKER_ROOT = "/var/lib/docker";
const CONFIG_BYTES = 1024 * 1024;
const missingPath = (cause: unknown): boolean =>
cause instanceof Error && "code" in cause && cause.code === "ENOENT";
/** Read what a desktop build needs from this host, changing nothing. */
export const readDesktopBuildFacts = async (
input: DesktopBuildFactsInput,
): Promise<DesktopBuildFacts> => {
const { environment } = input;
const docker = await settingCommand(
environment,
"REA_DOCKER_COMMAND",
"docker",
);
const daemon =
docker.status === "found"
? await dockerDaemon(input, docker.path)
: ({ status: "unchecked" } as const);
const agentEnv = await settingCommand(
environment,
"REA_AGENT_ENV_COMMAND",
"agent-env",
);
const versions = new Map<string, Promise<string | undefined>>();
const versionFor = (path: string): Promise<string | undefined> => {
const existing = versions.get(path);
if (existing !== undefined) return existing;
const pending = agentEnvVersion(input, path);
versions.set(path, pending);
return pending;
};
const archive = await archiveFact(input, async () =>
agentEnv.status === "found"
? agentEnvInterpreter(
{ ...input.environment, REA_AGENT_ENV_COMMAND: agentEnv.path },
"desktop_build_doctor",
input.resources,
).catch((cause: unknown) => {
if (cause instanceof ArtifactFileCleanupFailure)
throw runnerCleanupFailure(cause);
return "python3";
})
: "python3",
);
const chosenCommand = (
name: BuildComputerSetting,
command: DesktopBuildCommand,
) =>
(environment[name] ?? "") !== ""
? environment[name]
: command.status === "found"
? command.path
: undefined;
const selectedDocker = chosenCommand("REA_DOCKER_COMMAND", docker);
const selectedAgentEnv = chosenCommand("REA_AGENT_ENV_COMMAND", agentEnv);
const selectedSettings: Partial<Record<BuildComputerSetting, string>> = {
...(selectedDocker === undefined
? {}
: { REA_DOCKER_COMMAND: selectedDocker }),
...(selectedAgentEnv === undefined
? {}
: { REA_AGENT_ENV_COMMAND: selectedAgentEnv }),
REA_BUILD_COMPUTER_REA_ARCHIVE: archive.path,
};
return {
ps: await psFact(input),
docker,
daemon,
disk: await freeSpace(
daemon.status === "reachable"
? daemon.rootDirectory
: DEFAULT_DOCKER_ROOT,
),
agentEnv:
agentEnv.status === "found"
? { ...agentEnv, version: await versionFor(agentEnv.path) }
: agentEnv,
archive,
registrations: await registrationFacts(input, selectedSettings, versionFor),
environmentSettings: BUILD_COMPUTER_SETTINGS.filter(
(name) => (environment[name] ?? "") !== "",
),
solveEndpoint: await solveEndpoint(input, agentEnv),
leftoverContainers:
docker.status === "found" && daemon.status === "reachable"
? await leftoverContainers(input, docker.path)
: undefined,
};
};
/** Run a bounded command; undefined output with its stderr when it fails. */
const attempt = async (
input: DesktopBuildFactsInput,
command: string,
arguments_: readonly string[],
): Promise<
| { readonly ok: true; readonly stdout: string }
| { readonly ok: false; readonly reason: string }
> => {
try {
const { stdout } = await input.run(command, arguments_, {
env: input.environment,
});
return { ok: true, stdout };
} catch (cause: unknown) {
if (cause instanceof AnalysisCancelledError) throw cause;
const failure = execFileOutputFailure(cause);
const stderr = failure?.stderr.trim() ?? "";
return {
ok: false,
reason: stderr === "" ? errorMessage(cause) : stderr,
};
}
};
const executable = (path: string): Promise<boolean> =>
access(path, constants.X_OK).then(
async () => (await stat(path)).isFile(),
() => false,
);
const settingCommand = async (
environment: Readonly<NodeJS.ProcessEnv>,
name: BuildComputerSetting,
program: string,
): Promise<DesktopBuildCommand> => {
const value = environment[name];
if (value === undefined || value === "") {
const path = await programOnPath(program, environment);
return path === undefined
? { status: "missing" }
: { status: "found", path, source: "path" };
}
return isAbsolute(value) && (await executable(value))
? { status: "found", path: value, source: "environment" }
: { status: "invalid", value };
};
/**
* Probe the `ps` REA's process supervisor selects: a fixed system location
* first, REA's PATH only as the fallback. procps `ps` accepts `-p`; busybox's
* does not.
*/
const psFact = async (
input: DesktopBuildFactsInput,
): Promise<DesktopBuildFacts["ps"]> => {
const selected = await resolveSystemPs(input.platform);
const ps =
selected.source === "system"
? selected.command
: await programOnPath("ps", input.environment);
if (ps === undefined)
return { found: false, detail: `No ${describeSystemPs(selected)}.` };
const probe = await attempt(input, ps, [
"-o",
"pid=",
"-p",
String(process.pid),
]);
return probe.ok
? { found: true, detail: ps }
: {
found: false,
detail: `${ps} is not procps-compatible: ${probe.reason}`,
};
};
const dockerDaemon = async (
input: DesktopBuildFactsInput,
docker: string,
): Promise<DesktopBuildFacts["daemon"]> => {
const info = await attempt(input, docker, [
"info",
"--format",
"{{.DockerRootDir}}",
]);
if (info.ok)
return {
status: "reachable",
rootDirectory: info.stdout.trim() || DEFAULT_DOCKER_ROOT,
};
return {
status: /permission denied/iu.test(info.reason)
? "permission_denied"
: "unreachable",
detail: info.reason,
};
};
/** Free space on the filesystem that holds `path`, or its nearest existing parent. */
const freeSpace = async (path: string): Promise<DesktopBuildFacts["disk"]> => {
let candidate = path;
for (;;) {
try {
const fs = await statfs(candidate);
return { path: candidate, freeBytes: fs.bavail * fs.bsize };
} catch (cause: unknown) {
const parent = dirname(candidate);
if (parent === candidate || !missingPath(cause))
return {
path,
error: errorMessage(cause),
};
candidate = parent;
}
}
};
const agentEnvVersion = async (
input: DesktopBuildFactsInput,
agentEnv: string,
): Promise<string | undefined> => {
const reported = await attempt(input, agentEnv, ["--version"]);
return reported.ok ? agentEnvReportedVersion(reported.stdout) : undefined;
};
const archiveObservationSchema = z.object({
version: z.string().nullable(),
problem: z.string().nullable(),
});
/** Read layout and package version for the selected archive without extracting it. */
const archiveFact = async (
input: DesktopBuildFactsInput,
pythonForArchive: () => Promise<string | undefined>,
): Promise<DesktopBuildFacts["archive"]> => {
const selected = input.environment.REA_BUILD_COMPUTER_REA_ARCHIVE;
const source =
selected === undefined || selected === "" ? "cache" : "environment";
const path =
source === "cache"
? defaultBuildComputerArchive(input.environment, input.platform)
: (selected as string);
try {
if (!(await stat(path)).isFile())
return { path, source, status: "missing" };
} catch (cause: unknown) {
return missingPath(cause)
? { path, source, status: "missing" }
: {
path,
source,
status: "unknown",
detail: `REA could not inspect ${path}: ${errorMessage(cause)}`,
};
}
const python = await pythonForArchive();
if (python === undefined)
return {
path,
source,
status: "unknown",
detail: `REA could not identify the selected runner's Python to inspect ${path}.`,
};
const packed = await attempt(input, python, [
"-I",
"-c",
PYTHON_BUILD_ARCHIVE_PROBE,
path,
]);
if (!packed.ok)
return {
path,
source,
status: "unknown",
detail: `REA could not inspect ${path}: ${packed.reason}`,
};
const parsed = safeParseJson(packed.stdout);
const observation = parsed.ok
? archiveObservationSchema.safeParse(parsed.value)
: undefined;
if (observation?.success === true && observation.data.problem !== null) {
const { version, problem } = observation.data;
return {
path,
source,
status: "invalid",
detail: `${version === null ? path : `${path} declares REA ${version}`}. ${problem}`,
};
}
const version =
observation?.success === true ? observation.data.version : null;
return version === PRODUCT_IDENTITY.packageVersion
? { path, source, status: "current" }
: version === null
? {
path,
source,
status: "unknown",
detail: `REA could not identify the version of the runnable archive ${path}.`,
}
: {
path,
source,
status: "stale",
detail: `${path} holds REA ${version}; this is REA ${PRODUCT_IDENTITY.packageVersion}.`,
};
};
/** Setting names each considered registration records; values stay in its file. */
const registrationFacts = async (
input: DesktopBuildFactsInput,
selectedSettings: Partial<Record<BuildComputerSetting, string>>,
versionFor: (path: string) => Promise<string | undefined>,
): Promise<DesktopBuildFacts["registrations"]> => {
const selected = input.clientIds.length === 0 ? undefined : input.clientIds;
const recorded = new Map<string, Map<string, string>>();
const statuses = await input.registrations(
selected,
Object.fromEntries(
BUILD_COMPUTER_SETTINGS.map((name) => [
name,
selectedSettings[name] ?? "",
]),
),
undefined,
(client, name, value) => {
if (selected === undefined || selected.includes(client)) {
const settings = recorded.get(client) ?? new Map<string, string>();
settings.set(name, value);
recorded.set(client, settings);
}
},
);
const registered = statuses.filter(({ command }) => command.length > 0);
const considered = selected ?? registered.map(({ client }) => client);
// Every admitted client inspection settles before a failure is reported, so
// no file a peer opened outlives the doctor operation that owns it.
const outcomes = await Promise.allSettled(
considered.map(async (client) => {
const status = registered.find((entry) => entry.client === client);
const values = status === undefined ? undefined : recorded.get(client);
const recordedRunner = values?.get("REA_AGENT_ENV_COMMAND");
const effectiveRunner =
recordedRunner === undefined
? undefined
: await resolveBuildComputerProgram(
recordedRunner,
"agent-env",
input.environment,
);
let runner: DesktopBuildFacts["registrations"][number]["runner"];
if (recordedRunner !== undefined) {
if (
effectiveRunner === undefined ||
!isAbsolute(effectiveRunner) ||
!(await executable(effectiveRunner))
)
runner = { status: "invalid" };
else {
const version = await versionFor(effectiveRunner);
runner =
version === undefined
? { status: "unknown" }
: {
status:
version === DESKTOP_EXPORT_FRAMEWORK_VERSION
? "current"
: "stale",
version,
};
}
}
const differing = (status?.provider_settings?.differing ?? []).filter(
(name) =>
name !== "REA_AGENT_ENV_COMMAND" ||
recordedRunner !== "" ||
effectiveRunner === undefined ||
effectiveRunner !== selectedSettings.REA_AGENT_ENV_COMMAND,
);
const compared: string[] = [];
const unchecked: string[] = [];
for (const name of differing) {
if (name === "REA_AGENT_ENV_COMMAND") {
if (runner !== undefined) compared.push(name);
else unchecked.push(name);
continue;
}
const value = values?.get(name);
if (value === undefined) {
unchecked.push(name);
continue;
}
const environment = { ...input.environment, [name]: value };
if (name === "REA_DOCKER_COMMAND") {
const command = await settingCommand(environment, name, "docker");
if (command.status !== "found") compared.push(name);
else if (
(await dockerDaemon({ ...input, environment }, command.path))
.status !== "reachable"
)
unchecked.push(name);
} else if (name === "REA_BUILD_COMPUTER_REA_ARCHIVE") {
const archive = await archiveFact(
{ ...input, environment },
async () =>
effectiveRunner === undefined || runner?.status === "invalid"
? undefined
: agentEnvInterpreter(
{ ...environment, REA_AGENT_ENV_COMMAND: effectiveRunner },
"desktop_build_doctor",
input.resources,
).catch((cause: unknown) => {
if (cause instanceof ArtifactFileCleanupFailure)
throw runnerCleanupFailure(cause);
return undefined;
}),
);
if (archive.status === "unknown") unchecked.push(name);
else if (archive.status !== "current") compared.push(name);
} else unchecked.push(name);
}
return {
client,
registered: status !== undefined,
unrecorded: status?.provider_settings?.unrecorded ?? [],
unresolved: status?.provider_settings?.unresolved ?? [],
...(compared.length === 0 ? {} : { differing: compared }),
...(unchecked.length === 0 ? {} : { unchecked }),
...(runner === undefined ? {} : { runner }),
};
}),
);
const failure = outcomes.find((outcome) => outcome.status === "rejected");
if (failure !== undefined) throw failure.reason;
return outcomes.flatMap((outcome) =>
outcome.status === "fulfilled" ? [outcome.value] : [],
);
};
const solveEndpoint = async (
input: DesktopBuildFactsInput,
runner: DesktopBuildCommand,
): Promise<string | null | undefined> => {
if (input.signal.aborted) throw cancelledBy("doctor", input.signal);
if (runner.status !== "found") return null;
const discovery = await attempt(input, runner.path, [
"config",
"debug",
"--json",
]);
if (!discovery.ok) return null;
const discovered = safeParseJson(discovery.stdout);
const candidates = discovered.ok
? z
.object({
search_path: z.array(
z.object({ path: z.string(), exists: z.boolean() }),
),
})
.safeParse(discovered.value)
: undefined;
if (candidates === undefined || !candidates.success) return null;
const selected = candidates.data.search_path.find(
({ exists }) => exists,
)?.path;
if (
selected === undefined &&
(input.environment.AGENT_ENV_CONFIG ?? "") !== ""
)
return null;
if (selected !== undefined && !(await canReadModelConfig(selected, input)))
return null;
const explained = await attempt(input, runner.path, [
"config",
"explain",
"model.base_url",
"--json",
]);
if (!explained.ok) return null;
const parsed = safeParseJson(explained.stdout);
const result = parsed.ok
? z
.object({
path: z.literal("model.base_url"),
value: z.unknown(),
error: z.unknown(),
winner: z.object({ kind: z.string() }).nullable().optional(),
})
.safeParse(parsed.value)
: undefined;
if (result === undefined || !result.success || result.data.error != null)
return null;
const value = result.data.value;
// Agentenv's explain command lists an empty env override, while the runtime
// getter falls through to the file. The explanation cannot prove that value.
if (value === "" && result.data.winner?.kind === "env") return null;
if (value === null || value === "") return undefined;
if (typeof value !== "string" || /^(?:env|secret):/u.test(value)) return null;
return result.data.winner?.kind === "env"
? "LITELLM_BASE_URL"
: (selected ?? "agentenv model configuration");
};
/**
* A doctor file whose close failed stays owned by `input.resources`, which the
* doctor host retries on close. Report it as the doctor's typed cleanup
* failure, bound to that owner's lease, so the error document keeps the
* retained file and its recovery.
*/
const doctorFileCleanupFailure = (
lease: AnalysisCleanupLease,
resources: readonly string[],
reason: string,
cause: unknown,
): ProviderCleanupError => {
const failure = new ProviderCleanupError(
"rea",
resources,
{ reason },
{ operation: "doctor", cause },
);
new AnalysisCleanupLeaseGroup(failure, [lease]);
return failure;
};
const runnerCleanupFailure = (
cause: ArtifactFileCleanupFailure,
): ProviderCleanupError =>
doctorFileCleanupFailure(
cause.cleanupLease,
cause.cleanup?.resources ?? cause.cleanupLease.cleanupResources ?? [],
cause.cleanup?.reason ?? cause.message,
cause,
);
const canReadModelConfig = async (
path: string,
input: DesktopBuildFactsInput,
): Promise<boolean> => {
try {
if (input.signal.aborted) throw cancelledBy("doctor", input.signal);
const candidate = await stat(path);
if (input.signal.aborted) throw cancelledBy("doctor", input.signal);
if (!candidate.isFile() || candidate.size > CONFIG_BYTES) return false;
await readRegularFileText(path, {
signal: input.signal,
admit: (state) => {
if (state.size > CONFIG_BYTES)
throw new Error("Configuration exceeds the read limit");
},
cancellationFailure: (reason) =>
cancelledBy("doctor", carriedReason(reason)),
});
return true;
} catch (cause: unknown) {
if (cause instanceof RetainedRegularFileCleanupFailure) {
input.resources.retain(cause.cleanupOwner);
throw doctorFileCleanupFailure(
cause.cleanupLease,
[cause.path],
cause.message,
cause,
);
}
if (cause instanceof AnalysisCancelledError) throw cause;
if (input.signal.aborted) throw cancelledBy("doctor", input.signal);
return false;
}
};
/** Sandboxes agentenv runs as `agent-<id>`, and those it labels with their id. */
const leftoverContainers = async (
input: DesktopBuildFactsInput,
docker: string,
): Promise<readonly string[] | undefined> => {
const names = new Set<string>();
for (const filter of ["name=^agent-", "label=agentenv.sandbox"]) {
const listed = await attempt(input, docker, [
"ps",
"-a",
"--filter",
filter,
"--format",
"{{.Names}}",
]);
if (!listed.ok) return undefined;
for (const name of listed.stdout.split(/\s+/u).filter(Boolean))
names.add(name);
}
return [...names].sort();
};