@abot-ai/runtime 1.5.0 → 1.7.0

package/dist/src/computer-access/companion/install-link.js

@@ -0,0 +1,54 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { parsePluginInstallLink } from "../../plugin-contract/install-source.js";
+import { notificationRuntimeOrigin } from "./notification-protocol.js";
+export function pluginInstallReviewUrl(link, runtimeUrl) {
+    const source = parsePluginInstallLink(link);
+    const url = new URL("/plugins", notificationRuntimeOrigin(runtimeUrl));
+    url.searchParams.set("tab", "discover");
+    url.searchParams.set("pluginSource", source.repository);
+    if (source.ref)
+        url.searchParams.set("pluginRef", source.ref);
+    if (source.path)
+        url.searchParams.set("pluginPath", source.path);
+    return url.toString();
+}
+/** The saved pairing owns the destination. Incoming links cannot select a host. */
+export async function openPluginInstallLink(state, link, open = openReviewBrowser) {
+    parsePluginInstallLink(link);
+    const connection = await state.read();
+    if (!connection)
+        throw new Error("Connect Computer Access before opening an ABot installation link.");
+    await open(pluginInstallReviewUrl(link, connection.url));
+}
+async function openReviewBrowser(url) {
+    const execute = promisify(execFile);
+    const options = { windowsHide: true, timeout: 10_000, maxBuffer: 16_384 };
+    if (process.platform === "win32") {
+        await execute("rundll32.exe", ["url.dll,FileProtocolHandler", url], options);
+        return;
+    }
+    if (process.platform === "darwin") {
+        await execute("/usr/bin/open", [url], options);
+        return;
+    }
+    if (process.platform === "linux") {
+        await execute("xdg-open", [url], options);
+        return;
+    }
+    throw new Error("ABot installation links are not supported on this platform.");
+}
+/** Windows Script Host expands percent-delimited environment variables in Run().
+ * The launcher sends base64 so a website URL can never interpolate local values. */
+export function parsePluginInstallArguments(args) {
+    if (args.length === 1)
+        return args[0];
+    if (args.length !== 2 || args[0] !== "--encoded")
+        throw new Error("Usage: abot host open-link <abot://install link>");
+    const encoded = args[1];
+    if (encoded.length > 12_000 || !/^[A-Za-z0-9+/]+={0,2}$/u.test(encoded))
+        throw new Error("Invalid encoded installation link.");
+    const decoded = Buffer.from(encoded, "base64").toString("utf8");
+    parsePluginInstallLink(decoded);
+    return decoded;
+}

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

@@ -58,9 +58,13 @@ 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"],
+    system_command_capture: ["target", "command", "cwd", "elevated", "timeout_ms", "outputRetentionMs"],
+    system_command_output: ["target", "captureId", "stream", "offset"],
+    system_command_output_close: ["target", "captureId"],
     system_applications: ["target", "query", "limit"],
     system_launch: ["target", "application_id", "arguments"],
     computer_execute: ["target", "sessionId", "request"],

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.d.ts

