@xopcai/xopc 0.0.368 → 0.0.369

package/dist/src/browser/automations/runner.js

@@ -30,6 +30,26 @@ async function runBrowserAutomation(input) {
 				sessionId = observation?.sessionId;
 			}
 			if (step.action === "navigate") assertAllowedDomain(input.definition.allowedDomains, render(step.url, values));
+			if ("target" in step && step.target) {
+				const resolved = await input.runtime.execute(input.taskKey, {
+					action: "resolve",
+					sessionId,
+					semanticTarget: step.target
+				}, input.signal);
+				if (!resolved.ok) {
+					input.onStep({
+						index,
+						action: step.action,
+						status: "failed",
+						result: resolved
+					});
+					return resolved;
+				}
+				observation = resolved.receipt.observation;
+				sessionId = observation?.sessionId ?? sessionId;
+			}
+			if (observation) assertAllowedDomain(input.definition.allowedDomains, observation.url);
+			if (step.action === "click" && observation?.nodes[0]?.href) assertAllowedDomain(input.definition.allowedDomains, observation.nodes[0].href);
 			const action = buildAction(step, values, observation, sessionId);
 			const result = await input.runtime.execute(input.taskKey, action, input.signal);
 			if (!result.ok) {
@@ -43,7 +63,7 @@ async function runBrowserAutomation(input) {
 			}
 			observation = result.receipt.observation ?? observation;
 			sessionId = observation?.sessionId ?? sessionId;
-			if (step.action === "navigate") assertAllowedDomain(input.definition.allowedDomains, observation?.url ?? render(step.url, values));
+			if (observation) assertAllowedDomain(input.definition.allowedDomains, observation.url);
 			input.onStep({
 				index,
 				action: step.action,
@@ -61,16 +81,80 @@ async function runBrowserAutomation(input) {
 			return result;
 		}
 	}
-	return {
-		ok: true,
-		receipt: {
-			action: "sequence",
-			risk: input.definition.risk,
-			durationMs: Date.now() - startedAt,
-			verified: true,
-			observation
+	const readField = async (spec) => {
+		if (spec.target) {
+			const result = await input.runtime.execute(input.taskKey, {
+				action: "resolve",
+				sessionId,
+				semanticTarget: spec.target
+			}, input.signal);
+			if (!result.ok) return void 0;
+			observation = result.receipt.observation;
+		} else {
+			const result = await input.runtime.execute(input.taskKey, {
+				action: "observe",
+				sessionId,
+				visual: "never"
+			}, input.signal);
+			if (!result.ok) return void 0;
+			observation = result.receipt.observation;
 		}
+		if (!observation) return void 0;
+		assertAllowedDomain(input.definition.allowedDomains, observation.url);
+		const node = observation.nodes[0];
+		if (spec.field === "url") return observation.url;
+		if (spec.field === "title") return observation.title;
+		if (spec.field === "checked") return node?.states.includes("checked");
+		if (spec.field === "text") return node?.description ?? node?.name;
+		return node?.[spec.field];
 	};
+	try {
+		for (const assertion of input.definition.successCriteria ?? []) {
+			const deadline = Date.now() + 1e4;
+			let passed = false;
+			do {
+				if (input.signal.aborted) return automationFailure("INVALID_INPUT", "Run cancelled.", observation);
+				const actual = await readField(assertion);
+				passed = assertion.equals !== void 0 ? actual === (typeof assertion.equals === "string" ? render(assertion.equals, values) : assertion.equals) : typeof actual === "string" && actual.includes(render(assertion.includes, values));
+				if (!passed) await new Promise((resolve) => setTimeout(resolve, 200));
+			} while (!passed && Date.now() < deadline);
+			if (!passed) return {
+				ok: false,
+				error: {
+					code: "EXPECTATION_FAILED",
+					message: "The business result did not match its success criteria.",
+					observation
+				}
+			};
+		}
+		const outputs = {};
+		for (const [name, spec] of Object.entries(input.definition.outputs ?? {})) {
+			const value = await readField(spec);
+			if (typeof value !== "string" || !value) return {
+				ok: false,
+				error: {
+					code: "EXPECTATION_FAILED",
+					message: `Output ${name} is unavailable.`,
+					observation
+				}
+			};
+			outputs[name] = value;
+		}
+		return {
+			ok: true,
+			receipt: {
+				action: "sequence",
+				risk: input.definition.risk,
+				durationMs: Date.now() - startedAt,
+				verified: !!input.definition.successCriteria?.length,
+				businessOutcome: input.definition.successCriteria?.length ? "verified" : "completed",
+				outputs,
+				observation
+			}
+		};
+	} catch (error) {
+		return automationFailure("BLOCKED_URL", error, observation);
+	}
 }
 function buildAction(step, inputs, observation, sessionId) {
 	if (step.action === "navigate") return {
@@ -98,6 +182,13 @@ function buildAction(step, inputs, observation, sessionId) {
 			submit: step.submit,
 			expect: step.expect
 		};
+		case "check": return {
+			action: "check",
+			sessionId,
+			revision,
+			ref,
+			checked: step.checked
+		};
 		case "select": return {
 			action: "select",
 			sessionId,
@@ -149,6 +240,7 @@ function resolveBrowserAutomationInputs(definition, provided) {
 	for (const [name, spec] of Object.entries(definition.inputs)) {
 		const value = values[name] ?? spec.default;
 		if (value === void 0 && spec.required) throw new Error(`Missing required automation input: ${name}`);
+		if (value !== void 0 && spec.choices && !spec.choices.includes(value)) throw new Error(`Automation input ${name} is not an allowed choice.`);
 		if (value !== void 0 && typeof value !== spec.type) throw new Error(`Automation input ${name} must be ${spec.type}.`);
 		if (values[name] === void 0 && value !== void 0) values[name] = value;
 	}

package/dist/src/browser/automations/runtime-service.js

@@ -10,8 +10,8 @@ function createRuntimeBrowserAutomationService(deps) {
 		allowedUploadRoots: [process.cwd()],
 		emit: deps.emit
 	});
-	return new BrowserAutomationService(async ({ definition, inputs, signal, onStep }) => {
-		const taskKey = `browser-automation:${crypto.randomUUID()}`;
+	return new BrowserAutomationService(async ({ runId, definition, inputs, signal, onStep }) => {
+		const taskKey = `browser-automation:${runId}`;
 		try {
 			const result = await runBrowserAutomation({
 				definition,
@@ -23,7 +23,8 @@ function createRuntimeBrowserAutomationService(deps) {
 			});
 			return result.ok ? {
 				ok: true,
-				result: result.receipt
+				result: result.receipt.outputs ?? {},
+				businessOutcome: result.receipt.businessOutcome
 			} : {
 				ok: false,
 				error: "error" in result ? result.error.message : "Browser automation failed."

package/dist/src/browser/automations/schema.d.ts

@@ -8,8 +8,8 @@ export declare const BrowserAutomationDefinitionSchema: z.ZodObject<{
         read: "read";
         draft: "draft";
         destructive: "destructive";
-        external_effect: "external_effect";
         sensitive: "sensitive";
+        external_effect: "external_effect";
     }>;
     inputs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         type: z.ZodEnum<{
@@ -41,6 +41,11 @@ export declare const BrowserAutomationDefinitionSchema: z.ZodObject<{
             role: z.ZodString;
             name: z.ZodOptional<z.ZodString>;
             nameIncludes: z.ZodOptional<z.ZodString>;
+            testId: z.ZodOptional<z.ZodString>;
+            scope: z.ZodOptional<z.ZodObject<{
+                role: z.ZodString;
+                name: z.ZodString;
+            }, z.core.$strict>>;
         }, z.core.$strict>;
         expect: z.ZodOptional<z.ZodObject<{
             urlIncludes: z.ZodOptional<z.ZodString>;
@@ -58,6 +63,11 @@ export declare const BrowserAutomationDefinitionSchema: z.ZodObject<{
             role: z.ZodString;
             name: z.ZodOptional<z.ZodString>;
             nameIncludes: z.ZodOptional<z.ZodString>;
+            testId: z.ZodOptional<z.ZodString>;
+            scope: z.ZodOptional<z.ZodObject<{
+                role: z.ZodString;
+                name: z.ZodString;
+            }, z.core.$strict>>;
         }, z.core.$strict>;
         value: z.ZodString;
         submit: z.ZodOptional<z.ZodBoolean>;
@@ -77,6 +87,11 @@ export declare const BrowserAutomationDefinitionSchema: z.ZodObject<{
             role: z.ZodString;
             name: z.ZodOptional<z.ZodString>;
             nameIncludes: z.ZodOptional<z.ZodString>;
+            testId: z.ZodOptional<z.ZodString>;
+            scope: z.ZodOptional<z.ZodObject<{
+                role: z.ZodString;
+                name: z.ZodString;
+            }, z.core.$strict>>;
         }, z.core.$strict>;
         value: z.ZodString;
         expect: z.ZodOptional<z.ZodObject<{
@@ -89,12 +104,30 @@ export declare const BrowserAutomationDefinitionSchema: z.ZodObject<{
                 visible: "visible";
             }>>;
         }, z.core.$strict>>;
+    }, z.core.$strict>, z.ZodObject<{
+        action: z.ZodLiteral<"check">;
+        target: z.ZodObject<{
+            role: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+            nameIncludes: z.ZodOptional<z.ZodString>;
+            testId: z.ZodOptional<z.ZodString>;
+            scope: z.ZodOptional<z.ZodObject<{
+                role: z.ZodString;
+                name: z.ZodString;
+            }, z.core.$strict>>;
+        }, z.core.$strict>;
+        checked: z.ZodBoolean;
     }, z.core.$strict>, z.ZodObject<{
         action: z.ZodLiteral<"press">;
         target: z.ZodOptional<z.ZodObject<{
             role: z.ZodString;
             name: z.ZodOptional<z.ZodString>;
             nameIncludes: z.ZodOptional<z.ZodString>;
+            testId: z.ZodOptional<z.ZodString>;
+            scope: z.ZodOptional<z.ZodObject<{
+                role: z.ZodString;
+                name: z.ZodString;
+            }, z.core.$strict>>;
         }, z.core.$strict>>;
         key: z.ZodString;
         expect: z.ZodOptional<z.ZodObject<{
@@ -113,6 +146,11 @@ export declare const BrowserAutomationDefinitionSchema: z.ZodObject<{
             role: z.ZodString;
             name: z.ZodOptional<z.ZodString>;
             nameIncludes: z.ZodOptional<z.ZodString>;
+            testId: z.ZodOptional<z.ZodString>;
+            scope: z.ZodOptional<z.ZodObject<{
+                role: z.ZodString;
+                name: z.ZodString;
+            }, z.core.$strict>>;
         }, z.core.$strict>>;
         deltaY: z.ZodNumber;
         expect: z.ZodOptional<z.ZodObject<{
@@ -138,7 +176,52 @@ export declare const BrowserAutomationDefinitionSchema: z.ZodObject<{
             role: z.ZodString;
             name: z.ZodOptional<z.ZodString>;
             nameIncludes: z.ZodOptional<z.ZodString>;
+            testId: z.ZodOptional<z.ZodString>;
+            scope: z.ZodOptional<z.ZodObject<{
+                role: z.ZodString;
+                name: z.ZodString;
+            }, z.core.$strict>>;
         }, z.core.$strict>>;
         timeoutMs: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>], "action">>;
+    successCriteria: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        target: z.ZodOptional<z.ZodObject<{
+            role: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+            nameIncludes: z.ZodOptional<z.ZodString>;
+            testId: z.ZodOptional<z.ZodString>;
+            scope: z.ZodOptional<z.ZodObject<{
+                role: z.ZodString;
+                name: z.ZodString;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+        field: z.ZodEnum<{
+            value: "value";
+            text: "text";
+            title: "title";
+            url: "url";
+            checked: "checked";
+        }>;
+        equals: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodBoolean]>>;
+        includes: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    outputs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        target: z.ZodOptional<z.ZodObject<{
+            role: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+            nameIncludes: z.ZodOptional<z.ZodString>;
+            testId: z.ZodOptional<z.ZodString>;
+            scope: z.ZodOptional<z.ZodObject<{
+                role: z.ZodString;
+                name: z.ZodString;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+        field: z.ZodEnum<{
+            value: "value";
+            text: "text";
+            title: "title";
+            url: "url";
+            href: "href";
+        }>;
+    }, z.core.$strict>>>;
 }, z.core.$strict>;

package/dist/src/browser/automations/schema.js

@@ -10,7 +10,12 @@ const ExpectationSchema = z.object({
 const TargetSchema = z.object({
 	role: z.string().min(1),
 	name: z.string().min(1).optional(),
-	nameIncludes: z.string().min(1).optional()
+	nameIncludes: z.string().min(1).optional(),
+	testId: z.string().min(1).optional(),
+	scope: z.object({
+		role: z.string().min(1),
+		name: z.string().min(1)
+	}).strict().optional()
 }).strict().superRefine((target, ctx) => {
 	if (target.name && target.nameIncludes) ctx.addIssue({
 		code: "custom",
@@ -41,6 +46,11 @@ const StepSchema = z.discriminatedUnion("action", [
 		value: z.string(),
 		expect: ExpectationSchema.optional()
 	}).strict(),
+	z.object({
+		action: z.literal("check"),
+		target: TargetSchema,
+		checked: z.boolean()
+	}).strict(),
 	z.object({
 		action: z.literal("press"),
 		target: TargetSchema.optional(),
@@ -115,13 +125,61 @@ const BrowserAutomationDefinitionSchema = z.object({
 		"sensitive"
 	]),
 	inputs: z.record(z.string(), InputSchema).default({}),
-	steps: z.array(StepSchema).min(1).max(100)
+	steps: z.array(StepSchema).min(1).max(100),
+	successCriteria: z.array(z.object({
+		target: TargetSchema.optional(),
+		field: z.enum([
+			"text",
+			"value",
+			"url",
+			"title",
+			"checked"
+		]),
+		equals: z.union([z.string(), z.boolean()]).optional(),
+		includes: z.string().optional()
+	}).strict().superRefine((assertion, ctx) => {
+		if (assertion.equals === void 0 === (assertion.includes === void 0)) ctx.addIssue({
+			code: "custom",
+			message: "Specify exactly one comparison."
+		});
+		if (assertion.field === "checked" && typeof assertion.equals !== "boolean") ctx.addIssue({
+			code: "custom",
+			message: "Checked assertions require a boolean comparison."
+		});
+		if (assertion.field !== "checked" && typeof assertion.equals === "boolean") ctx.addIssue({
+			code: "custom",
+			message: "Text assertions require a string comparison."
+		});
+		if (!["url", "title"].includes(assertion.field) && !assertion.target) ctx.addIssue({
+			code: "custom",
+			message: "Element assertions require a target."
+		});
+	})).max(20).optional(),
+	outputs: z.record(z.string().regex(/^[a-zA-Z][a-zA-Z0-9_]*$/), z.object({
+		target: TargetSchema.optional(),
+		field: z.enum([
+			"text",
+			"value",
+			"url",
+			"title",
+			"href"
+		])
+	}).strict().superRefine((output, ctx) => {
+		if (!["url", "title"].includes(output.field) && !output.target) ctx.addIssue({
+			code: "custom",
+			message: "Element outputs require a target."
+		});
+	})).optional()
 }).strict().superRefine((definition, ctx) => {
 	if (new Set(definition.allowedDomains).size !== definition.allowedDomains.length) ctx.addIssue({
 		code: "custom",
 		path: ["allowedDomains"],
 		message: "Domains must be unique."
 	});
+	for (const spec of Object.values(definition.inputs)) if (spec.default !== void 0 && spec.choices && !spec.choices.includes(spec.default)) ctx.addIssue({
+		code: "custom",
+		message: "Default must be an allowed choice."
+	});
 	for (const [index, step] of definition.steps.entries()) {
 		const values = step.action === "navigate" ? [step.url] : step.action === "fill" || step.action === "select" ? [step.value] : step.action === "press" ? [step.key] : step.action === "wait" && step.value ? [step.value] : [];
 		for (const value of values) for (const match of value.matchAll(/\$\{input\.([a-zA-Z][a-zA-Z0-9_]*)\}/g)) if (!definition.inputs[match[1]]) ctx.addIssue({
@@ -130,6 +188,14 @@ const BrowserAutomationDefinitionSchema = z.object({
 			message: `Unknown input template: ${match[1]}.`
 		});
 	}
+	for (const [index, assertion] of (definition.successCriteria ?? []).entries()) for (const value of [assertion.equals, assertion.includes]) {
+		if (typeof value !== "string") continue;
+		for (const match of value.matchAll(/\$\{input\.([a-zA-Z][a-zA-Z0-9_]*)\}/g)) if (!definition.inputs[match[1]]) ctx.addIssue({
+			code: "custom",
+			path: ["successCriteria", index],
+			message: `Unknown input template: ${match[1]}.`
+		});
+	}
 });
 //#endregion
 export { BrowserAutomationDefinitionSchema };

package/dist/src/browser/automations/service.d.ts

@@ -4,10 +4,12 @@ export type BrowserAutomationExecutor = (input: {
     inputs: Record<string, unknown>;
     signal: AbortSignal;
     onStep: (event: unknown) => void;
+    runId: string;
 }) => Promise<{
     ok: boolean;
     result?: unknown;
     error?: string;
+    businessOutcome?: BrowserAutomationRun['businessOutcome'];
 }>;
 export declare class BrowserAutomationService {
     private readonly executor;
@@ -18,6 +20,7 @@ export declare class BrowserAutomationService {
     constructor(executor: BrowserAutomationExecutor, emit?: (type: string, payload: unknown) => void);
     list(): BrowserAutomation[];
     get(id: string): BrowserAutomation;
+    versions(id: string): BrowserAutomation[];
     listRuns(automationId?: string): BrowserAutomationRun[];
     getRun(id: string): BrowserAutomationRun;
     listRunEvents(id: string): import("./types.js").BrowserAutomationRunEvent[];
@@ -25,7 +28,7 @@ export declare class BrowserAutomationService {
         id: string;
         name: string;
         allowedDomains: string[];
-        risk: "read" | "draft" | "destructive" | "external_effect" | "sensitive";
+        risk: "read" | "draft" | "destructive" | "sensitive" | "external_effect";
         inputs: Record<string, {
             type: "string" | "number" | "boolean";
             required?: boolean;
@@ -49,6 +52,11 @@ export declare class BrowserAutomationService {
                 role: string;
                 name?: string;
                 nameIncludes?: string;
+                testId?: string;
+                scope?: {
+                    role: string;
+                    name: string;
+                };
             };
             expect?: {
                 urlIncludes?: string;
@@ -63,6 +71,11 @@ export declare class BrowserAutomationService {
                 role: string;
                 name?: string;
                 nameIncludes?: string;
+                testId?: string;
+                scope?: {
+                    role: string;
+                    name: string;
+                };
             };
             value: string;
             submit?: boolean;
@@ -79,6 +92,11 @@ export declare class BrowserAutomationService {
                 role: string;
                 name?: string;
                 nameIncludes?: string;
+                testId?: string;
+                scope?: {
+                    role: string;
+                    name: string;
+                };
             };
             value: string;
             expect?: {
@@ -88,6 +106,19 @@ export declare class BrowserAutomationService {
                 ref?: string;
                 state?: "hidden" | "visible";
             };
+        } | {
+            action: "check";
+            target: {
+                role: string;
+                name?: string;
+                nameIncludes?: string;
+                testId?: string;
+                scope?: {
+                    role: string;
+                    name: string;
+                };
+            };
+            checked: boolean;
         } | {
             action: "press";
             key: string;
@@ -95,6 +126,11 @@ export declare class BrowserAutomationService {
                 role: string;
                 name?: string;
                 nameIncludes?: string;
+                testId?: string;
+                scope?: {
+                    role: string;
+                    name: string;
+                };
             };
             expect?: {
                 urlIncludes?: string;
@@ -110,6 +146,11 @@ export declare class BrowserAutomationService {
                 role: string;
                 name?: string;
                 nameIncludes?: string;
+                testId?: string;
+                scope?: {
+                    role: string;
+                    name: string;
+                };
             };
             expect?: {
                 urlIncludes?: string;
@@ -126,15 +167,49 @@ export declare class BrowserAutomationService {
                 role: string;
                 name?: string;
                 nameIncludes?: string;
+                testId?: string;
+                scope?: {
+                    role: string;
+                    name: string;
+                };
             };
             timeoutMs?: number;
         })[];
         description?: string;
+        successCriteria?: {
+            field: "value" | "text" | "title" | "url" | "checked";
+            target?: {
+                role: string;
+                name?: string;
+                nameIncludes?: string;
+                testId?: string;
+                scope?: {
+                    role: string;
+                    name: string;
+                };
+            };
+            equals?: string | boolean;
+            includes?: string;
+        }[];
+        outputs?: Record<string, {
+            field: "value" | "text" | "title" | "url" | "href";
+            target?: {
+                role: string;
+                name?: string;
+                nameIncludes?: string;
+                testId?: string;
+                scope?: {
+                    role: string;
+                    name: string;
+                };
+            };
+        }>;
     }>;
     save(input: {
         definition: unknown;
         status?: BrowserAutomationStatus;
         expectedId?: string;
+        expectedRevision?: number;
     }): BrowserAutomation;
     remove(id: string): boolean;
     startRun(automationId: string, inputs: Record<string, unknown>, context?: BrowserAutomationExecutionContext): BrowserAutomationRun;
@@ -145,6 +220,8 @@ export declare class BrowserAutomationService {
     private execute;
 }
 export interface BrowserAutomationExecutionContext {
+    revision?: number;
+    clientRequestId?: string;
     triggerEvent?: {
         type: string;
         source?: string;