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; /** 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 => { 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> => { 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, "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; /** 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 keep: (handle: string, bytes: Buffer) => Promise; 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 { 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> { 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> { 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): { readonly consent: Readonly>; 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> { 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, ); } }