@abot-ai/runtime 1.5.0 → 1.7.0

package/dist/src/web-ui/session-read-state/store.d.ts

@@ -1,3 +1,4 @@
+import { type VisibleMessageReadState } from "./visible-messages.js";
 export type WebReadCursor = {
     messageId: string;
     createdAt: number;
@@ -7,6 +8,7 @@ export type WebReadState = {
     version: 1;
     initializedAt: number;
     cursors: Array<[string, WebReadCursor]>;
+    visibleMessages?: Array<[string, VisibleMessageReadState]>;
 };
 /** UI-owned state; never writes Runtime session records or model context. */
 export declare class WebReadStateStore {

package/dist/src/web-ui/session-read-state/store.js

@@ -1,6 +1,7 @@
 import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { randomUUID } from "node:crypto";
+import { readVisibleMessageReceipts } from "./visible-messages.js";
 const pendingWrites = new Map();
 function hasFileErrorCode(error, code) {
     return error instanceof Error && "code" in error && error.code === code;
@@ -29,6 +30,7 @@ function decodeReadState(raw) {
         if (typeof entry[0] !== "string" || !isReadCursor(entry[1]))
             throw new Error("Invalid Web UI read cursor entry.");
     }
+    state.visibleMessages = readVisibleMessageReceipts(state.visibleMessages);
     return state;
 }
 /** UI-owned state; never writes Runtime session records or model context. */
@@ -100,11 +102,16 @@ export class WebReadStateStore {
                 lastReadAt: Math.max(now, (previous?.lastReadAt ?? state.initializedAt) + 1),
             });
             state.cursors = [...cursors];
+            const visible = new Map(state.visibleMessages ?? []);
+            const prior = visible.get(sessionId);
+            visible.set(sessionId, { generation: randomUUID(), revision: Math.max(now, (prior?.revision ?? 0) + 1), messages: [] });
+            state.visibleMessages = [...visible];
         });
     }
     forget(sessionId) {
         return this.transaction((state) => {
             state.cursors = state.cursors.filter(([id]) => id !== sessionId);
+            state.visibleMessages = state.visibleMessages?.filter(([id]) => id !== sessionId);
         });
     }
 }

package/dist/src/web-ui/session-read-state/visible-messages.d.ts

@@ -0,0 +1,30 @@
+import type { SessionMessageIdentity } from "../../sessions/snapshot.js";
+import type { WebReadState } from "./store.js";
+export type VisibleMessageReceipt = {
+    messageId: string;
+    createdAt: number;
+    requestId: string | null;
+};
+export type VisibleMessageReadState = {
+    generation: string;
+    revision: number;
+    messages: VisibleMessageReceipt[];
+};
+export declare function isVisibleMessageReadState(value: unknown): value is VisibleMessageReadState;
+export declare function readVisibleMessageReceipts(value: unknown): WebReadState["visibleMessages"];
+export declare function visibleReadMessageIds(input: unknown): string[];
+export declare function visibleReadObservations(ids: readonly string[], input: unknown): VisibleMessageReceipt[];
+export declare function markVisibleAssistantMessages(state: WebReadState, sessionId: string, messages: SessionMessageIdentity[], observations: readonly VisibleMessageReceipt[], generation: unknown, now: number): void;
+export declare function projectVisibleSessionReadState(state: WebReadState, sessionId: string, messages: SessionMessageIdentity[]): {
+    sessionId: string;
+    readStateStatus: "available";
+    unreadMessageIds: (string | number)[];
+    unreadCount: number;
+    hasUnread: boolean;
+    readRevision: number;
+    readGeneration: string;
+    lastReadAt: number;
+    lastReadMessageId: string | number | null;
+    latestMessageId: string | number | null;
+    latestAssistantMessageId: string | number | null;
+};

package/dist/src/web-ui/session-read-state/visible-messages.js