@@ -14,6 +14,7 @@ export type NativeSessionOptions = Readonly<{
     onReady(hostId: string): void | Promise<void>;
     resolveHost?: NativeHostResolver;
     handlers?: Record<string, ToolImplementation>;
+    commandOutputStateDir?: string;
     heartbeatMs?: number;
     operationLimit?: number;
     observationCollector?: ObservationCollectorFactory;

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

@@ -1,4 +1,8 @@
 import WebSocket from "ws";
+import { CompanionCommandOutput } from "./command-output.js";
+import { SYSTEM_OUTPUT_CAPABILITY } from "./command-output-protocol.js";
+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";
@@ -39,10 +43,14 @@ export async function connectNativeHost(options) {
         await ownedNotifications?.close();
         options.signal.throwIfAborted();
     }
+    const commandOutput = options.commandOutputStateDir && !options.handlers
+        ? new CompanionCommandOutput(options.commandOutputStateDir) : undefined;
     const handlers = options.handlers ?? {
+        ...commandOutput?.handlers(),
         ...createSystemHandlers(),
         ...computers.handlers(),
         ...notifications.handlers(),
+        ...createNativePermissionHandlers(options.identity.os),
     };
     return new Promise((resolve) => {
         const socket = new WebSocket(endpoint.url, {
@@ -98,6 +106,7 @@ export async function connectNativeHost(options) {
                 clearTimeout(retirement);
             observations.close();
             void computers.close();
+            commandOutput?.close();
             if (!options.notifications)
                 void notifications.close();
             for (const controller of active.values())
@@ -145,6 +154,8 @@ export async function connectNativeHost(options) {
                 return false;
             if (computers.hasActiveSessions())
                 return false;
+            if (commandOutput?.hasTransfers())
+                return false;
             if (advertisedNotificationReady)
                 return false;
             return notifications.ready;
@@ -162,11 +173,14 @@ export async function connectNativeHost(options) {
                 throw new Error("Unbound native operation.");
             if (seen.has(message.id))
                 throw new Error("Repeated native operation identity.");
-            if (seen.size >= (options.operationLimit ?? 4_096)) {
+            const readsCommandOutput = message.operation === "system_command_output" || message.operation === "system_command_output_close";
+            if (!readsCommandOutput && seen.size >= (options.operationLimit ?? 4_096)) {
                 retireConnection(message.id);
                 return;
             }
-            seen.add(message.id);
+            // Reading stored bytes is idempotent and must not retire a large transfer.
+            if (!readsCommandOutput)
+                seen.add(message.id);
             if (active.size >= 4) {
                 sendResult(message.id, operationFailure("The host companion is busy.", "system_host_busy"));
                 return;
@@ -243,6 +257,8 @@ export async function connectNativeHost(options) {
                 capabilities: [
                     OBSERVATION_CAPABILITY,
                     COMPUTER_CAPABILITY,
+                    ...(commandOutput ? [SYSTEM_OUTPUT_CAPABILITY] : []),
+                    ...(options.identity.os === "macos" ? [MACOS_PERMISSION_CAPABILITY] : []),
                     ...(advertisedNotificationReady
                         ? [DESKTOP_NOTIFICATION_CAPABILITY]
                         : []),

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

@@ -102,6 +102,7 @@ export async function runNativeHostSupervisor(options) {
                 url: initial.url,
                 authorization: initial.credential,
                 hostId: initial.hostId,
+                commandOutputStateDir: options.state.directory,
                 identity: options.identity,
                 signal: controller.signal,
                 notifications: notificationSession,

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/notification-windows.d.ts

@@ -2,4 +2,4 @@ import type { DesktopNotification } from "./notification-protocol.js";
 import { type NotificationProcessRunner } from "./notification-process.js";
 export declare const WINDOWS_NOTIFICATION_IDENTITY_SCRIPT: string;
 export declare function powershellNotificationArguments(script: string): string[];
-export declare function sendWindowsNotification(notification: DesktopNotification, signal?: AbortSignal, run?: NotificationProcessRunner): Promise<void>;
+export declare function sendWindowsNotification(notification: DesktopNotification, signal?: AbortSignal, run?: NotificationProcessRunner, appUserModelId?: string): Promise<void>;

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

@@ -11,7 +11,9 @@ $Payload = [Console]::In.ReadToEnd() | ConvertFrom-Json
 [void][Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime]
 [void][Windows.UI.Notifications.ToastNotification, Windows.UI.Notifications, ContentType = WindowsRuntime]
 [void][Windows.Data.Xml.Dom.XmlDocument, Windows.Data.Xml.Dom.XmlDocument, ContentType = WindowsRuntime]
-$Notifier = [Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('${NOTIFICATION_APP_ID}')
+$ApplicationId = '${NOTIFICATION_APP_ID}'
+if ($Payload.appUserModelId) { $ApplicationId = [string]$Payload.appUserModelId }
+$Notifier = [Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier($ApplicationId)
 # Win32 Setting is unavailable until the first toast; Show honors Windows notification settings.
 $Xml = New-Object Windows.Data.Xml.Dom.XmlDocument
 $Xml.LoadXml('<toast activationType="protocol"><visual><binding template="ToastGeneric"><text/><text/></binding></visual><audio silent="true"/></toast>')
@@ -127,11 +129,14 @@ export function powershellNotificationArguments(script) {
         Buffer.from(script, "utf16le").toString("base64"),
     ];
 }
-export async function sendWindowsNotification(notification, signal, run = runNotificationProcess) {
+export async function sendWindowsNotification(notification, signal, run = runNotificationProcess, appUserModelId) {
     await run({
         file: "powershell.exe",
         args: powershellNotificationArguments(WINDOWS_NOTIFICATION_SCRIPT),
-        input: JSON.stringify(notification),
+        input: JSON.stringify({
+            ...notification,
+            ...(appUserModelId ? { appUserModelId } : {}),
+        }),
         signal,
     });
 }

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] | "system_command_capture" | "system_command_output" | "system_command_output_close" | 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;
@@ -19,8 +20,16 @@ export function isHostOperation(value) {
 export function isHostWireOperation(value) {
     if (isHostOperation(value))
         return true;
+    if (value === "system_command_capture")
+        return true;
+    if (value === "system_command_output")
+        return true;
+    if (value === "system_command_output_close")
+        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 = 12;
 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 = 12;
 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;