@abot-ai/runtime 1.5.0 → 1.6.0

package/dist/src/cli/host-companion.js

@@ -17,11 +17,13 @@ import { assertPrivateRuntimeAccess } from "../runtime/local-host/private-access
 import { completeHostCompanionStartup } from "./host-companion-startup.js";
 import { resolveHostCompanionSetupUrl } from "./host-companion-setup-target.js";
 import { readNativeCompanionBuildId } from "../computer-access/companion/native-build-identity.js";
+import { runHostPermissionsCli } from "./host-permissions.js";
 function printHostHelp() {
     console.log([
         "Usage:",
         "  abot host connect --url http://localhost:5177",
         "  abot host status",
+        "  abot host permissions [--request screen-recording|accessibility]",
         "  abot host disconnect",
         "  abot host uninstall",
         "  abot host run",
@@ -172,6 +174,10 @@ export async function runHostCompanionCli(args, options = {}) {
         printHostHelp();
         return;
     }
+    if (command === "permissions") {
+        await runHostPermissionsCli(rest);
+        return;
+    }
     const state = nativeState();
     if (command === "connect") {
         await connectHost(rest, state, options);

package/dist/src/cli/host-permissions.d.ts

@@ -0,0 +1,7 @@
+import { prepareMacPermissions } from "../computer-access/companion/native-permissions.js";
+/** Run from the same Terminal/app that starts ABot; never starts a companion. */
+export declare function runHostPermissionsCli(args: readonly string[], dependencies?: {
+    prepare?: typeof prepareMacPermissions;
+    print?: (message: string) => void;
+    platform?: string;
+}): Promise<void>;

package/dist/src/cli/host-permissions.js

@@ -0,0 +1,24 @@
+import { prepareMacPermissions } from "../computer-access/companion/native-permissions.js";
+function permissionCliAction(args) {
+    if (args.length === 0)
+        return { action: "check" };
+    if (args.length !== 2 || args[0] !== "--request")
+        throw new Error("Usage: abot host permissions [--request screen-recording|accessibility]");
+    if (args[1] === "screen-recording")
+        return { action: "request", permission: "screen_recording" };
+    if (args[1] === "accessibility")
+        return { action: "request", permission: "accessibility" };
+    throw new Error("Usage: abot host permissions [--request screen-recording|accessibility]");
+}
+/** Run from the same Terminal/app that starts ABot; never starts a companion. */
+export async function runHostPermissionsCli(args, dependencies = {}) {
+    const action = permissionCliAction(args);
+    if ((dependencies.platform ?? process.platform) !== "darwin")
+        throw new Error("Mac permission preparation is available only on macOS.");
+    const result = await (dependencies.prepare ?? prepareMacPermissions)(action);
+    (dependencies.print ?? console.log)(JSON.stringify({
+        scope: "calling_application",
+        ...result,
+        guidance: "These permissions belong to the Terminal/app running this command, not the installed companion. Run ABot from this same application. If macOS asks you to quit and reopen it, do so before starting a model session, then check again. App-specific Automation permissions are separate.",
+    }, null, 2));
+}

package/dist/src/computer-access/companion/native-messages.js

@@ -58,6 +58,7 @@ export function readNativeServerMessage(text) {
     };
 }
 const NATIVE_OPERATION_FIELDS = {
+    macos_permissions: ["target", "action", "permission"],
     desktop_notification: ["target", "notificationId", "title", "body", "url"],
     system_targets: [],
     system_command: ["target", "command", "cwd", "elevated", "timeout_ms"],

package/dist/src/computer-access/companion/native-permissions.d.ts

@@ -0,0 +1,14 @@
+import { type ExecFileOptionsWithStringEncoding } from "node:child_process";
+import { type ToolImplementation } from "../../plugin-sdk/index.js";
+import { missingMacosComputerPrerequisite } from "../computer/macos-prerequisites.js";
+import { type MacPermissionAction, type MacPermissionResult } from "./permission-protocol.js";
+/** Launched by the calling Runtime/companion, just like its real Swift computer helper. */
+export declare function prepareMacPermissions(action: MacPermissionAction, signal?: AbortSignal, dependencies?: {
+    platform?: string;
+    execute?: (file: string, args: string[], options: ExecFileOptionsWithStringEncoding) => Promise<{
+        stdout: string;
+        stderr: string;
+    }>;
+    prerequisite?: typeof missingMacosComputerPrerequisite;
+}): Promise<MacPermissionResult>;
+export declare function createNativePermissionHandlers(platform: string, prepare?: typeof prepareMacPermissions): Record<string, ToolImplementation>;

package/dist/src/computer-access/companion/native-permissions.js

@@ -0,0 +1,49 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { failureResult, successResult } from "../../plugin-sdk/index.js";
+import { MACOS_PERMISSION_HELPER } from "../computer/macos-permission-helper.js";
+import { missingMacosComputerPrerequisite } from "../computer/macos-prerequisites.js";
+import { isMacPermissionAction, isMacPermissionStatus, MACOS_PERMISSION_OPERATION, } from "./permission-protocol.js";
+const executeFile = promisify(execFile);
+/** Launched by the calling Runtime/companion, just like its real Swift computer helper. */
+export async function prepareMacPermissions(action, signal, dependencies = {}) {
+    if ((dependencies.platform ?? process.platform) !== "darwin")
+        throw new Error("macos_permissions_platform_required");
+    if (!isMacPermissionAction(action))
+        throw new Error("macos_permissions_input_invalid");
+    signal?.throwIfAborted();
+    const prerequisite = await (dependencies.prerequisite ?? missingMacosComputerPrerequisite)();
+    if (prerequisite)
+        throw new Error(prerequisite);
+    const requested = action.action === "request" ? action.permission : "check";
+    const output = await (dependencies.execute ?? executeFile)("/usr/bin/swift", ["-swift-version", "5", "-e", MACOS_PERMISSION_HELPER, requested], { timeout: 45_000, maxBuffer: 16_384, encoding: "utf8", signal });
+    const permissions = JSON.parse(String(output.stdout));
+    if (!isMacPermissionStatus(permissions))
+        throw new Error("macos_permissions_result_invalid");
+    return {
+        permissions,
+        executablePath: process.execPath,
+        restartMayBeRequired: requested === "screen_recording",
+    };
+}
+export function createNativePermissionHandlers(platform, prepare = prepareMacPermissions) {
+    if (platform !== "macos")
+        return {};
+    return {
+        [MACOS_PERMISSION_OPERATION]: async (params, context) => {
+            const { target, ...action } = params;
+            if (target !== "macos" || !isMacPermissionAction(action))
+                return failureResult({ errorCode: "macos_permissions_input_invalid", message: "Choose a permission check or one explicit permission request." });
+            try {
+                const result = await prepare(action, context?.abortSignal);
+                return successResult({ output: "Mac permission preparation completed.", data: result });
+            }
+            catch {
+                return failureResult({
+                    errorCode: "macos_permissions_check_failed",
+                    message: "Permission preparation could not complete. Check that macOS 14 or later and Swift developer tools are available, then check again. No desktop content was collected.",
+                });
+            }
+        },
+    };
+}

package/dist/src/computer-access/companion/native-session.js

@@ -1,4 +1,6 @@
 import WebSocket from "ws";
+import { createNativePermissionHandlers } from "./native-permissions.js";
+import { MACOS_PERMISSION_CAPABILITY } from "./permission-protocol.js";
 import { nativeLoopbackSocketOptions } from "./native-loopback-lookup.js";
 import { DESKTOP_NOTIFICATION_CAPABILITY } from "./notification-protocol.js";
 import { createNativeNotificationSession, } from "./native-notifications.js";
@@ -43,6 +45,7 @@ export async function connectNativeHost(options) {
         ...createSystemHandlers(),
         ...computers.handlers(),
         ...notifications.handlers(),
+        ...createNativePermissionHandlers(options.identity.os),
     };
     return new Promise((resolve) => {
         const socket = new WebSocket(endpoint.url, {
@@ -243,6 +246,7 @@ export async function connectNativeHost(options) {
                 capabilities: [
                     OBSERVATION_CAPABILITY,
                     COMPUTER_CAPABILITY,
+                    ...(options.identity.os === "macos" ? [MACOS_PERMISSION_CAPABILITY] : []),
                     ...(advertisedNotificationReady
                         ? [DESKTOP_NOTIFICATION_CAPABILITY]
                         : []),

package/dist/src/computer-access/companion/notification-installation.js

@@ -8,6 +8,7 @@ import { NOTIFICATION_APP_ID, NOTIFICATION_OWNER_MARKER, macNotificationAppPath,
 import { notificationRuntimeOrigin } from "./notification-protocol.js";
 import { runNotificationProcess, } from "./notification-process.js";
 import { powershellNotificationArguments, WINDOWS_NOTIFICATION_IDENTITY_SCRIPT, } from "./notification-windows.js";
+import { configureMacNotificationBundle } from "./notification-macos-bundle.js";
 export function notificationLocationsFromStartup(startup) {
     return {
         stateDir: startup.stateDir,
@@ -61,20 +62,6 @@ async function assertLinuxDesktopOwnership(path) {
         throw new Error("notification_registration_not_owned");
     return true;
 }
-function macNotificationPlist() {
-    return ('<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n' +
-        '<plist version="1.0"><dict>' +
-        "<key>CFBundleExecutable</key><string>applet</string>" +
-        "<key>CFBundleIdentifier</key><string>" +
-        NOTIFICATION_APP_ID +
-        "</string>" +
-        "<key>CFBundleName</key><string>ABot</string><key>CFBundleDisplayName</key><string>ABot</string>" +
-        "<key>CFBundlePackageType</key><string>APPL</string><key>CFBundleSignature</key><string>aplt</string>" +
-        "<key>CFBundleVersion</key><string>1</string><key>CFBundleShortVersionString</key><string>1.0</string>" +
-        "<key>CFBundleIconFile</key><string>applet</string><key>LSUIElement</key><true/>" +
-        "<key>OSAAppletStayOpen</key><true/><key>OSAAppletShowStartupScreen</key><false/>" +
-        "<key>NSHighResolutionCapable</key><true/></dict></plist>\n");
-}
 export async function stopMacNotificationApp(locations, run) {
     await run({
         file: "/usr/bin/osascript",
@@ -101,7 +88,7 @@ async function installMacNotificationApp(locations, run) {
         args: ["-l", "JavaScript", "-s", "-o", temporary, source],
         timeoutMs: 30_000,
     });
-    await writeFile(join(temporary, "Contents", "Info.plist"), macNotificationPlist());
+    await configureMacNotificationBundle(temporary, run);
     await run({
         file: "/usr/bin/codesign",
         args: [

package/dist/src/computer-access/companion/notification-macos-bundle.d.ts

@@ -0,0 +1,3 @@
+import type { NotificationProcessRunner } from "./notification-process.js";
+export declare function assertMacNotificationBundle(app: string, run: NotificationProcessRunner, signal?: AbortSignal): Promise<void>;
+export declare function configureMacNotificationBundle(app: string, run: NotificationProcessRunner): Promise<void>;

package/dist/src/computer-access/companion/notification-macos-bundle.js

@@ -0,0 +1,84 @@
+import { constants } from "node:fs";
+import { access, lstat } from "node:fs/promises";
+import { join } from "node:path";
+import { NOTIFICATION_APP_ID } from "./notification-locations.js";
+/** Foundation retains compiler-owned plist values and their native types. */
+const MAC_NOTIFICATION_PLIST_SCRIPT = String.raw `
+ObjC.import('Foundation');
+function run(argv) {
+  var plist = $.NSMutableDictionary.alloc.initWithContentsOfFile($(argv[0]));
+  if (!plist) throw new Error('notification_bundle_plist_invalid');
+  if (argv[1]) {
+    var updates = JSON.parse(argv[1]);
+    Object.keys(updates).forEach(function(key) {
+      plist.setObjectForKey($(updates[key]), $(key));
+    });
+    if (!plist.writeToFileAtomically($(argv[0]), true))
+      throw new Error('notification_bundle_plist_write_failed');
+  }
+  return JSON.stringify({
+    executable: ObjC.unwrap(plist.objectForKey('CFBundleExecutable')),
+    identifier: ObjC.unwrap(plist.objectForKey('CFBundleIdentifier'))
+  });
+}
+`;
+function isBundleExecutableName(value) {
+    if (typeof value !== "string" || value.length === 0)
+        return false;
+    if (value === "." || value === "..")
+        return false;
+    return !/[\\/\u0000-\u001f\u007f]/.test(value);
+}
+async function assertBundleDirectory(path) {
+    const stat = await lstat(path);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new Error("notification_bundle_directory_invalid");
+}
+async function assertBundleFile(path) {
+    const stat = await lstat(path);
+    if (!stat.isFile() || stat.isSymbolicLink())
+        throw new Error("notification_bundle_file_invalid");
+}
+async function readBundleMetadata(app, run, signal) {
+    await assertBundleDirectory(app);
+    await assertBundleDirectory(join(app, "Contents"));
+    await assertBundleDirectory(join(app, "Contents", "MacOS"));
+    const plist = join(app, "Contents", "Info.plist");
+    await assertBundleFile(plist);
+    return JSON.parse(await run({
+        file: "/usr/bin/osascript",
+        args: ["-l", "JavaScript", "-e", MAC_NOTIFICATION_PLIST_SCRIPT, plist],
+        signal,
+    }));
+}
+async function assertBundleExecutable(app, executable) {
+    if (!isBundleExecutableName(executable))
+        throw new Error("notification_bundle_executable_invalid");
+    const path = join(app, "Contents", "MacOS", executable);
+    await assertBundleFile(path);
+    await access(path, constants.X_OK);
+}
+export async function assertMacNotificationBundle(app, run, signal) {
+    const metadata = await readBundleMetadata(app, run, signal);
+    if (metadata.identifier !== NOTIFICATION_APP_ID)
+        throw new Error("notification_bundle_identity_invalid");
+    await assertBundleExecutable(app, metadata.executable);
+}
+export async function configureMacNotificationBundle(app, run) {
+    const metadata = await readBundleMetadata(app, run);
+    await assertBundleExecutable(app, metadata.executable);
+    await run({
+        file: "/usr/bin/osascript",
+        args: ["-l", "JavaScript", "-e", MAC_NOTIFICATION_PLIST_SCRIPT,
+            join(app, "Contents", "Info.plist"), JSON.stringify({
+                CFBundleIdentifier: NOTIFICATION_APP_ID,
+                CFBundleName: "ABot",
+                CFBundleDisplayName: "ABot",
+                LSUIElement: true,
+                OSAAppletStayOpen: true,
+                OSAAppletShowStartupScreen: false,
+                NSHighResolutionCapable: true,
+            })],
+    });
+    await assertMacNotificationBundle(app, run);
+}

package/dist/src/computer-access/companion/notification-macos.js

@@ -28,7 +28,7 @@ function sourceUrlAllowed(value) {
   var origin = connection.url.replace(/^ws:/, 'http:').replace(/^wss:/, 'https:');
   if (value.indexOf(origin + '/') !== 0) return false;
   var path = value.slice(origin.length).split('?')[0];
-  return ['/chat', '/notifications', '/home', '/learning'].indexOf(path) !== -1;
+  return ['/chat', '/notifications', '/home', '/learning', '/automations'].indexOf(path) !== -1;
 }
 ObjC.registerSubclass({
   name: 'ABotDesktopNotificationDelegate',

package/dist/src/computer-access/companion/notification-protocol.d.ts

@@ -1,7 +1,7 @@
 import { type HostIdentity } from "./protocol.js";
 export declare const DESKTOP_NOTIFICATION_CAPABILITY = "desktop_notifications_v1";
 export { DESKTOP_NOTIFICATION_OPERATION } from "./protocol.js";
-export declare const DESKTOP_NOTIFICATION_PATHS: readonly ["/chat", "/notifications", "/home", "/learning"];
+export declare const DESKTOP_NOTIFICATION_PATHS: readonly ["/chat", "/notifications", "/home", "/learning", "/automations"];
 export type DesktopNotification = Readonly<{
     target: HostIdentity["os"];
     notificationId: string;

package/dist/src/computer-access/companion/notification-protocol.js

@@ -1,4 +1,5 @@
 import { isHostRecord } from "./protocol.js";
+import { hasBoundSparkNotificationQuery } from "./spark-notification-query.js";
 export const DESKTOP_NOTIFICATION_CAPABILITY = "desktop_notifications_v1";
 export { DESKTOP_NOTIFICATION_OPERATION } from "./protocol.js";
 export const DESKTOP_NOTIFICATION_PATHS = [
@@ -6,6 +7,7 @@ export const DESKTOP_NOTIFICATION_PATHS = [
     "/notifications",
     "/home",
     "/learning",
+    "/automations",
 ];
 export function notificationRuntimeOrigin(runtimeUrl) {
     const url = new URL(runtimeUrl);
@@ -17,6 +19,23 @@ export function notificationRuntimeOrigin(runtimeUrl) {
         throw new Error("notification_runtime_invalid");
     return url.origin;
 }
+function hasBoundAutomationRunQuery(url) {
+    const keys = ["environment", "automation", "run"];
+    for (const key of keys) {
+        if (url.searchParams.getAll(key).length !== 1)
+            return false;
+        if (!url.searchParams.get(key))
+            return false;
+    }
+    return [...url.searchParams.keys()].every((key) => keys.includes(key));
+}
+function hasAllowedNotificationQuery(url) {
+    if (url.pathname === "/automations")
+        return hasBoundAutomationRunQuery(url);
+    if (url.searchParams.has("spark"))
+        return hasBoundSparkNotificationQuery(url);
+    return [...url.searchParams.keys()].every((key) => ["environment", "session"].includes(key));
+}
 export function resolveNotificationSourceUrl(value, runtimeUrl) {
     if (typeof value !== "string")
         throw new Error("notification_url_invalid");
@@ -34,7 +53,7 @@ export function resolveNotificationSourceUrl(value, runtimeUrl) {
         throw new Error("notification_url_invalid");
     if (!DESKTOP_NOTIFICATION_PATHS.some((path) => path === url.pathname))
         throw new Error("notification_url_path_invalid");
-    if ([...url.searchParams.keys()].some((key) => !["environment", "session"].includes(key)))
+    if (!hasAllowedNotificationQuery(url))
         throw new Error("notification_url_query_invalid");
     return url.toString();
 }

package/dist/src/computer-access/companion/notification-readiness.js

@@ -1,4 +1,5 @@
 import { hasLinuxNotificationActions } from "./notification-linux.js";
+import { assertMacNotificationBundle } from "./notification-macos-bundle.js";
 import { access, readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { hasOwnedNotificationDirectory, linuxNotificationDesktopPath, } from "./notification-installation.js";
@@ -16,7 +17,7 @@ export async function hasDesktopNotificationSupport(platform, locations, run = r
         if (platform === "windows")
             return true;
         if (platform === "macos") {
-            await access(join(macNotificationAppPath(locations), "Contents", "MacOS", "applet"));
+            await assertMacNotificationBundle(macNotificationAppPath(locations), run, signal);
             return true;
         }
         if (!process.env.DISPLAY && !process.env.WAYLAND_DISPLAY)

package/dist/src/computer-access/companion/permission-protocol.d.ts

@@ -0,0 +1,22 @@
+export declare const MACOS_PERMISSION_CAPABILITY = "macos_permission_preflight_v1";
+export { MACOS_PERMISSION_OPERATION } from "./protocol.js";
+export type MacPermission = "screen_recording" | "accessibility";
+export type MacPermissionAction = Readonly<{
+    action: "check";
+}> | Readonly<{
+    action: "request";
+    permission: MacPermission;
+}>;
+export type MacPermissionStatus = Readonly<{
+    screenRecording: "granted" | "required";
+    accessibility: "granted" | "required";
+}>;
+export type MacPermissionResult = Readonly<{
+    permissions: MacPermissionStatus;
+    executablePath: string;
+    restartMayBeRequired: boolean;
+}>;
+export declare function isMacPermissionAction(value: unknown): value is MacPermissionAction;
+export declare function isMacPermissionStatus(value: unknown): value is MacPermissionStatus;
+/** The browser receives only permission state and the current permission subject. */
+export declare function readMacPermissionResult(value: unknown): MacPermissionResult | undefined;

package/dist/src/computer-access/companion/permission-protocol.js

@@ -0,0 +1,45 @@
+import { isHostRecord } from "./protocol.js";
+export const MACOS_PERMISSION_CAPABILITY = "macos_permission_preflight_v1";
+export { MACOS_PERMISSION_OPERATION } from "./protocol.js";
+export function isMacPermissionAction(value) {
+    if (!isHostRecord(value))
+        return false;
+    if (Object.keys(value).some((key) => !["action", "permission"].includes(key)))
+        return false;
+    if (value.action === "check")
+        return !Object.hasOwn(value, "permission");
+    if (value.action !== "request")
+        return false;
+    return value.permission === "screen_recording" || value.permission === "accessibility";
+}
+export function isMacPermissionStatus(value) {
+    if (!isHostRecord(value))
+        return false;
+    if (Object.keys(value).some((key) => !["screenRecording", "accessibility"].includes(key)))
+        return false;
+    if (value.screenRecording !== "granted" && value.screenRecording !== "required")
+        return false;
+    return value.accessibility === "granted" || value.accessibility === "required";
+}
+/** The browser receives only permission state and the current permission subject. */
+export function readMacPermissionResult(value) {
+    if (!isHostRecord(value))
+        return undefined;
+    if (!isMacPermissionStatus(value.permissions))
+        return undefined;
+    if (typeof value.executablePath !== "string")
+        return undefined;
+    if (!value.executablePath.startsWith("/"))
+        return undefined;
+    if (value.executablePath.length > 4096)
+        return undefined;
+    if (/[\u0000-\u001f\u007f]/u.test(value.executablePath))
+        return undefined;
+    if (typeof value.restartMayBeRequired !== "boolean")
+        return undefined;
+    return {
+        permissions: value.permissions,
+        executablePath: value.executablePath,
+        restartMayBeRequired: value.restartMayBeRequired,
+    };
+}

package/dist/src/computer-access/companion/protocol.d.ts

@@ -3,12 +3,13 @@ import type { ObservationControl } from "./observation-protocol.js";
 import type { PassiveCollectorEvent } from "../../shared/passive-observation.js";
 import type { companionReleaseStatus } from "./release-version.js";
 export declare const DESKTOP_NOTIFICATION_OPERATION = "desktop_notification";
+export declare const MACOS_PERMISSION_OPERATION = "macos_permissions";
 export declare const HOST_PROTOCOL_VERSION = 1;
 export declare const HOST_SOCKET_PATH = "/system-host/connect";
 export declare const HOST_WIRE_MAX_BYTES: number;
 export declare const HOST_OPERATIONS: readonly ["system_targets", "system_command", "system_applications", "system_launch"];
 export declare const COMPUTER_HOST_OPERATIONS: readonly ["computer_execute", "computer_frame", "computer_close"];
-export type HostOperation = (typeof HOST_OPERATIONS)[number] | (typeof COMPUTER_HOST_OPERATIONS)[number] | typeof DESKTOP_NOTIFICATION_OPERATION;
+export type HostOperation = (typeof HOST_OPERATIONS)[number] | (typeof COMPUTER_HOST_OPERATIONS)[number] | typeof MACOS_PERMISSION_OPERATION | typeof DESKTOP_NOTIFICATION_OPERATION;
 export type HostIdentity = Readonly<{
     name: string;
     os: "windows" | "macos" | "linux";

package/dist/src/computer-access/companion/protocol.js

@@ -1,4 +1,5 @@
 export const DESKTOP_NOTIFICATION_OPERATION = "desktop_notification";
+export const MACOS_PERMISSION_OPERATION = "macos_permissions";
 export const HOST_PROTOCOL_VERSION = 1;
 export const HOST_SOCKET_PATH = "/system-host/connect";
 export const HOST_WIRE_MAX_BYTES = 256 * 1024;
@@ -21,6 +22,8 @@ export function isHostWireOperation(value) {
         return true;
     if (value === DESKTOP_NOTIFICATION_OPERATION)
         return true;
+    if (value === MACOS_PERMISSION_OPERATION)
+        return true;
     return COMPUTER_HOST_OPERATIONS.some((operation) => operation === value);
 }
 export function isHostRecord(value) {

package/dist/src/computer-access/companion/release-version.d.ts

@@ -1,5 +1,5 @@
 /** Increment when installed companions should be offered an update. Independent of the wire protocol. */
-export declare const COMPANION_RELEASE_VERSION = 6;
+export declare const COMPANION_RELEASE_VERSION = 10;
 export declare function companionReleaseStatus(version: unknown): {
     installedVersion: number | null;
     availableVersion: number;

package/dist/src/computer-access/companion/release-version.js

@@ -1,5 +1,5 @@
 /** Increment when installed companions should be offered an update. Independent of the wire protocol. */
-export const COMPANION_RELEASE_VERSION = 6;
+export const COMPANION_RELEASE_VERSION = 10;
 export function companionReleaseStatus(version) {
     const installedVersion = typeof version === "number" && Number.isSafeInteger(version) && version > 0
         ? version

package/dist/src/computer-access/companion/spark-notification-query.d.ts

@@ -0,0 +1,2 @@
+/** Validate the SPARK source link before the native host opens it. */
+export declare function hasBoundSparkNotificationQuery(url: URL): boolean;

package/dist/src/computer-access/companion/spark-notification-query.js

@@ -0,0 +1,62 @@
+const SPARK_NOTIFICATION_QUERY_KEYS = new Set([
+    "environment",
+    "spark",
+    "message",
+    "messageCreatedAt",
+    "request",
+]);
+function hasSingleAllowedSparkParameters(parameters) {
+    for (const key of parameters.keys()) {
+        if (!SPARK_NOTIFICATION_QUERY_KEYS.has(key))
+            return false;
+        if (parameters.getAll(key).length !== 1)
+            return false;
+    }
+    return true;
+}
+function isSparkNotificationReference(value) {
+    if (value === null)
+        return false;
+    if (value.trim() !== value)
+        return false;
+    if (!value.length)
+        return false;
+    if (value.length > 512)
+        return false;
+    return !/[\u0000-\u001f\u007f]/u.test(value);
+}
+function hasCanonicalSparkMessageTimestamp(value) {
+    if (value === null)
+        return false;
+    const timestamp = Number(value);
+    if (!Number.isSafeInteger(timestamp))
+        return false;
+    if (timestamp < 0)
+        return false;
+    return String(timestamp) === value;
+}
+function hasSparkMessageReference(parameters) {
+    return ["message", "messageCreatedAt", "request"].some((key) => parameters.has(key));
+}
+/** Validate the SPARK source link before the native host opens it. */
+export function hasBoundSparkNotificationQuery(url) {
+    if (url.pathname !== "/home")
+        return false;
+    const parameters = url.searchParams;
+    if (!hasSingleAllowedSparkParameters(parameters))
+        return false;
+    if (!isSparkNotificationReference(parameters.get("environment")))
+        return false;
+    if (parameters.get("spark") !== "1")
+        return false;
+    if (!hasSparkMessageReference(parameters))
+        return true;
+    if (!isSparkNotificationReference(parameters.get("message")))
+        return false;
+    if (!hasCanonicalSparkMessageTimestamp(parameters.get("messageCreatedAt")))
+        return false;
+    const request = parameters.get("request");
+    if (request === null)
+        return true;
+    return isSparkNotificationReference(request);
+}

package/dist/src/computer-access/computer/macos-desktop.js

@@ -29,7 +29,7 @@ func capability(_ available: Bool,_ reason: String = "",supported: Bool = true)
   return result
 }
 func rectJSON(_ rect: CGRect) -> [String:Any] {
-  return ["x":rect.minX,"y":rect.minY,"width":rect.width,"height":rect.height]
+  return ["x":Double(rect.minX),"y":Double(rect.minY),"width":Double(rect.width),"height":Double(rect.height)]
 }
 func boundedText(_ value:String,_ limit:Int=256) -> String {
   var result="",length=0

package/dist/src/computer-access/computer/macos-input.js

@@ -28,12 +28,9 @@ final class CancellationFlag {
     }
   }
 }
-let keyCodes:[String:CGKeyCode] = ["a":0,"s":1,"d":2,"f":3,"h":4,"g":5,"z":6,"x":7,"c":8,"v":9,"b":11,"q":12,"w":13,"e":14,"r":15,"y":16,"t":17,"1":18,"2":19,"3":20,"4":21,"6":22,"5":23,"=":24,"9":25,"7":26,"-":27,"8":28,"0":29,"]":30,"o":31,"u":32,"[":33,"i":34,"p":35,"l":37,"j":38,"'":39,"k":40,";":41,"\\":42,",":43,"/":44,"n":45,"m":46,".":47,"\u{60}":50,"Enter":36,"Return":36,"Tab":48,"Space":49,"Backspace":51,"Delete":117,"Esc":53,"Escape":53,"Meta":55,"Super":55,"Command":55,"Shift":56,"Alt":58,"Option":58,"Ctrl":59,"Control":59,"F1":122,"F2":120,"F3":99,"F4":118,"F5":96,"F6":97,"F7":98,"F8":100,"F9":101,"F10":109,"F11":103,"F12":111,"Home":115,"End":119,"PageUp":116,"PageDown":121,"ArrowLeft":123,"ArrowRight":124,"ArrowDown":125,"ArrowUp":126]
+let keyCodes:[String:CGKeyCode] = ["a":0,"s":1,"d":2,"f":3,"h":4,"g":5,"z":6,"x":7,"c":8,"v":9,"b":11,"q":12,"w":13,"e":14,"r":15,"y":16,"t":17,"1":18,"2":19,"3":20,"4":21,"6":22,"5":23,"=":24,"9":25,"7":26,"-":27,"8":28,"0":29,"]":30,"o":31,"u":32,"[":33,"i":34,"p":35,"l":37,"j":38,"'":39,"k":40,";":41,"\\":42,",":43,"/":44,"n":45,"m":46,".":47,"\u{60}":50,"enter":36,"return":36,"tab":48,"space":49,"backspace":51,"delete":117,"esc":53,"escape":53,"meta":55,"super":55,"command":55,"cmd":55,"shift":56,"alt":58,"option":58,"ctrl":59,"control":59,"f1":122,"f2":120,"f3":99,"f4":118,"f5":96,"f6":97,"f7":98,"f8":100,"f9":101,"f10":109,"f11":103,"f12":111,"home":115,"end":119,"pageup":116,"pagedown":121,"arrowleft":123,"arrowright":124,"arrowdown":125,"arrowup":126]
 func nativeKey(_ value:String) throws -> CGKeyCode {
-  if let key=keyCodes[value] {
-    return key
-  }
-  if value.count==1,let key=keyCodes[value.lowercased()] {
+  if let key=keyCodes[value.lowercased()] {
     return key
   }
   throw NativeFailure("macos_key_unsupported")

package/dist/src/computer-access/computer/macos-permission-helper.d.ts

@@ -0,0 +1,4 @@
+/** Permission checks never enumerate windows, capture pixels, or inject input. */
+export declare const MACOS_PERMISSION_GATE: string;
+export declare const MACOS_PERMISSION_INPUT: string;
+export declare const MACOS_PERMISSION_HELPER: string;

package/dist/src/computer-access/computer/macos-permission-helper.js

@@ -0,0 +1,38 @@
+/** Permission checks never enumerate windows, capture pixels, or inject input. */
+export const MACOS_PERMISSION_GATE = String.raw `
+func prepareMacPermissions(
+  action: String,
+  screenGranted: () -> Bool,
+  accessibilityGranted: () -> Bool,
+  requestScreen: () -> Void,
+  requestAccessibility: () -> Void
+) -> [String: String] {
+  if action == "screen_recording" && !screenGranted() { requestScreen() }
+  if action == "accessibility" && !accessibilityGranted() { requestAccessibility() }
+  return ["screenRecording": screenGranted() ? "granted" : "required",
+    "accessibility": accessibilityGranted() ? "granted" : "required"]
+}
+`;
+export const MACOS_PERMISSION_INPUT = String.raw `
+let action = CommandLine.arguments.last ?? "check"
+guard ["check", "screen_recording", "accessibility"].contains(action) else { exit(2) }
+`;
+export const MACOS_PERMISSION_HELPER = String.raw `
+import Foundation
+import CoreGraphics
+import ApplicationServices
+${MACOS_PERMISSION_GATE}
+${MACOS_PERMISSION_INPUT}
+let result = prepareMacPermissions(
+  action: action,
+  screenGranted: { CGPreflightScreenCaptureAccess() },
+  accessibilityGranted: { AXIsProcessTrusted() },
+  requestScreen: { _ = CGRequestScreenCaptureAccess() },
+  requestAccessibility: {
+    let options = [kAXTrustedCheckOptionPrompt.takeUnretainedValue() as String: true] as CFDictionary
+    _ = AXIsProcessTrustedWithOptions(options)
+  }
+)
+let data = try JSONSerialization.data(withJSONObject: result)
+print(String(data: data, encoding: .utf8)!)
+`;