@xopcai/xopc 0.0.435 → 0.0.437

package/dist/src/computer/stability-diagnostics.d.ts

@@ -0,0 +1,23 @@
+import type { ComputerTarget } from '@xopcai/computer-control-contract';
+import type { z } from 'zod';
+import type { ComputerDiagnosticSchema, ComputerStabilitySchema } from './errors.js';
+type Stability = z.infer<typeof ComputerStabilitySchema>;
+type Snapshot = {
+    target: ComputerTarget;
+    summary: string;
+    stateDigest: string;
+    imageWidth: number;
+    imageHeight: number;
+};
+/** Compare privately; retain only fixed change categories and bounded element positions, never values or hashes. */
+export declare class ComputerStabilityTracker {
+    private readonly stage;
+    private readonly action?;
+    private readonly changes;
+    private readonly indices;
+    constructor(stage: Stability['stage'], action?: Stability['action']);
+    deadline(): void;
+    compare(before: Snapshot, after: Snapshot): void;
+    diagnostic(errorCode: string, samples: number): z.infer<typeof ComputerDiagnosticSchema>;
+}
+export {};

package/dist/src/computer/stability-diagnostics.js

@@ -0,0 +1,71 @@
+import { randomUUID } from "node:crypto";
+//#region src/computer/stability-diagnostics.ts
+/** Compare privately; retain only fixed change categories and bounded element positions, never values or hashes. */
+var ComputerStabilityTracker = class {
+	changes = /* @__PURE__ */ new Set();
+	indices = /* @__PURE__ */ new Set();
+	constructor(stage, action) {
+		this.stage = stage;
+		this.action = action;
+	}
+	deadline() {
+		this.changes.add("deadline");
+	}
+	compare(before, after) {
+		const a = before.target, b = after.target;
+		if (a.appId !== b.appId || a.pid !== b.pid || a.processIdentity !== b.processIdentity || a.windowId !== b.windowId) this.changes.add("window_identity");
+		if (a.geometryRevision !== b.geometryRevision || a.width !== b.width || a.height !== b.height) this.changes.add("window_geometry");
+		if (before.imageWidth !== after.imageWidth || before.imageHeight !== after.imageHeight) this.changes.add("image_dimensions");
+		if (before.summary !== after.summary) try {
+			const left = JSON.parse(before.summary), right = JSON.parse(after.summary);
+			const ae = Array.isArray(left.elements) ? left.elements : [], be = Array.isArray(right.elements) ? right.elements : [];
+			if (ae.length !== be.length) this.changes.add("accessibility_structure");
+			if (left.text !== right.text) this.changes.add("accessibility_text");
+			const groups = {
+				accessibility_structure: [
+					"role",
+					"ref",
+					"depth",
+					"parent_index"
+				],
+				accessibility_text: [
+					"label",
+					"value",
+					"value_description"
+				],
+				accessibility_state: [
+					"enabled",
+					"selected",
+					"keyboardFocused",
+					"inputAllowed",
+					"semanticActions",
+					"in_web_content"
+				],
+				accessibility_geometry: ["bounds", "frame"]
+			};
+			for (let i = 0; i < Math.max(ae.length, be.length); i++) {
+				if (JSON.stringify(ae[i]) !== JSON.stringify(be[i]) && this.indices.size < 8 && i <= 16384) this.indices.add(i);
+				for (const [category, fields] of Object.entries(groups)) if (fields.some((field) => JSON.stringify(ae[i]?.[field]) !== JSON.stringify(be[i]?.[field]))) this.changes.add(category);
+			}
+		} catch {
+			this.changes.add("accessibility_structure");
+		}
+		if (before.stateDigest !== after.stateDigest && before.summary === after.summary && JSON.stringify(a) === JSON.stringify(b) && before.imageWidth === after.imageWidth && before.imageHeight === after.imageHeight) this.changes.add("visual_or_unexposed_state");
+	}
+	diagnostic(errorCode, samples) {
+		return {
+			errorCode,
+			phase: this.stage === "initial_capture" ? "observe" : "dispatch",
+			diagnosticId: randomUUID(),
+			stability: {
+				stage: this.stage,
+				samples,
+				...this.action ? { action: this.action } : {},
+				changes: [...this.changes],
+				changedElementIndices: [...this.indices]
+			}
+		};
+	}
+};
+//#endregion
+export { ComputerStabilityTracker };

