feat(process): add deterministic capture v3

This commit is contained in:
morluto
2026-07-13 17:01:09 +08:00
parent a504342d2b
commit 5a361a6725
29 changed files with 1616 additions and 243 deletions
+173
View File
@@ -0,0 +1,173 @@
import { createServer, type Server } from "node:http";
import { chmod, mkdir, writeFile } from "node:fs/promises";
import { join } from "node:path";
import type { ProcessScenario, ShimEvent } from "../domain/processCapture.js";
interface Invocation {
readonly command: string;
readonly arguments: readonly string[];
readonly working_directory: string;
}
/** Owned command-shim replay resources for one process scenario. */
export interface CommandShimReplay {
readonly binPath: string;
readonly url: string;
readonly events: readonly ShimEvent[];
readonly truncated: boolean;
close(): Promise<void>;
}
const RUNNER = `const command = process.argv[2];
const response = await fetch(process.env.REA_SHIM_LEDGER_URL, {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ command, arguments: process.argv.slice(3), working_directory: process.cwd() }),
});
if (!response.ok) process.exit(127);
const route = await response.json();
let elapsed = 0;
for (const output of route.outputs) {
const wait = Math.max(0, output.at_ms - elapsed);
if (wait > 0) await new Promise((resolve) => setTimeout(resolve, wait));
elapsed = output.at_ms;
(output.stream === "stdout" ? process.stdout : process.stderr).write(output.data);
}
if (route.termination.type === "signal") process.kill(process.pid, route.termination.signal);
else process.exit(route.termination.code);
`;
const shellQuote = (value: string): string =>
`'${value.replaceAll("'", `'\\''`)}'`;
/** Start bounded executable replay wrappers and their private invocation ledger. */
export const startCommandShimReplay = async (
scenario: ProcessScenario,
temporaryRoot: string,
started: number,
): Promise<CommandShimReplay> => {
const binPath = join(temporaryRoot, "shims");
await mkdir(binPath);
const runnerPath = join(temporaryRoot, "shim-runner.mjs");
await writeFile(runnerPath, RUNNER, { mode: 0o600, flag: "wx" });
for (const shim of scenario.command_shims) {
const path = join(binPath, shim.name);
const wrapper = `#!/bin/sh\nexec ${shellQuote(process.execPath)} ${shellQuote(runnerPath)} ${shellQuote(shim.name)} "$@"\n`;
await writeFile(path, wrapper, { mode: 0o700, flag: "wx" });
await chmod(path, 0o700);
}
const events: ShimEvent[] = [];
let truncated = false;
const calls = new Map<string, number>();
const server = createServer((request, response) => {
if (request.method !== "POST" || request.url !== "/invoke") {
response.writeHead(404).end();
return;
}
readInvocation(request)
.then((invocation) => {
const shim = scenario.command_shims.find(
({ name }) => name === invocation.command,
);
const routeIndex = shim?.routes.findIndex(
({ arguments: expected }) =>
JSON.stringify(expected) === JSON.stringify(invocation.arguments),
);
const key = `${invocation.command}:${String(routeIndex ?? -1)}`;
const used = calls.get(key) ?? 0;
const route =
shim !== undefined && routeIndex !== undefined && routeIndex >= 0
? shim.routes[routeIndex]
: undefined;
const outcome =
route === undefined
? "unmatched"
: used >= route.max_calls
? "exhausted"
: "matched";
if (events.length >= scenario.limits.protocol_events) truncated = true;
else
events.push({
sequence: events.length,
at_ms: Math.max(0, Date.now() - started),
command: invocation.command,
arguments: invocation.arguments,
working_directory: invocation.working_directory,
outcome,
});
if (outcome !== "matched" || route === undefined) {
response.writeHead(409).end();
return;
}
calls.set(key, used + 1);
response
.writeHead(200, { "content-type": "application/json" })
.end(JSON.stringify(route));
})
.catch(() => response.writeHead(400).end());
});
await listen(server);
const address = server.address();
if (address === null || typeof address === "string") {
await closeServer(server);
throw new Error("command shim ledger did not bind an IPv4 port");
}
return {
binPath,
url: `http://127.0.0.1:${String(address.port)}/invoke`,
events,
get truncated() {
return truncated;
},
close: () => closeServer(server),
};
};
const readInvocation = async (
request: import("node:http").IncomingMessage,
): Promise<Invocation> => {
const chunks: Buffer[] = [];
let bytes = 0;
for await (const chunk of request) {
const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
bytes += buffer.length;
if (bytes > 64 * 1024) throw new Error("shim invocation exceeds limit");
chunks.push(buffer);
}
const value: unknown = JSON.parse(Buffer.concat(chunks).toString("utf8"));
if (
typeof value !== "object" ||
value === null ||
!("command" in value) ||
typeof value.command !== "string" ||
!("arguments" in value) ||
!Array.isArray(value.arguments) ||
!value.arguments.every((item) => typeof item === "string") ||
!("working_directory" in value) ||
typeof value.working_directory !== "string"
)
throw new Error("invalid shim invocation");
return {
command: value.command,
arguments: value.arguments,
working_directory: value.working_directory,
};
};
const listen = (server: Server): Promise<void> =>
new Promise((resolveListen, rejectListen) => {
server.once("error", rejectListen);
server.listen(0, "127.0.0.1", () => {
server.off("error", rejectListen);
resolveListen();
});
});
const closeServer = (server: Server): Promise<void> =>
new Promise((resolveClose, rejectClose) =>
server.close((cause) =>
cause === undefined ? resolveClose() : rejectClose(cause),
),
);
+147
View File
@@ -0,0 +1,147 @@
import type {
FileState,
FilesystemCheckpoint,
ProcessScenario,
} from "../domain/processCapture.js";
import { snapshotRoots, type SnapshotResult } from "./FilesystemSnapshot.js";
/** Classify path-stable filesystem effects between two bounded states. */
export const classifyFilesystemEffects = (
before: readonly FileState[],
after: readonly FileState[],
): FilesystemCheckpoint["effects"] => {
const beforeByPath = new Map(before.map((file) => [file.path, file]));
const afterByPath = new Map(after.map((file) => [file.path, file]));
return [...new Set([...beforeByPath.keys(), ...afterByPath.keys()])]
.sort()
.map((path) => {
const beforeFile = beforeByPath.get(path) ?? null;
const afterFile = afterByPath.get(path) ?? null;
const status =
beforeFile === null
? "created"
: afterFile === null
? "deleted"
: JSON.stringify(beforeFile) === JSON.stringify(afterFile)
? "unchanged"
: "modified";
return { path, status, before: beforeFile, after: afterFile } as const;
});
};
/** Coordinates named lifecycle filesystem observations without overlapping scans. */
export class ProcessCheckpoints {
readonly #captures: FilesystemCheckpoint[] = [];
readonly #captured = new Set<string>();
readonly #terminalCounts = new Map<string, number>();
readonly #terminalTails = new Map<string, string>();
readonly #timers = new Set<NodeJS.Timeout>();
#pending: Promise<void> = Promise.resolve();
constructor(
private readonly scenario: ProcessScenario,
private readonly started: number,
before: SnapshotResult,
private readonly signal: AbortSignal | undefined,
) {
this.#captures.push({
name: "before",
at_ms: 0,
files: before.files,
effects: [],
truncated: before.truncated,
});
this.#captured.add("before");
for (const checkpoint of scenario.checkpoints) {
if (checkpoint.trigger.type !== "time") continue;
const timer = setTimeout(
() => this.capture(checkpoint.name),
checkpoint.trigger.at_ms,
);
this.#timers.add(timer);
}
}
/** Observe normalized terminal text and fire matching literal checkpoints once. */
observeTerminal(data: string): void {
for (const checkpoint of this.scenario.checkpoints) {
const trigger = checkpoint.trigger;
if (
trigger.type !== "terminal_literal" ||
this.#captured.has(checkpoint.name)
)
continue;
const combined = `${this.#terminalTails.get(checkpoint.name) ?? ""}${data}`;
const count =
(this.#terminalCounts.get(checkpoint.name) ?? 0) +
countOccurrences(combined, trigger.value);
this.#terminalCounts.set(checkpoint.name, count);
this.#terminalTails.set(
checkpoint.name,
trigger.value.length === 1
? ""
: combined.slice(-(trigger.value.length - 1)),
);
if (count >= trigger.occurrence) this.capture(checkpoint.name);
}
}
/** Capture every checkpoint assigned to the specified lifecycle trigger. */
trigger(type: "root_exit" | "settled"): void {
for (const checkpoint of this.scenario.checkpoints)
if (checkpoint.trigger.type === type) this.capture(checkpoint.name);
}
/** Queue one idempotent named snapshot. */
capture(name: string): void {
if (this.#captured.has(name)) return;
this.#captured.add(name);
this.#pending = this.#pending.then(async () => {
const snapshot = await snapshotRoots(this.scenario, this.signal);
const previous = this.#captures.at(-1)?.files ?? [];
this.#captures.push({
name,
at_ms: Math.max(0, Date.now() - this.started),
files: snapshot.files,
effects: classifyFilesystemEffects(previous, snapshot.files),
truncated: snapshot.truncated,
});
});
}
/** Finish pending snapshots and return them in observation order. */
async finish(
after: SnapshotResult,
): Promise<readonly FilesystemCheckpoint[]> {
for (const timer of this.#timers) clearTimeout(timer);
await this.#pending;
const previous = this.#captures.at(-1)?.files ?? [];
this.#captures.push({
name: "after_settlement",
at_ms: Math.max(0, Date.now() - this.started),
files: after.files,
effects: classifyFilesystemEffects(previous, after.files),
truncated: after.truncated,
});
return this.#captures;
}
/** Cancel scheduled captures and await any snapshot already in progress. */
async dispose(): Promise<void> {
for (const timer of this.#timers) clearTimeout(timer);
this.#timers.clear();
await this.#pending;
}
}
const countOccurrences = (text: string, value: string): number => {
let count = 0;
let offset = 0;
while (offset <= text.length - value.length) {
const found = text.indexOf(value, offset);
if (found < 0) break;
count += 1;
offset = found + value.length;
}
return count;
};
+77
View File
@@ -0,0 +1,77 @@
import { readFile } from "node:fs/promises";
import { parseConfig } from "../config.js";
import { createEvidence, parseEvidence } from "../domain/evidence.js";
import { jsonValueSchema } from "../domain/jsonValue.js";
import {
compareProcessCaptures,
parseProcessScenario,
processCaptureSchema,
} from "../domain/processCapture.js";
import { captureProcessScenario } from "./ProcessHarness.js";
import {
PROCESS_PROVIDER,
createProcessCaptureEvidence,
} from "./ProcessEvidence.js";
const MAX_INPUT_BYTES = 64 * 1024 * 1024;
/** Capture one JSON scenario through the same policy and evidence contract as MCP. */
export const captureProcessScenarioFile = async (path: string) => {
const scenario = parseProcessScenario(await readJson(path));
const config = parseConfig(process.env);
if (!config.ok) throw config.error;
const captured = await captureProcessScenario(
scenario,
config.value.processExecutionPolicy,
);
if (!captured.ok) throw captured.error;
return createProcessCaptureEvidence(scenario, captured.value);
};
/** Compare two capture Evidence files and emit derived comparison Evidence. */
export const compareProcessEvidenceFiles = async (
leftPath: string,
rightPath: string,
) => {
const left = parseCaptureEvidence(await readJson(leftPath));
const right = parseCaptureEvidence(await readJson(rightPath));
const comparison = compareProcessCaptures(left.capture, right.capture);
return createEvidence(undefined, PROCESS_PROVIDER, {
predicateType: "rea.process-comparison/v2",
operation: "compare_process_captures",
parameters: {
left_evidence_id: left.id,
right_evidence_id: right.id,
left_normalization: left.capture.normalization,
right_normalization: right.capture.normalization,
},
result: jsonValueSchema.parse(comparison),
confidence: "derived",
authority: "analyst-inference",
limitations: comparison.limitations,
evidenceLinks: [left.id, right.id],
});
};
const parseCaptureEvidence = (input: unknown) => {
const evidence = parseEvidence(input);
if (
evidence.operation !== "capture_process_scenario" ||
evidence.predicate_type !== "rea.process-capture/v3" ||
evidence.provider.id !== PROCESS_PROVIDER.id ||
evidence.provider.version !== PROCESS_PROVIDER.version
)
throw new TypeError("Expected REA Process Capture v3 Evidence");
return {
id: evidence.evidence_id,
capture: processCaptureSchema.parse(evidence.normalized_result),
};
};
const readJson = async (path: string): Promise<unknown> => {
const bytes = await readFile(path);
if (bytes.length > MAX_INPUT_BYTES)
throw new TypeError("Process JSON input exceeds byte limit");
return JSON.parse(bytes.toString("utf8")) as unknown;
};
+48
View File
@@ -0,0 +1,48 @@
import type { JsonValue } from "../domain/jsonValue.js";
import { createEvidence } from "../domain/evidence.js";
import { jsonValueSchema } from "../domain/jsonValue.js";
import type {
ProcessCapture,
ProcessScenario,
} from "../domain/processCapture.js";
/** Provider identity for controlled Process Capture v3 evidence. */
export const PROCESS_PROVIDER = {
id: "rea-process",
name: "REA deterministic process harness",
version: "2",
} as const;
/** Project one process scenario into secret-free Evidence parameters. */
const processEvidenceParameters = (
scenario: ProcessScenario,
): Readonly<Record<string, JsonValue>> => ({
executable_name: scenario.executable.split("/").at(-1) ?? scenario.executable,
argument_count: scenario.arguments.length,
event_count: scenario.events.length,
filesystem_root_count: scenario.filesystem_roots.length,
checkpoint_count: scenario.checkpoints.length,
command_shim_count: scenario.command_shims.length,
normalization: scenario.normalization,
});
/** Create one canonical observed Process Capture v3 Evidence record. */
export const createProcessCaptureEvidence = (
scenario: ProcessScenario,
capture: ProcessCapture,
) =>
createEvidence(undefined, PROCESS_PROVIDER, {
predicateType: "rea.process-capture/v3",
operation: "capture_process_scenario",
parameters: processEvidenceParameters(scenario),
result: jsonValueSchema.parse(capture),
confidence: "observed",
authority: "controlled-replay",
environment: {
id: `${process.platform}-${process.arch}`,
platform: process.platform,
architecture: process.arch,
isolation: "process",
},
limitations: capture.limitations,
});
+229 -74
View File
@@ -1,10 +1,11 @@
import { randomUUID } from "node:crypto";
import { mkdtemp, realpath, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { dirname, join } from "node:path";
import { spawn, type IPty } from "node-pty";
import type {
FileState,
FilesystemCheckpoint,
InteractionEvent,
ProcessCapture,
ProcessExecutionPolicy,
ProcessSample,
@@ -18,6 +19,15 @@ import { startLoopbackReplay, type LoopbackReplay } from "./LoopbackReplay.js";
import { cleanupOwnedProcessGroup } from "./ProcessOwnership.js";
import { startProcessSampler } from "./ProcessSampling.js";
import { snapshotRoots, type SnapshotResult } from "./FilesystemSnapshot.js";
import {
classifyFilesystemEffects,
ProcessCheckpoints,
} from "./ProcessCheckpoints.js";
import { TerminalRenderer } from "./TerminalRenderer.js";
import {
startCommandShimReplay,
type CommandShimReplay,
} from "./CommandShimReplay.js";
import {
normalizeProcessSamples,
normalizeProcessText,
@@ -104,12 +114,18 @@ export const probeProcessCaptureCapability =
}
};
interface EnvironmentOptions {
readonly scenario: ProcessScenario;
readonly home: string;
readonly replay: LoopbackReplay;
readonly shimReplay: CommandShimReplay;
readonly runId: string;
}
const makeEnvironment = (
scenario: ProcessScenario,
home: string,
replay: LoopbackReplay,
runId: string,
options: EnvironmentOptions,
): Record<string, string> => {
const { scenario, home, replay, shimReplay, runId } = options;
const environment: Record<string, string> = {
...scenario.environment,
HOME: home,
@@ -122,36 +138,75 @@ const makeEnvironment = (
}
environment.REA_REPLAY_HTTP_URL = replay.httpUrl;
environment.REA_REPLAY_WEBSOCKET_URL = replay.websocketUrl;
environment.REA_SHIM_LEDGER_URL = shimReplay.url;
environment.PATH = [shimReplay.binPath, environment.PATH ?? ""]
.filter((part) => part.length > 0)
.join(":");
return environment;
};
const scheduleScenarioEvents = (
scenario: ProcessScenario,
getTerminal: () => IPty | undefined,
timers: Set<NodeJS.Timeout>,
): void => {
for (const event of scenario.events) {
interface ScenarioEventOptions {
readonly scenario: ProcessScenario;
readonly getTerminal: () => IPty | undefined;
readonly timers: Set<NodeJS.Timeout>;
readonly interactions: InteractionEvent[];
readonly renderer: TerminalRenderer;
readonly started: number;
readonly dispatchedEventIndexes: Set<number>;
}
const scheduleScenarioEvents = (options: ScenarioEventOptions): void => {
const { scenario, getTerminal, timers, interactions, renderer, started } =
options;
for (const [eventIndex, event] of scenario.events.entries()) {
const timer = setTimeout(() => {
options.dispatchedEventIndexes.add(eventIndex);
const terminal = getTerminal();
if (event.type === "input") terminal?.write(event.data);
else if (event.type === "resize")
terminal?.resize(event.columns, event.rows);
else terminal?.kill(event.signal);
const dispatchedAt = Math.max(0, Date.now() - started);
let outcome: InteractionEvent["outcome"] = "dispatched";
if (terminal === undefined) outcome = "target_exited";
else {
try {
if (event.type === "input") terminal.write(event.data);
else if (event.type === "resize") {
terminal.resize(event.columns, event.rows);
renderer.resize(event.columns, event.rows, dispatchedAt);
} else terminal.kill(event.signal);
} catch {
outcome = "failed";
}
}
interactions.push({
sequence: interactions.length,
scheduled_at_ms: event.at_ms,
dispatched_at_ms: dispatchedAt,
type: event.type,
data:
event.type === "input"
? event.sensitive
? `<redacted-input:${String(Buffer.byteLength(event.data))}-bytes>`
: normalizeProcessText(
event.data,
scenario,
"<no-temporary-root>",
-1,
)
: event.type === "resize"
? `${String(event.columns)}x${String(event.rows)}`
: event.signal,
outcome,
});
}, event.at_ms);
timers.add(timer);
}
};
const startScenarioEvents = (
scenario: ProcessScenario,
getTerminal: () => IPty | undefined,
timers: Set<NodeJS.Timeout>,
): (() => void) => {
let started = false;
const startScenarioEvents = (options: ScenarioEventOptions): (() => void) => {
let eventsStarted = false;
return () => {
if (started) return;
started = true;
scheduleScenarioEvents(scenario, getTerminal, timers);
if (eventsStarted) return;
eventsStarted = true;
scheduleScenarioEvents(options);
};
};
@@ -167,6 +222,8 @@ interface TerminalExitOptions {
readonly lastOutput: () => number;
readonly signal: AbortSignal | undefined;
readonly timers: Set<NodeJS.Timeout>;
readonly interactions: InteractionEvent[];
readonly dispatchedEventIndexes: ReadonlySet<number>;
}
interface CaptureResultOptions {
@@ -184,36 +241,18 @@ interface CaptureResultOptions {
readonly scenario: ProcessScenario;
readonly rootPid: number;
readonly samplingPartial: boolean;
readonly renderedFrames: ProcessCapture["rendered_frames"];
readonly interactions: readonly InteractionEvent[];
readonly checkpoints: readonly FilesystemCheckpoint[];
readonly shimEvents: ProcessCapture["shim_events"];
}
const classifyFilesystemEffects = (
before: readonly FileState[],
after: readonly FileState[],
): ProcessCapture["filesystem_effects"] => {
const beforeByPath = new Map(before.map((file) => [file.path, file]));
const afterByPath = new Map(after.map((file) => [file.path, file]));
const paths = [
...new Set([...beforeByPath.keys(), ...afterByPath.keys()]),
].sort();
return paths.map((path) => {
const beforeFile = beforeByPath.get(path) ?? null;
const afterFile = afterByPath.get(path) ?? null;
const status =
beforeFile === null
? "created"
: afterFile === null
? "deleted"
: JSON.stringify(beforeFile) === JSON.stringify(afterFile)
? "unchanged"
: "modified";
return { path, status, before: beforeFile, after: afterFile };
});
};
const buildCaptureResult = (options: CaptureResultOptions): ProcessCapture => ({
schema_version: 2,
schema_version: 3,
normalization: options.scenario.normalization,
frames: options.frames,
rendered_frames: options.renderedFrames,
interaction_events: options.interactions,
exit: {
code: options.exit.exitCode < 0 ? null : options.exit.exitCode,
signal: options.exit.signal ?? null,
@@ -224,6 +263,8 @@ const buildCaptureResult = (options: CaptureResultOptions): ProcessCapture => ({
options.scenario,
options.rootPid,
),
filesystem_checkpoints: options.checkpoints,
shim_events: options.shimEvents,
protocol_events: redactProtocolEvents(
options.replay.events,
options.scenario,
@@ -266,6 +307,8 @@ const awaitTerminalExit = async ({
lastOutput,
signal,
timers,
interactions,
dispatchedEventIndexes,
}: TerminalExitOptions): Promise<{
exitCode: number;
signal?: number;
@@ -274,6 +317,22 @@ const awaitTerminalExit = async ({
new Promise((resolveExit) => {
let reason: "exited" | "timeout" | "idle_timeout" | "cancelled" = "exited";
terminal.onExit((exit) => {
for (const [eventIndex, event] of scenario.events.entries()) {
if (dispatchedEventIndexes.has(eventIndex)) continue;
interactions.push({
sequence: interactions.length,
scheduled_at_ms: event.at_ms,
dispatched_at_ms: Math.max(0, Date.now() - started),
type: event.type,
data:
event.type === "input"
? "<not-dispatched>"
: event.type === "resize"
? `${String(event.columns)}x${String(event.rows)}`
: event.signal,
outcome: "target_exited",
});
}
for (const timer of timers) {
clearTimeout(timer);
clearInterval(timer);
@@ -300,8 +359,12 @@ const releaseProcessResources = async (options: {
readonly timers: ReadonlySet<NodeJS.Timeout>;
readonly replay: LoopbackReplay | undefined;
readonly terminal: IPty | undefined;
readonly renderer: TerminalRenderer | undefined;
readonly shimReplay: CommandShimReplay | undefined;
readonly checkpoints: ProcessCheckpoints | undefined;
readonly runId: string;
readonly temporaryRoot: string;
readonly sampledProcessGroupIds: readonly number[];
}): Promise<string | undefined> => {
for (const timer of options.timers) clearTimeout(timer);
let failure: string | undefined;
@@ -310,13 +373,34 @@ const releaseProcessResources = async (options: {
} catch {
failure = "loopback replay cleanup failed";
}
try {
await options.shimReplay?.close();
} catch {
failure ??= "command shim replay cleanup failed";
}
try {
await options.renderer?.dispose();
} catch {
failure ??= "terminal renderer cleanup failed";
}
try {
await options.checkpoints?.dispose();
} catch {
failure ??= "filesystem checkpoint cleanup failed";
}
if (options.terminal !== undefined && process.platform !== "win32") {
const cleaned = await cleanupOwnedProcessGroup({
runId: options.runId,
leaderPid: options.terminal.pid,
processGroupId: options.terminal.pid,
});
if (!cleaned.cleaned) failure ??= cleaned.reason;
const processGroupIds = new Set([
options.terminal.pid,
...options.sampledProcessGroupIds,
]);
for (const processGroupId of processGroupIds) {
const cleaned = await cleanupOwnedProcessGroup({
runId: options.runId,
leaderPid: processGroupId,
processGroupId,
});
if (!cleaned.cleaned) failure ??= cleaned.reason;
}
}
try {
await rm(options.temporaryRoot, { recursive: true, force: true });
@@ -334,6 +418,8 @@ const captureTerminalFrames = (options: {
readonly temporaryRoot: string;
readonly onOutput: () => void;
readonly onFirstOutput: () => void;
readonly renderer: TerminalRenderer;
readonly checkpoints: ProcessCheckpoints;
}): (() => boolean) => {
let outputBytes = 0;
let truncated = false;
@@ -349,20 +435,24 @@ const captureTerminalFrames = (options: {
return;
}
outputBytes += bytes;
const atMs =
Math.floor(
(Date.now() - options.started) /
options.scenario.normalization.time_bucket_ms,
) * options.scenario.normalization.time_bucket_ms;
const normalized = normalizeProcessText(
data,
options.scenario,
options.temporaryRoot,
options.terminal.pid,
);
options.frames.push({
sequence: options.frames.length,
at_ms:
Math.floor(
(Date.now() - options.started) /
options.scenario.normalization.time_bucket_ms,
) * options.scenario.normalization.time_bucket_ms,
data: normalizeProcessText(
data,
options.scenario,
options.temporaryRoot,
options.terminal.pid,
),
at_ms: atMs,
data: normalized,
});
options.renderer.write(data, atMs);
options.checkpoints.observeTerminal(normalized);
});
return () => truncated;
};
@@ -422,6 +512,9 @@ const runProcessScenario = async (
let truncated = before.truncated;
let terminal: IPty | undefined;
let replay: LoopbackReplay | undefined;
let renderer: TerminalRenderer | undefined;
let checkpoints: ProcessCheckpoints | undefined;
let shimReplay: CommandShimReplay | undefined;
let started = 0;
let lastOutput = 0;
const timers = new Set<NodeJS.Timeout>();
@@ -430,19 +523,45 @@ const runProcessScenario = async (
let framesTruncated = (): boolean => false;
let stopSampler = async () => ({ partial: false });
let samplingPartial = false;
const interactions: InteractionEvent[] = [];
const dispatchedEventIndexes = new Set<number>();
try {
replay = await startLoopbackReplay(scenario);
started = Date.now();
lastOutput = started;
renderer = new TerminalRenderer({
columns: scenario.terminal.columns,
rows: scenario.terminal.rows,
scrollback: scenario.terminal.scrollback,
maxFrames: scenario.limits.frames,
maxBytes: scenario.limits.output_bytes,
normalize: (value) =>
normalizeProcessText(
value,
scenario,
temporaryRoot,
terminal?.pid ?? -1,
),
});
checkpoints = new ProcessCheckpoints(scenario, started, before, signal);
shimReplay = await startCommandShimReplay(scenario, temporaryRoot, started);
terminal = spawn(scenario.executable, [...scenario.arguments], {
cwd: scenario.working_directory,
env: makeEnvironment(scenario, home, replay, runId),
cols: 80,
rows: 24,
env: makeEnvironment({ scenario, home, replay, shimReplay, runId }),
cols: scenario.terminal.columns,
rows: scenario.terminal.rows,
name: "xterm-256color",
});
const startEvents = startScenarioEvents(scenario, () => terminal, timers);
const startEvents = startScenarioEvents({
scenario,
getTerminal: () => terminal,
timers,
interactions,
renderer,
started,
dispatchedEventIndexes,
});
if (!eventsRequireReadiness(scenario)) startEvents();
framesTruncated = captureTerminalFrames({
terminal,
@@ -452,6 +571,8 @@ const runProcessScenario = async (
temporaryRoot,
onOutput: () => (lastOutput = Date.now()),
onFirstOutput: startEvents,
renderer,
checkpoints,
});
stopSampler = startProcessSampler(
terminal.pid,
@@ -466,22 +587,30 @@ const runProcessScenario = async (
lastOutput: () => lastOutput,
signal,
timers,
interactions,
dispatchedEventIndexes,
});
const exitReason = exit.reason;
samplingPartial = (await stopSampler()).partial;
checkpoints.trigger("root_exit");
if (exitReason === "cancelled")
throw new ProcessCaptureError("process capture was cancelled");
await new Promise((resolveSettle) =>
setTimeout(resolveSettle, scenario.settle_ms),
);
checkpoints.trigger("settled");
samplingPartial = (await stopSampler()).partial;
assertNotCancelled(signal);
const after = await snapshotRoots(scenario, signal);
const renderedFrames = await renderer.frames();
const filesystemCheckpoints = await checkpoints.finish(after);
truncated ||=
after.truncated ||
replay.truncated ||
shimReplay.truncated ||
framesTruncated() ||
samples.length >= scenario.limits.processes;
truncated ||= samplingPartial;
filesystemCheckpoints.some(({ truncated: partial }) => partial) ||
samplingPartial;
truncated ||= renderer.truncated();
capture = buildCaptureResult({
frames,
exit: { ...exit, reason: exitReason },
@@ -493,6 +622,26 @@ const runProcessScenario = async (
scenario,
rootPid: terminal.pid,
samplingPartial,
renderedFrames,
interactions,
checkpoints: filesystemCheckpoints,
shimEvents: shimReplay.events.map((event) => ({
...event,
arguments: event.arguments.map((argument) =>
normalizeProcessText(
argument,
scenario,
temporaryRoot,
terminal?.pid ?? -1,
),
),
working_directory: normalizeProcessText(
event.working_directory,
scenario,
temporaryRoot,
terminal?.pid ?? -1,
),
})),
});
} catch (cause: unknown) {
terminal?.kill("SIGKILL");
@@ -503,8 +652,14 @@ const runProcessScenario = async (
timers,
replay,
terminal,
renderer,
shimReplay,
checkpoints,
runId,
temporaryRoot,
sampledProcessGroupIds: samples.flatMap(({ process_group_id }) =>
process_group_id === null ? [] : [process_group_id],
),
});
return resolveProcessResult(capture, executionFailure, cleanupFailure);
};
+12 -1
View File
@@ -46,7 +46,12 @@ export const normalizeProcessSamples = (
): readonly ProcessSample[] => {
const identifiers = [
rootPid,
...samples.flatMap((sample) => [sample.pid, sample.parent_pid]),
...samples.flatMap((sample) => [
sample.pid,
sample.parent_pid,
sample.process_group_id ?? 0,
sample.session_id ?? 0,
]),
];
const mapping = new Map<number, number>();
for (const identifier of identifiers)
@@ -58,6 +63,12 @@ export const normalizeProcessSamples = (
scenario.normalization.time_bucket_ms,
pid: mapping.get(sample.pid) ?? 1,
parent_pid: mapping.get(sample.parent_pid) ?? 0,
process_group_id:
sample.process_group_id === null
? null
: (mapping.get(sample.process_group_id) ?? 0),
session_id:
sample.session_id === null ? null : (mapping.get(sample.session_id) ?? 0),
command: normalizeProcessText(
sample.command,
scenario,
+40 -22
View File
@@ -9,6 +9,8 @@ const PROC_READ_CONCURRENCY = 64;
interface ProcessRow {
readonly pid: number;
readonly parent_pid: number;
readonly process_group_id: number | null;
readonly session_id: number | null;
readonly command: string;
readonly startTime: string | undefined;
}
@@ -21,7 +23,6 @@ interface SampleProcessContext {
readonly rootPid: number;
readonly elapsedMs: number;
readonly limit: number;
readonly sampledPids: Set<number>;
readonly identities: Map<number, string>;
readonly signal: AbortSignal;
}
@@ -51,12 +52,18 @@ const parseProcStat = (
.split(/\s+/);
const pid = Number(identifier);
const parentPid = Number(fields[1]);
const processGroupId = Number(fields[2]);
const sessionId = Number(fields[3]);
const startTime = fields[19];
if (
!Number.isSafeInteger(pid) ||
pid <= 0 ||
!Number.isSafeInteger(parentPid) ||
parentPid < 0 ||
!Number.isSafeInteger(processGroupId) ||
processGroupId <= 0 ||
!Number.isSafeInteger(sessionId) ||
sessionId <= 0 ||
startTime === undefined ||
!/^\d+$/.test(startTime)
)
@@ -64,6 +71,8 @@ const parseProcStat = (
return {
pid,
parent_pid: parentPid,
process_group_id: processGroupId,
session_id: sessionId,
command: "",
startTime,
};
@@ -153,6 +162,8 @@ const inspectProcess = async (
return {
pid: before.pid,
parent_pid: before.parent_pid,
process_group_id: before.process_group_id,
session_id: before.session_id,
startTime: before.startTime,
command,
children: children ?? [],
@@ -162,7 +173,7 @@ const inspectProcess = async (
const sampleLinux = async (
context: SampleProcessContext,
): Promise<readonly ProcessRow[]> => {
const { rootPid, limit, signal, sampledPids, identities } = context;
const { rootPid, limit, signal, identities } = context;
if (limit <= 0) return [];
const rootStat = await readProcessStat(rootPid, signal);
@@ -192,10 +203,8 @@ const sampleLinux = async (
for (const node of batchResults) {
if (node === undefined) continue;
if (!sampledPids.has(node.pid)) {
if (rows.length >= limit) break;
rows.push(node);
}
if (rows.length >= limit) break;
rows.push(node);
if (rows.length >= limit) break;
for (const child of node.children) {
@@ -217,17 +226,19 @@ const readPsRows = async (
): Promise<readonly ProcessRow[]> => {
const { stdout } = await execFileAsync(
"ps",
["-axo", "pid=,ppid=,command="],
["-axo", "pid=,ppid=,pgid=,sess=,command="],
{ signal },
);
return stdout
.split("\n")
.map((line) => /\s*(\d+)\s+(\d+)\s+(.*)/u.exec(line))
.map((line) => /\s*(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(.*)/u.exec(line))
.filter((match): match is RegExpExecArray => match !== null)
.map((match) => ({
pid: Number(match[1]),
parent_pid: Number(match[2]),
command: match[3] ?? "",
process_group_id: Number(match[3]),
session_id: Number(match[4]),
command: match[5] ?? "",
startTime: undefined,
}))
.filter(
@@ -243,7 +254,7 @@ const readPsRows = async (
const samplePs = async (
context: SampleProcessContext,
): Promise<readonly ProcessRow[]> => {
const { rootPid, limit, signal, sampledPids } = context;
const { rootPid, limit, signal } = context;
if (limit <= 0) return [];
const rows = await readPsRows(signal);
@@ -268,9 +279,7 @@ const samplePs = async (
visited.add(pid);
const row = rowByPid.get(pid);
if (row !== undefined && !sampledPids.has(row.pid)) {
result.push(row);
}
if (row !== undefined) result.push(row);
if (result.length >= limit) break;
for (const child of childrenByParent.get(pid) ?? []) {
@@ -291,10 +300,9 @@ const sampleProcesses = async (
? await sampleLinux(context)
: await samplePs(context);
const { elapsedMs, sampledPids, identities } = context;
const { elapsedMs, identities } = context;
const samples: ProcessSample[] = [];
for (const row of rows) {
if (sampledPids.has(row.pid)) continue;
if (row.startTime !== undefined) {
const existing = identities.get(row.pid);
if (existing !== undefined && existing !== row.startTime) continue;
@@ -305,6 +313,8 @@ const sampleProcesses = async (
pid: row.pid,
parent_pid: row.parent_pid,
command: row.command,
process_group_id: row.process_group_id,
session_id: row.session_id,
});
}
return samples;
@@ -318,30 +328,38 @@ export const startProcessSampler = (
samples: ProcessSample[],
): (() => Promise<{ readonly partial: boolean }>) => {
const identities = new Map<number, string>();
const sampledPids = new Set<number>(samples.map(({ pid }) => pid));
const lastObservations = new Map<number, string>();
let pending: Promise<void> | undefined;
let stopped = false;
let abortCurrent: (() => void) | undefined;
let partial = false;
const sample = (): void => {
if (stopped || pending !== undefined || sampledPids.size >= limit) return;
if (stopped || pending !== undefined) return;
const controller = new AbortController();
abortCurrent = () => controller.abort();
pending = sampleProcesses({
rootPid,
elapsedMs: Date.now() - started,
limit: limit - sampledPids.size,
sampledPids,
limit: limit + 1,
identities,
signal: controller.signal,
})
.then((values) => {
for (const value of values) {
if (sampledPids.size >= limit) break;
if (sampledPids.has(value.pid)) continue;
sampledPids.add(value.pid);
const observation = JSON.stringify({
parent_pid: value.parent_pid,
command: value.command,
process_group_id: value.process_group_id,
session_id: value.session_id,
});
if (lastObservations.get(value.pid) === observation) continue;
if (samples.length >= limit) {
partial = true;
continue;
}
lastObservations.set(value.pid, observation);
samples.push(value);
}
})
+120
View File
@@ -0,0 +1,120 @@
import { createRequire } from "node:module";
import type { RenderedTerminalFrame } from "../domain/processCapture.js";
const require = createRequire(import.meta.url);
// SAFETY: both pinned xterm packages publish CommonJS at runtime and matching declarations.
const HeadlessPackage =
require("@xterm/headless") as typeof import("@xterm/headless");
// SAFETY: the addon package is pinned with the compatible headless xterm release.
const SerializePackage =
require("@xterm/addon-serialize") as typeof import("@xterm/addon-serialize");
interface TerminalRendererOptions {
readonly columns: number;
readonly rows: number;
readonly scrollback: number;
readonly maxFrames: number;
readonly maxBytes: number;
readonly normalize: (value: string) => string;
}
/** Owns one headless terminal and serializes writes into deterministic frames. */
export class TerminalRenderer {
readonly #terminal: InstanceType<typeof HeadlessPackage.Terminal>;
readonly #serializeAddon = new SerializePackage.SerializeAddon();
readonly #frames: RenderedTerminalFrame[] = [];
#pending: Promise<void> = Promise.resolve();
#capturedBytes = 0;
#truncated = false;
constructor(private readonly options: TerminalRendererOptions) {
this.#terminal = new HeadlessPackage.Terminal({
allowProposedApi: true,
cols: options.columns,
rows: options.rows,
scrollback: options.scrollback,
});
this.#terminal.loadAddon(this.#serializeAddon);
}
/** Queue one PTY chunk and capture state only after xterm has parsed it. */
write(data: string, atMs: number): void {
this.#pending = this.#pending.then(
() =>
new Promise<void>((resolveWrite) => {
this.#terminal.write(data, () => {
this.#capture(atMs);
resolveWrite();
});
}),
);
}
/** Queue a terminal resize after every preceding write. */
resize(columns: number, rows: number, atMs: number): void {
this.#pending = this.#pending.then(() => {
this.#terminal.resize(columns, rows);
this.#capture(atMs);
});
}
/** Await all queued parsing and return immutable rendered observations. */
async frames(): Promise<readonly RenderedTerminalFrame[]> {
await this.#pending;
return this.#frames;
}
/** Whether a rendered observation exceeded its independent capture budget. */
truncated(): boolean {
return this.#truncated;
}
/** Release addon and terminal resources after all writes settle. */
async dispose(): Promise<void> {
await this.#pending;
this.#serializeAddon.dispose();
this.#terminal.dispose();
}
#capture(atMs: number): void {
const buffer = this.#terminal.buffer.active;
const lines: string[] = [];
for (let row = 0; row < this.#terminal.rows; row += 1) {
const line = buffer.getLine(buffer.viewportY + row);
lines.push(
this.options.normalize(
(line?.translateToString(false, 0, this.#terminal.cols) ?? "").padEnd(
this.#terminal.cols,
" ",
),
),
);
}
const serializedState = this.options.normalize(
this.#serializeAddon.serialize(),
);
const bytes =
Buffer.byteLength(serializedState) +
lines.reduce((total, line) => total + Buffer.byteLength(line), 0);
if (
this.#frames.length >= this.options.maxFrames ||
this.#capturedBytes + bytes > this.options.maxBytes
) {
this.#truncated = true;
return;
}
this.#capturedBytes += bytes;
this.#frames.push({
sequence: this.#frames.length,
at_ms: atMs,
columns: this.#terminal.cols,
rows: this.#terminal.rows,
cursor_x: buffer.cursorX,
cursor_y: buffer.cursorY,
active_buffer: buffer.type,
lines,
serialized_state: serializedState,
});
}
}