@abot-ai/runtime 1.4.0 → 1.5.0

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

@@ -0,0 +1,50 @@
+import { shellString, } from "./installer-contract.js";
+/** Native desktop install; Node and desktop accessibility dependencies remain user-managed. */
+export function renderLinuxCompanionScript(input) {
+    const url = new URL(input.url);
+    const localAlias = url.hostname === "localhost" || url.hostname.endsWith(".localhost");
+    const resolve = localAlias
+        ? ` --resolve ${shellString(`${url.hostname}:${url.port || "80"}:127.0.0.1`)}`
+        : "";
+    const payload = JSON.stringify({
+        url: input.url,
+        code: input.code,
+        ...(input.upgradeHostId ? { upgradeHostId: input.upgradeHostId } : {}),
+    });
+    return `#!/bin/bash
+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 [ -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
+"$NODE" -e 'const [major,minor]=process.versions.node.split(".").map(Number); if(!((major===20&&minor>=19)||(major===22&&minor>=12)||major>22))process.exit(1)' || { echo 'The installed Node.js version is unsupported.' >&2; exit 1; }
+for TOOL in curl sha256sum mktemp; do command -v "$TOOL" >/dev/null || { echo "Required tool is unavailable: $TOOL" >&2; exit 1; }; done
+BASE="\${XDG_DATA_HOME:-$HOME/.local/share}/ABot/HostCompanion"
+case "$BASE" in /*) ;; *) echo 'The installation directory must be absolute.' >&2; exit 1 ;; esac
+TEMP=''
+cleanup() { case "$TEMP" in "$BASE"/setup.*) rm -rf -- "$TEMP" ;; esac; }
+trap cleanup EXIT
+if [ -L "$BASE" ]; then echo 'The installation directory must not be a link.' >&2; exit 1; fi
+mkdir -p "$BASE"
+if [ ! -O "$BASE" ]; then echo 'The installation directory must belong to this user.' >&2; exit 1; fi
+chmod 700 "$BASE"
+BUNDLE="$BASE/companion-${input.bundleSha256}.mjs"
+if [ -L "$BUNDLE" ]; then echo 'The companion bundle must not be a link.' >&2; exit 1; fi
+if [ ! -f "$BUNDLE" ]; then
+  if [ "$(date +%s)" -ge ${Math.floor(Date.parse(input.expiresAt) / 1000)} ]; then echo 'This setup invitation expired. Download a fresh setup file in ABot.' >&2; exit 1; fi
+  TEMP=$(mktemp -d "$BASE/setup.XXXXXX")
+  PAIRING_CODE=${shellString(input.code)}
+  printf 'header = "Authorization: Bearer %s"\n' "$PAIRING_CODE" | curl --config - --fail --show-error --silent --proto '=http' --max-redirs 0 --noproxy '*' --connect-timeout 10 --max-time 120${resolve} --output "$TEMP/companion.mjs" ${shellString(input.url + "/web-api/runtime/system-host/bundle")}
+  ACTUAL_SHA=$(sha256sum "$TEMP/companion.mjs"); ACTUAL_SHA=\${ACTUAL_SHA%% *}
+  if [ "$ACTUAL_SHA" != '${input.bundleSha256}' ]; then echo 'Companion checksum verification failed. Nothing was executed.' >&2; exit 1; fi
+  chmod 600 "$TEMP/companion.mjs"
+  mv "$TEMP/companion.mjs" "$BUNDLE"
+fi
+ACTUAL_SHA=$(sha256sum "$BUNDLE"); ACTUAL_SHA=\${ACTUAL_SHA%% *}
+if [ "$ACTUAL_SHA" != '${input.bundleSha256}' ]; then echo 'The installed bundle does not match its checksum.' >&2; exit 1; fi
+printf '%s' ${shellString(payload)} | "$NODE" "$BUNDLE" setup
+echo 'Companion connected for this user and registered for graphical login. Return to ABot to use the connected computer.'
+`;
+}

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