package/dist/src/computer/validation-diagnostics.d.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+import { ComputerValidationSchema } from './errors.js';
+type Validation = z.infer<typeof ComputerValidationSchema>;
+/** Project only allowlisted metadata; Zod messages, values and arbitrary property names may contain private data. */
+export declare function modelValidation(value: unknown, stage: Validation['stage'], error?: unknown, failure?: {
+    path: (string | number)[];
+    code: Validation['issues'][number]['code'];
+}): Validation;
+export {};

package/dist/src/computer/validation-diagnostics.js

@@ -0,0 +1,54 @@
+import { ComputerValidationSchema } from "./errors.js";
+import { z } from "zod";
+//#region src/computer/validation-diagnostics.ts
+const Field = ComputerValidationSchema.shape.issues.element.shape.path.element;
+const Action = ComputerValidationSchema.shape.action;
+const Code = ComputerValidationSchema.shape.issues.element.shape.code;
+function actionName(value) {
+	if (!value || typeof value !== "object") return "unknown";
+	const node = value;
+	return Action.safeParse(typeof node.action === "string" ? node.action : node.kind).data ?? "unknown";
+}
+/** Project only allowlisted metadata; Zod messages, values and arbitrary property names may contain private data. */
+function modelValidation(value, stage, error, failure) {
+	const root = value && typeof value === "object" ? value : {};
+	const payload = root.arguments && typeof root.arguments === "object" ? root.arguments : root;
+	const proposal = payload.proposal && typeof payload.proposal === "object" ? payload.proposal : payload;
+	const action = actionName(typeof proposal.action === "object" ? proposal.action : proposal);
+	const issues = [];
+	const append = (path, code) => {
+		if (issues.length >= 4) return;
+		let node = value;
+		let nestedAction = action;
+		for (const part of path) {
+			if (!node || typeof node !== "object") break;
+			node = node[part];
+			const candidate = actionName(node);
+			if (candidate !== "unknown") nestedAction = candidate;
+		}
+		issues.push({
+			path: path.slice(0, 10).map((part) => Field.safeParse(part).data ?? "unknown_field"),
+			code: Code.safeParse(code).data ?? "invalid_value",
+			action: nestedAction
+		});
+	};
+	const branchScore = (list) => list.length + list.filter((issue) => issue.code === "invalid_value" && ["kind", "action"].includes(String(issue.path.at(-1)))).length * 100;
+	const visit = (list, prefix = []) => {
+		for (const issue of list) if (issue.code === "invalid_union" && issue.errors.length) visit([...issue.errors].sort((a, b) => branchScore(a) - branchScore(b))[0], [...prefix, ...issue.path]);
+		else if (issue.code === "unrecognized_keys") for (const key of issue.keys) append([
+			...prefix,
+			...issue.path,
+			key
+		], issue.code);
+		else append([...prefix, ...issue.path], issue.code);
+	};
+	if (error instanceof z.ZodError) visit(error.issues);
+	if (failure) append(failure.path, failure.code);
+	return {
+		action,
+		stage,
+		issues
+	};
+}
+//#endregion
+export { modelValidation };

package/dist/src/providers/model-response.js

@@ -1,5 +1,6 @@
 //#region src/providers/model-response.ts
 const TRANSIENT_PROVIDER_ERROR_SUBSTRINGS = [
+	"connection error",
 	"fetch failed",
 	"econnreset",
 	"econnrefused",

package/dist/src/realtime/runtime.js

@@ -195,15 +195,23 @@ var RealtimeRuntime = class {
 					const output = item.view === "compact" ? compactRunEvent(event) : event;
 					if (output) writer.enqueue(output);
 				});
