@xopcai/xopc 0.0.251 → 0.0.253

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

@@ -0,0 +1,17 @@
+import type { BrowserControlResult } from '@xopcai/browser-control-contract';
+import type { BrowserRuntime } from '../runtime/browser-runtime.js';
+import type { BrowserAutomationDefinition } from './types.js';
+export declare function runBrowserAutomation(input: {
+    definition: BrowserAutomationDefinition;
+    inputs: Record<string, unknown>;
+    runtime: BrowserRuntime;
+    taskKey: string;
+    signal: AbortSignal;
+    onStep: (event: {
+        index: number;
+        action: string;
+        status: 'started' | 'completed' | 'failed';
+        result?: BrowserControlResult;
+    }) => void;
+}): Promise<BrowserControlResult>;
+export declare function resolveBrowserAutomationInputs(definition: BrowserAutomationDefinition, provided: Record<string, unknown>): Record<string, unknown>;

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

@@ -0,0 +1,173 @@
+//#region src/browser/automations/runner.ts
+async function runBrowserAutomation(input) {
+	const startedAt = Date.now();
+	const values = resolveBrowserAutomationInputs(input.definition, input.inputs);
+	let observation;
+	let sessionId;
+	for (let index = 0; index < input.definition.steps.length; index += 1) {
+		const step = input.definition.steps[index];
+		input.onStep({
+			index,
+			action: step.action,
+			status: "started"
+		});
+		try {
+			if (step.action !== "navigate" && !observation) {
+				const observed = await input.runtime.execute(input.taskKey, {
+					action: "observe",
+					sessionId
+				}, input.signal);
+				if (!observed.ok) {
+					input.onStep({
+						index,
+						action: step.action,
+						status: "failed",
+						result: observed
+					});
+					return observed;
+				}
+				observation = observed.receipt.observation;
+				sessionId = observation?.sessionId;
+			}
+			if (step.action === "navigate") assertAllowedDomain(input.definition.allowedDomains, render(step.url, values));
+			const action = buildAction(step, values, observation, sessionId);
+			const result = await input.runtime.execute(input.taskKey, action, input.signal);
+			if (!result.ok) {
+				input.onStep({
+					index,
+					action: step.action,
+					status: "failed",
+					result
+				});
+				return result;
+			}
+			observation = result.receipt.observation ?? observation;
+			sessionId = observation?.sessionId ?? sessionId;
+			if (step.action === "navigate") assertAllowedDomain(input.definition.allowedDomains, observation?.url ?? render(step.url, values));
+			input.onStep({
+				index,
+				action: step.action,
+				status: "completed",
+				result
+			});
+		} catch (error) {
+			const result = automationFailure(step.action === "navigate" ? "BLOCKED_URL" : "INVALID_INPUT", error, observation);
+			input.onStep({
+				index,
+				action: step.action,
+				status: "failed",
+				result
+			});
+			return result;
+		}
+	}
+	return {
+		ok: true,
+		receipt: {
+			action: "sequence",
+			risk: input.definition.risk,
+			durationMs: Date.now() - startedAt,
+			verified: true,
+			observation
+		}
+	};
+}
+function buildAction(step, inputs, observation, sessionId) {
+	if (step.action === "navigate") return {
+		...step,
+		url: render(step.url, inputs),
+		sessionId
+	};
+	if (!observation) throw new Error("Browser observation is unavailable.");
+	const revision = observation.revision;
+	const ref = "target" in step && step.target ? resolveTarget(step.target, observation) : void 0;
+	switch (step.action) {
+		case "click": return {
+			action: "click",
+			sessionId,
+			revision,
+			ref,
+			expect: step.expect
+		};
+		case "fill": return {
+			action: "fill",
+			sessionId,
+			revision,
+			ref,
+			value: render(step.value, inputs),
+			submit: step.submit,
+			expect: step.expect
+		};
+		case "select": return {
+			action: "select",
+			sessionId,
+			revision,
+			ref,
+			value: render(step.value, inputs),
+			expect: step.expect
+		};
+		case "press": return {
+			action: "press",
+			sessionId,
+			revision,
+			ref,
+			key: render(step.key, inputs),
+			expect: step.expect
+		};
+		case "scroll": return {
+			action: "scroll",
+			sessionId,
+			revision,
+			ref,
+			deltaY: step.deltaY,
+			expect: step.expect
+		};
+		case "wait": return {
+			action: "wait",
+			sessionId,
+			revision,
+			ref,
+			condition: step.condition,
+			value: step.value ? render(step.value, inputs) : void 0,
+			timeoutMs: step.timeoutMs
+		};
+	}
+}
+function resolveTarget(target, observation) {
+	const matches = observation.nodes.filter((node) => node.role === target.role && (!target.name || node.name === target.name) && (!target.nameIncludes || node.name.includes(target.nameIncludes)));
+	if (matches.length !== 1) throw new Error(`Semantic target must match exactly one element; matched ${matches.length}: ${JSON.stringify(target)}`);
+	return matches[0].ref;
+}
+function render(value, inputs) {
+	return value.replace(/\$\{input\.([a-zA-Z][a-zA-Z0-9_]*)\}/g, (_match, key) => {
+		if (!(key in inputs)) throw new Error(`Missing automation input: ${key}`);
+		return String(inputs[key]);
+	});
+}
+function resolveBrowserAutomationInputs(definition, provided) {
+	const values = { ...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 && 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;
+	}
+	for (const name of Object.keys(values)) if (!definition.inputs[name]) throw new Error(`Unknown automation input: ${name}`);
+	return values;
+}
+function assertAllowedDomain(allowedDomains, url) {
+	const host = new URL(url).hostname.toLowerCase();
+	if (!allowedDomains.some((domain) => domain.toLowerCase() === host)) throw new Error(`Automation navigated outside its allowed domains: ${host}`);
+}
+function automationFailure(code, error, observation) {
+	return {
+		ok: false,
+		error: {
+			code,
+			message: error instanceof Error ? error.message : String(error),
+			observation
+		}
+	};
+}
+//#endregion
+export { resolveBrowserAutomationInputs, runBrowserAutomation };

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