@@ -6,7 +6,11 @@ export function renderMacCompanionScript(input) {
     const resolve = localAlias
         ? ` --resolve ${shellString(`${url.hostname}:${url.port || "80"}:127.0.0.1`)}`
         : "";
-    const payload = JSON.stringify({ url: input.url, code: input.code });
+    const payload = JSON.stringify({
+        url: input.url,
+        code: input.code,
+        ...(input.upgradeHostId ? { upgradeHostId: input.upgradeHostId } : {}),
+    });
     return `#!/bin/bash
 set -euo pipefail
 umask 077
@@ -22,6 +26,11 @@ verify_installation_directory() {
   if [ -L "$BASE" ]; then echo 'The installation directory must not be a link.' >&2; exit 1; fi
   if [ ! -O "$BASE" ]; then echo 'The installation directory must belong to this user.' >&2; exit 1; fi
 }
+can_resume_cached_setup() {
+  [ -f "$HOME/.abot/host-companion/connection.json" ] || return 1
+  [ -f "$NODE" ] || return 1
+  [ -f "$BUNDLE" ]
+}
 run_verified_companion_setup() {
   if [ ! -f "$NODE" ]; then echo 'The cached Node.js runtime is missing. Restore this installation before resuming setup.' >&2; exit 1; fi
   if [ ! -f "$BUNDLE" ]; then echo 'The cached companion bundle is missing. Restore this installation before resuming setup.' >&2; exit 1; fi
@@ -41,7 +50,7 @@ esac
 NODE_NAME="node-${COMPANION_NODE_VERSION}-darwin-$ARCH"
 NODE="$BASE/$NODE_NAME/bin/node"
 BUNDLE="$BASE/companion-${input.bundleSha256}.mjs"
-if [ -e "$HOME/.abot/host-companion/connection.json" ]; then
+if can_resume_cached_setup; then
   run_verified_companion_setup
   exit 0
 fi

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

@@ -23,7 +23,9 @@ function Invoke-VerifiedCompanionSetup {
   if ((& $Node --version) -ne $Metadata.nodeVersion -or $LASTEXITCODE -ne 0) { throw 'The dedicated Node.js runtime could not be verified.' }
   if ((Get-FileHash -LiteralPath $Bundle -Algorithm SHA256).Hash -ne $Metadata.bundleSha256) { throw 'The existing companion bundle does not match its recorded checksum.' }
   Write-Host 'Connecting this computer and enabling startup at sign-in...'
-  $Payload = @{ url = $Metadata.url; code = $Metadata.code } | ConvertTo-Json -Compress
+  $Setup = @{ url = $Metadata.url; code = $Metadata.code }
+  if ($Metadata.upgradeHostId) { $Setup.upgradeHostId = $Metadata.upgradeHostId }
+  $Payload = $Setup | ConvertTo-Json -Compress
   $Payload | & $Node $Bundle setup
   if ($LASTEXITCODE -ne 0) { throw 'Companion setup did not complete. Check the message above before resuming setup.' }
   Write-Host 'Companion setup completed. Return to ABot to check the computer connection.'
@@ -68,7 +70,8 @@ try {
   $Node = Join-Path $NodeDirectory 'node.exe'
   $Bundle = Join-Path $Base ('companion-' + $Metadata.bundleSha256 + '.mjs')
   $ExistingConnection = Join-Path ([Environment]::GetFolderPath('UserProfile')) '.abot\host-companion\connection.json'
-  if (Test-Path -LiteralPath $ExistingConnection) {
+  $CanResumeCached = (Test-Path -LiteralPath $ExistingConnection -PathType Leaf) -and (Test-Path -LiteralPath $Node -PathType Leaf) -and (Test-Path -LiteralPath $Bundle -PathType Leaf)
+  if ($CanResumeCached) {
     Invoke-VerifiedCompanionSetup
     exit 0
   }

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

@@ -1,11 +1,12 @@
 export declare class InstallerInputError extends Error {
 }
 export type CompanionInstallerInput = Readonly<{
-    platform: "windows" | "macos";
+    platform: "windows" | "macos" | "linux";
     url: string;
     code: string;
     bundleSha256: string;
     expiresAt: string;
+    upgradeHostId?: string;
 }>;
 export type InstallerDownload = Readonly<{
     filename: string;

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

@@ -1,4 +1,5 @@
-import { isNativeLoopbackAddress } from "../../../plugins/system/source/companion/native-address.js";
+import { isNativeLoopbackAddress } from "../../computer-access/companion/native-address.js";
+import { isHostIdentifier } from "../../computer-access/companion/protocol.js";
 export class InstallerInputError extends Error {
 }
 function hasLocalInstallerHost(hostname) {
@@ -9,8 +10,8 @@ function hasLocalInstallerHost(hostname) {
     return isNativeLoopbackAddress(hostname);
 }
 export function validateCompanionInstaller(input) {
-    if (!["windows", "macos"].includes(input.platform))
-        throw new InstallerInputError("Choose Windows or macOS.");
+    if (!["windows", "macos", "linux"].includes(input.platform))
+        throw new InstallerInputError("Choose Windows, macOS or Linux.");
     if (/[\x00-\x1f\x7f]/u.test(input.url))
         throw new InstallerInputError("The Runtime origin must not contain control characters.");
     let url;
@@ -22,7 +23,11 @@ export function validateCompanionInstaller(input) {
     }
     if (url.protocol !== "http:")
         throw new InstallerInputError("Downloaded setup currently requires a local HTTP Runtime address. HTTPS setup is not supported; certificate verification is never disabled.");
-    if (url.username || url.password || url.search || url.hash || url.pathname !== "/")
+    if (url.username ||
+        url.password ||
+        url.search ||
+        url.hash ||
+        url.pathname !== "/")
         throw new InstallerInputError("Use a Runtime origin without credentials, a path, query or fragment.");
     if (!hasLocalInstallerHost(url.hostname))
         throw new InstallerInputError("Setup can connect only to a Runtime on this computer's loopback interface.");
@@ -32,7 +37,15 @@ export function validateCompanionInstaller(input) {
         throw new InstallerInputError("The companion bundle checksum is invalid.");
     if (!Number.isFinite(Date.parse(input.expiresAt)))
         throw new InstallerInputError("The pairing expiration is invalid.");
-    return { ...input, url: url.origin, expiresAt: new Date(input.expiresAt).toISOString(), bundleSha256: input.bundleSha256.toLowerCase() };
+    if (input.upgradeHostId !== undefined &&
+        !isHostIdentifier(input.upgradeHostId))
+        throw new InstallerInputError("The paired computer identity is invalid.");
+    return {
+        ...input,
+        url: url.origin,
+        expiresAt: new Date(input.expiresAt).toISOString(),
+        bundleSha256: input.bundleSha256.toLowerCase(),
+    };
 }
 export function validateWslDistribution(distribution) {
     if (distribution === undefined)

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

@@ -2,10 +2,17 @@ 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";
 export { InstallerInputError } from "./installer-contract.js";
 export async function renderCompanionInstaller(raw) {
     const input = validateCompanionInstaller(raw);
+    if (input.platform === "linux")
+        return {
+            filename: "ABot-Connect-Computer-Linux.sh",
+            mimeType: "application/x-sh",
+            contentBase64: Buffer.from(renderLinuxCompanionScript(input), "utf8").toString("base64"),
+        };
     if (input.platform === "windows")
         return {
             filename: "ABot-Connect-Computer.cmd",
@@ -13,11 +20,17 @@ export async function renderCompanionInstaller(raw) {
             contentBase64: Buffer.from(renderWindowsCompanionScript(input), "utf8").toString("base64"),
         };
     const zip = new JSZip();
-    zip.file("ABot-Connect-Computer.command", renderMacCompanionScript(input), { unixPermissions: 0o100755 });
+    zip.file("ABot-Connect-Computer.command", renderMacCompanionScript(input), {
+        unixPermissions: 0o100755,
+    });
     return {
         filename: "ABot-Connect-Computer-macOS.zip",
         mimeType: "application/zip",
-        contentBase64: await zip.generateAsync({ type: "base64", platform: "UNIX", compression: "DEFLATE" }),
+        contentBase64: await zip.generateAsync({
+            type: "base64",
+            platform: "UNIX",
+            compression: "DEFLATE",
+        }),
     };
 }
 export async function renderWslInteropInstaller(input) {

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

@@ -0,0 +1,21 @@
+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";
+export declare const LOCAL_HOST_SETUP_PATH = "/web-api/runtime/system-host/connect-local";
+export declare class LocalHostConnection {
+    private readonly dependencies;
+    private pending?;
+    constructor(dependencies: {
+        store: HostPairingStore;
+        readiness(): Promise<HostReadiness>;
+        prepareCompanion(): Promise<void>;
+        bundle(): Promise<Buffer>;
+        install?: typeof installLocalMacCompanion;
+    });
+    get busy(): boolean;
+    rejectConcurrentMutation(response: ServerResponse): boolean;
+    handle(request: IncomingMessage, response: ServerResponse): Promise<void>;
+    private connect;
+    close(): Promise<void>;
+}

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

@@ -0,0 +1,77 @@
+import { installLocalMacCompanion, LocalCompanionSetupError } from "../../computer-access/companion/local-installation.js";
+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";
+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;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    get busy() { return this.pending !== undefined; }
+    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;
+    }
+    async handle(request, response) {
+        if (request.method !== "POST") {
+            sendJson(response, 405, { ok: false, error: "method_not_allowed" });
+            return;
+        }
+        if (!acceptConfigMutationRequest(request, response))
+            return;
+        const raw = await readBody(request, { maxBytes: 1024 });
+        let body;
+        try {
+            body = JSON.parse(raw.toString());
+        }
+        catch { /* rejected below */ }
+        if (!isEmptyLocalSetupRequest(body)) {
+            sendJson(response, 400, { ok: false, error: "unexpected_host_configuration_fields" });
+            return;
+        }
+        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;
+            sendJson(response, 200, { ok: true });
+        }
+        catch (error) {
+            if (!(error instanceof LocalCompanionSetupError))
+                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();
+        await this.dependencies.prepareCompanion();
+        const host = this.dependencies.store.host();
+        const grant = host
+            ? this.dependencies.store.beginBundleUpgrade()
+            : this.dependencies.store.begin(15 * 60_000);
+        await (this.dependencies.install ?? installLocalMacCompanion)({
+            bundle, url, code: grant.code,
+            ...(host ? { upgradeHostId: host.hostId } : {}),
+        });
+    }
+    async close() { await this.pending?.catch(() => undefined); }
+}

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

@@ -0,0 +1,7 @@
+import type { IncomingMessage } from "node:http";
+import type { HostReadiness } from "./readiness.js";
+/** Local setup controls the Runtime's computer, never an inferred browser OS. */
+export declare function canSetUpLocalMac(request: IncomingMessage, readiness: HostReadiness, platform?: NodeJS.Platform): boolean;
+/** Use only after eligibility validates the loopback listener and authority. */
+export declare function localMacSetupRuntimeUrl(request: IncomingMessage): string;
+export declare function withLocalMacSetup(request: IncomingMessage, readiness: HostReadiness): HostReadiness;

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

@@ -0,0 +1,44 @@
+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";
+/** Local setup controls the Runtime's computer, never an inferred browser OS. */
+export function canSetUpLocalMac(request, readiness, platform = process.platform) {
+    if (platform !== "darwin")
+        return false;
+    if (readiness.environment !== "native")
+        return false;
+    if (!readiness.platforms.includes("macos"))
+        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;
+}
+/** Use only after eligibility validates the loopback listener and authority. */
+export function localMacSetupRuntimeUrl(request) {
+    const encrypted = "encrypted" in request.socket && request.socket.encrypted;
+    if (encrypted)
+        return new URL(`https://${request.headers.host}`).origin;
+    const address = request.socket.localAddress;
+    const host = isIP(address) === 6 ? `[${address}]` : address;
+    return new URL(`http://${host}:${request.socket.localPort}`).origin;
+}
+export function withLocalMacSetup(request, readiness) {
+    if (!canSetUpLocalMac(request, readiness))
+        return { ...readiness, localSetupAvailable: false };
+    return {
+        ...readiness,
+        localSetupAvailable: true,
+        localComputerName: hostname(),
+        message: "Connect this Mac using the installed ABot Runtime. The companion starts now and at sign-in; macOS permissions are requested separately.",
+    };
+}

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