@@ -0,0 +1,119 @@
+import { randomUUID } from "node:crypto";
+export function isVisibleMessageReadState(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const state = value;
+    if (typeof state.generation !== "string" || !state.generation)
+        return false;
+    if (!Number.isSafeInteger(state.revision) || state.revision < 0)
+        return false;
+    if (!Array.isArray(state.messages))
+        return false;
+    return state.messages.every((message) => typeof message?.messageId === "string" && Number.isFinite(message.createdAt)
+        && (message.requestId === null || typeof message.requestId === "string"));
+}
+export function readVisibleMessageReceipts(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value))
+        throw new Error("Invalid visible message receipts.");
+    for (const entry of value) {
+        if (!isVisibleReceiptEntry(entry))
+            throw new Error("Invalid visible message receipts.");
+    }
+    return value;
+}
+function isVisibleReceiptEntry(entry) {
+    if (!Array.isArray(entry) || entry.length !== 2)
+        return false;
+    if (typeof entry[0] !== "string")
+        return false;
+    return isVisibleMessageReadState(entry[1]);
+}
+function ensureVisibleReadState(state, sessionId) {
+    const stored = new Map(state.visibleMessages ?? []);
+    const previous = stored.get(sessionId);
+    if (previous)
+        return previous;
+    const initial = { generation: randomUUID(), revision: 0, messages: [] };
+    stored.set(sessionId, initial);
+    state.visibleMessages = [...stored];
+    return initial;
+}
+function receiptIdentity(messageId, createdAt, requestId) {
+    return JSON.stringify([String(messageId), createdAt, requestId || null]);
+}
+export function visibleReadMessageIds(input) {
+    if (!Array.isArray(input) || input.length > 500)
+        throw new Error("visible_message_ids_invalid");
+    return [...new Set(input.map((id) => {
+            if (typeof id === "number" && Number.isSafeInteger(id) && id >= 0)
+                return String(id);
+            if (typeof id === "string" && id.length > 0 && id.length <= 256)
+                return id;
+            throw new Error("visible_message_ids_invalid");
+        }))];
+}
+export function visibleReadObservations(ids, input) {
+    if (!Array.isArray(input) || input.length !== ids.length)
+        throw new Error("visible_message_receipts_invalid");
+    const observations = input.map((entry) => {
+        if (!entry || typeof entry !== "object")
+            throw new Error("visible_message_receipts_invalid");
+        const id = visibleReadMessageIds([entry.id])[0];
+        if (!ids.includes(id))
+            throw new Error("visible_message_receipts_invalid");
+        if (!Number.isFinite(entry.createdAt))
+            throw new Error("visible_message_receipts_invalid");
+        const requestId = entry.requestId;
+        if (requestId !== null && typeof requestId !== "string")
+            throw new Error("visible_message_receipts_invalid");
+        return { messageId: id, createdAt: entry.createdAt, requestId: requestId || null };
+    });
+    if (new Set(observations.map((receipt) => receipt.messageId)).size !== ids.length)
+        throw new Error("visible_message_receipts_invalid");
+    return observations;
+}
+export function markVisibleAssistantMessages(state, sessionId, messages, observations, generation, now) {
+    const previous = ensureVisibleReadState(state, sessionId);
+    if (generation !== previous.generation)
+        throw new Error("read_generation_changed");
+    const stored = new Map(state.visibleMessages ?? []);
+    const assistants = messages.filter((message) => message.role === "assistant");
+    const canonical = new Set(assistants.map((message) => receiptIdentity(message.id, message.createdAt, message.requestId)));
+    const requested = new Set(observations.map((receipt) => receiptIdentity(receipt.messageId, receipt.createdAt, receipt.requestId)));
+    for (const identity of requested) {
+        if (!canonical.has(identity))
+            throw new Error("visible_message_receipt_stale");
+    }
+    const prior = new Set(previous.messages.map((receipt) => receiptIdentity(receipt.messageId, receipt.createdAt, receipt.requestId)));
+    const receipts = messages.filter((message) => message.role === "assistant").filter((message) => {
+        const identity = receiptIdentity(message.id, message.createdAt, message.requestId);
+        if (requested.has(identity))
+            return true;
+        return prior.has(identity);
+    }).map((message) => ({ messageId: String(message.id), createdAt: message.createdAt, requestId: message.requestId }));
+    if (JSON.stringify(receipts) === JSON.stringify(previous?.messages ?? []))
+        return;
+    stored.set(sessionId, { generation: previous.generation, revision: Math.max(now, previous.revision + 1), messages: receipts });
+    state.visibleMessages = [...stored];
+}
+export function projectVisibleSessionReadState(state, sessionId, messages) {
+    const saved = ensureVisibleReadState(state, sessionId);
+    const assistants = messages.filter((message) => message.role === "assistant");
+    const identities = new Set(saved.messages.map((receipt) => receiptIdentity(receipt.messageId, receipt.createdAt, receipt.requestId)));
+    const wasRead = (message) => identities.has(receiptIdentity(message.id, message.createdAt, message.requestId));
+    const unread = assistants.filter((message) => !wasRead(message));
+    const lastRead = [...assistants].reverse().find(wasRead);
+    return {
+        sessionId, readStateStatus: "available",
+        unreadMessageIds: unread.map((message) => message.id),
+        unreadCount: unread.length, hasUnread: unread.length > 0,
+        readRevision: saved?.revision ?? 0,
+        readGeneration: saved.generation,
+        lastReadAt: saved?.revision ?? state.initializedAt,
+        lastReadMessageId: lastRead?.id ?? null,
+        latestMessageId: messages.at(-1)?.id ?? null,
+        latestAssistantMessageId: assistants.at(-1)?.id ?? null,
+    };
+}

