@abot-ai/runtime 1.3.1 → 1.5.0

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

@@ -0,0 +1,19 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { Duplex } from "node:stream";
+export declare class WebSystemHostService {
+    private readonly rootDir;
+    private readonly store;
+    private readonly connection;
+    private readonly setup;
+    private readonly wss;
+    private broker?;
+    private starting?;
+    private closing;
+    constructor(rootDir: string, connectionChanged?: () => void);
+    private ensureStarted;
+    /** Native upgrade is separate from browser realtime and requires its own credential. */
+    handleUpgrade(request: IncomingMessage, socket: Duplex, head: Buffer, listenHost?: string): boolean;
+    private acceptCompanion;
+    handleHttp(request: IncomingMessage, response: ServerResponse, pathname: string): Promise<boolean>;
+    close(): Promise<void>;
+}

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

@@ -0,0 +1,168 @@
+import { join } from "node:path";
+import { WebSocketServer } from "ws";
+import { HostConnection } from "../computer-access/companion/connection.js";
+import { HostPairingStore } from "../computer-access/companion/pairing-store.js";
+import { startHostBroker } from "../computer-access/companion/broker-server.js";
+import { hostStateDirectory } from "../computer-access/companion/private-store.js";
+import { HOST_SOCKET_PATH, HOST_WIRE_MAX_BYTES, } from "../computer-access/companion/protocol.js";
+import { isProcessOwnerAlive, requireCurrentProcessOwnerIdentity, } from "../computer-access/companion/process-owner-identity.js";
+import { ensurePrivateRuntimeDirectory } from "../runtime/local-host/private-directory.js";
+import { acquireFileLock } from "../runtime/adapters/long-term-memory/file-lock/acquisition.js";
+import { acceptConfigMutationRequest } from "./local-runtime/config-mutation-request.js";
+import { readBody, sendJson } from "./local-runtime/http.js";
+import { hostBearerCredential } from "./system-host-setup/native-authorization.js";
+import { hasTrustedSystemHostUpgrade, rejectSystemHostUpgrade } from "./system-host-upgrade-authority.js";
+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";
+function isSystemHostRoute(pathname) {
+    if (pathname === "/web-api/runtime/system-host")
+        return true;
+    return pathname === "/web-api/runtime/system-host/pairing";
+}
+export class WebSystemHostService {
+    rootDir;
+    store;
+    connection;
+    setup;
+    wss = new WebSocketServer({
+        noServer: true,
+        maxPayload: HOST_WIRE_MAX_BYTES,
+        perMessageDeflate: false,
+    });
+    broker;
+    starting;
+    closing = false;
+    constructor(rootDir, connectionChanged) {
+        this.rootDir = rootDir;
+        this.store = new HostPairingStore(rootDir);
+        this.connection = new HostConnection(this.store, connectionChanged);
+        this.setup = new HostSetupRoutes({
+            store: this.store,
+            readiness: () => readHostReadiness(this.connection.status()),
+            prepareCompanion: () => this.ensureStarted(),
+        });
+    }
+    ensureStarted() {
+        if (this.closing)
+            return Promise.reject(new Error("host_service_stopped"));
+        this.starting ??= (async () => {
+            await ensurePrivateRuntimeDirectory(hostStateDirectory(this.rootDir));
+            const ownerIdentity = await requireCurrentProcessOwnerIdentity();
+            this.broker = await startHostBroker(this.rootDir, this.connection, () => acquireFileLock(join(hostStateDirectory(this.rootDir), "owner.lock"), {
+                waitMs: 0,
+                ownerIdentity,
+                processIsAlive: isProcessOwnerAlive,
+            }));
+        })().catch((error) => {
+            this.starting = undefined;
+            reportHostStartupFailure(error);
+            throw error;
+        });
+        return this.starting;
+    }
+    /** Native upgrade is separate from browser realtime and requires its own credential. */
+    handleUpgrade(request, socket, head, listenHost = "127.0.0.1") {
+        const pathname = new URL(request.url ?? "/", "http://localhost").pathname;
+        if (pathname !== HOST_SOCKET_PATH)
+            return false;
+        if (!hasTrustedSystemHostUpgrade(request, listenHost)) {
+            rejectSystemHostUpgrade(socket);
+            return true;
+        }
+        void this.acceptCompanion(request, socket, head).catch(() => socket.destroy());
+        return true;
+    }
+    async acceptCompanion(request, socket, head) {
+        await this.ensureStarted();
+        const token = hostBearerCredential(request);
+        if (!token || !this.store.authenticate(token)) {
+            rejectSystemHostUpgrade(socket);
+            return;
+        }
+        if (this.wss.clients.size >= 4) {
+            socket.destroy();
+            return;
+        }
+        if (this.closing) {
+            socket.destroy();
+            return;
+        }
+        this.wss.handleUpgrade(request, socket, head, (client) => this.connection.accept(client, token));
+    }
+    async handleHttp(request, response, pathname) {
+        if (!isSystemHostRoute(pathname) && !isHostSetupRoute(pathname))
+            return false;
+        response.setHeader("cache-control", "no-store");
+        try {
+            if (isHostSetupRoute(pathname)) {
+                await this.setup.handle(request, response, pathname);
+                return true;
+            }
+            if (request.method === "GET" &&
+                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 });
+                return true;
+            }
+            if (!acceptConfigMutationRequest(request, response))
+                return true;
+            const raw = await readBody(request, { maxBytes: 1024 });
+            const body = raw.length ? JSON.parse(raw.toString()) : {};
+            if (JSON.stringify(body) !== "{}") {
+                sendJson(response, 400, {
+                    ok: false,
+                    error: "unexpected_host_configuration_fields",
+                });
+                return true;
+            }
+            if (request.method === "POST" && pathname.endsWith("/pairing")) {
+                await this.ensureStarted();
+                if (this.setup.rejectConcurrentMutation(response))
+                    return true;
+                sendJson(response, 200, { ok: true, ...this.store.begin() });
+                return true;
+            }
+            if (request.method === "DELETE" &&
+                pathname === "/web-api/runtime/system-host") {
+                await this.ensureStarted();
+                if (this.setup.rejectConcurrentMutation(response))
+                    return true;
+                this.store.revoke();
+                this.connection.disconnect();
+                const status = this.connection.status();
+                sendJson(response, 200, { ok: true, ...status,
+                    readiness: withLocalMacSetup(request, await readHostReadiness(status)) });
+                return true;
+            }
+            sendJson(response, 405, { ok: false, error: "method_not_allowed" });
+        }
+        catch (error) {
+            if (sendHostSetupInputError(response, error))
+                return true;
+            const alreadyPaired = error instanceof Error && error.message === "host_already_paired";
+            sendJson(response, alreadyPaired ? 409 : 503, {
+                ok: false,
+                error: alreadyPaired
+                    ? "host_already_paired"
+                    : "host_connection_unavailable",
+                message: alreadyPaired
+                    ? "Disconnect the paired computer before creating a new pairing."
+                    : "The host connection service could not be started or updated.",
+            });
+        }
+        return true;
+    }
+    async close() {
+        if (this.closing)
+            return;
+        this.closing = true;
+        await this.setup.close();
+        await this.starting?.catch(() => undefined);
+        this.connection.close();
+        await this.broker?.close();
+        await new Promise((resolve) => this.wss.close(() => resolve()));
+    }
+}

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