-				subscriptions.set(item.topic, handle);
 				writer.enqueue(serverMessage("realtime.subscribed", {
 					topic: item.topic,
 					cursor: handle.cursor
 				}), "critical");
-				for (const message of handle.initial) {
-					const output = item.view === "compact" ? compactRunEvent(message) : message;
-					if (output) writer.enqueue(output);
-				}
+				const cancelReplay = writer.enqueueReplay((function* () {
+					for (const message of handle.initial) {
+						const output = item.view === "compact" ? compactRunEvent(message) : message;
+						if (output) yield output;
+					}
+				})());
+				subscriptions.set(item.topic, {
+					...handle,
+					unsubscribe: () => {
+						cancelReplay();
+						handle.unsubscribe();
+					}
+				});
 			}
 			return true;
 		};

package/dist/src/realtime/writer.d.ts

@@ -8,8 +8,15 @@ export declare class RealtimeSocketWriter {
     private sending;
     private closed;
     private retryTimer?;
+    private stallTimer?;
     constructor(socket: WebSocket);
     enqueue(message: ServerRealtimeMessage, priority?: 'critical' | 'normal'): boolean;
+    /** Serialize replay only as the socket drains; live messages stay behind the replay. */
+    enqueueReplay(messages: Iterable<ServerRealtimeMessage>): () => void;
     close(): void;
+    private fail;
+    private serialize;
+    private watchForStall;
+    private next;
     private flush;
 }

package/dist/src/realtime/writer.js

@@ -1,7 +1,12 @@
+import { createLogger } from "../utils/logger/index.js";
+import { init_logger } from "../utils/logger.js";
 //#region src/realtime/writer.ts
+init_logger();
+const log = createLogger("RealtimeSocketWriter");
 const SOFT_BUFFERED_BYTES = 512 * 1024;
