@zhanguym/chatroom 1.0.0

package/dist/plugins/computer/computer-protocol.js

@@ -0,0 +1,74 @@
+import { z } from "zod";
+import { ChatRoomError } from "#core/errors/chatroom-error";
+import { computerActionResultSchema, computerNativeStatusSchema, computerSnapshotSchema, } from "./computer-schemas.js";
+export const COMPUTER_NATIVE_PROTOCOL_VERSION = 1;
+const responseEnvelopeSchema = z
+    .object({
+    protocol: z.literal(COMPUTER_NATIVE_PROTOCOL_VERSION),
+    id: z.string().min(1),
+    result: z.unknown().optional(),
+    error: z
+        .object({
+        code: z.string().optional(),
+        message: z.string(),
+    })
+        .strict()
+        .optional(),
+})
+    .strict()
+    .refine((value) => (value.result === undefined) !== (value.error === undefined), {
+    message: "Native response must contain exactly one of result or error",
+});
+export function parseNativeEnvelope(value) {
+    const parsed = responseEnvelopeSchema.safeParse(value);
+    if (!parsed.success) {
+        throw new ChatRoomError("INTERNAL", "Computer helper returned an invalid protocol response", { issues: parsed.error.issues });
+    }
+    return {
+        id: parsed.data.id,
+        ...(parsed.data.result === undefined ? {} : { result: parsed.data.result }),
+        ...(parsed.data.error === undefined
+            ? {}
+            : {
+                error: {
+                    message: parsed.data.error.message,
+                    ...(parsed.data.error.code === undefined
+                        ? {}
+                        : { code: parsed.data.error.code }),
+                },
+            }),
+    };
+}
+export function parseNativeResult(method, value) {
+    const schema = method === "status" || method === "requestPermission"
+        ? computerNativeStatusSchema
+        : method === "snapshot"
+            ? computerSnapshotSchema
+            : computerActionResultSchema;
+    const parsed = schema.safeParse(value);
+    if (!parsed.success) {
+        throw new ChatRoomError("INTERNAL", `Computer helper returned an invalid ${method} result`, { issues: parsed.error.issues });
+    }
+    return parsed.data;
+}
+export function nativeError(error) {
+    return new ChatRoomError(nativeErrorCode(error.code), error.message, {
+        nativeCode: error.code ?? null,
+    });
+}
+function nativeErrorCode(code) {
+    switch (code) {
+        case "invalid_request":
+            return "INVALID_INPUT";
+        case "not_found":
+            return "NOT_FOUND";
+        case "permission_required":
+            return "FORBIDDEN";
+        case "stale_snapshot":
+            return "CONFLICT";
+        case "unsupported":
+            return "UNSUPPORTED";
+        default:
+            return "INTERNAL";
+    }
+}

package/dist/plugins/computer/computer-schemas.d.ts