@@ -0,0 +1,6 @@
+import type { Config } from '../../config/schema.js';
+import { BrowserAutomationService } from './service.js';
+export declare function createRuntimeBrowserAutomationService(deps: {
+    getConfig: () => Config;
+    emit?: (type: string, payload: unknown) => void;
+}): BrowserAutomationService;

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

@@ -0,0 +1,37 @@
+import { BrowserRuntime } from "../runtime/browser-runtime.js";
+import { createBrowserDriver } from "../drivers/create-driver.js";
+import { runBrowserAutomation } from "./runner.js";
+import { BrowserAutomationService } from "./service.js";
+//#region src/browser/automations/runtime-service.ts
+function createRuntimeBrowserAutomationService(deps) {
+	const runtime = new BrowserRuntime({
+		getConfig: () => deps.getConfig().browser,
+		createDriver: () => createBrowserDriver(deps.getConfig().browser),
+		allowedUploadRoots: [process.cwd()],
+		emit: deps.emit
+	});
+	return new BrowserAutomationService(async ({ definition, inputs, signal, onStep }) => {
+		const taskKey = `browser-automation:${crypto.randomUUID()}`;
+		try {
+			const result = await runBrowserAutomation({
+				definition,
+				inputs,
+				runtime,
+				taskKey,
+				signal,
+				onStep
+			});
+			return result.ok ? {
+				ok: true,
+				result: result.receipt
+			} : {
+				ok: false,
+				error: "error" in result ? result.error.message : "Browser automation failed."
+			};
+		} finally {
+			await runtime.closeTaskSession(taskKey);
+		}
+	}, deps.emit);
+}
+//#endregion
+export { createRuntimeBrowserAutomationService };

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