@@ -1,13 +1,17 @@
-import { type SystemHostFacts } from "../../../plugins/system/source/host-observation.js";
-import { resolveSystemTarget } from "../../../plugins/system/source/targets.js";
-import type { HostStatus } from "../../../plugins/system/source/companion/protocol.js";
-export type HostSetupPlatform = "windows" | "macos";
+import { type SystemHostFacts } from "../../computer-access/host-observation.js";
+import { resolveSystemTarget } from "../../computer-access/targets.js";
+import type { HostStatus } from "../../computer-access/companion/protocol.js";
+export type HostSetupPlatform = "windows" | "macos" | "linux";
 export type HostReadiness = Readonly<{
     ready: boolean;
     route: "native" | "wsl_interop" | "companion" | "setup_required";
     environment: "native" | "wsl" | "container";
     platforms: readonly HostSetupPlatform[];
     restartRequired: boolean;
+    companionUpdateRequired?: boolean;
+    directAccessReady?: boolean;
+    localSetupAvailable?: boolean;
+    localComputerName?: string;
     distribution?: string;
     message?: string;
 }>;

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

@@ -1,5 +1,7 @@
-import { observeSystemHost, readSystemHostFacts, } from "../../../plugins/system/source/host-observation.js";
-import { resolveSystemTarget } from "../../../plugins/system/source/targets.js";
+import { observeSystemHost, readSystemHostFacts, } from "../../computer-access/host-observation.js";
+import { resolveSystemTarget } from "../../computer-access/targets.js";
+import { OBSERVATION_CAPABILITY } from "../../computer-access/companion/observation-protocol.js";
+import { COMPUTER_CAPABILITY } from "../../computer-access/computer/native-validation.js";
 function classifyHostEnvironment(facts) {
     const observed = observeSystemHost(facts);
     if (observed.environment === "container")
@@ -8,63 +10,90 @@ function classifyHostEnvironment(facts) {
         return "wsl";
     return "native";
 }
+function isCompanionComputerControlReady(status) {
+    if (!status.connected)
+        return false;
+    if (status.companion?.updateAvailable)
+        return false;
+    if (!status.capabilities?.includes(OBSERVATION_CAPABILITY))
+        return false;
+    return status.capabilities.includes(COMPUTER_CAPABILITY);
+}
+function isCompanionNewerThanRuntime(status) {
+    const release = status.companion;
+    if (!release?.installedVersion)
+        return false;
+    return release.installedVersion > release.availableVersion;
+}
+function readPairedCompanionReadiness(status, environment) {
+    const base = {
+        route: "companion",
+        environment,
+        platforms: [],
+        restartRequired: false,
+    };
+    if (isCompanionComputerControlReady(status))
+        return { ...base, ready: true, message: "Connected computer is ready." };
+    if (isCompanionNewerThanRuntime(status))
+        return {
+            ...base,
+            ready: false,
+            message: "This companion is newer than this Runtime. Update ABot before setting up computer access again.",
+        };
+    if (!status.connected)
+        return {
+            ...base,
+            ready: false,
+            companionUpdateRequired: true,
+            platforms: status.identity ? [status.identity.os] : [],
+            message: "The paired computer is offline. Sign in to reconnect, or use Computer access setup to repair its connection. Your existing pairing is kept.",
+        };
+    return {
+        ...base,
+        ready: false,
+        companionUpdateRequired: true,
+        platforms: status.identity ? [status.identity.os] : [],
+        message: status.companion?.updateAvailable === false
+            ? "Reinstall this computer's connection for computer tools and background collection. Your existing pairing is kept."
+            : "Update this computer's connection for computer tools and background collection. Your existing pairing is kept.",
+    };
+}
 export async function readHostReadiness(status, dependencies = {}) {
     const facts = dependencies.facts ?? readSystemHostFacts();
     const observed = observeSystemHost(facts);
     const environment = classifyHostEnvironment(facts);
     if (status.paired)
-        return {
-            ready: status.connected,
-            route: "companion",
-            environment,
-            platforms: [],
-            restartRequired: false,
-            message: status.connected
-                ? "Connected computer is ready."
-                : "The paired computer is offline. Sign in on that computer to reconnect.",
-        };
+        return readPairedCompanionReadiness(status, environment);
     if (environment === "container")
         return {
             ready: false,
             route: "setup_required",
             environment,
-            platforms: ["windows", "macos"],
+            platforms: ["windows", "macos", "linux"],
             restartRequired: false,
-            message: "Install the connection on the Windows or Mac computer running Docker.",
+            message: "Install the connection on the Windows, Mac or Linux computer running Docker.",
         };
     const target = environment === "wsl" ? "windows" : observed.runtimeOs;
     const resolveTarget = dependencies.resolveTarget ?? resolveSystemTarget;
+    let directAccessReady = false;
     try {
-        if (target === "unsupported")
-            throw new Error("unsupported_native_platform");
-        await resolveTarget(target);
-        return {
-            ready: true,
-            route: environment === "wsl" ? "wsl_interop" : "native",
-            environment,
-            platforms: [],
-            restartRequired: false,
-            message: "Direct system access is ready. No additional installation is needed.",
-        };
+        if (target !== "unsupported") {
+            await resolveTarget(target);
+            directAccessReady = true;
+        }
     }
     catch {
-        if (environment === "wsl")
-            return {
-                ready: false,
-                route: "setup_required",
-                environment,
-                platforms: ["windows"],
-                restartRequired: true,
-                distribution: dependencies.distribution ?? process.env.WSL_DISTRO_NAME,
-                message: "Windows interop is unavailable. Open the Windows setup script. It enables access and automatically restarts the selected WSL distribution, interrupting its running services.",
-            };
-        return {
-            ready: false,
-            route: "setup_required",
-            environment,
-            platforms: [],
-            restartRequired: false,
-            message: "The native execution target is unavailable. Restore the operating system shell, then refresh status.",
-        };
+        // The shared companion also serves hosts without native shell/WSL interop.
     }
+    return {
+        ready: false,
+        route: "setup_required",
+        environment,
+        platforms: target === "unsupported" ? [] : [target],
+        restartRequired: false,
+        directAccessReady,
+        message: directAccessReady
+            ? "Direct commands are available. Set up Computer access once to also connect desktop tools and ABot Spark."
+            : "Set up Computer access once for desktop tools and ABot Spark. The connection does not require WSL interop or a WSL restart.",
+    };
 }

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

@@ -1,5 +1,5 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
-import type { HostPairingStore } from "../../../plugins/system/source/companion/pairing-store.js";
+import type { HostPairingStore } from "../../computer-access/companion/pairing-store.js";
 import type { HostReadiness } from "./readiness.js";
 export declare function isHostSetupRoute(pathname: string): boolean;
 export declare function sendHostSetupInputError(response: ServerResponse, error: unknown): boolean;
@@ -12,7 +12,10 @@ export type HostSetupRouteDependencies = {
 /** GUI writes use same-origin JSON; native code downloads use the expiring setup grant. */
 export declare class HostSetupRoutes {
     private readonly dependencies;
+    private readonly local;
     constructor(dependencies: HostSetupRouteDependencies);
+    rejectConcurrentMutation(response: ServerResponse): boolean;
+    close(): Promise<void>;
     private bundle;
     handle(request: IncomingMessage, response: ServerResponse, pathname: string): Promise<void>;
     private downloadBundle;