fix(process)!: bound terminal buffers before capture
Validate columns × (rows + scrollback) against a 1,000,000-cell xterm working-buffer budget, including every resize with the selected scrollback. Document the budget in the advertised MCP input and process-capture guide; never clamp caller dimensions. Validation: default/exact-boundary schema cases, prelaunch MCP rejection, compiled CLI capture, terminal rendering, normalization, cancellation, and lifecycle checks pass on macOS. This is resource admission, not a measured serializer throughput improvement; Linux-only and real deep-analysis providers were not exercised. BREAKING CHANGE: process scenarios whose initial or resized terminal exceeds 1,000,000 combined visible-plus-scrollback cells are now rejected before launch.
This commit is contained in:
@@ -94,7 +94,7 @@ export const SESSION_TOOL_CONTRACTS = [
|
||||
),
|
||||
session(
|
||||
"capture_process_scenario",
|
||||
"Run one caller-selected command under a PTY and return process capture Evidence with residual unknowns. A command name resolves through the inherited PATH; the working directory defaults to the caller's current directory; host environment variables are inherited with scenario overrides. Environment keys cannot contain '=' or NUL, and REA_PROCESS_RUN_ID is reserved for process ownership. Filesystem snapshots are opt-in through filesystem_observation_paths. The target runs with the current user's permissions; this is not a security sandbox.",
|
||||
"Run one caller-selected command under a PTY and return process capture Evidence with residual unknowns. The renderer admits at most 1,000,000 combined terminal cells, computed as columns × (rows + scrollback); every resize uses the selected scrollback and must fit the same budget. Supply a smaller terminal shape when that product is too large; dimensions are never clamped. A command name resolves through the inherited PATH; the working directory defaults to the caller's current directory; host environment variables are inherited with scenario overrides. Environment keys cannot contain '=' or NUL, and REA_PROCESS_RUN_ID is reserved for process ownership. Filesystem snapshots are opt-in through filesystem_observation_paths. The target runs with the current user's permissions; this is not a security sandbox.",
|
||||
processScenarioSchema,
|
||||
),
|
||||
session(
|
||||
|
||||
@@ -0,0 +1,71 @@
|
||||
import { expect, it } from "vitest";
|
||||
|
||||
import {
|
||||
parseProcessScenario,
|
||||
PROCESS_TERMINAL_CELL_BUDGET,
|
||||
processScenarioSchema,
|
||||
} from "./processScenario.js";
|
||||
|
||||
it("admits the default and the exact combined terminal-cell budget", () => {
|
||||
expect(parseProcessScenario({ executable: "/bin/true" }).terminal).toEqual({
|
||||
columns: 80,
|
||||
rows: 24,
|
||||
scrollback: 1_000,
|
||||
});
|
||||
|
||||
expect(
|
||||
processScenarioSchema.safeParse({
|
||||
executable: "/bin/true",
|
||||
terminal: {
|
||||
columns: 1,
|
||||
rows: 1,
|
||||
scrollback: PROCESS_TERMINAL_CELL_BUDGET - 1,
|
||||
},
|
||||
}).success,
|
||||
).toBe(true);
|
||||
});
|
||||
|
||||
it("rejects an oversized initial buffer without clamping caller dimensions", () => {
|
||||
const input = {
|
||||
executable: "/bin/true",
|
||||
terminal: { columns: 1_000, rows: 1, scrollback: 1_000 },
|
||||
};
|
||||
const parsed = processScenarioSchema.safeParse(input);
|
||||
|
||||
expect(parsed.success).toBe(false);
|
||||
if (parsed.success) throw new Error("expected terminal capacity rejection");
|
||||
expect(parsed.error.issues).toContainEqual(
|
||||
expect.objectContaining({
|
||||
code: "custom",
|
||||
path: ["terminal"],
|
||||
message: expect.stringContaining(
|
||||
`${String(PROCESS_TERMINAL_CELL_BUDGET)} renderer cells`,
|
||||
),
|
||||
}),
|
||||
);
|
||||
});
|
||||
|
||||
it("applies the selected scrollback budget to every scheduled resize", () => {
|
||||
const parsed = processScenarioSchema.safeParse({
|
||||
executable: "/bin/true",
|
||||
events: [{ type: "resize", at_ms: 10, columns: 1_000, rows: 1 }],
|
||||
});
|
||||
|
||||
expect(parsed.success).toBe(false);
|
||||
if (parsed.success) throw new Error("expected resize capacity rejection");
|
||||
expect(parsed.error.issues).toContainEqual(
|
||||
expect.objectContaining({
|
||||
code: "custom",
|
||||
path: ["events", 0],
|
||||
message: expect.stringContaining("resize event at 10 ms"),
|
||||
}),
|
||||
);
|
||||
|
||||
expect(
|
||||
processScenarioSchema.safeParse({
|
||||
executable: "/bin/true",
|
||||
terminal: { columns: 1, rows: 1, scrollback: 0 },
|
||||
events: [{ type: "resize", at_ms: 10, columns: 1_000, rows: 1 }],
|
||||
}).success,
|
||||
).toBe(true);
|
||||
});
|
||||
@@ -3,6 +3,12 @@ import canonicalize from "canonicalize";
|
||||
import { z } from "zod";
|
||||
|
||||
const positiveBudget = z.number().int().safe().positive();
|
||||
/**
|
||||
* Maximum xterm backing cells for one visible-plus-scrollback buffer. Each
|
||||
* xterm BufferLine stores three Uint32 words per cell (12 MB at this cap),
|
||||
* before row objects, serialization strings, and retained frame copies.
|
||||
*/
|
||||
export const PROCESS_TERMINAL_CELL_BUDGET = 1_000_000;
|
||||
const timedEventBase = { at_ms: z.number().int().safe().nonnegative() };
|
||||
const reservedRunIdEnvironmentName = "REA_PROCESS_RUN_ID";
|
||||
const ENVIRONMENT_NAME_CHARACTER = "[^=\\x00]";
|
||||
@@ -41,6 +47,14 @@ const childProcessString = z
|
||||
/^[^\x00]*$/u,
|
||||
"Values passed to operating-system APIs cannot contain NUL",
|
||||
);
|
||||
|
||||
const fitsProcessTerminalCellBudget = (
|
||||
columns: number,
|
||||
rows: number,
|
||||
scrollback: number,
|
||||
): boolean =>
|
||||
rows + scrollback <= Math.floor(PROCESS_TERMINAL_CELL_BUDGET / columns);
|
||||
|
||||
export const normalizationSchema = z.object({
|
||||
paths: z.boolean(),
|
||||
pids: z.boolean(),
|
||||
@@ -131,8 +145,11 @@ export const processScenarioSchema = z
|
||||
.strictObject({
|
||||
columns: z.number().int().min(1).max(65_535).default(80),
|
||||
rows: z.number().int().min(1).max(65_535).default(24),
|
||||
scrollback: z.number().int().min(0).default(1_000),
|
||||
scrollback: z.number().int().safe().nonnegative().default(1_000),
|
||||
})
|
||||
.describe(
|
||||
"The visible terminal and scrollback together must use at most 1,000,000 xterm renderer cells: columns × (rows + scrollback). Resize events use the same scrollback and limit.",
|
||||
)
|
||||
.default({ columns: 80, rows: 24, scrollback: 1_000 }),
|
||||
events: z
|
||||
.array(
|
||||
@@ -204,6 +221,18 @@ export const processScenarioSchema = z
|
||||
}),
|
||||
})
|
||||
.superRefine((scenario, context) => {
|
||||
if (
|
||||
!fitsProcessTerminalCellBudget(
|
||||
scenario.terminal.columns,
|
||||
scenario.terminal.rows,
|
||||
scenario.terminal.scrollback,
|
||||
)
|
||||
)
|
||||
context.addIssue({
|
||||
code: "custom",
|
||||
path: ["terminal"],
|
||||
message: `terminal columns × (rows + scrollback) must not exceed ${String(PROCESS_TERMINAL_CELL_BUDGET)} renderer cells`,
|
||||
});
|
||||
for (let index = 1; index < scenario.events.length; index += 1) {
|
||||
const event = scenario.events[index];
|
||||
const previous = scenario.events[index - 1];
|
||||
@@ -215,7 +244,20 @@ export const processScenarioSchema = z
|
||||
});
|
||||
}
|
||||
}
|
||||
for (const event of scenario.events) {
|
||||
for (const [index, event] of scenario.events.entries()) {
|
||||
if (
|
||||
event.type === "resize" &&
|
||||
!fitsProcessTerminalCellBudget(
|
||||
event.columns,
|
||||
event.rows,
|
||||
scenario.terminal.scrollback,
|
||||
)
|
||||
)
|
||||
context.addIssue({
|
||||
code: "custom",
|
||||
path: ["events", index],
|
||||
message: `resize event at ${String(event.at_ms)} ms exceeds the ${String(PROCESS_TERMINAL_CELL_BUDGET)}-cell renderer budget with the selected scrollback`,
|
||||
});
|
||||
if (event.at_ms > scenario.timeout_ms) {
|
||||
context.addIssue({
|
||||
code: "custom",
|
||||
|
||||
Reference in New Issue
Block a user