package/dist/src/web-ui/system-host-service.d.ts

@@ -1,15 +1,18 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { Duplex } from "node:stream";
+import { type NativePermissionAccess } from "./system-host-setup/native-permission-route.js";
 export declare class WebSystemHostService {
     private readonly rootDir;
     private readonly store;
     private readonly connection;
     private readonly setup;
+    private readonly permissions;
+    private readonly nativePermissions;
     private readonly wss;
     private broker?;
     private starting?;
     private closing;
-    constructor(rootDir: string, connectionChanged?: () => void);
+    constructor(rootDir: string, connectionChanged?: () => void, nativePermissionAccess?: NativePermissionAccess);
     private ensureStarted;
     /** Native upgrade is separate from browser realtime and requires its own credential. */
     handleUpgrade(request: IncomingMessage, socket: Duplex, head: Buffer, listenHost?: string): boolean;

package/dist/src/web-ui/system-host-service.js

@@ -16,6 +16,8 @@ import { readHostReadiness } from "./system-host-setup/readiness.js";
 import { HostSetupRoutes, isHostSetupRoute, sendHostSetupInputError } from "./system-host-setup/routes.js";
 import { reportHostStartupFailure } from "./system-host-startup-diagnostic.js";
 import { withLocalMacSetup } from "./system-host-setup/local-setup-availability.js";
+import { HOST_PERMISSION_PATH, HostPermissionRoute } from "./system-host-setup/permission-route.js";
+import { NativeRuntimePermissionRoute } from "./system-host-setup/native-permission-route.js";
 function isSystemHostRoute(pathname) {
     if (pathname === "/web-api/runtime/system-host")
         return true;
@@ -26,6 +28,8 @@ export class WebSystemHostService {
     store;
     connection;
     setup;
+    permissions;
+    nativePermissions;
     wss = new WebSocketServer({
         noServer: true,
         maxPayload: HOST_WIRE_MAX_BYTES,
@@ -34,10 +38,12 @@ export class WebSystemHostService {
     broker;
     starting;
     closing = false;
-    constructor(rootDir, connectionChanged) {
+    constructor(rootDir, connectionChanged, nativePermissionAccess) {
         this.rootDir = rootDir;
         this.store = new HostPairingStore(rootDir);
         this.connection = new HostConnection(this.store, connectionChanged);
+        this.nativePermissions = new NativeRuntimePermissionRoute(nativePermissionAccess);
+        this.permissions = new HostPermissionRoute(this.connection, this.nativePermissions);
         this.setup = new HostSetupRoutes({
             store: this.store,
             readiness: () => readHostReadiness(this.connection.status()),
@@ -92,10 +98,14 @@ export class WebSystemHostService {
         this.wss.handleUpgrade(request, socket, head, (client) => this.connection.accept(client, token));
     }
     async handleHttp(request, response, pathname) {
-        if (!isSystemHostRoute(pathname) && !isHostSetupRoute(pathname))
+        if (!isSystemHostRoute(pathname) && !isHostSetupRoute(pathname) && pathname !== HOST_PERMISSION_PATH)
             return false;
         response.setHeader("cache-control", "no-store");
         try {
+            if (pathname === HOST_PERMISSION_PATH) {
+                await this.permissions.handle(request, response);
+                return true;
+            }
             if (isHostSetupRoute(pathname)) {
                 await this.setup.handle(request, response, pathname);
                 return true;
@@ -104,7 +114,8 @@ export class WebSystemHostService {
                 pathname === "/web-api/runtime/system-host") {
                 const status = this.connection.status();
                 const readiness = withLocalMacSetup(request, await readHostReadiness(status));
-                sendJson(response, 200, { ok: true, ...status, readiness });
+                const nativePermissions = await this.nativePermissions.status(request);
+                sendJson(response, 200, { ok: true, ...status, readiness, nativePermissions });
                 return true;
             }
             if (!acceptConfigMutationRequest(request, response))

package/dist/src/web-ui/system-host-setup/companion-linux.js

@@ -15,7 +15,7 @@ export function renderLinuxCompanionScript(input) {
 set -euo pipefail
 umask 077
 if [ "$(uname -s)" != 'Linux' ]; then echo 'Run this setup on the Linux desktop host.' >&2; exit 1; fi
-if [ -n "\${WSL_DISTRO_NAME:-}" ]; then echo 'For a Windows desktop, use the Windows companion installer outside WSL.' >&2; exit 1; fi
+if [ -n "\${WSL_DISTRO_NAME:-}" ]; then echo 'For a Windows desktop, install ABot AI Companion from Microsoft Store on Windows.' >&2; exit 1; fi
 if [ -z "\${DISPLAY:-}" ] && [ -z "\${WAYLAND_DISPLAY:-}" ]; then echo 'Run this setup from your graphical desktop session.' >&2; exit 1; fi
 NODE=$(command -v node || true)
 if [ -z "$NODE" ] || [ ! -x "$NODE" ]; then echo 'Node.js 20.19+ or 22.12+ must already be installed on this computer.' >&2; exit 1; fi

package/dist/src/web-ui/system-host-setup/installer-contract.d.ts

@@ -1,7 +1,7 @@
 export declare class InstallerInputError extends Error {
 }
 export type CompanionInstallerInput = Readonly<{
-    platform: "windows" | "macos" | "linux";
+    platform: "macos" | "linux";
     url: string;
     code: string;
     bundleSha256: string;

package/dist/src/web-ui/system-host-setup/installer-contract.js

@@ -10,8 +10,8 @@ function hasLocalInstallerHost(hostname) {
     return isNativeLoopbackAddress(hostname);
 }
 export function validateCompanionInstaller(input) {
-    if (!["windows", "macos", "linux"].includes(input.platform))
-        throw new InstallerInputError("Choose Windows, macOS or Linux.");
+    if (!["macos", "linux"].includes(input.platform))
+        throw new InstallerInputError("Choose macOS or Linux. Windows Companion is installed and updated through Microsoft Store.");
     if (/[\x00-\x1f\x7f]/u.test(input.url))
         throw new InstallerInputError("The Runtime origin must not contain control characters.");
     let url;

package/dist/src/web-ui/system-host-setup/installers.js

@@ -1,6 +1,5 @@
 import JSZip from "jszip";
 import { validateCompanionInstaller, validateWslDistribution, } from "./installer-contract.js";
-import { renderWindowsCompanionScript } from "./companion-windows.js";
 import { renderMacCompanionScript } from "./companion-macos.js";
 import { renderLinuxCompanionScript } from "./companion-linux.js";
 import { renderWindowsWslInteropScript } from "./wsl-interop-windows.js";
@@ -13,12 +12,6 @@ export async function renderCompanionInstaller(raw) {
             mimeType: "application/x-sh",
             contentBase64: Buffer.from(renderLinuxCompanionScript(input), "utf8").toString("base64"),
         };
-    if (input.platform === "windows")
-        return {
-            filename: "ABot-Connect-Computer.cmd",
-            mimeType: "application/octet-stream",
-            contentBase64: Buffer.from(renderWindowsCompanionScript(input), "utf8").toString("base64"),
-        };
     const zip = new JSZip();
     zip.file("ABot-Connect-Computer.command", renderMacCompanionScript(input), {
         unixPermissions: 0o100755,

package/dist/src/web-ui/system-host-setup/local-connection.d.ts

@@ -2,20 +2,23 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import type { HostPairingStore } from "../../computer-access/companion/pairing-store.js";
 import { installLocalMacCompanion } from "../../computer-access/companion/local-installation.js";
 import type { HostReadiness } from "./readiness.js";
+import { HostSetupMutation } from "./setup-mutation.js";
 export declare const LOCAL_HOST_SETUP_PATH = "/web-api/runtime/system-host/connect-local";
 export declare class LocalHostConnection {
     private readonly dependencies;
-    private pending?;
+    private readonly mutation;
     constructor(dependencies: {
         store: HostPairingStore;
         readiness(): Promise<HostReadiness>;
         prepareCompanion(): Promise<void>;
         bundle(): Promise<Buffer>;
         install?: typeof installLocalMacCompanion;
+        mutation?: HostSetupMutation;
     });
     get busy(): boolean;
     rejectConcurrentMutation(response: ServerResponse): boolean;
     handle(request: IncomingMessage, response: ServerResponse): Promise<void>;
+    private completeConnection;
     private connect;
     close(): Promise<void>;
 }

package/dist/src/web-ui/system-host-setup/local-connection.js

@@ -2,23 +2,21 @@ import { installLocalMacCompanion, LocalCompanionSetupError } from "../../comput
 import { acceptConfigMutationRequest } from "../local-runtime/config-mutation-request.js";
 import { readBody, sendJson } from "../local-runtime/http.js";
 import { canSetUpLocalMac, localMacSetupRuntimeUrl } from "./local-setup-availability.js";
+import { HostSetupMutation } from "./setup-mutation.js";
 export const LOCAL_HOST_SETUP_PATH = "/web-api/runtime/system-host/connect-local";
 function isEmptyLocalSetupRequest(body) {
     return JSON.stringify(body) === "{}";
 }
 export class LocalHostConnection {
     dependencies;
-    pending;
+    mutation;
     constructor(dependencies) {
         this.dependencies = dependencies;
+        this.mutation = dependencies.mutation ?? new HostSetupMutation();
     }
-    get busy() { return this.pending !== undefined; }
+    get busy() { return this.mutation.busy; }
     rejectConcurrentMutation(response) {
-        if (!this.busy)
-            return false;
-        sendJson(response, 409, { ok: false, error: "host_setup_in_progress",
-            message: "Computer access is being connected. Wait for setup to finish." });
-        return true;
+        return this.mutation.rejectConcurrentMutation(response);
     }
     async handle(request, response) {
         if (request.method !== "POST") {
@@ -37,18 +35,17 @@ export class LocalHostConnection {
             sendJson(response, 400, { ok: false, error: "unexpected_host_configuration_fields" });
             return;
         }
+        await this.mutation.run(response, () => this.completeConnection(request, response));
+    }
+    async completeConnection(request, response) {
         const readiness = await this.dependencies.readiness();
         if (!canSetUpLocalMac(request, readiness)) {
             sendJson(response, 409, { ok: false, error: "host_local_setup_unavailable",
                 message: "Direct setup requires ABot running natively on this Mac through its local address. Use a pairing code on the Mac for Docker or a forwarded Runtime." });
             return;
         }
-        if (this.rejectConcurrentMutation(response))
-            return;
-        const pending = this.connect(localMacSetupRuntimeUrl(request));
-        this.pending = pending;
         try {
-            await pending;
+            await this.connect(localMacSetupRuntimeUrl(request));
             sendJson(response, 200, { ok: true });
         }
         catch (error) {
@@ -56,10 +53,6 @@ export class LocalHostConnection {
                 throw error;
             sendJson(response, 503, { ok: false, error: error.code, message: error.message });
         }
-        finally {
-            if (this.pending === pending)
-                this.pending = undefined;
-        }
     }
     async connect(url) {
         const bundle = await this.dependencies.bundle();
@@ -73,5 +66,5 @@ export class LocalHostConnection {
             ...(host ? { upgradeHostId: host.hostId } : {}),
         });
     }
-    async close() { await this.pending?.catch(() => undefined); }
+    async close() { await this.mutation.close(); }
 }

package/dist/src/web-ui/system-host-setup/local-request-authority.d.ts

@@ -0,0 +1,3 @@
+import type { IncomingMessage } from "node:http";
+/** Native preparation controls this listener's Mac, never a remote browser's OS. */
+export declare function hasLocalRuntimeRequestAuthority(request: IncomingMessage): boolean;

package/dist/src/web-ui/system-host-setup/local-request-authority.js

@@ -0,0 +1,15 @@
+import { isNativeLoopbackAddress } from "../../computer-access/companion/native-address.js";
+import { hasLoopbackRequestAuthority } from "../request-authority.js";
+/** Native preparation controls this listener's Mac, never a remote browser's OS. */
+export function hasLocalRuntimeRequestAuthority(request) {
+    if (!hasLoopbackRequestAuthority(request))
+        return false;
+    if (!isNativeLoopbackAddress(request.socket.remoteAddress ?? ""))
+        return false;
+    if (!isNativeLoopbackAddress(request.socket.localAddress ?? ""))
+        return false;
+    const encrypted = "encrypted" in request.socket && request.socket.encrypted;
+    const authority = new URL(`${encrypted ? "https" : "http"}://${request.headers.host}`);
+    const port = Number(authority.port || (encrypted ? 443 : 80));
+    return port === request.socket.localPort;
+}

package/dist/src/web-ui/system-host-setup/local-setup-availability.js

@@ -1,7 +1,6 @@
 import { isIP } from "node:net";
 import { hostname } from "node:os";
-import { isNativeLoopbackAddress } from "../../computer-access/companion/native-address.js";
-import { hasLoopbackRequestAuthority } from "../request-authority.js";
+import { hasLocalRuntimeRequestAuthority } from "./local-request-authority.js";
 /** Local setup controls the Runtime's computer, never an inferred browser OS. */
 export function canSetUpLocalMac(request, readiness, platform = process.platform) {
     if (platform !== "darwin")
@@ -12,16 +11,7 @@ export function canSetUpLocalMac(request, readiness, platform = process.platform
         return false;
     if (readiness.ready)
         return false;
-    if (!hasLoopbackRequestAuthority(request))
-        return false;
-    if (!isNativeLoopbackAddress(request.socket.remoteAddress ?? ""))
-        return false;
-    if (!isNativeLoopbackAddress(request.socket.localAddress ?? ""))
-        return false;
-    const encrypted = "encrypted" in request.socket && request.socket.encrypted;
-    const authority = new URL(`${encrypted ? "https" : "http"}://${request.headers.host}`);
-    const port = Number(authority.port || (encrypted ? 443 : 80));
-    return port === request.socket.localPort;
+    return hasLocalRuntimeRequestAuthority(request);
 }
 /** Use only after eligibility validates the loopback listener and authority. */
 export function localMacSetupRuntimeUrl(request) {

package/dist/src/web-ui/system-host-setup/native-permission-route.d.ts

@@ -0,0 +1,26 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { type NativePermissionClient } from "../../computer-access/native-permission-contract.js";
+export type NativePermissionAccess = (environmentId: string) => NativePermissionClient | undefined;
+export declare function isNativeRuntimePermissionRequest(value: unknown): value is Record<string, unknown>;
+/** Browser management binds to a running environment owner; it never starts one. */
+export declare class NativeRuntimePermissionRoute {
+    private readonly clients;
+    private readonly platform;
+    constructor(clients?: NativePermissionAccess, platform?: NodeJS.Platform);
+    private unavailableReason;
+    private hasCurrentOwner;
+    status(request: IncomingMessage): Promise<{
+        available: boolean;
+        reason: string;
+        scope: "native_runtime";
+        environmentId: string;
+    } | {
+        available: true;
+        ownerId: string;
+        computerName: string;
+        executablePath: string;
+        scope: "native_runtime";
+        environmentId: string;
+    }>;
+    handle(request: IncomingMessage, response: ServerResponse, body: Record<string, unknown>): Promise<void>;
+}

package/dist/src/web-ui/system-host-setup/native-permission-route.js

@@ -0,0 +1,96 @@
+import { isHostRecord } from "../../computer-access/companion/protocol.js";
+import { isNativePermissionEnvironment, readNativePermissionInput } from "../../computer-access/native-permission-contract.js";
+import { sendJson } from "../local-runtime/http.js";
+import { hasLocalRuntimeRequestAuthority } from "./local-request-authority.js";
+export function isNativeRuntimePermissionRequest(value) {
+    return isHostRecord(value) && value.scope === "native_runtime";
+}
+/** Browser management binds to a running environment owner; it never starts one. */
+export class NativeRuntimePermissionRoute {
+    clients;
+    platform;
+    constructor(clients = () => undefined, platform = process.platform) {
+        this.clients = clients;
+        this.platform = platform;
+    }
+    unavailableReason(request) {
+        if (this.platform !== "darwin")
+            return "native_macos_unavailable";
+        if (!hasLocalRuntimeRequestAuthority(request))
+            return "local_browser_required";
+        return undefined;
+    }
+    hasCurrentOwner(environmentId, client, status, ownerId) {
+        if (!status.available)
+            return false;
+        if (status.ownerId !== ownerId)
+            return false;
+        return this.clients(environmentId) === client;
+    }
+    async status(request) {
+        const environmentId = new URL(request.url ?? "/", "http://localhost").searchParams.get("environment") ?? "";
+        const binding = { scope: "native_runtime", environmentId };
+        const unavailable = this.unavailableReason(request);
+        if (unavailable)
+            return { ...binding, available: false, reason: unavailable };
+        if (!isNativePermissionEnvironment(environmentId))
+            return { ...binding, available: false, reason: "runtime_not_started" };
+        const client = this.clients(environmentId);
+        if (!client)
+            return { ...binding, available: false, reason: "runtime_not_started" };
+        try {
+            const status = await client.status();
+            if (this.clients(environmentId) !== client)
+                return { ...binding, available: false, reason: "runtime_owner_unavailable" };
+            return { ...binding, ...status };
+        }
+        catch {
+            return { ...binding, available: false, reason: "runtime_owner_unavailable" };
+        }
+    }
+    async handle(request, response, body) {
+        const { scope, environmentId, ...fields } = body;
+        const input = readNativePermissionInput(fields);
+        if (scope !== "native_runtime" || !isNativePermissionEnvironment(environmentId) || !input) {
+            sendJson(response, 400, { ok: false, error: "macos_permissions_input_invalid" });
+            return;
+        }
+        const unavailable = this.unavailableReason(request);
+        if (unavailable) {
+            sendJson(response, 409, { ok: false, error: unavailable, message: "Prepare native permissions from this Mac's local ABot page." });
+            return;
+        }
+        const client = this.clients(environmentId);
+        if (!client) {
+            sendJson(response, 409, { ok: false, error: "runtime_not_started", message: "Start the selected Runtime environment, then check its native permissions." });
+            return;
+        }
+        try {
+            const status = await client.status();
+            if (response.destroyed)
+                return;
+            if (!this.hasCurrentOwner(environmentId, client, status, input.ownerId))
+                throw new Error("macos_permissions_owner_changed");
+            const result = await client.prepare(input);
+            if (response.destroyed)
+                return;
+            if (this.clients(environmentId) !== client)
+                throw new Error("macos_permissions_owner_changed");
+            sendJson(response, 200, { ok: true, scope, environmentId, ...result });
+        }
+        catch (error) {
+            if (response.destroyed)
+                return;
+            const code = error instanceof Error ? error.message : "macos_permissions_check_failed";
+            if (code === "macos_permissions_owner_changed") {
+                sendJson(response, 409, { ok: false, error: code, message: "The native Runtime owner changed. Refresh and check its permissions again." });
+                return;
+            }
+            if (code === "macos_permissions_busy") {
+                sendJson(response, 409, { ok: false, error: code, message: "A permission check or request is already in progress for this Runtime." });
+                return;
+            }
+            sendJson(response, 503, { ok: false, error: "macos_permissions_check_failed", message: "Native permission preparation did not complete. Check the running Runtime and Swift developer tools. Any macOS permission prompt already opened is not revoked." });
+        }
+    }
+}

package/dist/src/web-ui/system-host-setup/permission-route.d.ts

@@ -0,0 +1,13 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { HostConnection } from "../../computer-access/companion/connection.js";
+import { type NativeRuntimePermissionRoute } from "./native-permission-route.js";
+export declare const HOST_PERMISSION_PATH = "/web-api/runtime/system-host/permissions";
+/** User-only setup endpoint; permission actions are never exposed as model tools. */
+export declare class HostPermissionRoute {
+    private readonly connection;
+    private readonly native?;
+    private busy;
+    constructor(connection: Pick<HostConnection, "status" | "execute">, native?: NativeRuntimePermissionRoute | undefined);
+    private hasCurrentMacBinding;
+    handle(request: IncomingMessage, response: ServerResponse): Promise<void>;
+}