@xopcai/xopc 0.0.435 → 0.0.437

package/dist/src/computer/errors.d.ts

@@ -1,5 +1,175 @@
 import type { ComputerWindow } from '@xopcai/computer-control-contract';
 import { z } from 'zod';
+export declare const ComputerValidationSchema: z.ZodObject<{
+    action: z.ZodEnum<{
+        type: "type";
+        key: "key";
+        unknown: "unknown";
+        answer: "answer";
+        wait: "wait";
+        typeText: "typeText";
+        batch: "batch";
+        terminate: "terminate";
+        activate: "activate";
+        showMenu: "showMenu";
+        click: "click";
+        drag: "drag";
+        setValue: "setValue";
+        pressKeys: "pressKeys";
+        scroll: "scroll";
+        activateSequence: "activateSequence";
+        interact: "interact";
+        takeover: "takeover";
+        finished: "finished";
+        button_plan: "button_plan";
+        activate_sequence: "activate_sequence";
+        show_menu: "show_menu";
+        set_value: "set_value";
+        left_click: "left_click";
+        right_click: "right_click";
+        double_click: "double_click";
+        hscroll: "hscroll";
+    }>;
+    stage: z.ZodEnum<{
+        plan: "plan";
+        schema: "schema";
+        converted_action: "converted_action";
+        typing_target: "typing_target";
+        keyboard: "keyboard";
+    }>;
+    issues: z.ZodArray<z.ZodObject<{
+        path: z.ZodArray<z.ZodUnion<readonly [z.ZodEnum<{
+            reason: "reason";
+            keys: "keys";
+            value: "value";
+            name: "name";
+            time: "time";
+            from: "from";
+            action: "action";
+            when: "when";
+            label: "label";
+            text: "text";
+            kind: "kind";
+            status: "status";
+            durationMs: "durationMs";
+            role: "role";
+            to: "to";
+            actions: "actions";
+            count: "count";
+            x: "x";
+            y: "y";
+            point: "point";
+            arguments: "arguments";
+            ref: "ref";
+            button: "button";
+            deltaX: "deltaX";
+            deltaY: "deltaY";
+            refs: "refs";
+            pixels: "pixels";
+            steps: "steps";
+            coordinate: "coordinate";
+            unknown_field: "unknown_field";
+            proposal: "proposal";
+            claimedSuccess: "claimedSuccess";
+        }>, z.ZodNumber]>>;
+        code: z.ZodEnum<{
+            custom: "custom";
+            invalid_type: "invalid_type";
+            unrecognized_keys: "unrecognized_keys";
+            invalid_union: "invalid_union";
+            invalid_value: "invalid_value";
+            invalid_format: "invalid_format";
+            too_big: "too_big";
+            too_small: "too_small";
+            not_multiple_of: "not_multiple_of";
+            missing_point: "missing_point";
+            outside_frame: "outside_frame";
+            editable_target_missing: "editable_target_missing";
+            editable_target_ambiguous: "editable_target_ambiguous";
+            invalid_context: "invalid_context";
+            unsupported_key: "unsupported_key";
+            plan_not_grounded: "plan_not_grounded";
+        }>;
+        action: z.ZodEnum<{
+            type: "type";
+            key: "key";
+            unknown: "unknown";
+            answer: "answer";
+            wait: "wait";
+            typeText: "typeText";
+            batch: "batch";
+            terminate: "terminate";
+            activate: "activate";
+            showMenu: "showMenu";
+            click: "click";
+            drag: "drag";
+            setValue: "setValue";
+            pressKeys: "pressKeys";
+            scroll: "scroll";
+            activateSequence: "activateSequence";
+            interact: "interact";
+            takeover: "takeover";
+            finished: "finished";
+            button_plan: "button_plan";
+            activate_sequence: "activate_sequence";
+            show_menu: "show_menu";
+            set_value: "set_value";
+            left_click: "left_click";
+            right_click: "right_click";
+            double_click: "double_click";
+            hscroll: "hscroll";
+        }>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const ComputerStabilitySchema: z.ZodObject<{
+    stage: z.ZodEnum<{
+        initial_capture: "initial_capture";
+        pre_dispatch: "pre_dispatch";
+        post_action: "post_action";
+    }>;
+    samples: z.ZodNumber;
+    action: z.ZodOptional<z.ZodEnum<{
+        type: "type";
+        key: "key";
+        unknown: "unknown";
+        answer: "answer";
+        wait: "wait";
+        typeText: "typeText";
+        batch: "batch";
+        terminate: "terminate";
+        activate: "activate";
+        showMenu: "showMenu";
+        click: "click";
+        drag: "drag";
+        setValue: "setValue";
+        pressKeys: "pressKeys";
+        scroll: "scroll";
+        activateSequence: "activateSequence";
+        interact: "interact";
+        takeover: "takeover";
+        finished: "finished";
+        button_plan: "button_plan";
+        activate_sequence: "activate_sequence";
+        show_menu: "show_menu";
+        set_value: "set_value";
+        left_click: "left_click";
+        right_click: "right_click";
+        double_click: "double_click";
+        hscroll: "hscroll";
+    }>>;
+    changes: z.ZodArray<z.ZodEnum<{
+        window_identity: "window_identity";
+        window_geometry: "window_geometry";
+        image_dimensions: "image_dimensions";
+        accessibility_structure: "accessibility_structure";
+        accessibility_text: "accessibility_text";
+        accessibility_state: "accessibility_state";
+        accessibility_geometry: "accessibility_geometry";
+        visual_or_unexposed_state: "visual_or_unexposed_state";
+        deadline: "deadline";
+    }>>;
+    changedElementIndices: z.ZodArray<z.ZodNumber>;
+}, z.core.$strict>;
 export declare const ComputerDiagnosticSchema: z.ZodObject<{
     errorCode: z.ZodString;
     phase: z.ZodEnum<{
@@ -17,6 +187,176 @@ export declare const ComputerDiagnosticSchema: z.ZodObject<{
         invalid_envelope: "invalid_envelope";
         output_limit: "output_limit";
     }>>;
+    validation: z.ZodOptional<z.ZodObject<{
+        action: z.ZodEnum<{
+            type: "type";
+            key: "key";
+            unknown: "unknown";
+            answer: "answer";
+            wait: "wait";
+            typeText: "typeText";
+            batch: "batch";
+            terminate: "terminate";
+            activate: "activate";
+            showMenu: "showMenu";
+            click: "click";
+            drag: "drag";
+            setValue: "setValue";
+            pressKeys: "pressKeys";
+            scroll: "scroll";
+            activateSequence: "activateSequence";
+            interact: "interact";
+            takeover: "takeover";
+            finished: "finished";
+            button_plan: "button_plan";
+            activate_sequence: "activate_sequence";
+            show_menu: "show_menu";
+            set_value: "set_value";
+            left_click: "left_click";
+            right_click: "right_click";
+            double_click: "double_click";
+            hscroll: "hscroll";
+        }>;
+        stage: z.ZodEnum<{
+            plan: "plan";
+            schema: "schema";
+            converted_action: "converted_action";
+            typing_target: "typing_target";
+            keyboard: "keyboard";
+        }>;
+        issues: z.ZodArray<z.ZodObject<{
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodEnum<{
+                reason: "reason";
+                keys: "keys";
+                value: "value";
+                name: "name";
+                time: "time";
+                from: "from";
+                action: "action";
+                when: "when";
+                label: "label";
+                text: "text";
+                kind: "kind";
+                status: "status";
+                durationMs: "durationMs";
+                role: "role";
+                to: "to";
+                actions: "actions";
+                count: "count";
+                x: "x";
+                y: "y";
+                point: "point";
+                arguments: "arguments";
+                ref: "ref";
+                button: "button";
+                deltaX: "deltaX";
+                deltaY: "deltaY";
+                refs: "refs";
+                pixels: "pixels";
+                steps: "steps";
+                coordinate: "coordinate";
+                unknown_field: "unknown_field";
+                proposal: "proposal";
+                claimedSuccess: "claimedSuccess";
+            }>, z.ZodNumber]>>;
+            code: z.ZodEnum<{
+                custom: "custom";
+                invalid_type: "invalid_type";
+                unrecognized_keys: "unrecognized_keys";
+                invalid_union: "invalid_union";
+                invalid_value: "invalid_value";
+                invalid_format: "invalid_format";
+                too_big: "too_big";
+                too_small: "too_small";
+                not_multiple_of: "not_multiple_of";
+                missing_point: "missing_point";
+                outside_frame: "outside_frame";
+                editable_target_missing: "editable_target_missing";
+                editable_target_ambiguous: "editable_target_ambiguous";
+                invalid_context: "invalid_context";
+                unsupported_key: "unsupported_key";
+                plan_not_grounded: "plan_not_grounded";
+            }>;
+            action: z.ZodEnum<{
+                type: "type";
+                key: "key";
+                unknown: "unknown";
+                answer: "answer";
+                wait: "wait";
+                typeText: "typeText";
+                batch: "batch";
+                terminate: "terminate";
+                activate: "activate";
+                showMenu: "showMenu";
+                click: "click";
+                drag: "drag";
+                setValue: "setValue";
+                pressKeys: "pressKeys";
+                scroll: "scroll";
+                activateSequence: "activateSequence";
+                interact: "interact";
+                takeover: "takeover";
+                finished: "finished";
+                button_plan: "button_plan";
+                activate_sequence: "activate_sequence";
+                show_menu: "show_menu";
+                set_value: "set_value";
+                left_click: "left_click";
+                right_click: "right_click";
+                double_click: "double_click";
+                hscroll: "hscroll";
+            }>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    stability: z.ZodOptional<z.ZodObject<{
+        stage: z.ZodEnum<{
+            initial_capture: "initial_capture";
+            pre_dispatch: "pre_dispatch";
+            post_action: "post_action";
+        }>;
+        samples: z.ZodNumber;
+        action: z.ZodOptional<z.ZodEnum<{
+            type: "type";
+            key: "key";
+            unknown: "unknown";
+            answer: "answer";
+            wait: "wait";
+            typeText: "typeText";
+            batch: "batch";
+            terminate: "terminate";
+            activate: "activate";
+            showMenu: "showMenu";
+            click: "click";
+            drag: "drag";
+            setValue: "setValue";
+            pressKeys: "pressKeys";
+            scroll: "scroll";
+            activateSequence: "activateSequence";
+            interact: "interact";
+            takeover: "takeover";
+            finished: "finished";
+            button_plan: "button_plan";
+            activate_sequence: "activate_sequence";
+            show_menu: "show_menu";
+            set_value: "set_value";
+            left_click: "left_click";
+            right_click: "right_click";
+            double_click: "double_click";
+            hscroll: "hscroll";
+        }>>;
+        changes: z.ZodArray<z.ZodEnum<{
+            window_identity: "window_identity";
+            window_geometry: "window_geometry";
+            image_dimensions: "image_dimensions";
+            accessibility_structure: "accessibility_structure";
+            accessibility_text: "accessibility_text";
+            accessibility_state: "accessibility_state";
+            accessibility_geometry: "accessibility_geometry";
+            visual_or_unexposed_state: "visual_or_unexposed_state";
+            deadline: "deadline";
+        }>>;
+        changedElementIndices: z.ZodArray<z.ZodNumber>;
+    }, z.core.$strict>>;
     httpStatus: z.ZodOptional<z.ZodNumber>;
     requestId: z.ZodOptional<z.ZodString>;
     serviceErrorCode: z.ZodOptional<z.ZodEnum<{

package/dist/src/computer/errors.js

@@ -1,5 +1,120 @@
 import { z } from "zod";
 //#region src/computer/errors.ts
+const ValidationActionSchema = z.enum([
+	"unknown",
+	"activate",
+	"activate_sequence",
+	"batch",
+	"show_menu",
+	"set_value",
+	"left_click",
+	"right_click",
+	"double_click",
+	"type",
+	"key",
+	"scroll",
+	"hscroll",
+	"wait",
+	"terminate",
+	"answer",
+	"interact",
+	"showMenu",
+	"click",
+	"drag",
+	"setValue",
+	"typeText",
+	"pressKeys",
+	"activateSequence",
+	"finished",
+	"takeover",
+	"button_plan"
+]);
+const ComputerValidationSchema = z.object({
+	action: ValidationActionSchema,
+	stage: z.enum([
+		"schema",
+		"converted_action",
+		"typing_target",
+		"keyboard",
+		"plan"
+	]),
+	issues: z.array(z.object({
+		path: z.array(z.union([z.enum([
+			"unknown_field",
+			"name",
+			"arguments",
+			"proposal",
+			"action",
+			"kind",
+			"actions",
+			"refs",
+			"ref",
+			"text",
+			"coordinate",
+			"keys",
+			"pixels",
+			"time",
+			"status",
+			"point",
+			"x",
+			"y",
+			"button",
+			"count",
+			"from",
+			"to",
+			"deltaX",
+			"deltaY",
+			"durationMs",
+			"claimedSuccess",
+			"reason",
+			"steps",
+			"label",
+			"when",
+			"role",
+			"value"
+		]), z.number().int().min(0).max(16384)])).max(10),
+		code: z.enum([
+			"invalid_type",
+			"invalid_value",
+			"invalid_union",
+			"unrecognized_keys",
+			"too_small",
+			"too_big",
+			"invalid_format",
+			"not_multiple_of",
+			"custom",
+			"missing_point",
+			"outside_frame",
+			"editable_target_missing",
+			"editable_target_ambiguous",
+			"invalid_context",
+			"unsupported_key",
+			"plan_not_grounded"
+		]),
+		action: ValidationActionSchema
+	}).strict()).max(4)
+}).strict();
+const ComputerStabilitySchema = z.object({
+	stage: z.enum([
+		"initial_capture",
+		"pre_dispatch",
+		"post_action"
+	]),
+	samples: z.number().int().min(1).max(6),
+	action: ValidationActionSchema.optional(),
+	changes: z.array(z.enum([
+		"window_identity",
+		"window_geometry",
+		"image_dimensions",
+		"accessibility_structure",
+		"accessibility_text",
+		"accessibility_state",
+		"accessibility_geometry",
+		"visual_or_unexposed_state",
+		"deadline"
+	])).max(9),
+	changedElementIndices: z.array(z.number().int().nonnegative().max(16384)).max(8)
+}).strict();
 const ComputerDiagnosticSchema = z.object({
 	errorCode: z.string().regex(/^COMPUTER_[A-Z_0-9]+$/).max(100),
 	phase: z.enum([
@@ -17,6 +132,8 @@ const ComputerDiagnosticSchema = z.object({
 		"invalid_envelope",
 		"output_limit"
 	]).optional(),
+	validation: ComputerValidationSchema.optional(),
+	stability: ComputerStabilitySchema.optional(),
 	httpStatus: z.number().int().min(100).max(599).optional(),
 	requestId: z.string().regex(/^(?:[a-f0-9]{32}|[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12})$/i).optional(),
 	serviceErrorCode: z.enum([
@@ -39,7 +156,7 @@ var ComputerOperationError = class extends Error {
 };
 /** Only typed, bounded diagnostics cross the endpoint transport; never forward raw exceptions. */
 function computerDiagnostic(error) {
-	if (!(error instanceof Error) || error.message.length > 1e3) return;
+	if (!(error instanceof Error) || error.message.length > 4096) return;
 	try {
 		return ComputerDiagnosticSchema.safeParse(JSON.parse(error.message)).data;
 	} catch {
@@ -133,7 +250,7 @@ function computerRecovery(code) {
 		case "COMPUTER_SEMANTIC_ACTION_UNSUPPORTED": return "The native element reference or action is unavailable for this window. No automatic coordinate fallback. Reopen and observe fresh evidence before choosing a different action; never reuse an old reference or replay an uncertain input.";
 		case "COMPUTER_SEMANTIC_ACTION_UNCONFIRMED": return "The native action returned uncertain execution evidence. Inspect the application before continuing. Do not repeat it or fall back to coordinates; its effect may already have occurred.";
 		case "COMPUTER_INVALID_MODEL_OUTPUT":
-		case "COMPUTER_EXPECTED_SINGLE_ACTION": return "The GUI model returned an invalid action after bounded format correction. No input from this prediction was dispatched. Report validationReason and diagnosticId; do not guess coordinates, replay the action or change providers.";
+		case "COMPUTER_EXPECTED_SINGLE_ACTION": return "The GUI model returned an invalid action after bounded format correction. No input from this prediction was dispatched. Report validationReason, validation (action, stage and field issues) and diagnosticId; do not guess coordinates, replay the action or change providers.";
 		case "COMPUTER_MODEL_HTTP_400": return "The configured model service rejected the request. No input was dispatched from this model request. Report serviceErrorCode, requestId and diagnosticId; check the model request format and input/output limits before reopening. Do not automatically retry or change providers.";
 		case "COMPUTER_RELEASE_UNCONFIRMED": return "Desktop release was not confirmed. Do not switch to other tools. Stop desktop control locally or restore the endpoint connection, then call close again to confirm release.";
 		case "COMPUTER_DRIVER_CLEANUP_UNCONFIRMED": return "The private desktop driver did not confirm shutdown. The old grant is revoked and a new driver cannot start. Stop desktop control locally and confirm cleanup before reopening; never replay the previous input.";
@@ -143,7 +260,7 @@ function computerRecovery(code) {
 		case "COMPUTER_MODEL_HTTP_429": return "The configured model service is rate-limited. No input was dispatched from this model request. Check the service quota and retry only after it resets; do not automatically change providers.";
 		case "COMPUTER_MODEL_HTTP_409": return "The pinned model deployment changed. No input was dispatched from this model request. Refresh the model catalog and reopen after reviewing the configured screenshot recipient.";
 		case "COMPUTER_OBSERVATION_CHANGED": return "No input was dispatched. Observe the changed window and re-plan with fresh evidence; the old proposed action was discarded.";
-		case "COMPUTER_UI_UNSTABLE": return "No input was dispatched by the unstable attempts. The window changed during prediction and the session rescue allowance is unavailable or exhausted. Wait for a local state change, then discover/open again; never replay old coordinates.";
+		case "COMPUTER_UI_UNSTABLE": return "Report stability.stage, changes and samples with diagnosticId. initial_capture means no stable observation was obtained; pre_dispatch means the proposed input was not dispatched and rescue is exhausted; post_action means an input completed but its resulting view did not settle. Check receipts and completedInputs for earlier inputs; do not replay them. Wait for a local state change before reopening; never reuse old coordinates.";
 		case "COMPUTER_NO_PROGRESS": return "Repeated inputs produced no observed progress. Inspect the actual outcome and change the plan; do not keep clicking or repeat a potentially submitted action.";
 		case "COMPUTER_INVALID_INPUT": return "Read tool_manual(computer_use) and use only the fields documented for this operation. Start with discover; open requires appRef, mode and prepare.";
 		case "COMPUTER_APP_INSTANCE_AMBIGUOUS": return "Multiple processes for this app are running. Ask the user to keep the intended app instance open; do not guess a process.";
@@ -152,7 +269,7 @@ function computerRecovery(code) {
 		case "COMPUTER_APP_NOT_FOUND": return "Discover again. If absent, ask the user to install the app; do not guess an identifier.";
 		case "COMPUTER_APP_NOT_AUTHORIZED": return "This application has not been authorized in the local Computer Use settings. Tell the user where to configure access. Do not request a chat approval or try another control route.";
 		case "COMPUTER_APP_NOT_RUNNING": return "Open with prepare=true only if the user requested launching the app; otherwise ask them to open it.";
-		case "COMPUTER_WINDOW_OTHER_SPACE": return "The target window is on another macOS desktop/Space. Ask the user to leave full screen or move the target and chat onto the same desktop with both visible. Clicking the target then switching back to a different Space does not fix this. Do not retry unchanged or bypass visibility checks.";
+		case "COMPUTER_WINDOW_OTHER_SPACE": return "The target window is on another macOS desktop/Space and automatic exact-window recovery is unavailable or did not succeed. Current desktop hosts temporarily let chat follow Spaces and reveal the existing authorized window without replaying input. Check host support and the returned failure before asking for a manual workspace change; do not retry unchanged or bypass visibility checks.";
 		case "COMPUTER_WINDOW_REQUIRED": return "No visible target window. If the task permits bringing the app forward, open with prepare=true; otherwise ask the user to show the window. If preparation already failed, require a local state change before retrying.";
 		case "COMPUTER_DRIVER_BRING_TO_FRONT_REFUSED": return "The native driver refused to activate the app window. Ask the user to bring the intended window to the foreground locally, then discover and open it with prepare=false. Do not repeat prepare=true or use another control route.";
 		case "COMPUTER_WINDOW_AMBIGUOUS": return "Choose a returned windowRef only when its title matches the task. Otherwise ask the user using window titles, not IDs.";
@@ -166,4 +283,4 @@ function computerRecovery(code) {
 	}
 }
 //#endregion
-export { ComputerDiagnosticSchema, ComputerOperationError, ComputerRecoverySchema, ComputerTargetError, computerDiagnostic, computerRecovery, computerRecoveryDirective };
+export { ComputerDiagnosticSchema, ComputerOperationError, ComputerRecoverySchema, ComputerStabilitySchema, ComputerTargetError, ComputerValidationSchema, computerDiagnostic, computerRecovery, computerRecoveryDirective };