@@ -0,0 +1,285 @@
+import { z } from "zod";
+export declare const computerNativeStatusSchema: z.ZodObject<{
+    platform: z.ZodEnum<{
+        macos: "macos";
+        windows: "windows";
+        linux: "linux";
+        unsupported: "unsupported";
+    }>;
+    helper: z.ZodEnum<{
+        running: "running";
+        stopped: "stopped";
+        unavailable: "unavailable";
+    }>;
+    permissions: z.ZodObject<{
+        accessibility: z.ZodEnum<{
+            granted: "granted";
+            denied: "denied";
+            unknown: "unknown";
+            "not-required": "not-required";
+        }>;
+        screenRecording: z.ZodEnum<{
+            granted: "granted";
+            denied: "denied";
+            unknown: "unknown";
+            "not-required": "not-required";
+        }>;
+    }, z.core.$strip>;
+    displays: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        scale: z.ZodNumber;
+        primary: z.ZodBoolean;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const computerSnapshotSchema: z.ZodObject<{
+    snapshotId: z.ZodString;
+    revision: z.ZodNumber;
+    display: z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        scale: z.ZodNumber;
+        primary: z.ZodBoolean;
+    }, z.core.$strip>>;
+    activeApp: z.ZodNullable<z.ZodString>;
+    activeWindow: z.ZodNullable<z.ZodString>;
+    cursor: z.ZodNullable<z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strip>>;
+    elements: z.ZodArray<z.ZodObject<{
+        id: z.ZodNumber;
+        role: z.ZodString;
+        name: z.ZodNullable<z.ZodString>;
+        value: z.ZodNullable<z.ZodString>;
+        enabled: z.ZodBoolean;
+        focused: z.ZodBoolean;
+        selected: z.ZodBoolean;
+        sensitive: z.ZodBoolean;
+        bounds: z.ZodNullable<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+        actions: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+    screenshot: z.ZodOptional<z.ZodObject<{
+        mimeType: z.ZodEnum<{
+            "image/jpeg": "image/jpeg";
+            "image/png": "image/png";
+        }>;
+        data: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const computerSnapshotMetadataSchema: z.ZodObject<{
+    display: z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        scale: z.ZodNumber;
+        primary: z.ZodBoolean;
+    }, z.core.$strip>>;
+    snapshotId: z.ZodString;
+    revision: z.ZodNumber;
+    activeApp: z.ZodNullable<z.ZodString>;
+    activeWindow: z.ZodNullable<z.ZodString>;
+    cursor: z.ZodNullable<z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strip>>;
+    elements: z.ZodArray<z.ZodObject<{
+        id: z.ZodNumber;
+        role: z.ZodString;
+        name: z.ZodNullable<z.ZodString>;
+        value: z.ZodNullable<z.ZodString>;
+        enabled: z.ZodBoolean;
+        focused: z.ZodBoolean;
+        selected: z.ZodBoolean;
+        sensitive: z.ZodBoolean;
+        bounds: z.ZodNullable<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+        actions: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const computerActionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"move">;
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"click">;
+    x: z.ZodOptional<z.ZodNumber>;
+    y: z.ZodOptional<z.ZodNumber>;
+    elementId: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"double_click">;
+    x: z.ZodOptional<z.ZodNumber>;
+    y: z.ZodOptional<z.ZodNumber>;
+    elementId: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"right_click">;
+    x: z.ZodOptional<z.ZodNumber>;
+    y: z.ZodOptional<z.ZodNumber>;
+    elementId: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"drag">;
+    from: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strip>;
+    to: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strip>;
+    durationMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"scroll">;
+    deltaX: z.ZodOptional<z.ZodNumber>;
+    deltaY: z.ZodNumber;
+    elementId: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"keypress">;
+    keys: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"type_text">;
+    text: z.ZodString;
+    elementId: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"invoke">;
+    elementId: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"set_value">;
+    elementId: z.ZodNumber;
+    value: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"select_text">;
+    elementId: z.ZodNumber;
+    start: z.ZodNumber;
+    length: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"activate_app">;
+    app: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"activate_window">;
+    elementId: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"move_window">;
+    elementId: z.ZodNumber;
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"resize_window">;
+    elementId: z.ZodNumber;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"wait">;
+    ms: z.ZodNumber;
+}, z.core.$strip>], "type">;
+export declare const computerActionResultSchema: z.ZodObject<{
+    success: z.ZodLiteral<true>;
+    revision: z.ZodNumber;
+    snapshot: z.ZodOptional<z.ZodObject<{
+        snapshotId: z.ZodString;
+        revision: z.ZodNumber;
+        display: z.ZodNullable<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+            scale: z.ZodNumber;
+            primary: z.ZodBoolean;
+        }, z.core.$strip>>;
+        activeApp: z.ZodNullable<z.ZodString>;
+        activeWindow: z.ZodNullable<z.ZodString>;
+        cursor: z.ZodNullable<z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strip>>;
+        elements: z.ZodArray<z.ZodObject<{
+            id: z.ZodNumber;
+            role: z.ZodString;
+            name: z.ZodNullable<z.ZodString>;
+            value: z.ZodNullable<z.ZodString>;
+            enabled: z.ZodBoolean;
+            focused: z.ZodBoolean;
+            selected: z.ZodBoolean;
+            sensitive: z.ZodBoolean;
+            bounds: z.ZodNullable<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+            actions: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>>;
+        screenshot: z.ZodOptional<z.ZodObject<{
+            mimeType: z.ZodEnum<{
+                "image/jpeg": "image/jpeg";
+                "image/png": "image/png";
+            }>;
+            data: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    executionMode: z.ZodEnum<{
+        semantic: "semantic";
+        background: "background";
+        foreground: "foreground";
+        mixed: "mixed";
+    }>;
+    focusChanged: z.ZodBoolean;
+}, z.core.$strip>;
+export declare const computerActionMetadataSchema: z.ZodObject<{
+    success: z.ZodLiteral<true>;
+    revision: z.ZodNumber;
+    executionMode: z.ZodEnum<{
+        semantic: "semantic";
+        background: "background";
+        foreground: "foreground";
+        mixed: "mixed";
+    }>;
+    focusChanged: z.ZodBoolean;
+    snapshot: z.ZodOptional<z.ZodObject<{
+        display: z.ZodNullable<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+            scale: z.ZodNumber;
+            primary: z.ZodBoolean;
+        }, z.core.$strip>>;
+        snapshotId: z.ZodString;
+        revision: z.ZodNumber;
+        activeApp: z.ZodNullable<z.ZodString>;
+        activeWindow: z.ZodNullable<z.ZodString>;
+        cursor: z.ZodNullable<z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strip>>;
+        elements: z.ZodArray<z.ZodObject<{
+            id: z.ZodNumber;
+            role: z.ZodString;
+            name: z.ZodNullable<z.ZodString>;
+            value: z.ZodNullable<z.ZodString>;
+            enabled: z.ZodBoolean;
+            focused: z.ZodBoolean;
+            selected: z.ZodBoolean;
+            sensitive: z.ZodBoolean;
+            bounds: z.ZodNullable<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+            actions: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const computerSnapshotTargetSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"desktop">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"display">;
+    displayId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"app">;
+    app: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"window">;
+    elementId: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"region">;
+    displayId: z.ZodOptional<z.ZodString>;
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+}, z.core.$strip>], "type">;

package/dist/plugins/computer/computer-schemas.js

@@ -0,0 +1,152 @@
+import { z } from "zod";
+const computerPermissionStateSchema = z.enum([
+    "granted",
+    "denied",
+    "unknown",
+    "not-required",
+]);
+const computerDisplaySchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    width: z.number(),
+    height: z.number(),
+    scale: z.number(),
+    primary: z.boolean(),
+});
+const computerElementSchema = z.object({
+    id: z.number().int(),
+    role: z.string(),
+    name: z.string().nullable(),
+    value: z.string().nullable(),
+    enabled: z.boolean(),
+    focused: z.boolean(),
+    selected: z.boolean(),
+    sensitive: z.boolean(),
+    bounds: z.tuple([z.number(), z.number(), z.number(), z.number()]).nullable(),
+    actions: z.array(z.string()),
+});
+const computerScreenshotSchema = z.object({
+    mimeType: z.enum(["image/jpeg", "image/png"]),
+    data: z.string(),
+});
+export const computerNativeStatusSchema = z.object({
+    platform: z.enum(["macos", "windows", "linux", "unsupported"]),
+    helper: z.enum(["running", "stopped", "unavailable"]),
+    permissions: z.object({
+        accessibility: computerPermissionStateSchema,
+        screenRecording: computerPermissionStateSchema,
+    }),
+    displays: z.array(computerDisplaySchema),
+});
+export const computerSnapshotSchema = z.object({
+    snapshotId: z.string().min(1),
+    revision: z.number().int(),
+    display: computerDisplaySchema.nullable(),
+    activeApp: z.string().nullable(),
+    activeWindow: z.string().nullable(),
+    cursor: z.object({ x: z.number(), y: z.number() }).nullable(),
+    elements: z.array(computerElementSchema),
+    screenshot: computerScreenshotSchema.optional(),
+});
+export const computerSnapshotMetadataSchema = computerSnapshotSchema.omit({
+    screenshot: true,
+});
+export const computerActionSchema = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("move"), x: z.number(), y: z.number() }),
+    z.object({
+        type: z.literal("click"),
+        x: z.number().optional(),
+        y: z.number().optional(),
+        elementId: z.number().int().optional(),
+    }),
+    z.object({
+        type: z.literal("double_click"),
+        x: z.number().optional(),
+        y: z.number().optional(),
+        elementId: z.number().int().optional(),
+    }),
+    z.object({
+        type: z.literal("right_click"),
+        x: z.number().optional(),
+        y: z.number().optional(),
+        elementId: z.number().int().optional(),
+    }),
+    z.object({
+        type: z.literal("drag"),
+        from: z.object({ x: z.number(), y: z.number() }),
+        to: z.object({ x: z.number(), y: z.number() }),
+        durationMs: z.number().int().min(0).max(10_000).optional(),
+    }),
+    z.object({
+        type: z.literal("scroll"),
+        deltaX: z.number().optional(),
+        deltaY: z.number(),
+        elementId: z.number().int().optional(),
+    }),
+    z.object({
+        type: z.literal("keypress"),
+        keys: z.array(z.string().min(1)).min(1).max(8),
+    }),
+    z.object({
+        type: z.literal("type_text"),
+        text: z.string().max(100_000),
+        elementId: z.number().int().optional(),
+    }),
+    z.object({ type: z.literal("invoke"), elementId: z.number().int() }),
+    z.object({
+        type: z.literal("set_value"),
+        elementId: z.number().int(),
+        value: z.string().max(100_000),
+    }),
+    z.object({
+        type: z.literal("select_text"),
+        elementId: z.number().int(),
+        start: z.number().int().min(0),
+        length: z.number().int().min(0),
+    }),
+    z.object({ type: z.literal("activate_app"), app: z.string().min(1) }),
+    z.object({ type: z.literal("activate_window"), elementId: z.number().int() }),
+    z.object({
+        type: z.literal("move_window"),
+        elementId: z.number().int(),
+        x: z.number(),
+        y: z.number(),
+    }),
+    z.object({
+        type: z.literal("resize_window"),
+        elementId: z.number().int(),
+        width: z.number().positive(),
+        height: z.number().positive(),
+    }),
+    z.object({
+        type: z.literal("wait"),
+        ms: z.number().int().min(0).max(30_000),
+    }),
+]);
+export const computerActionResultSchema = z.object({
+    success: z.literal(true),
+    revision: z.number().int(),
+    snapshot: computerSnapshotSchema.optional(),
+    executionMode: z.enum(["semantic", "background", "foreground", "mixed"]),
+    focusChanged: z.boolean(),
+});
+export const computerActionMetadataSchema = computerActionResultSchema.extend({
+    snapshot: computerSnapshotMetadataSchema.optional(),
+});
+export const computerSnapshotTargetSchema = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("desktop") }),
+    z.object({
+        type: z.literal("display"),
+        displayId: z.string().optional(),
+    }),
+    z.object({ type: z.literal("app"), app: z.string().min(1) }),
+    z.object({ type: z.literal("window"), elementId: z.number().int() }),
+    z.object({
+        type: z.literal("region"),
+        displayId: z.string().optional(),
+        x: z.number(),
+        y: z.number(),
+        width: z.number().positive(),
+        height: z.number().positive(),
+    }),
+]);

