Files
rea/src/domain/native/nativeUiObservation.ts
T
morlutoandGitHub 4a6073810a fix(contracts): align CLI/MCP boundary contracts (#946)
* fix(cli): validate native scenario and preserve JSON paths

* fix(process): reject invalid UTF-8 JSON inputs

* fix(cli): retain missing JSON path diagnostics

* test(cli): cover relative brace and bracket JSON paths

* test(cli): reject missing native scenario steps

* fix(mcp): advertise reserved process environment key

* fix(process): reject NUL in process scenario values

* fix(process): advertise NUL input constraints to MCP

* fix(cli): report scenario input schema issues

* fix(contracts): align CLI and MCP input validation

* fix(mcp): document semantic output constraints

* fix(mcp): describe process journal compatibility

* docs: regenerate catalog after schema grouping

* docs: regenerate catalog after main merge

* fix(cli): preserve JSON and native UI input diagnostics

* test(mcp): reuse advertised tool schemas in managed flow
2026-10-08 00:03:36 +08:00

159 lines
4.6 KiB
TypeScript

import { createHash } from "node:crypto";
import { z } from "zod";
import { decodeCanonicalBase64 } from "../webScreenshot.js";
const scope = {
pid: z.number().int().positive(),
window_id: z.number().int().positive(),
screenshot: z.boolean().default(true),
accessibility: z.boolean().default(true),
max_nodes: z
.number()
.int()
.positive()
.safe()
.default(500)
.describe(
"Maximum accessibility nodes per capture; increase for large windows.",
),
};
/** Opt-in passive observation binds one already-running process and window. */
export const nativeUiObservationInputSchema = z.strictObject(scope);
/** Active scenarios use explicit actions and leave application state as-is. */
export const nativeUiScenarioInputSchema = z.strictObject({
...scope,
steps: z
.array(
z.discriminatedUnion("kind", [
z.strictObject({
kind: z.literal("click"),
path: z.array(z.number().int().nonnegative()).max(32),
}),
z.strictObject({
kind: z.literal("scroll"),
path: z.array(z.number().int().nonnegative()).max(32),
direction: z.enum(["increment", "decrement"]),
}),
z.strictObject({
kind: z.literal("key-entry"),
path: z.array(z.number().int().nonnegative()).max(32),
text: z.string(),
}),
z.strictObject({
kind: z.literal("wait"),
milliseconds: z
.number()
.int()
.min(0)
.max(180_000)
.describe(
"Wait duration in milliseconds, within the 180-second operation deadline.",
),
}),
]),
)
.min(1),
});
/** Ordered captures and failures distinguish missing observation from a failed action. */
const nativeUiScreenshotSchema = z
.strictObject({
mime_type: z.literal("image/png"),
base64: z
.string()
.min(4)
.describe(
"Canonical base64 encoding of PNG bytes; the decoded bytes must have a PNG signature and IHDR chunk.",
),
sha256: z
.string()
.regex(/^[a-f0-9]{64}$/u)
.describe("SHA-256 digest of the decoded PNG bytes."),
width: z
.number()
.int()
.positive()
.describe("Must equal the width encoded in the PNG IHDR chunk."),
height: z
.number()
.int()
.positive()
.describe("Must equal the height encoded in the PNG IHDR chunk."),
})
.superRefine((screenshot, context) => {
const bytes = decodeCanonicalBase64(screenshot.base64);
if (bytes === undefined) {
context.addIssue({
code: "custom",
message: "Invalid canonical PNG base64",
});
return;
}
if (createHash("sha256").update(bytes).digest("hex") !== screenshot.sha256)
context.addIssue({
code: "custom",
message: "PNG screenshot digest mismatch",
});
if (
bytes.byteLength < 24 ||
!bytes.subarray(0, 8).equals(PNG_SIGNATURE) ||
bytes.subarray(12, 16).toString("ascii") !== "IHDR"
) {
context.addIssue({
code: "custom",
message: "Screenshot bytes are not a PNG image",
});
return;
}
if (
bytes.readUInt32BE(16) !== screenshot.width ||
bytes.readUInt32BE(20) !== screenshot.height
)
context.addIssue({
code: "custom",
message: "PNG screenshot dimensions mismatch",
});
});
const PNG_SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
export const nativeUiSnapshotSchema = z.strictObject({
window: z.strictObject({
pid: z.number().int().positive(),
window_id: z.number().int().positive(),
executable: z.string(),
launch_time: z.number(),
title: z.string(),
}),
nodes: z.array(
z.strictObject({
path: z.array(z.number().int().nonnegative()),
role: z.string().nullable(),
title: z.string().nullable(),
value: z.string().nullable(),
actions: z.array(z.string()),
children_count: z.number().int().nonnegative().nullable(),
}),
),
truncated: z.boolean(),
screenshot: nativeUiScreenshotSchema.nullable(),
gaps: z.array(z.string()),
});
export const nativeUiResultSchema = z.strictObject({
target_sha256: z.string(),
initial: nativeUiSnapshotSchema,
steps: z.array(
z.strictObject({
index: z.number().int().nonnegative(),
kind: z.string(),
before: nativeUiSnapshotSchema,
after: nativeUiSnapshotSchema.nullable(),
outcome: z.enum(["completed", "failed", "cancelled"]),
reason: z.string().nullable(),
}),
),
restore: z.literal("leave-as-is"),
limitations: z.array(z.string()),
});