@@ -0,0 +1,2 @@
+/** Packaged entries use their sibling CLI; source mode serves the built artifact. */
+export declare function readInstallerCompanionBundle(moduleUrl?: string, read?: (url: URL) => Promise<Buffer>): Promise<Buffer>;

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

@@ -0,0 +1,12 @@
+import { readFile } from "node:fs/promises";
+/** Packaged entries use their sibling CLI; source mode serves the built artifact. */
+export async function readInstallerCompanionBundle(moduleUrl = import.meta.url, read = readFile) {
+    try {
+        return await read(new URL("../../cli/host-companion-bundle.mjs", moduleUrl));
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        return read(new URL("../../../dist/src/cli/host-companion-bundle.mjs", moduleUrl));
+    }
+}

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

@@ -0,0 +1,3 @@
+import { type CompanionInstallerInput } from "./installer-contract.js";
+/** Native desktop install; Node and desktop accessibility dependencies remain user-managed. */
+export declare function renderLinuxCompanionScript(input: CompanionInstallerInput): string;

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

@@ -0,0 +1,2 @@
+import { type CompanionInstallerInput } from "./installer-contract.js";
+export declare function renderMacCompanionScript(input: CompanionInstallerInput): string;

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

@@ -0,0 +1,83 @@
+import { shellString, } from "./installer-contract.js";
+import { COMPANION_NODE_DISTRIBUTIONS, COMPANION_NODE_VERSION, } from "./node-distribution.js";
+export function renderMacCompanionScript(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
+BASE="$HOME/Library/Application Support/ABot/HostCompanion"
+TEMP=''
+cleanup() {
+  case "$TEMP" in "$BASE"/setup.*) /bin/rm -rf -- "$TEMP" ;; esac
+}
+failed() { echo 'Setup did not complete. Review the error above, then obtain a fresh setup file if needed.' >&2; }
+trap cleanup EXIT
+trap failed ERR
+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
+  verify_installation_directory
+  if [ "$("$NODE" --version)" != '${COMPANION_NODE_VERSION}' ]; then echo 'The dedicated Node.js runtime could not be verified.' >&2; exit 1; fi
+  EXISTING_SHA=$(/usr/bin/shasum -a 256 "$BUNDLE" | /usr/bin/awk '{print $1}')
+  if [ "$EXISTING_SHA" != '${input.bundleSha256}' ]; then echo 'The existing companion bundle does not match its checksum.' >&2; exit 1; fi
+  echo 'Connecting this computer and enabling startup at sign-in...'
+  printf '%s' ${shellString(payload)} | "$NODE" "$BUNDLE" setup
+  echo 'Companion setup completed. Return to ABot to check the computer connection.'
+}
+case "$(/usr/bin/uname -m)" in
+  arm64) ARCH='arm64'; NODE_SHA='${COMPANION_NODE_DISTRIBUTIONS["darwin-arm64"].sha256}' ;;
+  x86_64) ARCH='x64'; NODE_SHA='${COMPANION_NODE_DISTRIBUTIONS["darwin-x64"].sha256}' ;;
+  *) echo 'This Mac architecture is not supported by companion setup.' >&2; exit 1 ;;
+esac
+NODE_NAME="node-${COMPANION_NODE_VERSION}-darwin-$ARCH"
+NODE="$BASE/$NODE_NAME/bin/node"
+BUNDLE="$BASE/companion-${input.bundleSha256}.mjs"
+if can_resume_cached_setup; then
+  run_verified_companion_setup
+  exit 0
+fi
+if [ "$(/bin/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
+if [ -L "$BASE" ]; then echo 'The installation directory must not be a link.' >&2; exit 1; fi
+/bin/mkdir -p "$BASE"
+verify_installation_directory
+/bin/chmod 700 "$BASE"
+TEMP=$(/usr/bin/mktemp -d "$BASE/setup.XXXXXX")
+if [ ! -f "$NODE" ]; then
+  echo 'Downloading the verified per-user Node.js runtime...'
+  /usr/bin/curl --fail --show-error --silent --proto '=https' --tlsv1.2 --max-redirs 0 --connect-timeout 15 --max-time 300 --output "$TEMP/node.tar.gz" "https://nodejs.org/dist/${COMPANION_NODE_VERSION}/$NODE_NAME.tar.gz"
+  ACTUAL_SHA=$(/usr/bin/shasum -a 256 "$TEMP/node.tar.gz" | /usr/bin/awk '{print $1}')
+  if [ "$ACTUAL_SHA" != "$NODE_SHA" ]; then echo 'Node.js checksum verification failed.' >&2; exit 1; fi
+  /usr/bin/tar -xzf "$TEMP/node.tar.gz" -C "$TEMP"
+  /bin/mv "$TEMP/$NODE_NAME" "$BASE/$NODE_NAME"
+fi
+echo 'Downloading and verifying the ABot companion...'
+PAIRING_CODE=${shellString(input.code)}
+printf 'header = "Authorization: Bearer %s"\n' "$PAIRING_CODE" | /usr/bin/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=$(/usr/bin/shasum -a 256 "$TEMP/companion.mjs" | /usr/bin/awk '{print $1}')
+if [ "$ACTUAL_SHA" != '${input.bundleSha256}' ]; then echo 'Companion checksum verification failed. Nothing was executed.' >&2; exit 1; fi
+/bin/chmod 600 "$TEMP/companion.mjs"
+if [ ! -e "$BUNDLE" ]; then /bin/mv "$TEMP/companion.mjs" "$BUNDLE"; fi
+run_verified_companion_setup
+`;
+}

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

@@ -0,0 +1,2 @@
+import { type CompanionInstallerInput } from "./installer-contract.js";
+export declare function renderWindowsCompanionScript(input: CompanionInstallerInput): string;

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

@@ -0,0 +1,108 @@
+import { installerMetadataBase64, } from "./installer-contract.js";
+import { COMPANION_NODE_DISTRIBUTIONS, COMPANION_NODE_VERSION, } from "./node-distribution.js";
+import { wrapWindowsSetupScript } from "./windows-script-wrapper.js";
+export function renderWindowsCompanionScript(input) {
+    const metadata = installerMetadataBase64({
+        ...input,
+        nodeVersion: COMPANION_NODE_VERSION,
+        distributions: COMPANION_NODE_DISTRIBUTIONS,
+    });
+    return wrapWindowsSetupScript(String.raw `
+$ErrorActionPreference = 'Stop'
+$ProgressPreference = 'SilentlyContinue'
+$OutputEncoding = New-Object System.Text.UTF8Encoding($false)
+$Metadata = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('${metadata}')) | ConvertFrom-Json
+$Temporary = $null
+function Assert-CompanionDirectory {
+  if ((Get-Item -LiteralPath $Base).Attributes -band [IO.FileAttributes]::ReparsePoint) { throw 'The companion installation directory must not be a link.' }
+}
+function Invoke-VerifiedCompanionSetup {
+  if (-not (Test-Path -LiteralPath $Node -PathType Leaf)) { throw 'The cached Node.js runtime is missing. Restore this installation before resuming setup.' }
+  if (-not (Test-Path -LiteralPath $Bundle -PathType Leaf)) { throw 'The cached companion bundle is missing. Restore this installation before resuming setup.' }
+  Assert-CompanionDirectory
+  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...'
+  $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.'
+}
+function Get-VerifiedDownload([string]$Url, [string]$Destination, [string]$ExpectedHash, [string]$Bearer = '') {
+  $Original = [Uri]$Url
+  $Address = $Original
+  if ($Original.Host -eq 'localhost' -or $Original.Host.EndsWith('.localhost')) {
+    $Builder = New-Object UriBuilder($Original)
+    $Builder.Host = '127.0.0.1'
+    $Address = $Builder.Uri
+  }
+  $Request = [Net.HttpWebRequest]::Create($Address)
+  $Request.Host = $Original.Authority
+  $Request.AllowAutoRedirect = $false
+  $Request.Timeout = 300000
+  $Request.ReadWriteTimeout = 300000
+  $Request.Proxy = $null
+  if ($Bearer) { $Request.Headers['Authorization'] = 'Bearer ' + $Bearer }
+  $Response = $null
+  $File = $null
+  try {
+    $Response = $Request.GetResponse()
+    if ([int]$Response.StatusCode -ne 200) { throw 'The download endpoint did not return a file.' }
+    $File = [IO.File]::Open($Destination, [IO.FileMode]::CreateNew)
+    $Response.GetResponseStream().CopyTo($File)
+  } finally {
+    if ($File) { $File.Dispose() }
+    if ($Response) { $Response.Dispose() }
+  }
+  if ((Get-FileHash -LiteralPath $Destination -Algorithm SHA256).Hash -ne $ExpectedHash) {
+    throw 'Checksum verification failed. The downloaded file will not be executed.'
+  }
+}
+try {
+  $Base = Join-Path ([Environment]::GetFolderPath('LocalApplicationData')) 'ABot\HostCompanion'
+  $Architecture = $env:PROCESSOR_ARCHITECTURE
+  if ($env:PROCESSOR_ARCHITEW6432) { $Architecture = $env:PROCESSOR_ARCHITEW6432 }
+  $Key = switch ($Architecture.ToUpperInvariant()) { 'AMD64' { 'win-x64' }; 'ARM64' { 'win-arm64' }; default { throw 'This Windows architecture is not supported by companion setup.' } }
+  $Distribution = $Metadata.distributions.$Key
+  $NodeDirectory = Join-Path $Base ([IO.Path]::GetFileNameWithoutExtension($Distribution.archive))
+  $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'
+  $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
+  }
+  if ([DateTimeOffset]::UtcNow -ge [DateTimeOffset]::Parse($Metadata.expiresAt)) { throw 'This setup invitation expired. Download a fresh setup file in ABot.' }
+  [Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12
+  [IO.Directory]::CreateDirectory($Base) | Out-Null
+  Assert-CompanionDirectory
+  $Temporary = Join-Path $Base ('setup-' + [Guid]::NewGuid().ToString('N'))
+  [IO.Directory]::CreateDirectory($Temporary) | Out-Null
+  if (-not (Test-Path -LiteralPath $Node -PathType Leaf)) {
+    Write-Host 'Downloading the verified per-user Node.js runtime...'
+    $Archive = Join-Path $Temporary 'node.zip'
+    Get-VerifiedDownload ('https://nodejs.org/dist/' + $Metadata.nodeVersion + '/' + $Distribution.archive) $Archive $Distribution.sha256
+    $Extracted = Join-Path $Temporary 'node'
+    Expand-Archive -LiteralPath $Archive -DestinationPath $Extracted
+    Move-Item -LiteralPath (Join-Path $Extracted ([IO.Path]::GetFileNameWithoutExtension($Distribution.archive))) -Destination $NodeDirectory
+  }
+  Write-Host 'Downloading and verifying the ABot companion...'
+  $Candidate = Join-Path $Temporary 'companion.mjs'
+  Get-VerifiedDownload ($Metadata.url + '/web-api/runtime/system-host/bundle') $Candidate $Metadata.bundleSha256 $Metadata.code
+  if (-not (Test-Path -LiteralPath $Bundle)) { Move-Item -LiteralPath $Candidate -Destination $Bundle }
+  Invoke-VerifiedCompanionSetup
+} catch {
+  Write-Host ('Setup failed: ' + $_.Exception.Message) -ForegroundColor Red
+  exit 1
+} finally {
+  if ($Temporary -and (Test-Path -LiteralPath $Temporary)) {
+    $ResolvedBase = [IO.Path]::GetFullPath($Base).TrimEnd('\') + '\'
+    $ResolvedTemporary = [IO.Path]::GetFullPath($Temporary)
+    if ($ResolvedTemporary.StartsWith($ResolvedBase, [StringComparison]::OrdinalIgnoreCase)) { Remove-Item -LiteralPath $ResolvedTemporary -Recurse -Force }
+  }
+}
+`);
+}

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

@@ -0,0 +1,19 @@
+export declare class InstallerInputError extends Error {
+}
+export type CompanionInstallerInput = Readonly<{
+    platform: "windows" | "macos" | "linux";
+    url: string;
+    code: string;
+    bundleSha256: string;
+    expiresAt: string;
+    upgradeHostId?: string;
+}>;
+export type InstallerDownload = Readonly<{
+    filename: string;
+    mimeType: string;
+    contentBase64: string;
+}>;
+export declare function validateCompanionInstaller(input: CompanionInstallerInput): CompanionInstallerInput;
+export declare function validateWslDistribution(distribution?: string): string | undefined;
+export declare function installerMetadataBase64(value: unknown): string;
+export declare function shellString(value: string): string;

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

@@ -0,0 +1,64 @@
+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) {
+    if (hostname === "localhost")
+        return true;
+    if (hostname.endsWith(".localhost"))
+        return true;
+    return isNativeLoopbackAddress(hostname);
+}
+export function validateCompanionInstaller(input) {
+    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;
+    try {
+        url = new URL(input.url);
+    }
+    catch {
+        throw new InstallerInputError("The setup address is not a valid Runtime origin.");
+    }
+    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 !== "/")
+        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.");
+    if (!/^[A-Za-z0-9_-]{43}$/u.test(input.code))
+        throw new InstallerInputError("The pairing code is invalid.");
+    if (!/^[a-f0-9]{64}$/iu.test(input.bundleSha256))
+        throw new InstallerInputError("The companion bundle checksum is invalid.");
+    if (!Number.isFinite(Date.parse(input.expiresAt)))
+        throw new InstallerInputError("The pairing expiration is invalid.");
+    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)
+        return undefined;
+    if (!/^[A-Za-z0-9][A-Za-z0-9._ -]{0,127}$/u.test(distribution))
+        throw new InstallerInputError("The WSL distribution name is invalid.");
+    if (distribution.toLowerCase().startsWith("docker-desktop"))
+        throw new InstallerInputError("Docker Desktop internal distributions cannot be changed by this setup.");
+    return distribution;
+}
+export function installerMetadataBase64(value) {
+    return Buffer.from(JSON.stringify(value), "utf8").toString("base64");
+}
+export function shellString(value) {
+    return "'" + value.replaceAll("'", "'\"'\"'") + "'";
+}

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

@@ -0,0 +1,6 @@
+import { type CompanionInstallerInput, type InstallerDownload } from "./installer-contract.js";
+export { InstallerInputError } from "./installer-contract.js";
+export declare function renderCompanionInstaller(raw: CompanionInstallerInput): Promise<InstallerDownload>;
+export declare function renderWslInteropInstaller(input: Readonly<{
+    distribution?: string;
+}>): Promise<InstallerDownload>;

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

@@ -0,0 +1,43 @@
+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",
+            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,
+    });
+    return {
+        filename: "ABot-Connect-Computer-macOS.zip",
+        mimeType: "application/zip",
+        contentBase64: await zip.generateAsync({
+            type: "base64",
+            platform: "UNIX",
+            compression: "DEFLATE",
+        }),
+    };
+}
+export async function renderWslInteropInstaller(input) {
+    const distribution = validateWslDistribution(input.distribution);
+    return {
+        filename: "ABot-Enable-WSL-Interop.cmd",
+        mimeType: "application/octet-stream",
+        contentBase64: Buffer.from(renderWindowsWslInteropScript(distribution), "utf8").toString("base64"),
+    };
+}

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>;
+}