package/dist/plugins/computer/computer-service.d.ts

@@ -0,0 +1,29 @@
+import type { RuntimeEventBus } from "#app/event-bus";
+import type { ComputerSettingsRepository } from "./computer-settings-repository.js";
+import type { ComputerAccessScope, ComputerActionRequest, ComputerActionResult, ComputerBackend, ComputerPermission, ComputerSettings, ComputerSnapshot, ComputerSnapshotRequest, ComputerStatus } from "./types.js";
+type ComputerSettingsStore = Pick<ComputerSettingsRepository, "get" | "set">;
+export declare class ComputerService {
+    private readonly backend;
+    private readonly settingsRepository;
+    private readonly events;
+    private revision;
+    private currentSnapshotId;
+    private latestSnapshotValue;
+    private latestSnapshotCapturedAt;
+    private queue;
+    constructor(backend: ComputerBackend, settingsRepository: ComputerSettingsStore, events: RuntimeEventBus);
+    settings(): ComputerSettings;
+    latestSnapshot(scope: ComputerAccessScope): ComputerSnapshot | null;
+    latestSnapshotTimestamp(): string | null;
+    requestPermission(permission: ComputerPermission): Promise<ComputerStatus>;
+    status(): Promise<ComputerStatus>;
+    setSettings(patch: Partial<Pick<ComputerSettings, "enabled" | "remoteAccess">>): ComputerSettings;
+    snapshot(scope: ComputerAccessScope, request: ComputerSnapshotRequest): Promise<ComputerSnapshot>;
+    action(scope: ComputerAccessScope, request: ComputerActionRequest): Promise<ComputerActionResult>;
+    shutdown(): Promise<void>;
+    private assertActionBudget;
+    private assertAllowed;
+    private assertScopeAllowed;
+    private serial;
+}
+export {};

