refactor(desktop): give the agentenv provider name an entry file and name the build computer's controlled routes as a port (#11600)

* refactor(desktop): give the agentenv provider name its own entry file and move ComputerRelease into src/domain

* refactor(desktop): name the build computer's controlled routes and controller answer as a port (#11604)
This commit is contained in:
morluto authored and GitHub committed 2026-11-16 08:51:27 +08:00
1 parent 2910fc0b13
commit 793ab582be
26 files changed
+146 -87

No files matched your search

+1 -1
View File
@@ -12,6 +12,6 @@
"model -> artifacts": 1
},
"entry": {
"application -> desktop": 41
"application -> desktop": 28
}
}
+1
View File
@@ -281,6 +281,7 @@ export const ENTRY_FILES = Object.freeze(
],
desktop: [
"AgentEnvComputer.ts",
"AgentEnvProviderIdentity.ts",
"BuildComputerEnvironment.ts",
"DconfDatabaseReader.ts",
"DesktopBuildDoctorFacts.ts",
@@ -18,7 +18,7 @@ import {
AnalysisInputError,
} from "../../domain/analysisErrorCore.js";
import { isLockFile } from "../../domain/desktop/appExportUnowned.js";
import { AGENTENV_PROVIDER } from "../../desktop/AgentEnvComputerHelper.js";
import { AGENTENV_PROVIDER } from "../../desktop/AgentEnvProviderIdentity.js";
import { PrivateRuntimeRoot } from "../../process/PrivateRuntimeRoot.js";
import {
type ArtifactResourceScope,
+11 -8
View File
@@ -26,13 +26,13 @@ import {
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/AgentEnvComputerHelper.js";
import { AGENTENV_PROVIDER } from "../../desktop/AgentEnvProviderIdentity.js";
import type { AgentEnvComputer } from "../../desktop/AgentEnvComputer.js";
import {
controller,
type Answer,
type ControlledComputer,
} from "../../desktop/BuildComputerController.js";
import { controller } from "../../desktop/BuildComputerController.js";
import type {
BuildControllerAnswer,
ControlledComputer,
} from "../../ports/BuildComputerControl.js";
import { BuildComputerLongRuns } from "../../desktop/BuildComputerLongRuns.js";
import {
endedCapture,
@@ -394,10 +394,13 @@ export class DesktopBuildCapture {
readonly package_lists: number;
readonly package_lists_error: string | null;
},
{ readonly failure: AnalysisError; readonly answer?: Answer }
{
readonly failure: AnalysisError;
readonly answer?: BuildControllerAnswer;
}
>
> {
let answer: Answer;
let answer: BuildControllerAnswer;
try {
answer = await controller(
this.computer,
@@ -6,11 +6,11 @@ import {
type DesktopApplicationCapture,
} from "../../domain/desktop/desktopCapture.js";
import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
import { AGENTENV_PROVIDER } from "../../desktop/AgentEnvComputerHelper.js";
import { AGENTENV_PROVIDER } from "../../desktop/AgentEnvProviderIdentity.js";
import type {
Answer,
BuildControllerAnswer,
ControlledComputer,
} from "../../desktop/BuildComputerController.js";
} from "../../ports/BuildComputerControl.js";
import {
adapterError,
readOutput,
@@ -75,7 +75,7 @@ const unredacted: Redact = (text) => text;
/** Why the capture is not answering, from what the controller saw instead of the event; its output stays out of the message. */
export const notAnswered = (
operation: string,
answer: Answer,
answer: BuildControllerAnswer,
redact: Redact = unredacted,
): AnalysisError => {
if (answer.error !== undefined) return adapterError(operation, answer.error);
@@ -151,7 +151,7 @@ const appExited = (
export const endedCapture = async (
computer: ControlledComputer,
step: CaptureStep & { readonly folder: string; readonly redact?: Redact },
answer: Answer,
answer: BuildControllerAnswer,
signal: AbortSignal,
): Promise<AnalysisError> => {
const { redact = unredacted } = step;
@@ -16,11 +16,9 @@ import {
guestFileAnswerCeiling,
guestFileAnswerRefusal,
} from "../../desktop/AgentEnvComputer.js";
import { AGENTENV_PROVIDER } from "../../desktop/AgentEnvComputerHelper.js";
import {
runRea as runControllerRea,
type ControlledComputer,
} from "../../desktop/BuildComputerController.js";
import { AGENTENV_PROVIDER } from "../../desktop/AgentEnvProviderIdentity.js";
import { runRea as runControllerRea } from "../../desktop/BuildComputerController.js";
import type { ControlledComputer } from "../../ports/BuildComputerControl.js";
/** The work folder REA keeps under the computer user's home; every capture leaves it out. */
export const WORK = ".rea-build";
@@ -35,11 +35,9 @@ import {
type ComputerStartTiming,
type DriverResult,
} from "../../desktop/AgentEnvComputer.js";
import {
AGENTENV_PROVIDER,
ComputerHelper,
type ComputerRelease,
} from "../../desktop/AgentEnvComputerHelper.js";
import { ComputerHelper } from "../../desktop/AgentEnvComputerHelper.js";
import { AGENTENV_PROVIDER } from "../../desktop/AgentEnvProviderIdentity.js";
import type { ComputerRelease } from "../../domain/desktop/computerRelease.js";
import {
resolveBuildComputerEnvironment,
type BuildComputerDefaults,
@@ -29,12 +29,12 @@ import {
} from "../../domain/desktop/buildSecrets.js";
import { jsonValueSchema, type JsonValue } from "../../domain/jsonValue.js";
import { err, ok, type Result } from "../../domain/result.js";
import { AGENTENV_PROVIDER } from "../../desktop/AgentEnvComputerHelper.js";
import { AGENTENV_PROVIDER } from "../../desktop/AgentEnvProviderIdentity.js";
import {
BUILD_REA_TIMEOUT_S,
fetchHomeFolder,
type ControlledComputer,
} from "../../desktop/BuildComputerController.js";
import type { ControlledComputer } from "../../ports/BuildComputerControl.js";
import {
adapterError,
ENDS,
@@ -25,7 +25,7 @@ import type {
AgentEnvComputer,
DriverResult,
} from "../../desktop/AgentEnvComputer.js";
import { AGENTENV_PROVIDER } from "../../desktop/AgentEnvComputerHelper.js";
import { AGENTENV_PROVIDER } from "../../desktop/AgentEnvProviderIdentity.js";
import {
listBuildSecretHandles,
readBuildSecretFile,
@@ -38,7 +38,7 @@ import {
import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
import { err, ok, type Result } from "../../domain/result.js";
import { safeParseUtf8Json } from "../../domain/safeJson.js";
import { AGENTENV_PROVIDER } from "../../desktop/AgentEnvComputerHelper.js";
import { AGENTENV_PROVIDER } from "../../desktop/AgentEnvProviderIdentity.js";
import {
runSolveHelper,
SolveCleanupError,
@@ -19,7 +19,7 @@ import {
type JsonValue,
} from "../../domain/jsonValue.js";
import { err, ok, type Result } from "../../domain/result.js";
import type { ControlledComputer } from "../../desktop/BuildComputerController.js";
import type { ControlledComputer } from "../../ports/BuildComputerControl.js";
import { readOutput, reportedFailure, runRea } from "./DesktopBuildCommands.js";
const STOP = "stop_build_capture";
@@ -34,7 +34,7 @@ import type {
AgentEnvComputer,
RecordingManifest,
} from "../../desktop/AgentEnvComputer.js";
import { AGENTENV_PROVIDER } from "../../desktop/AgentEnvComputerHelper.js";
import { AGENTENV_PROVIDER } from "../../desktop/AgentEnvProviderIdentity.js";
import {
silentProgressReporter,
type ProgressReporter,
@@ -32,7 +32,7 @@ import {
guestFileAnswerWorkingBytes,
type AgentEnvComputer,
} from "../../desktop/AgentEnvComputer.js";
import { AGENTENV_PROVIDER } from "../../desktop/AgentEnvComputerHelper.js";
import { AGENTENV_PROVIDER } from "../../desktop/AgentEnvProviderIdentity.js";
import { readHostFile } from "../../desktop/HostFileRead.js";
import { errorMessage } from "../../kernel/errorMessage.js";
@@ -17,7 +17,7 @@ import type {
AgentEnvComputer,
RecordingManifest,
} from "../../desktop/AgentEnvComputer.js";
import { AGENTENV_PROVIDER } from "../../desktop/AgentEnvComputerHelper.js";
import { AGENTENV_PROVIDER } from "../../desktop/AgentEnvProviderIdentity.js";
import {
LOGGED_ACTIONS,
LOGGED_BYTES,
@@ -19,10 +19,8 @@ import {
import { ProviderCleanupError } from "../../domain/providerCleanupError.js";
import { AnalysisCleanupRelease } from "../../domain/analysisCleanupRelease.js";
import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
import {
AGENTENV_PROVIDER,
type ComputerRelease,
} from "../../desktop/AgentEnvComputerHelper.js";
import { AGENTENV_PROVIDER } from "../../desktop/AgentEnvProviderIdentity.js";
import type { ComputerRelease } from "../../domain/desktop/computerRelease.js";
import {
AbortedWait,
waitForAbortable,
+8 -7
View File
@@ -10,10 +10,12 @@ import { Deadline } from "../domain/deadline.js";
import { jsonObjectSchema, type JsonValue } from "../domain/jsonValue.js";
import { StructuredContentMcpClient } from "../providers/StructuredContentMcpClient.js";
import { validateMcpHttpResponse } from "../providers/Utf8McpResponse.js";
import type { ComputerHelper } from "./AgentEnvComputerHelper.js";
import type { ComputerRelease } from "../domain/desktop/computerRelease.js";
import type {
ComputerHelper,
ComputerRelease,
} from "./AgentEnvComputerHelper.js";
ComputerCommandResult,
ControlledComputer,
} from "../ports/BuildComputerControl.js";
import {
DATA_OBJECTS,
dataGetSchema,
@@ -183,15 +185,14 @@ const rpcSchema = z.union([
z.object({ result: z.looseObject({}) }),
z.object({ error: z.looseObject({ message: z.string() }) }),
]);
const execSchema = z.object({
/** `computer-exec/v1`'s answer: a command's outcome, its output without the control token. */
const execSchema: z.ZodType<ComputerCommandResult> = z.object({
exit_code: z.int().nullable(),
stdout: z.string(),
stderr: z.string(),
truncated: z.boolean(),
timed_out: z.boolean(),
});
/** A command's outcome through `computer-exec/v1`, its output without the control token. */
export type ComputerCommandResult = z.infer<typeof execSchema>;
const cardSchema = z.looseObject({
children_environments: z
.array(z.looseObject({ name: z.string(), url: z.string().optional() }))
@@ -324,7 +325,7 @@ export class AppDataRefusal extends Error {
}
}
export class AgentEnvComputer {
export class AgentEnvComputer implements ControlledComputer {
readonly sandboxId: string;
readonly #baseUrl: string;
readonly #token: string | null;
+2 -13
View File
@@ -23,10 +23,11 @@ import {
type ArtifactResourceScope,
} from "../resources/index.js";
import { errorMessage } from "../kernel/errorMessage.js";
import type { ComputerRelease } from "../domain/desktop/computerRelease.js";
import { AGENTENV_PROVIDER } from "./AgentEnvProviderIdentity.js";
const execFileAsync = promisify(execFile);
export const AGENTENV_PROVIDER = "agentenv";
const HELPER = fileURLToPath(
new URL("../../bridge/agentenv/computer.py", import.meta.url),
);
@@ -48,18 +49,6 @@ const handshakeSchema = z.union([
/** The helper's one JSON line: where the kept computer is, or why there is none. */
export type Handshake = z.infer<typeof handshakeSchema>;
/** How a computer's teardown ended: confirmed by agentenv or by removing its containers, or not confirmed. */
export type ComputerRelease =
| {
readonly verified: true;
readonly teardown: "agentenv" | "container_label";
}
| {
readonly verified: false;
readonly reason: string;
readonly resources: readonly string[];
};
const unavailable = (operation: string, reason: string, cause?: unknown) =>
new AnalysisCapabilityUnavailableError(AGENTENV_PROVIDER, operation, reason, {
userMessage: reason,
+2
View File
@@ -0,0 +1,2 @@
/** Provider name the desktop build workflows report for the agentenv computer they drive. */
export const AGENTENV_PROVIDER = "agentenv";
+1 -1
View File
@@ -15,10 +15,10 @@ import {
} from "../process/ProviderProcess.js";
import { SolveSandboxRoot } from "./SolveSandboxRoot.js";
import {
AGENTENV_PROVIDER,
agentEnvInterpreter,
removeSandbox,
} from "./AgentEnvComputerHelper.js";
import { AGENTENV_PROVIDER } from "./AgentEnvProviderIdentity.js";
import { errorMessage } from "../kernel/errorMessage.js";
const HELPER = fileURLToPath(
+7 -11
View File
@@ -11,8 +11,11 @@ import {
guestFileAnswerBytes,
guestFileAnswerCeiling,
guestFileAnswerWorkingBytes,
type AgentEnvComputer,
} from "./AgentEnvComputer.js";
import type {
BuildControllerAnswer,
ControlledComputer,
} from "../ports/BuildComputerControl.js";
const CONTROLLER = fileURLToPath(
new URL("../../bridge/agentenv/capture.py", import.meta.url),
@@ -64,12 +67,6 @@ const controllerArgumentPieces = (text: string): readonly string[] => {
return pieces;
};
/** The computer routes REA's build controller uses, and the control token's redaction for what it reads. */
export type ControlledComputer = Pick<
AgentEnvComputer,
"exec" | "homeFiles" | "redacted"
>;
/**
* Run one command of REA's build controller in the computer, as its user and
* in its home, and return the JSON object it answers with. The controller's
@@ -145,8 +142,8 @@ export const runBuildController = async (
);
};
/** What REA's build controller answers a command with. The wire format stays here. */
export const answerSchema = z.looseObject({
/** What REA's build controller answers a command with. The wire format stays here; the port names its fields. */
export const answerSchema: z.ZodType<BuildControllerAnswer> = z.looseObject({
error: z.string().optional(),
/** Why the controller refused a request before acting on it, such as a state path outside the home. */
refused: z.string().optional(),
@@ -170,7 +167,6 @@ export const answerSchema = z.looseObject({
.looseObject({ lists: z.int().nonnegative(), error: z.string().optional() })
.optional(),
});
export type Answer = z.infer<typeof answerSchema>;
/** One controller command, its answer parsed. */
export const controller = async (
@@ -178,7 +174,7 @@ export const controller = async (
command: "start" | "mark" | "stop",
argumentsJson: Readonly<Record<string, JsonValue>>,
options: { readonly timeoutS: number; readonly signal: AbortSignal },
): Promise<Answer> =>
): Promise<BuildControllerAnswer> =>
answerSchema.parse(
await runBuildController(computer, command, argumentsJson, options),
);
+1 -1
View File
@@ -3,7 +3,7 @@ import { expect, it } from "vitest";
import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
import { ProviderCleanupError } from "../domain/providerCleanupError.js";
import { BuildComputerLongRuns } from "./BuildComputerLongRuns.js";
import type { ControlledComputer } from "./BuildComputerController.js";
import type { ControlledComputer } from "../ports/BuildComputerControl.js";
const response = (value: unknown) => ({
exit_code: 0,
+8 -11
View File
@@ -8,16 +8,13 @@ import {
import type { JsonValue } from "../domain/jsonValue.js";
import { ProviderAdapterError } from "../domain/providerAdapterError.js";
import { ProviderCleanupError } from "../domain/providerCleanupError.js";
import {
AGENTENV_PROVIDER,
type ComputerRelease,
} from "./AgentEnvComputerHelper.js";
import {
answerSchema,
runBuildController,
type Answer,
type ControlledComputer,
} from "./BuildComputerController.js";
import { AGENTENV_PROVIDER } from "./AgentEnvProviderIdentity.js";
import type { ComputerRelease } from "../domain/desktop/computerRelease.js";
import { answerSchema, runBuildController } from "./BuildComputerController.js";
import type {
BuildControllerAnswer,
ControlledComputer,
} from "../ports/BuildComputerControl.js";
import { errorMessage } from "../kernel/errorMessage.js";
const OPERATION = "export_build_environment";
@@ -285,7 +282,7 @@ export class BuildComputerLongRuns {
}
}
#receipt(job: Job, answer: Answer): JsonValue {
#receipt(job: Job, answer: BuildControllerAnswer): JsonValue {
return {
stdout: job.stdout,
...(typeof answer.stdout_bytes === "number"
+3 -5
View File
@@ -15,11 +15,9 @@ import {
OwnedCommandFailure,
runOwnedCommand,
} from "../process/OwnedCommand.js";
import {
AGENTENV_PROVIDER,
agentEnvInterpreter,
type ComputerRelease,
} from "./AgentEnvComputerHelper.js";
import { agentEnvInterpreter } from "./AgentEnvComputerHelper.js";
import { AGENTENV_PROVIDER } from "./AgentEnvProviderIdentity.js";
import type { ComputerRelease } from "../domain/desktop/computerRelease.js";
import { errorMessage } from "../kernel/errorMessage.js";
const JUDGE_TIMEOUT_MS = 10 * 60 * 1000;
+11
View File
@@ -0,0 +1,11 @@
/** How a computer's teardown ended: confirmed by agentenv or by removing its containers, or not confirmed. */
export type ComputerRelease =
| {
readonly verified: true;
readonly teardown: "agentenv" | "container_label";
}
| {
readonly verified: false;
readonly reason: string;
readonly resources: readonly string[];
};
+67
View File
@@ -0,0 +1,67 @@
import type { Buffer } from "node:buffer";
/**
* What the desktop build workflows ask of a running build computer, and what
* REA's build controller answers. The desktop provider implements and parses
* these; application workflows consume them without the provider's wire
* formats.
*/
/** A command's outcome in the computer, its output without the control token. */
export interface ComputerCommandResult {
readonly exit_code: number | null;
readonly stdout: string;
readonly stderr: string;
readonly truncated: boolean;
readonly timed_out: boolean;
}
/** The computer routes REA's build controller uses, and the control token's redaction for what it reads. */
export interface ControlledComputer {
/** Run `argv` in the computer, as its user and in its home. */
exec(
argv: readonly string[],
timeoutS: number,
signal?: AbortSignal,
requestId?: string,
): Promise<ComputerCommandResult>;
/** Read files under the computer's home, within `bytes` in total. */
homeFiles(
paths: readonly string[],
bytes: number,
signal?: AbortSignal,
): Promise<ReadonlyMap<string, Buffer>>;
/** `text` with the computer's control token redacted. */
redacted(text: string): string;
}
/** What REA's build controller answers a command with. Other fields it sends are kept but not named here. */
export interface BuildControllerAnswer {
readonly error?: string | undefined;
/** Why the controller refused a request before acting on it, such as a state path outside the home. */
readonly refused?: string | undefined;
readonly absent?: boolean | undefined;
readonly started?: boolean | undefined;
readonly pending?: boolean | undefined;
readonly finished?: boolean | undefined;
readonly cancelled?: boolean | undefined;
readonly line?: string | undefined;
readonly exited?: number | undefined;
readonly timed_out?: boolean | undefined;
readonly progress?: string | undefined;
readonly output?: string | undefined;
readonly exit_code?: number | null | undefined;
readonly output_bytes?: number | undefined;
readonly stdout_bytes?: number | undefined;
readonly stderr?: string | undefined;
/** False when the supervisor published a result but the process group is not confirmed gone. */
readonly settled?: boolean | undefined;
readonly apt?:
| {
readonly lists: number;
readonly error?: string | undefined;
readonly [key: string]: unknown;
}
| undefined;
readonly [key: string]: unknown;
}
@@ -7,7 +7,7 @@ import { expect, it } from "vitest";
import { AnalysisCancelledError } from "../../../src/domain/analysisErrorCore.js";
import { BuildComputerLongRuns } from "../../../src/desktop/BuildComputerLongRuns.js";
import type { ControlledComputer } from "../../../src/desktop/BuildComputerController.js";
import type { ControlledComputer } from "../../../src/ports/BuildComputerControl.js";
import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
const execute = promisify(execFile);