mirror of
https://github.com/morluto/rea.git
synced 2026-11-15 19:23:24 +00:00
* fix(errors): name rea doctor only for providers it can check An unclassified ProviderAdapterError, an unreadable result and the final presentation fallback all told the caller to run rea doctor, although doctor checks only hopper, ghidra, ida, jadx, kuna and desktop_build. The doctor scope list moves into the domain so presentation can consult it: covered providers get `rea doctor --provider ID`, others are told plainly that the failure is unclassified and where its reason is reported. Producers whose actionable reason lived only in details.diagnostics now author it: Ghidra's committed-profile conflicts share one owner that says to reopen the target, closed analysis clients share one owner, and a jadx-reported request failure no longer points at provider readiness. The deep-analysis profile rejection names doctor only for doctor-checkable providers. Dead presentation branches for tags handled earlier are removed. * fix(errors): make provider recovery actionable * test(android): remove brittle recovery wording check * test: wait for observed child exit before cancellation * test(errors): check that doctor is not offered instead of matching recovery prose
465 lines
17 KiB
TypeScript
465 lines
17 KiB
TypeScript
import { DESKTOP_EXPORT_FRAMEWORK_VERSION } from "../domain/desktop/appExport.js";
|
|
import type { execFileOutput } from "../process/ExecFileOutput.js";
|
|
import type { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
|
|
import type { ClientRegistrationStatus } from "./ClientRegistrationStatus.js";
|
|
import type { DoctorCheck, DoctorHost, DoctorSkillState } from "./Doctor.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}`;
|
|
|
|
/** How a build setting's program was found: set in the environment, or on PATH. */
|
|
export type DesktopBuildCommand =
|
|
| {
|
|
readonly status: "found";
|
|
readonly path: string;
|
|
readonly source: "environment" | "path";
|
|
}
|
|
| { readonly status: "missing" }
|
|
| { readonly status: "invalid"; readonly value: string };
|
|
|
|
/** What a desktop build host has, read without changing anything. */
|
|
export interface DesktopBuildFacts {
|
|
readonly ps: { readonly found: boolean; readonly detail: string };
|
|
readonly docker: DesktopBuildCommand;
|
|
readonly daemon:
|
|
| { readonly status: "reachable"; readonly rootDirectory: string }
|
|
| {
|
|
readonly status: "permission_denied" | "unreachable";
|
|
readonly detail: string;
|
|
}
|
|
| { readonly status: "unchecked" };
|
|
readonly disk:
|
|
| { readonly path: string; readonly freeBytes: number }
|
|
| { readonly path: string; readonly error: string };
|
|
readonly agentEnv: DesktopBuildCommand & {
|
|
readonly version?: string | undefined;
|
|
};
|
|
readonly archive: {
|
|
readonly path: string;
|
|
readonly source: "environment" | "cache";
|
|
readonly status: "current" | "missing" | "stale" | "unknown";
|
|
readonly detail?: string;
|
|
};
|
|
/** Each considered client's registration, by setting names only. */
|
|
readonly registrations: readonly {
|
|
readonly client: string;
|
|
readonly registered: boolean;
|
|
readonly unrecorded: readonly string[];
|
|
readonly unresolved: readonly string[];
|
|
readonly differing?: readonly string[];
|
|
readonly unchecked?: readonly string[];
|
|
/** Version check of this client's recorded runner, without the recorded path. */
|
|
readonly runner?: {
|
|
readonly status: "current" | "stale" | "invalid" | "unknown";
|
|
readonly version?: string;
|
|
};
|
|
}[];
|
|
/** Build settings this terminal's environment sets. */
|
|
readonly environmentSettings: readonly string[];
|
|
/** Where a solve endpoint is configured; null means its configuration is unknown. */
|
|
readonly solveEndpoint: string | null | undefined;
|
|
/** Names of agentenv sandbox containers; undefined when Docker was not reachable. */
|
|
readonly leftoverContainers: readonly string[] | undefined;
|
|
}
|
|
|
|
/** What a facts reader gets from doctor: its environment, bounded runner and registration reader. */
|
|
export interface DesktopBuildFactsInput {
|
|
readonly signal: AbortSignal;
|
|
readonly resources: ArtifactResourceScope;
|
|
readonly environment: Readonly<NodeJS.ProcessEnv>;
|
|
readonly platform: NodeJS.Platform;
|
|
readonly run: typeof execFileOutput;
|
|
readonly clientIds: readonly string[];
|
|
readonly registrations: (
|
|
clientIds: readonly string[] | undefined,
|
|
settings: Readonly<Record<string, string>>,
|
|
owned?: undefined,
|
|
observe?: (client: string, name: string, value: string) => void,
|
|
) => Promise<readonly ClientRegistrationStatus[]>;
|
|
}
|
|
|
|
/** What doctor already knows that the build checks reuse. */
|
|
export interface DesktopBuildContext {
|
|
readonly host: Pick<DoctorHost, "platform" | "architecture" | "runtime">;
|
|
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<DoctorCheck["classification"], "healthy">;
|
|
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<readonly DoctorCheck[]> =>
|
|
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 <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(" ")}`,
|
|
},
|
|
);
|