-const HARD_BUFFERED_BYTES = 4 * 1024 * 1024;
-const MAX_QUEUED_BYTES = 2 * 1024 * 1024;
+const MAX_EVENT_BYTES = 2 * 1024 * 1024;
+const MAX_QUEUED_BYTES = 16 * 1024 * 1024;
+const DELIVERY_STALL_MS = 15e3;
 var RealtimeSocketWriter = class {
 	critical = [];
 	normal = [];
@@ -9,80 +14,141 @@ var RealtimeSocketWriter = class {
 	sending = false;
 	closed = false;
 	retryTimer;
+	stallTimer;
 	constructor(socket) {
 		this.socket = socket;
 	}
 	enqueue(message, priority = "normal") {
 		if (this.closed || this.socket.readyState !== 1) return false;
-		let data;
-		try {
-			data = JSON.stringify(message);
-		} catch {
-			this.socket.close(1011, "Realtime message serialization failed");
-			this.close();
-			return false;
-		}
-		const item = {
-			data,
-			bytes: Buffer.byteLength(data)
-		};
-		if (item.bytes > MAX_QUEUED_BYTES) {
-			this.socket.close(1009, "Realtime event exceeds delivery limit");
-			this.close();
-			return false;
-		}
+		const item = this.serialize(message);
+		if (!item) return false;
 		if (this.queuedBytes + item.bytes > MAX_QUEUED_BYTES) {
-			this.socket.close(4413, "Realtime client is too slow");
-			this.close();
+			this.fail(4413, "Realtime delivery queue limit exceeded", {
+				eventBytes: item.bytes,
+				...message.kind === "realtime.event" ? {
+					topic: message.payload.topic,
+					event: message.payload.event
+				} : {}
+			});
 			return false;
 		}
 		this.queuedBytes += item.bytes;
 		(priority === "critical" ? this.critical : this.normal).push(item);
 		this.flush();
-		return true;
+		return !this.closed;
+	}
+	/** Serialize replay only as the socket drains; live messages stay behind the replay. */
+	enqueueReplay(messages) {
+		if (this.closed || this.socket.readyState !== 1) return () => {};
+		const item = { iterator: messages[Symbol.iterator]() };
+		this.normal.push(item);
+		this.flush();
+		return () => {
+			const index = this.normal.indexOf(item);
+			if (index >= 0) this.normal.splice(index, 1);
+			item.iterator.return?.();
+		};
 	}
 	close() {
 		if (this.closed) return;
 		this.closed = true;
 		if (this.retryTimer) clearTimeout(this.retryTimer);
+		if (this.stallTimer) clearTimeout(this.stallTimer);
 		this.retryTimer = void 0;
+		this.stallTimer = void 0;
+		for (const item of this.normal) if ("iterator" in item) item.iterator.return?.();
 		this.critical.length = 0;
 		this.normal.length = 0;
 		this.queuedBytes = 0;
 	}
+	fail(code, reason, fields = {}) {
+		log.warn({
+			...fields,
+			code,
+			queuedBytes: this.queuedBytes,
+			bufferedBytes: this.socket.bufferedAmount,
+			pendingItems: this.normal.length + this.critical.length
+		}, reason);
+		this.close();
+		this.socket.close(code, reason);
+	}
+	serialize(message) {
+		let data;
+		try {
+			data = JSON.stringify(message);
+		} catch {
+			this.fail(1011, "Realtime message serialization failed");
+			return;
+		}
+		const bytes = Buffer.byteLength(data);
+		if (bytes > MAX_EVENT_BYTES) {
+			this.fail(1009, "Realtime event exceeds delivery limit", {
+				eventBytes: bytes,
+				...message.kind === "realtime.event" ? {
+					topic: message.payload.topic,
+					event: message.payload.event
+				} : {}
+			});
+			return;
+		}
+		return {
+			data,
+			bytes
+		};
+	}
+	watchForStall() {
+		if (!this.stallTimer) this.stallTimer = setTimeout(() => this.fail(4413, "Realtime delivery stalled"), DELIVERY_STALL_MS);
+	}
+	next() {
+		const critical = this.critical.shift();
+		if (critical) return critical;
+		while (this.normal.length) {
+			const head = this.normal[0];
+			if (!("iterator" in head)) return this.normal.shift();
+			const next = head.iterator.next();
+			if (next.done) {
+				this.normal.shift();
+				continue;
+			}
+			const item = this.serialize(next.value);
+			if (item) this.queuedBytes += item.bytes;
+			return item;
+		}
+	}
 	flush() {
 		if (this.closed || this.sending || this.socket.readyState !== 1) return;
-		if (this.socket.bufferedAmount > HARD_BUFFERED_BYTES) {
-			this.socket.close(4413, "Realtime client is too slow");
-			this.close();
+		if (this.socket.bufferedAmount > MAX_QUEUED_BYTES) {
+			this.fail(4413, "Realtime socket buffer limit exceeded");
 			return;
 		}
 		if (this.socket.bufferedAmount > SOFT_BUFFERED_BYTES) {
+			this.watchForStall();
 			if (!this.retryTimer) this.retryTimer = setTimeout(() => {
 				this.retryTimer = void 0;
 				this.flush();
 			}, 10);
 			return;
 		}
-		const item = this.critical.shift() ?? this.normal.shift();
+		const item = this.next();
 		if (!item) return;
 		this.sending = true;
+		this.watchForStall();
 		try {
 			this.socket.send(item.data, (error) => {
 				if (this.closed) return;
 				this.sending = false;
 				this.queuedBytes -= item.bytes;
+				if (this.stallTimer) clearTimeout(this.stallTimer);
+				this.stallTimer = void 0;
 				if (error) {
-					this.socket.close(1011, "Realtime delivery failed");
-					this.close();
+					this.fail(1011, "Realtime delivery failed");
 					return;
 				}
 				this.flush();
 			});
 		} catch {
 			this.sending = false;
-			this.close();
-			this.socket.close(1011, "Realtime delivery failed");
+			this.fail(1011, "Realtime delivery failed");
 		}
 	}
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xopcai/xopc",
-  "version": "0.0.435",
+  "version": "0.0.437",
   "description": "An open-source AI assistant for work and everyday life. Remembers context and helps you get things done. Local-first, on a computer you choose.",
   "type": "module",
   "main": "dist/src/index.js",