package/dist/plugins/computer/computer-service.js

@@ -0,0 +1,117 @@
+import { randomUUID } from "node:crypto";
+import { ChatRoomError } from "#core/errors/chatroom-error";
+export class ComputerService {
+    backend;
+    settingsRepository;
+    events;
+    revision = 0;
+    currentSnapshotId = null;
+    latestSnapshotValue = null;
+    latestSnapshotCapturedAt = null;
+    queue = Promise.resolve();
+    constructor(backend, settingsRepository, events) {
+        this.backend = backend;
+        this.settingsRepository = settingsRepository;
+        this.events = events;
+    }
+    settings() {
+        return this.settingsRepository.get();
+    }
+    latestSnapshot(scope) {
+        const settings = this.settings();
+        if (!settings.enabled)
+            return null;
+        this.assertScopeAllowed(scope, settings);
+        return this.latestSnapshotValue;
+    }
+    latestSnapshotTimestamp() {
+        return this.latestSnapshotValue ? this.latestSnapshotCapturedAt : null;
+    }
+    requestPermission(permission) {
+        return this.serial(async () => {
+            const base = await this.backend.requestPermission(permission);
+            return { ...base, settings: this.settings() };
+        });
+    }
+    async status() {
+        const base = await this.backend.status();
+        return { ...base, settings: this.settings() };
+    }
+    setSettings(patch) {
+        const next = this.settingsRepository.set({ ...this.settings(), ...patch });
+        if (!next.enabled) {
+            this.currentSnapshotId = null;
+            this.latestSnapshotValue = null;
+            this.latestSnapshotCapturedAt = null;
+            void this.backend.dispose().catch(() => undefined);
+        }
+        this.events.emit({ type: "computer-settings", settings: next });
+        return next;
+    }
+    snapshot(scope, request) {
+        return this.serial(async () => {
+            this.assertAllowed(scope);
+            this.currentSnapshotId = null;
+            const value = await this.backend.snapshot(request, this.revision);
+            this.currentSnapshotId = value.snapshotId || `snap_${randomUUID()}`;
+            value.snapshotId = this.currentSnapshotId;
+            value.revision = this.revision;
+            this.latestSnapshotValue = value;
+            this.latestSnapshotCapturedAt = new Date().toISOString();
+            return value;
+        });
+    }
+    action(scope, request) {
+        return this.serial(async () => {
+            this.assertAllowed(scope);
+            this.assertActionBudget(request);
+            const referencesElements = request.actions.some((action) => "elementId" in action && action.elementId !== undefined);
+            if (referencesElements && !request.snapshotId)
+                throw new ChatRoomError("CONFLICT", "Actions using elementId require the latest snapshotId");
+            if (request.snapshotId && request.snapshotId !== this.currentSnapshotId)
+                throw new ChatRoomError("CONFLICT", "Computer snapshot is stale; take a new snapshot before acting");
+            this.currentSnapshotId = null;
+            const result = await this.backend.action(request, ++this.revision);
+            this.currentSnapshotId = result.snapshot?.snapshotId ?? null;
+            if (result.snapshot) {
+                this.latestSnapshotValue = result.snapshot;
+                this.latestSnapshotCapturedAt = new Date().toISOString();
+            }
+            return result;
+        });
+    }
+    async shutdown() {
+        this.currentSnapshotId = null;
+        this.latestSnapshotValue = null;
+        this.latestSnapshotCapturedAt = null;
+        await this.backend.dispose();
+    }
+    assertActionBudget(request) {
+        const durationMs = request.actions.reduce((total, action) => {
+            if (action.type === "wait")
+                return total + action.ms;
+            if (action.type === "drag")
+                return total + (action.durationMs ?? 0);
+            return total;
+        }, 0);
+        if (durationMs > 30_000)
+            throw new ChatRoomError("INVALID_INPUT", "Computer action batch exceeds the 30 second execution budget");
+    }
+    assertAllowed(scope) {
+        const settings = this.settings();
+        if (!settings.enabled)
+            throw new ChatRoomError("FORBIDDEN", "Computer Use is disabled");
+        this.assertScopeAllowed(scope, settings);
+    }
+    assertScopeAllowed(scope, settings) {
+        if (scope === "remote" && !settings.remoteAccess)
+            throw new ChatRoomError("FORBIDDEN", "Remote Computer Use is disabled", {
+                reason: "remote_computer_disabled",
+            });
+    }
+    serial(action) {
+        const next = this.queue.then(action, action);
+        this.queue = next.then(() => undefined, () => undefined);
+        return next;
+    }
+}

package/dist/plugins/computer/computer-settings-repository.d.ts

@@ -0,0 +1,8 @@
+import type { AppDatabase } from "#infrastructure/database/app-database";
+import type { ComputerSettings } from "./types.js";
+export declare class ComputerSettingsRepository {
+    private readonly database;
+    constructor(database: AppDatabase);
+    get(): ComputerSettings;
+    set(value: Omit<ComputerSettings, "updatedAt"> | ComputerSettings): ComputerSettings;
+}