@@ -0,0 +1,144 @@
+import { z } from 'zod';
+export declare const BrowserAutomationDefinitionSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    allowedDomains: z.ZodArray<z.ZodString>;
+    risk: z.ZodEnum<{
+        read: "read";
+        sensitive: "sensitive";
+        destructive: "destructive";
+        draft: "draft";
+        external_effect: "external_effect";
+    }>;
+    inputs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        type: z.ZodEnum<{
+            string: "string";
+            number: "number";
+            boolean: "boolean";
+        }>;
+        required: z.ZodOptional<z.ZodBoolean>;
+        default: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+        description: z.ZodOptional<z.ZodString>;
+        choices: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    }, z.core.$strict>>>;
+    steps: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        action: z.ZodLiteral<"navigate">;
+        url: z.ZodString;
+        expect: z.ZodOptional<z.ZodObject<{
+            urlIncludes: z.ZodOptional<z.ZodString>;
+            titleIncludes: z.ZodOptional<z.ZodString>;
+            textIncludes: z.ZodOptional<z.ZodString>;
+            ref: z.ZodOptional<z.ZodString>;
+            state: z.ZodOptional<z.ZodEnum<{
+                hidden: "hidden";
+                visible: "visible";
+            }>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>, z.ZodObject<{
+        action: z.ZodLiteral<"click">;
+        target: z.ZodObject<{
+            role: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+            nameIncludes: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        expect: z.ZodOptional<z.ZodObject<{
+            urlIncludes: z.ZodOptional<z.ZodString>;
+            titleIncludes: z.ZodOptional<z.ZodString>;
+            textIncludes: z.ZodOptional<z.ZodString>;
+            ref: z.ZodOptional<z.ZodString>;
+            state: z.ZodOptional<z.ZodEnum<{
+                hidden: "hidden";
+                visible: "visible";
+            }>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>, z.ZodObject<{
+        action: z.ZodLiteral<"fill">;
+        target: z.ZodObject<{
+            role: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+            nameIncludes: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        value: z.ZodString;
+        submit: z.ZodOptional<z.ZodBoolean>;
+        expect: z.ZodOptional<z.ZodObject<{
+            urlIncludes: z.ZodOptional<z.ZodString>;
+            titleIncludes: z.ZodOptional<z.ZodString>;
+            textIncludes: z.ZodOptional<z.ZodString>;
+            ref: z.ZodOptional<z.ZodString>;
+            state: z.ZodOptional<z.ZodEnum<{
+                hidden: "hidden";
+                visible: "visible";
+            }>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>, z.ZodObject<{
+        action: z.ZodLiteral<"select">;
+        target: z.ZodObject<{
+            role: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+            nameIncludes: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        value: z.ZodString;
+        expect: z.ZodOptional<z.ZodObject<{
+            urlIncludes: z.ZodOptional<z.ZodString>;
+            titleIncludes: z.ZodOptional<z.ZodString>;
+            textIncludes: z.ZodOptional<z.ZodString>;
+            ref: z.ZodOptional<z.ZodString>;
+            state: z.ZodOptional<z.ZodEnum<{
+                hidden: "hidden";
+                visible: "visible";
+            }>>;
+        }, z.core.$strict>>;
+    }, 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>;
+        }, z.core.$strict>>;
+        key: z.ZodString;
+        expect: z.ZodOptional<z.ZodObject<{
+            urlIncludes: z.ZodOptional<z.ZodString>;
+            titleIncludes: z.ZodOptional<z.ZodString>;
+            textIncludes: z.ZodOptional<z.ZodString>;
+            ref: z.ZodOptional<z.ZodString>;
+            state: z.ZodOptional<z.ZodEnum<{
+                hidden: "hidden";
+                visible: "visible";
+            }>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>, z.ZodObject<{
+        action: z.ZodLiteral<"scroll">;
+        target: z.ZodOptional<z.ZodObject<{
+            role: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+            nameIncludes: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        deltaY: z.ZodNumber;
+        expect: z.ZodOptional<z.ZodObject<{
+            urlIncludes: z.ZodOptional<z.ZodString>;
+            titleIncludes: z.ZodOptional<z.ZodString>;
+            textIncludes: z.ZodOptional<z.ZodString>;
+            ref: z.ZodOptional<z.ZodString>;
+            state: z.ZodOptional<z.ZodEnum<{
+                hidden: "hidden";
+                visible: "visible";
+            }>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>, z.ZodObject<{
+        action: z.ZodLiteral<"wait">;
+        condition: z.ZodEnum<{
+            hidden: "hidden";
+            text: "text";
+            visible: "visible";
+            page_idle: "page_idle";
+        }>;
+        value: z.ZodOptional<z.ZodString>;
+        target: z.ZodOptional<z.ZodObject<{
+            role: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+            nameIncludes: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        timeoutMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>], "action">>;
+}, z.core.$strict>;

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

@@ -0,0 +1,135 @@
+import { z } from "zod";
+//#region src/browser/automations/schema.ts
+const ExpectationSchema = z.object({
+	urlIncludes: z.string().optional(),
+	titleIncludes: z.string().optional(),
+	textIncludes: z.string().optional(),
+	ref: z.string().optional(),
+	state: z.enum(["visible", "hidden"]).optional()
+}).strict();
+const TargetSchema = z.object({
+	role: z.string().min(1),
+	name: z.string().min(1).optional(),
+	nameIncludes: z.string().min(1).optional()
+}).strict().superRefine((target, ctx) => {
+	if (target.name && target.nameIncludes) ctx.addIssue({
+		code: "custom",
+		message: "Use name or nameIncludes, not both."
+	});
+});
+const StepSchema = z.discriminatedUnion("action", [
+	z.object({
+		action: z.literal("navigate"),
+		url: z.string().min(1),
+		expect: ExpectationSchema.optional()
+	}).strict(),
+	z.object({
+		action: z.literal("click"),
+		target: TargetSchema,
+		expect: ExpectationSchema.optional()
+	}).strict(),
+	z.object({
+		action: z.literal("fill"),
+		target: TargetSchema,
+		value: z.string(),
+		submit: z.boolean().optional(),
+		expect: ExpectationSchema.optional()
+	}).strict(),
+	z.object({
+		action: z.literal("select"),
+		target: TargetSchema,
+		value: z.string(),
+		expect: ExpectationSchema.optional()
+	}).strict(),
+	z.object({
+		action: z.literal("press"),
+		target: TargetSchema.optional(),
+		key: z.string().min(1),
+		expect: ExpectationSchema.optional()
+	}).strict(),
+	z.object({
+		action: z.literal("scroll"),
+		target: TargetSchema.optional(),
+		deltaY: z.number(),
+		expect: ExpectationSchema.optional()
+	}).strict(),
+	z.object({
+		action: z.literal("wait"),
+		condition: z.enum([
+			"page_idle",
+			"text",
+			"visible",
+			"hidden"
+		]),
+		value: z.string().optional(),
+		target: TargetSchema.optional(),
+		timeoutMs: z.number().int().min(100).max(12e4).optional()
+	}).strict()
+]);
+const InputSchema = z.object({
+	type: z.enum([
+		"string",
+		"number",
+		"boolean"
+	]),
+	required: z.boolean().optional(),
+	default: z.union([
+		z.string(),
+		z.number(),
+		z.boolean()
+	]).optional(),
+	description: z.string().min(1).max(200).optional(),
+	choices: z.array(z.union([
+		z.string(),
+		z.number(),
+		z.boolean()
+	])).min(1).max(50).optional()
+}).strict().superRefine((input, ctx) => {
+	if (input.default !== void 0 && typeof input.default !== input.type) ctx.addIssue({
+		code: "custom",
+		message: `Default must be ${input.type}.`
+	});
+	if (input.choices?.some((choice) => typeof choice !== input.type)) ctx.addIssue({
+		code: "custom",
+		message: `Every choice must be ${input.type}.`
+	});
+});
+const DomainSchema = z.string().min(1).refine((value) => {
+	if (value !== value.toLowerCase() || value.includes("/") || value.includes(":")) return false;
+	try {
+		return new URL(`https://${value}`).hostname === value;
+	} catch {
+		return false;
+	}
+}, "Domain must be one exact lowercase hostname.");
+const BrowserAutomationDefinitionSchema = z.object({
+	id: z.string().regex(/^[a-z][a-z0-9-]{1,63}$/),
+	name: z.string().min(1).max(120),
+	description: z.string().max(500).optional(),
+	allowedDomains: z.array(DomainSchema).min(1),
+	risk: z.enum([
+		"read",
+		"draft",
+		"external_effect",
+		"destructive",
+		"sensitive"
+	]),
+	inputs: z.record(z.string(), InputSchema).default({}),
+	steps: z.array(StepSchema).min(1).max(100)
+}).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 [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({
+			code: "custom",
+			path: ["steps", index],
+			message: `Unknown input template: ${match[1]}.`
+		});
+	}
+});
+//#endregion
+export { BrowserAutomationDefinitionSchema };

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

@@ -0,0 +1,146 @@
+import type { BrowserAutomation, BrowserAutomationDefinition, BrowserAutomationRun, BrowserAutomationStatus } from './types.js';
+export type BrowserAutomationExecutor = (input: {
+    definition: BrowserAutomationDefinition;
+    inputs: Record<string, unknown>;
+    signal: AbortSignal;
+    onStep: (event: unknown) => void;
+}) => Promise<{
+    ok: boolean;
+    result?: unknown;
+    error?: string;
+}>;
+export declare class BrowserAutomationService {
+    private readonly executor;
+    private readonly emit?;
+    private activeRuns;
+    private executions;
+    private waiters;
+    constructor(executor: BrowserAutomationExecutor, emit?: (type: string, payload: unknown) => void);
+    list(): BrowserAutomation[];
+    get(id: string): BrowserAutomation;
+    listRuns(automationId?: string): BrowserAutomationRun[];
+    getRun(id: string): BrowserAutomationRun;
+    listRunEvents(id: string): import("./types.js").BrowserAutomationRunEvent[];
+    validate(definition: unknown): import("zod/index.cjs").ZodSafeParseResult<{
+        id: string;
+        name: string;
+        allowedDomains: string[];
+        risk: "read" | "sensitive" | "destructive" | "draft" | "external_effect";
+        inputs: Record<string, {
+            type: "string" | "number" | "boolean";
+            required?: boolean;
+            default?: string | number | boolean;
+            description?: string;
+            choices?: (string | number | boolean)[];
+        }>;
+        steps: ({
+            action: "navigate";
+            url: string;
+            expect?: {
+                urlIncludes?: string;
+                titleIncludes?: string;
+                textIncludes?: string;
+                ref?: string;
+                state?: "hidden" | "visible";
+            };
+        } | {
+            action: "click";
+            target: {
+                role: string;
+                name?: string;
+                nameIncludes?: string;
+            };
+            expect?: {
+                urlIncludes?: string;
+                titleIncludes?: string;
+                textIncludes?: string;
+                ref?: string;
+                state?: "hidden" | "visible";
+            };
+        } | {
+            action: "fill";
+            target: {
+                role: string;
+                name?: string;
+                nameIncludes?: string;
+            };
+            value: string;
+            submit?: boolean;
+            expect?: {
+                urlIncludes?: string;
+                titleIncludes?: string;
+                textIncludes?: string;
+                ref?: string;
+                state?: "hidden" | "visible";
+            };
+        } | {
+            action: "select";
+            target: {
+                role: string;
+                name?: string;
+                nameIncludes?: string;
+            };
+            value: string;
+            expect?: {
+                urlIncludes?: string;
+                titleIncludes?: string;
+                textIncludes?: string;
+                ref?: string;
+                state?: "hidden" | "visible";
+            };
+        } | {
+            action: "press";
+            key: string;
+            target?: {
+                role: string;
+                name?: string;
+                nameIncludes?: string;
+            };
+            expect?: {
+                urlIncludes?: string;
+                titleIncludes?: string;
+                textIncludes?: string;
+                ref?: string;
+                state?: "hidden" | "visible";
+            };
+        } | {
+            action: "scroll";
+            deltaY: number;
+            target?: {
+                role: string;
+                name?: string;
+                nameIncludes?: string;
+            };
+            expect?: {
+                urlIncludes?: string;
+                titleIncludes?: string;
+                textIncludes?: string;
+                ref?: string;
+                state?: "hidden" | "visible";
+            };
+        } | {
+            action: "wait";
+            condition: "hidden" | "text" | "visible" | "page_idle";
+            value?: string;
+            target?: {
+                role: string;
+                name?: string;
+                nameIncludes?: string;
+            };
+            timeoutMs?: number;
+        })[];
+        description?: string;
+    }>;
+    save(input: {
+        definition: unknown;
+        status?: BrowserAutomationStatus;
+        expectedId?: string;
+    }): BrowserAutomation;
+    remove(id: string): boolean;
+    startRun(automationId: string, inputs: Record<string, unknown>): BrowserAutomationRun;
+    cancel(runId: string): boolean;
+    shutdown(): Promise<void>;
+    runAndWait(automationId: string, inputs: Record<string, unknown>, signal?: AbortSignal): Promise<BrowserAutomationRun>;
+    private addEvent;
+    private execute;
+}