feat(process): add deterministic capture v3
This commit is contained in:
@@ -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),
|
||||
),
|
||||
);
|
||||
@@ -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;
|
||||
};
|
||||
@@ -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;
|
||||
};
|
||||
@@ -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,
|
||||
});
|
||||
@@ -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);
|
||||
};
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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);
|
||||
}
|
||||
})
|
||||
|
||||
@@ -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,
|
||||
});
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user