Files
reverse-engineering-anything/src/application/desktop/DesktopBuildCapture.ts
T

711 lines
24 KiB
TypeScript

import type { DownloadInstall } from "../../domain/desktop/appDownloadInstall.js";
import { z } from "zod";
import { AnalysisError } from "../../domain/analysisErrorBase.js";
import { cancelledBy } from "../../domain/analysisErrorCore.js";
import type { BuildRequest } from "../../domain/desktop/appBuild.js";
import {
SIGN_IN_END,
SIGN_IN_START,
type BuildConsent,
} from "../../domain/desktop/appWithheld.js";
import type { KnownSecret } from "../../domain/desktop/buildSecrets.js";
import {
BUILD_PACKAGE_FILE,
downloadInstallOf,
extraPackagesOf,
} from "../../domain/desktop/appBuild.js";
import {
END_CHECKPOINT,
SEED_CHECKPOINT,
} from "../../domain/desktop/buildCapture.js";
import {
captureProgressEvent,
type DesktopCaptureEvent,
} from "../../domain/desktop/desktopCapture.js";
import type { JsonValue } from "../../domain/jsonValue.js";
import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
import { err, ok, type Result } from "../../domain/result.js";
import { AGENTENV_PROVIDER } from "../../desktop/AgentEnvProviderIdentity.js";
import type { AgentEnvComputer } from "../../desktop/AgentEnvComputer.js";
import { controller } from "../../desktop/BuildComputerController.js";
import type {
BuildControllerAnswer,
ControlledComputer,
} from "../../ports/BuildComputerControl.js";
import { BuildComputerLongRuns } from "../../desktop/BuildComputerLongRuns.js";
import {
endedCapture,
notAnswered,
type CaptureStep,
} from "./DesktopBuildCaptureFailure.js";
import {
adapterError,
parseBuildComputerJson,
refused,
runRea,
WORK,
} from "./DesktopBuildCommands.js";
import {
exportBuild,
type BuildExportRequest,
type ExportedBuild,
} from "./DesktopBuildExport.js";
import {
summarizeCapture,
secretDraftRefusal,
type StoppedCapture,
} from "./DesktopBuildSummary.js";
import { errorMessage } from "../../kernel/errorMessage.js";
const START = "start_build_capture";
const MARK = "mark_build_checkpoint";
/** The computer routes a capture uses: REA's controller, and the screenshot it keeps of each checkpoint. */
type CaptureComputer = ControlledComputer &
Pick<AgentEnvComputer, "callTool" | "addHomeFiles">;
/** A checkpoint's screenshot as the export takes a screen judge's examples: JPEG, small enough for a judge's prompt. */
const CHECKPOINT_SHOT = { format: "jpeg", quality: 70 } as const;
/**
* Keep a screenshot of the checkpoint just taken in the capture's screens
* folder, where the export finds a screen judge's examples. A screenshot
* that fails leaves the checkpoint as it is; only cancellation propagates.
*/
const keepScreenshot = async (
computer: CaptureComputer,
folder: string,
name: string,
signal: AbortSignal,
): Promise<void> => {
try {
const shot = await computer.callTool(
"computer_screenshot",
CHECKPOINT_SHOT,
signal,
);
const image = shot.content.find((block) => block.type === "image")?.data;
if (shot.isError || typeof image !== "string") return;
await computer.addHomeFiles(
new Map([
[`${folder}/screens/${name}.jpg`, Buffer.from(image, "base64")],
]),
signal,
);
} catch (cause: unknown) {
if (signal.aborted) throw cause;
}
};
const STOP = "stop_build_capture";
const EXPORT = "export_build_environment";
/** The start's step, for a capture that ended before the app's window opened. */
const STARTING: CaptureStep = {
operation: START,
when: "before the app's window opened",
afterAppExit:
"The app does not run as installed: check what it needs, such as a runtime its stderr names, and name that package in an archive install's extra_packages, or install the app from another source, on a new build computer; close this one.",
};
/** A checkpoint's step, for a capture that ended before acknowledging it. */
const marking = (name: string): CaptureStep => ({
operation: MARK,
when: `before checkpoint ${name}`,
afterAppExit:
"The capture ended with the app: stop_build_capture reads what it recorded, then start_build_capture captures again.",
});
const NOT_RUNNING = [
"No capture is running on this computer.",
"Start one with start_build_capture.",
] as const;
/** What the agent asks of a capture's launch: arguments for the app, and files or folders in the home that are its state. */
export interface CaptureInput {
readonly arguments?: readonly string[] | undefined;
readonly state_paths?: readonly string[] | undefined;
}
const exportOptionsSchema = z.object({
options: z.object({ properties: z.record(z.string(), z.unknown()) }),
});
const repackRuntime =
"Run npm run pack:build-computer-runtime -- /absolute/path/rea-prod.tar.xz in a current REA checkout, set REA_BUILD_COMPUTER_REA_ARCHIVE to that archive, restart the REA MCP server, and start a new build computer.";
const schemaCommandError = (exitCode: number | null, detail: string) =>
new ProviderAdapterError(AGENTENV_PROVIDER, START, {
userMessage: `The build computer's REA export schema command ${exitCode === null ? "ended without an exit status" : `exited ${String(exitCode)}`}: ${detail}`,
remediationAction: `Inspect the command error. If the runtime is outdated, ${repackRuntime}`,
});
/** Export options a build passes, as the runtime's schema names them, with what each supports. */
const BUILD_EXPORT_OPTIONS = {
syntheticSeed: "synthetic seeds",
taskEnd: "task ends",
} as const;
/** Check the installed runtime's advertised export contract before capturing the user's work. */
const checkExportRuntime = async (
computer: ControlledComputer,
signal: AbortSignal,
): Promise<Result<void, AnalysisError>> => {
try {
const path = `${WORK}/export-schema.json`;
const command = await runRea(
computer,
["export-desktop-application", "--schema", "--json"],
{ stdout: path, timeoutS: 30, signal },
);
if (command.exitCode !== 0 && command.stderr !== "")
return err(
schemaCommandError(command.exitCode, computer.redacted(command.stderr)),
);
if (command.stdoutBytes > 1024 * 1024)
return err(
adapterError(
START,
"The build computer's REA export schema exceeds 1 MiB.",
),
);
const content = (
await computer.homeFiles([path], command.stdoutBytes, signal)
).get(path);
if (content === undefined)
return err(
adapterError(
START,
"The build computer did not return its REA export schema.",
),
);
if (command.exitCode !== 0)
return err(
schemaCommandError(
command.exitCode,
computer.redacted(content.toString("utf8")).slice(-2048),
),
);
let rawSchema: unknown;
try {
rawSchema = parseBuildComputerJson(content);
} catch {
return err(
adapterError(
START,
"The build computer's REA export schema is invalid JSON.",
),
);
}
const schema = exportOptionsSchema.safeParse(rawSchema);
if (!schema.success)
return err(
adapterError(
START,
"The build computer's REA returned an invalid export schema.",
),
);
const unsupported = Object.entries(BUILD_EXPORT_OPTIONS)
.filter(([name]) => !(name in schema.data.options.properties))
.map(([, what]) => what);
if (unsupported.length > 0)
return err(
refused(
START,
`The REA runtime in this build computer does not support ${unsupported.join(" or ")} required by build export.`,
repackRuntime,
),
);
return ok(undefined);
} catch (cause: unknown) {
if (signal.aborted) return err(cancelledBy(START, signal));
const message = errorMessage(cause);
const redacted = computer.redacted(message);
return err(
adapterError(
START,
`Could not read the build computer's REA export schema: ${redacted}`,
redacted === message ? cause : undefined,
),
);
}
};
/** A taken checkpoint as the tool reports it: changed files null when the REA in the computer predates them. */
type CheckpointTaken = Omit<
Extract<DesktopCaptureEvent, { kind: "checkpoint" }>,
"kind" | "changed_files" | "more_changed_files"
> & {
readonly changed_files: string[] | null;
readonly more_changed_files: number | null;
};
/**
* One capture in the computer. `unreleased` is a capture that may be
* running although its start failed, kept until a stop is confirmed;
* `stopped` keeps the stop's result once it was read, so a retried stop
* resumes or repeats it.
*/
interface CaptureRun {
readonly folder: string;
status: "running" | "unreleased" | "stopped" | "released";
/** Checkpoints the capture acknowledged, then those its own Evidence records. */
checkpoints: Set<string>;
/** The capture's package installs only from its file, so the export takes the request's URL. */
packageFile?: boolean;
outputBytes?: number;
stopped?: StoppedCapture;
exports: number;
}
/** The capture of a failed start may still run; REA still owns it. */
const unreleasedError = (
operation: string,
run: CaptureRun,
cause: AnalysisError | undefined,
) =>
new ProviderAdapterError(AGENTENV_PROVIDER, operation, {
userMessage: `The capture REA began in ~/${run.folder} could not be confirmed stopped${cause === undefined ? "" : ` after: ${cause.message}`}.`,
remediationAction:
"Call start_build_capture again, which retries its stop first, or close the computer.",
cleanup: {
reason: "its stop was not confirmed",
resources: [`~/${run.folder}`],
},
...(cause === undefined ? {} : { cause }),
});
/**
* REA's capture of a build computer's app, run inside the computer by REA's
* controller: start it, take named checkpoints with their acknowledgements,
* stop it and draft the task between `seed` and `end`, then export the
* bundle with the agent's task and bring it back to this host. Every step
* can be asked again after a lost answer.
*/
export class DesktopBuildCapture {
readonly longRuns: BuildComputerLongRuns;
#count = 0;
#run: CaptureRun | undefined;
readonly #entry: string | undefined;
readonly #packageFile: { readonly url: string } | undefined;
/** The AppImage or tarball the request unpacked the app from, which the export downloads too. */
readonly #download: DownloadInstall | undefined;
/** What the request named beside the app, which the export installs too, so a package file's dependencies outlive an install by name. */
readonly #extraPackages: readonly string[];
/** The person's consents, in their words, which the export writes into consent.json. */
readonly #consents: BuildConsent[] = [];
/** `secrets` lists the secrets no exported bundle may hold, keeps the withheld files' bytes as secrets, and redacts a quote of the app's output before it is cut. */
constructor(
private readonly computer: CaptureComputer,
request: BuildRequest | undefined,
private readonly secrets: {
readonly all: (signal?: AbortSignal) => Promise<readonly KnownSecret[]>;
readonly keep: (handle: string, bytes: Buffer) => Promise<string>;
readonly redact: (text: string) => string;
readonly hasDeclaredSecret: boolean;
} = {
all: () => Promise.resolve([]),
keep: (handle) => Promise.resolve(handle),
redact: (text) => text,
hasDeclaredSecret: false,
},
) {
this.longRuns = new BuildComputerLongRuns(computer);
this.#entry = request?.desktop_entry;
this.#packageFile =
request?.install.kind === "package_file"
? { url: request.install.url }
: undefined;
this.#extraPackages = request === undefined ? [] : extraPackagesOf(request);
this.#download =
request === undefined ? undefined : downloadInstallOf(request);
}
async start(
input: CaptureInput,
signal: AbortSignal,
): Promise<
Result<
{
readonly desktop_entry: string;
readonly package_lists: number;
readonly package_lists_error: string | null;
},
AnalysisError
>
> {
const entry = this.#entry;
if (entry === undefined)
return err(
refused(
START,
"This computer was started from a bundle folder; REA captures the app of a computer started from a request, which installs REA inside it.",
"Start a computer from a request with start_build_computer and capture its app there.",
),
);
const previous = this.#run;
if (previous?.status === "running")
return err(
refused(
START,
"A capture is already running on this computer.",
"Stop it with stop_build_capture before starting another.",
),
);
if (
previous?.status === "unreleased" &&
!(await this.#release(previous, signal))
)
return err(unreleasedError(START, previous, undefined));
const runtime = await checkExportRuntime(this.computer, signal);
if (!runtime.ok) return runtime;
this.#count += 1;
const run: CaptureRun = {
folder: `${WORK}/captures/${String(this.#count)}`,
status: "running",
checkpoints: new Set(),
exports: 0,
};
this.#run = run;
const started = await this.#launch(run, entry, input, signal);
if (started.ok) return started;
// An answer naming no live capture means none runs; anything else may have left one running.
const released =
started.error.answer !== undefined &&
started.error.answer.timed_out !== true;
if (released) run.status = "released";
else if (!(await this.#release(run, signal)))
return err(unreleasedError(START, run, started.error.failure));
return err(started.error.failure);
}
/**
* The capture launched, then the caller cancelled before the start was
* reported. The next start stops it; until then it is not a second capture.
*/
abandon(): void {
const run = this.#run;
if (run?.status === "running" && run.stopped === undefined)
run.status = "unreleased";
}
async #launch(
run: CaptureRun,
entry: string,
input: CaptureInput,
signal: AbortSignal,
): Promise<
Result<
{
readonly desktop_entry: string;
readonly package_lists: number;
readonly package_lists_error: string | null;
},
{
readonly failure: AnalysisError;
readonly answer?: BuildControllerAnswer;
}
>
> {
let answer: BuildControllerAnswer;
try {
answer = await controller(
this.computer,
"start",
{
work: WORK,
capture: run.folder,
desktop_entry: entry,
arguments: [...(input.arguments ?? [])],
state_paths: [...(input.state_paths ?? [])],
...(this.#packageFile === undefined
? {}
: { package_file: BUILD_PACKAGE_FILE }),
timeout_s: 120,
apt_timeout_s: 600,
},
{ timeoutS: 720, signal },
);
} catch (cause: unknown) {
return err({
failure:
cause instanceof AnalysisError
? cause
: adapterError(START, errorMessage(cause), cause),
});
}
if (answer.refused !== undefined)
return err({
failure: refused(
START,
answer.refused,
"Name files or folders under the computer's home in state_paths, relative to it or absolute, with no link on the way leading out of it.",
),
answer,
});
const event =
answer.line === undefined ? undefined : captureProgressEvent(answer.line);
if (event?.kind !== "window_open")
return err({
failure: await endedCapture(
this.computer,
{ ...STARTING, folder: run.folder, redact: this.secrets.redact },
answer,
signal,
),
answer,
});
return ok({
desktop_entry: entry,
package_lists: answer.apt?.lists ?? 0,
package_lists_error: answer.apt?.error ?? null,
});
}
/** Stop a capture whose start failed; true once the computer confirms it ended or never launched. */
async #release(run: CaptureRun, signal: AbortSignal): Promise<boolean> {
try {
const answer = await controller(
this.computer,
"stop",
{ capture: run.folder, timeout_s: 120 },
{ timeoutS: 120, signal },
);
const confirmed =
answer.absent === true || typeof answer.exit_code === "number";
run.status = confirmed ? "released" : "unreleased";
return confirmed;
} catch {
run.status = "unreleased";
return false;
}
}
async mark(
name: string,
signal: AbortSignal,
): Promise<Result<CheckpointTaken, AnalysisError>> {
const run = this.#run;
if (run?.status !== "running") return err(refused(MARK, ...NOT_RUNNING));
if (run.checkpoints.has(name))
return err(
refused(
MARK,
`A checkpoint named ${name} was already taken.`,
"Each name is taken once per capture; use another name, or capture again to retake it.",
),
);
try {
// A checkpoint the capture already took, whose answer was lost, comes back from its log.
const answer = await controller(
this.computer,
"mark",
{ capture: run.folder, name, timeout_s: 600 },
{ timeoutS: 600, signal },
);
const event =
answer.line === undefined
? undefined
: captureProgressEvent(answer.line);
if (event?.kind === "checkpoint_refused")
return err(refused(MARK, event.reason, "Use another checkpoint name."));
if (event?.kind !== "checkpoint")
return err(
await endedCapture(
this.computer,
{
...marking(name),
folder: run.folder,
redact: this.secrets.redact,
},
answer,
signal,
),
);
run.checkpoints.add(name);
await keepScreenshot(this.computer, run.folder, name, signal);
const {
kind: _kind,
changed_files: changed,
more_changed_files: more,
...taken
} = event;
return ok({
...taken,
changed_files: changed ?? null,
more_changed_files: more ?? null,
});
} catch (cause: unknown) {
return err(
cause instanceof AnalysisError
? cause
: adapterError(MARK, errorMessage(cause), cause),
);
}
}
/** Stop the capture, read what it recorded and draft the task; asked again, it resumes or repeats the result. */
async stop(
signal: AbortSignal,
): Promise<Result<StoppedCapture, AnalysisError>> {
const run = this.#run;
if (run?.status === "unreleased")
return (await this.#release(run, signal))
? err(
refused(
STOP,
`The capture of the failed start in ~/${run.folder} is now stopped; no capture is running.`,
"Start one with start_build_capture.",
),
)
: err(unreleasedError(STOP, run, undefined));
if (run === undefined || run.status === "released")
return err(refused(STOP, ...NOT_RUNNING));
if (run.stopped !== undefined) {
if (this.secrets.hasDeclaredSecret)
run.stopped = { ...run.stopped, ...secretDraftRefusal };
return ok(run.stopped);
}
try {
if (run.outputBytes === undefined) {
const answer = await controller(
this.computer,
"stop",
{ capture: run.folder, timeout_s: 600 },
{ timeoutS: 600, signal },
);
if (answer.exit_code === undefined || answer.output_bytes === undefined)
return err(notAnswered(STOP, answer, this.secrets.redact));
run.status = "stopped";
run.outputBytes = answer.output_bytes;
}
const summary = await summarizeCapture(
this.computer,
{ folder: run.folder, outputBytes: run.outputBytes },
() => this.secrets.hasDeclaredSecret,
signal,
);
if (!summary.ok) {
run.status = "released";
return summary;
}
run.checkpoints = summary.value.checkpoints;
run.packageFile = summary.value.packageFile;
run.stopped = this.secrets.hasDeclaredSecret
? { ...summary.value.stopped, ...secretDraftRefusal }
: summary.value.stopped;
return ok(run.stopped);
} catch (cause: unknown) {
return err(
cause instanceof AnalysisError
? cause
: adapterError(STOP, errorMessage(cause), cause),
);
}
}
/** Record a consent the person gave, in their own words, relayed by the agent; the export ships every one. */
recordConsent({
url,
...consent
}: Omit<BuildConsent, "recorded_at" | "source">): {
readonly consent: Readonly<Record<string, JsonValue>>;
readonly consents: number;
} {
const recorded = {
...consent,
...(url === undefined ? {} : { url }),
recorded_at: new Date().toISOString(),
source: "relayed" as const,
};
this.#consents.push(recorded);
return { consent: recorded, consents: this.#consents.length };
}
/** Export the bundle with the agent's task inside the computer and write it to a folder on this host. */
async export(
input: BuildExportRequest,
signal: AbortSignal,
): Promise<Result<ExportedBuild, AnalysisError>> {
const run = this.#run;
const ends = input.tasks.map(
({ end_checkpoint: end }) => end ?? END_CHECKPOINT,
);
if (
run?.stopped === undefined ||
!run.checkpoints.has(SEED_CHECKPOINT) ||
!run.checkpoints.has(END_CHECKPOINT)
)
return err(
refused(
EXPORT,
`Export needs a stopped capture with ${SEED_CHECKPOINT} and ${END_CHECKPOINT} checkpoints; capture with start_build_capture, mark both and stop it.`,
"Capture with start_build_capture, mark seed and end, then call stop_build_capture.",
),
);
const untaken = ends.filter((end) => !run.checkpoints.has(end));
if (untaken.length > 0)
return err(
refused(
EXPORT,
`The capture took no checkpoint named ${untaken.join(" or ")}; its checkpoints are ${[...run.checkpoints].join(", ")}.`,
"Give each task the end checkpoint marked once its change was saved.",
),
);
const signIn = [SIGN_IN_START, SIGN_IN_END].filter((name) =>
run.checkpoints.has(name),
);
if (signIn.length === 1)
return err(
refused(
EXPORT,
`The capture has ${signIn.join("")} but not ${signIn[0] === SIGN_IN_START ? SIGN_IN_END : SIGN_IN_START}, so REA cannot tell which files the sign-in wrote.`,
`Capture again on a new build computer, marking ${SIGN_IN_START} before the sign-in and ${SIGN_IN_END} after it.`,
),
);
if (
input.seed_sign_in === true &&
!this.#consents.some(({ kind }) => kind === "seed_sign_in")
)
return err(
refused(
EXPORT,
"Seeding the withheld sign-in state needs the person's consent, and record_build_consent recorded none on this computer.",
"Ask the person whether the bundle may hold their signed-in state; if they say yes, record their words with record_build_consent, kind seed_sign_in, then export again. Otherwise export without seed_sign_in.",
),
);
run.exports += 1;
let secrets: readonly KnownSecret[];
try {
secrets = await this.secrets.all(signal);
} catch (cause: unknown) {
return err(
cause instanceof AnalysisError
? cause
: signal.aborted
? cancelledBy(EXPORT, signal)
: adapterError(EXPORT, errorMessage(cause), cause),
);
}
return exportBuild(
this.computer,
{
folder: run.folder,
attempt: run.exports,
...(this.#packageFile === undefined || run.packageFile !== true
? {}
: { packageUrl: this.#packageFile.url }),
extraPackages: this.#extraPackages,
...(this.#download === undefined
? {}
: { downloadInstall: this.#download }),
secrets,
keep: this.secrets.keep,
signIn: signIn.length === 2,
consents: [...this.#consents],
checkpoints: run.checkpoints,
},
input,
signal,
this.longRuns,
);
}
}