@abot-ai/runtime 1.4.0 → 1.5.0

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

@@ -1,7 +1,7 @@
 import { stdin } from "node:process";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { isNativeCredential } from "../../plugins/system/source/companion/native-state.js";
-import { isHostRecord } from "../../plugins/system/source/companion/protocol.js";
+import { isNativeCredential } from "../computer-access/companion/native-state.js";
+import { isHostIdentifier, isHostRecord, } from "../computer-access/companion/protocol.js";
 import { runHostCompanionCli } from "./host-companion.js";
 const SETUP_INPUT_LIMIT_BYTES = 16_384;
 const SETUP_INPUT_TIMEOUT_MS = 10_000;
@@ -33,7 +33,7 @@ async function readSetupInput(input) {
 function readSetupRequest(value) {
     if (!isHostRecord(value))
         throw new Error("Invalid host setup request.");
-    if (Object.keys(value).some((key) => !["url", "code"].includes(key)))
+    if (Object.keys(value).some((key) => !["url", "code", "upgradeHostId"].includes(key)))
         throw new Error("Unexpected host setup fields.");
     if (typeof value.url !== "string")
         throw new Error("Missing Runtime URL.");
@@ -41,7 +41,16 @@ function readSetupRequest(value) {
         throw new Error("Invalid Runtime URL length.");
     if (!isNativeCredential(value.code))
         throw new Error("Invalid pairing code.");
-    return { url: value.url, code: value.code };
+    if (value.upgradeHostId !== undefined &&
+        !isHostIdentifier(value.upgradeHostId))
+        throw new Error("Invalid paired computer identity.");
+    return {
+        url: value.url,
+        code: value.code,
+        ...(value.upgradeHostId !== undefined
+            ? { upgradeHostId: value.upgradeHostId }
+            : {}),
+    };
 }
 /** Installer-only setup receives secrets over stdin; login startup uses host run. */
 export async function runHostCompanionEntry(args, options = {}) {
@@ -54,6 +63,7 @@ export async function runHostCompanionEntry(args, options = {}) {
         await runCli(["connect", "--url", setup.url], {
             cliPath,
             pairingCode: setup.code,
+            ...(setup.upgradeHostId ? { upgradeHostId: setup.upgradeHostId } : {}),
         });
         return;
     }

package/dist/src/cli/host-companion-setup-target.d.ts

@@ -0,0 +1,3 @@
+import type { NativeHostConnection } from "../computer-access/companion/native-state.js";
+/** Upgrade identity selects existing private state, never a new credential destination. */
+export declare function resolveHostCompanionSetupUrl(saved: NativeHostConnection | undefined, requestedUrl: string, upgradeHostId?: string): string;

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

@@ -0,0 +1,23 @@
+import { isHostIdentifier } from "../computer-access/companion/protocol.js";
+function hasConflictingSavedRuntime(saved, requestedUrl) {
+    if (!saved)
+        return false;
+    return saved.url !== requestedUrl;
+}
+function resolveOrdinaryConnectUrl(saved, requestedUrl) {
+    if (hasConflictingSavedRuntime(saved, requestedUrl))
+        throw new Error("A Runtime is already paired. Use 'abot host disconnect' before pairing another.");
+    return requestedUrl;
+}
+/** Upgrade identity selects existing private state, never a new credential destination. */
+export function resolveHostCompanionSetupUrl(saved, requestedUrl, upgradeHostId) {
+    if (upgradeHostId === undefined)
+        return resolveOrdinaryConnectUrl(saved, requestedUrl);
+    if (!isHostIdentifier(upgradeHostId))
+        throw new Error("Invalid paired computer identity.");
+    if (!saved)
+        throw new Error("The paired computer connection is missing. Reconnect from ABot Settings.");
+    if (saved.hostId !== upgradeHostId)
+        throw new Error("This upgrade belongs to a different paired computer connection.");
+    return saved.url;
+}

package/dist/src/cli/host-companion-startup.d.ts

@@ -1,4 +1,4 @@
-import { type NativeAutostartOptions } from "../../plugins/system/source/companion/autostart.js";
-import type { NativeHostState } from "../../plugins/system/source/companion/native-state.js";
+import { type NativeAutostartOptions } from "../computer-access/companion/autostart.js";
+import type { NativeHostState } from "../computer-access/companion/native-state.js";
 /** Startup can be resumed without consuming another grant or changing the saved pairing. */
 export declare function completeHostCompanionStartup(state: NativeHostState, startup: NativeAutostartOptions, hostId: string): Promise<void>;

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

@@ -1,6 +1,10 @@
 import { spawn } from "node:child_process";
+import { installDesktopNotificationIdentity } from "../computer-access/companion/notification-installation.js";
 import { setTimeout as delay } from "node:timers/promises";
-import { installNativeAutostart, } from "../../plugins/system/source/companion/autostart.js";
+import { installNativeAutostart, existingOwnedRegistration, nativeAutostartFile, } from "../computer-access/companion/autostart.js";
+import { readNativeCompanionBuildId } from "../computer-access/companion/native-build-identity.js";
+import { stopOwnedNativeCompanion } from "../computer-access/companion/native-replacement.js";
+import { prepareNativeCompanionRuntime } from "../computer-access/companion/native-runtime-installation.js";
 async function startDetachedCompanion(options) {
     const child = spawn(options.nodePath, [options.cliPath, "host", "run"], {
         cwd: options.homeDir,
@@ -14,10 +18,10 @@ async function startDetachedCompanion(options) {
     });
     child.unref();
 }
-async function waitForNativeConnection(state, hostId) {
+async function waitForNativeConnection(state, hostId, buildId, connectedAfter) {
     const deadline = Date.now() + 10_000;
     do {
-        if (await state.isConnected(hostId))
+        if (await state.isConnected(hostId, buildId, connectedAfter))
             return true;
         await delay(200);
     } while (Date.now() < deadline);
@@ -25,11 +29,21 @@ async function waitForNativeConnection(state, hostId) {
 }
 /** Startup can be resumed without consuming another grant or changing the saved pairing. */
 export async function completeHostCompanionStartup(state, startup, hostId) {
-    const installed = await installNativeAutostart(startup);
+    const buildId = await readNativeCompanionBuildId(startup.cliPath);
+    await existingOwnedRegistration(nativeAutostartFile(startup));
+    await stopOwnedNativeCompanion(state.directory);
+    const managedStartup = await prepareNativeCompanionRuntime(startup);
+    const connection = await state.read();
+    if (connection)
+        await installDesktopNotificationIdentity(managedStartup, connection.url).catch((error) => {
+            console.warn("Desktop notifications setup needs attention: " +
+                (error instanceof Error ? error.message : String(error)));
+        });
+    const connectedAfter = Date.now();
+    const installed = await installNativeAutostart(managedStartup);
     if (!installed.started)
-        await startDetachedCompanion(startup);
-    const connected = await waitForNativeConnection(state, hostId);
-    console.log(connected
-        ? "Host companion connected. It will start automatically when you log in."
-        : "Host companion installed for login startup. It is waiting for the local Runtime to reconnect.");
+        await startDetachedCompanion(managedStartup);
+    if (!(await waitForNativeConnection(state, hostId, buildId, connectedAfter)))
+        throw new Error("The updated host companion did not connect. The saved pairing is preserved; run setup again to retry.");
+    console.log("Host companion connected. It will start automatically when you log in.");
 }

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

@@ -1,5 +1,6 @@
 export type HostCompanionCliOptions = Readonly<{
     cliPath?: string;
     pairingCode?: string;
+    upgradeHostId?: string;
 }>;
 export declare function runHostCompanionCli(args: string[], options?: HostCompanionCliOptions): Promise<void>;

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

@@ -1,19 +1,22 @@
 import { homedir } from "node:os";
+import { uninstallDesktopNotificationIdentity } from "../computer-access/companion/notification-installation.js";
 import { join } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { stdin, stdout } from "node:process";
 import { fileURLToPath } from "node:url";
-import { nativeAutostartFile, uninstallNativeAutostart, } from "../../plugins/system/source/companion/autostart.js";
-import { normalizeNativeRuntimeUrl, resolveNativeRuntimeAddress, } from "../../plugins/system/source/companion/native-address.js";
-import { readNativeHostIdentity } from "../../plugins/system/source/companion/native-identity.js";
-import { connectNativeHost } from "../../plugins/system/source/companion/native-session.js";
-import { createNativeHostState, } from "../../plugins/system/source/companion/native-state.js";
-import { runNativeHostSupervisor } from "../../plugins/system/source/companion/native-supervisor.js";
-import { isProcessOwnerAlive, requireCurrentProcessOwnerIdentity, } from "../../plugins/system/source/companion/process-owner-identity.js";
+import { nativeAutostartFile, uninstallNativeAutostart, } from "../computer-access/companion/autostart.js";
+import { normalizeNativeRuntimeUrl, resolveNativeRuntimeAddress, } from "../computer-access/companion/native-address.js";
+import { readNativeHostIdentity } from "../computer-access/companion/native-identity.js";
+import { connectNativeHost } from "../computer-access/companion/native-session.js";
+import { createNativeHostState, } from "../computer-access/companion/native-state.js";
+import { runNativeHostSupervisor } from "../computer-access/companion/native-supervisor.js";
+import { isProcessOwnerAlive, requireCurrentProcessOwnerIdentity, } from "../computer-access/companion/process-owner-identity.js";
 import { acquireFileLock } from "../runtime/adapters/long-term-memory/file-lock/acquisition.js";
 import { ensurePrivateRuntimeDirectory } from "../runtime/local-host/private-directory.js";
 import { assertPrivateRuntimeAccess } from "../runtime/local-host/private-access.js";
 import { completeHostCompanionStartup } from "./host-companion-startup.js";
+import { resolveHostCompanionSetupUrl } from "./host-companion-setup-target.js";
+import { readNativeCompanionBuildId } from "../computer-access/companion/native-build-identity.js";
 function printHostHelp() {
     console.log([
         "Usage:",
@@ -24,7 +27,7 @@ function printHostHelp() {
         "  abot host run",
         "",
         "Connect asks for a one-time code from ABot Settings, saves a private credential,",
-        "and starts the companion now and at future Windows/macOS user logins.",
+        "and starts the companion now and at future Windows/macOS/Linux desktop logins.",
         "Run is the foreground companion used by the login registration.",
         "Disconnect/uninstall stop the registration and remove this computer's credential.",
         "Revoke the host in ABot Settings to remove Runtime-side pairing too.",
@@ -41,6 +44,7 @@ function autostartOptions(state, options = {}) {
         platform: process.platform,
         homeDir: homedir(),
         appData: process.env.APPDATA,
+        xdgConfigHome: process.env.XDG_CONFIG_HOME,
         uid: process.getuid?.(),
         nodePath: process.execPath,
         cliPath: options.cliPath ?? fileURLToPath(new URL("./bin.js", import.meta.url)),
@@ -69,21 +73,14 @@ async function withStopSignals(operation) {
         process.removeListener("SIGTERM", stop);
     }
 }
-function hasConflictingSavedRuntime(saved, url) {
-    if (!saved)
-        return false;
-    return saved.url !== url;
-}
 async function connectHost(args, state, options) {
     if (args.length !== 2 || args[0] !== "--url")
         throw new Error("Usage: abot host connect --url http://localhost:5177");
     const startup = autostartOptions(state, options);
     nativeAutostartFile(startup);
-    const url = normalizeNativeRuntimeUrl(args[1]);
-    await resolveNativeRuntimeAddress(url);
     const saved = await state.read();
-    if (hasConflictingSavedRuntime(saved, url))
-        throw new Error("A Runtime is already paired. Use 'abot host disconnect' before pairing another.");
+    const url = resolveHostCompanionSetupUrl(saved, normalizeNativeRuntimeUrl(args[1]), options.upgradeHostId);
+    await resolveNativeRuntimeAddress(url);
     if (saved) {
         await completeHostCompanionStartup(state, startup, saved.hostId);
         return;
@@ -123,9 +120,10 @@ async function connectHost(args, state, options) {
         throw new Error("Pairing did not complete. Check ABot Settings and use a fresh pairing code.");
     await completeHostCompanionStartup(state, startup, pairedHostId);
 }
-async function runHost(state) {
+async function runHost(state, options) {
     if (!(await state.read()))
         return;
+    const buildId = await readNativeCompanionBuildId(autostartOptions(state, options).cliPath);
     const ownerIdentity = await requireCurrentProcessOwnerIdentity();
     let release;
     try {
@@ -147,6 +145,7 @@ async function runHost(state) {
             state,
             identity: readNativeHostIdentity(),
             signal,
+            buildId,
         }));
     }
     finally {
@@ -156,6 +155,7 @@ async function runHost(state) {
 async function disconnectHost(state) {
     await state.remove();
     await uninstallNativeAutostart(autostartOptions(state));
+    await uninstallDesktopNotificationIdentity(autostartOptions(state));
     const ownerIdentity = await requireCurrentProcessOwnerIdentity();
     const release = await acquireFileLock(join(state.directory, "agent"), {
         waitMs: 5_000,
@@ -180,7 +180,7 @@ export async function runHostCompanionCli(args, options = {}) {
     if (rest.length > 0)
         throw new Error(`Unknown host argument: ${rest[0]}`);
     if (command === "run") {
-        await runHost(state);
+        await runHost(state, options);
         return;
     }
     if (command === "disconnect" || command === "uninstall") {

package/dist/{plugins/system/source → src/computer-access}/application-launch.js

@@ -1,4 +1,4 @@
-import { readRequiredString } from "../../../src/plugin-sdk/index.js";
+import { readRequiredString } from "../plugin-sdk/index.js";
 import { readSystemApplications } from "./application-catalog.js";
 import { SystemOperationError, } from "./contracts.js";
 import { findExecutable, powershellArguments, powershellLiteral, } from "./targets.js";

package/dist/src/computer-access/client.d.ts

@@ -0,0 +1,19 @@
+import type { ToolImplementationOutput } from "../plugin-contract/index.js";
+import type { SystemTargetId } from "./contracts.js";
+import type { HostOperation, HostStatus } from "./companion/protocol.js";
+/** A connection bound to one installation and one accepted host session. */
+export type ComputerAccessConnection = Readonly<{
+    readHostStatus(rootDir: string): Promise<HostStatus>;
+    executeHostOperation(rootDir: string, input: Readonly<{
+        hostId: string;
+        connectionId: string;
+        operation: HostOperation;
+        params: Record<string, unknown>;
+        abortSignal?: AbortSignal;
+    }>): Promise<ToolImplementationOutput>;
+}>;
+export type CompanionTarget = Readonly<{
+    hostId: string;
+    connectionId: string;
+    target: SystemTargetId;
+}>;

package/dist/src/computer-access/client.js

@@ -0,0 +1 @@
+export {};

package/dist/{plugins/system/source → src/computer-access}/commands.js

@@ -1,6 +1,6 @@
 import { stat } from "node:fs/promises";
 import { isAbsolute } from "node:path";
-import { readBoundedInteger, readRequiredString, } from "../../../src/plugin-sdk/index.js";
+import { readBoundedInteger, readRequiredString, } from "../plugin-sdk/index.js";
 import { SystemOperationError, } from "./contracts.js";
 import { elevatedSystemCommand } from "./elevation.js";
 import { powershellArguments, windowsSystemCommandScript } from "./targets.js";

package/dist/{plugins/system/source → src/computer-access}/companion/autostart.d.ts

@@ -2,6 +2,7 @@ export type NativeAutostartOptions = Readonly<{
     platform: NodeJS.Platform;
     homeDir: string;
     appData?: string;
+    xdgConfigHome?: string;
     uid?: number;
     nodePath: string;
     cliPath: string;
@@ -10,6 +11,7 @@ export type NativeAutostartOptions = Readonly<{
 }>;
 export declare function nativeAutostartFile(options: NativeAutostartOptions): string;
 export declare function renderNativeAutostart(options: NativeAutostartOptions): string;
+export declare function existingOwnedRegistration(path: string): Promise<boolean>;
 export declare function installNativeAutostart(options: NativeAutostartOptions): Promise<{
     started: boolean;
 }>;

package/dist/{plugins/system/source → src/computer-access}/companion/autostart.js

@@ -1,6 +1,6 @@
 import { execFile } from "node:child_process";
 import { lstat, mkdir, readFile, rename, unlink, writeFile, } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { dirname, join, posix } from "node:path";
 import { promisify } from "node:util";
 import { randomUUID } from "node:crypto";
 const executeFile = promisify(execFile);
@@ -23,7 +23,16 @@ function windowsArgument(value) {
 function vbsString(value) {
     return `"${value.replaceAll('"', '""')}"`;
 }
+function linuxConfigHome(options) {
+    if (!options.xdgConfigHome)
+        return join(options.homeDir, ".config");
+    if (!posix.isAbsolute(options.xdgConfigHome))
+        return join(options.homeDir, ".config");
+    return options.xdgConfigHome;
+}
 export function nativeAutostartFile(options) {
+    if (options.platform === "linux")
+        return join(linuxConfigHome(options), "autostart", `${LABEL}.desktop`);
     if (options.platform === "darwin")
         return join(options.homeDir, "Library", "LaunchAgents", `${LABEL}.plist`);
     if (options.platform !== "win32")
@@ -33,6 +42,14 @@ export function nativeAutostartFile(options) {
     return join(options.appData, "Microsoft", "Windows", "Start Menu", "Programs", "Startup", "ABot Host Companion.vbs");
 }
 export function renderNativeAutostart(options) {
+    if (options.platform === "linux") {
+        const quote = (value) => {
+            if (/[\r\n\0]/u.test(value))
+                throw new Error("Unsupported native startup path.");
+            return `"${value.replaceAll("\\", "\\\\\\\\").replaceAll('"', '\\\\"').replaceAll("`", "\\\\`").replaceAll("$", "\\\\$").replaceAll("%", "%%")}"`;
+        };
+        return `[Desktop Entry]\n# ${OWNER_MARKER}\nType=Application\nName=ABot Host Companion\nExec=${quote(options.nodePath)} ${quote(options.cliPath)} host run\nTerminal=false\nX-GNOME-Autostart-enabled=true\n`;
+    }
     if (options.platform === "win32") {
         const command = `${windowsArgument(options.nodePath)} ${windowsArgument(options.cliPath)} host run`;
         return [
@@ -64,7 +81,7 @@ function errorCode(error) {
         ? error.code
         : undefined;
 }
-async function existingOwnedRegistration(path) {
+export async function existingOwnedRegistration(path) {
     const stat = await lstat(path).catch((error) => {
         if (errorCode(error) === "ENOENT")
             return undefined;

package/dist/src/computer-access/companion/broker-client.d.ts

@@ -0,0 +1,10 @@
+import { type ToolImplementationOutput } from "../../plugin-sdk/index.js";
+import { type HostOperation, type HostStatus } from "./protocol.js";
+export declare function readHostStatus(rootDir: string): Promise<HostStatus>;
+export declare function executeHostOperation(rootDir: string, input: {
+    hostId: string;
+    connectionId: string;
+    operation: HostOperation;
+    params: Record<string, unknown>;
+    abortSignal?: AbortSignal;
+}): Promise<ToolImplementationOutput>;

package/dist/src/computer-access/companion/broker-client.js

@@ -0,0 +1,149 @@
+import { connect } from "node:net";
+import { failureResult, } from "../../plugin-sdk/index.js";
+import { readBrokerLocation } from "./broker-location.js";
+import { HostPairingStore } from "./pairing-store.js";
+import { HOST_WIRE_MAX_BYTES, isHostIdentity, isHostIdentifier, isHostRecord, isHostToolResult, } from "./protocol.js";
+async function callBroker(rootDir, request, signal) {
+    const location = readBrokerLocation(rootDir);
+    if (!location)
+        throw new Error("host_broker_unavailable");
+    if (signal?.aborted)
+        throw new Error("host_request_cancelled");
+    return new Promise((resolve, reject) => {
+        const socket = connect(location.socketPath);
+        let received = Buffer.alloc(0);
+        let settled = false;
+        let sent = false;
+        const finish = (error, result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(deadline);
+            signal?.removeEventListener("abort", abort);
+            socket.destroy();
+            if (error) {
+                reject(sent && request.kind === "execute"
+                    ? new Error("host_outcome_unknown")
+                    : error);
+                return;
+            }
+            resolve(result);
+        };
+        const abort = () => finish(new Error(sent ? "host_outcome_unknown" : "host_request_cancelled"));
+        const deadline = setTimeout(abort, request.kind === "status" ? 3_000 : 615_000);
+        signal?.addEventListener("abort", abort, { once: true });
+        socket.once("connect", () => {
+            const bytes = JSON.stringify({ ...request, version: 1, token: location.token }) +
+                "\n";
+            if (Buffer.byteLength(bytes) > HOST_WIRE_MAX_BYTES) {
+                finish(new Error("host_request_too_large"));
+                return;
+            }
+            sent = true;
+            socket.write(bytes);
+        });
+        socket.on("error", () => finish(new Error(sent ? "host_outcome_unknown" : "host_broker_unavailable")));
+        socket.on("close", () => finish(new Error(sent ? "host_outcome_unknown" : "host_broker_unavailable")));
+        socket.on("data", (chunk) => {
+            received = Buffer.concat([received, chunk]);
+            if (received.length > HOST_WIRE_MAX_BYTES) {
+                finish(new Error("host_response_too_large"));
+                return;
+            }
+            const boundary = received.indexOf(10);
+            if (boundary < 0)
+                return;
+            if (boundary !== received.length - 1) {
+                finish(new Error("host_response_invalid"));
+                return;
+            }
+            try {
+                finish(undefined, JSON.parse(received.subarray(0, boundary).toString()));
+            }
+            catch {
+                finish(new Error("host_response_invalid"));
+            }
+        });
+    });
+}
+function isHostStatus(value) {
+    if (!isHostRecord(value))
+        return false;
+    if (typeof value.paired !== "boolean")
+        return false;
+    if (typeof value.connected !== "boolean")
+        return false;
+    if (!hasValidHostConnectionBinding(value))
+        return false;
+    if (!value.paired)
+        return value.connected === false;
+    if (!isHostIdentifier(value.hostId))
+        return false;
+    return isHostIdentity(value.identity);
+}
+function hasValidHostConnectionBinding(value) {
+    if (value.connected === true)
+        return isHostIdentifier(value.connectionId);
+    return !Object.hasOwn(value, "connectionId");
+}
+export async function readHostStatus(rootDir) {
+    try {
+        const response = await callBroker(rootDir, { kind: "status" });
+        if (!isHostRecord(response))
+            throw new Error("host_response_invalid");
+        if (!isHostStatus(response.status))
+            throw new Error("host_status_invalid");
+        return response.status;
+    }
+    catch {
+        const host = new HostPairingStore(rootDir).host();
+        if (!host)
+            return { paired: false, connected: false };
+        return {
+            paired: true,
+            connected: false,
+            hostId: host.hostId,
+            identity: host.identity,
+        };
+    }
+}
+export async function executeHostOperation(rootDir, input) {
+    if (!isHostIdentifier(input.connectionId))
+        return failureResult({
+            errorCode: "system_host_binding_invalid",
+            message: "An observed host connection identity is required before dispatch.",
+            data: { outcome: "not_dispatched", retrySafe: true },
+        });
+    try {
+        const response = await callBroker(rootDir, {
+            kind: "execute",
+            hostId: input.hostId,
+            connectionId: input.connectionId,
+            operation: input.operation,
+            params: input.params,
+        }, input.abortSignal);
+        if (!isHostRecord(response))
+            throw new Error("host_outcome_unknown");
+        if (response.ok !== true)
+            throw new Error("host_outcome_unknown");
+        if (!isHostToolResult(response.result))
+            throw new Error("host_outcome_unknown");
+        return response.result;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "host_request_failed";
+        const uncertain = message === "host_outcome_unknown";
+        return failureResult({
+            errorCode: uncertain
+                ? "system_host_outcome_unknown"
+                : "system_host_unavailable",
+            message: uncertain
+                ? "Host communication ended after dispatch. Effects may remain; inspect before retrying. The action was not replayed."
+                : "The selected host connection is unavailable. No fallback target was used.",
+            data: {
+                outcome: uncertain ? "unknown" : "not_dispatched",
+                retrySafe: !uncertain,
+            },
+        });
+    }
+}

package/dist/{plugins/system/source → src/computer-access}/companion/broker-location.js

@@ -7,14 +7,22 @@ import { isHostIdentifier, isHostRecord } from "./protocol.js";
 function brokerRecordPath(rootDir) {
     return join(hostStateDirectory(rootDir), "broker.json");
 }
+function brokerSocketDirectoryRoot() {
+    // macOS TMPDIR can exceed its Unix socket limit and differ between launch
+    // environments. Keep a short address; the UID/root directory stays private.
+    if (process.platform === "darwin")
+        return "/tmp";
+    if (process.platform === "linux")
+        return tmpdir();
+    throw new Error("host_broker_requires_linux_runtime");
+}
 function brokerSocketPath(rootDir) {
-    if (process.platform !== "linux")
-        throw new Error("host_broker_requires_linux_runtime");
+    const socketRoot = brokerSocketDirectoryRoot();
     const key = createHash("sha256")
         .update(realpathSync(rootDir))
         .digest("hex")
         .slice(0, 20);
-    return join(tmpdir(), `abot-host-${process.getuid?.()}-${key}`, "broker.sock");
+    return join(socketRoot, `abot-host-${process.getuid?.()}-${key}`, "broker.sock");
 }
 function isBrokerLocation(value) {
     if (!isHostRecord(value))

package/dist/{plugins/system/source → src/computer-access}/companion/broker-server.js

@@ -1,7 +1,8 @@
 import { createHash, timingSafeEqual } from "node:crypto";
 import { createServer } from "node:net";
+import { serveObservationSubscription } from "./observation-broker.js";
 import { createBrokerLocation, publishBrokerLocation, releaseBrokerLocation, } from "./broker-location.js";
-import { HOST_WIRE_MAX_BYTES, isHostIdentifier, isHostOperation, isHostRecord, } from "./protocol.js";
+import { HOST_WIRE_MAX_BYTES, isHostIdentifier, isHostWireOperation, isHostRecord, } from "./protocol.js";
 function hasBrokerAuthorization(input, token) {
     if (typeof input.token !== "string")
         return false;
@@ -26,7 +27,7 @@ async function dispatchBrokerRequest(input, connection, token, signal) {
         return brokerFailure("invalid_host_identity");
     if (!isHostIdentifier(input.connectionId))
         return brokerFailure("invalid_host_connection");
-    if (!isHostOperation(input.operation))
+    if (!isHostWireOperation(input.operation))
         return brokerFailure("invalid_host_operation");
     if (!isHostRecord(input.params))
         return brokerFailure("invalid_host_params");
@@ -45,6 +46,7 @@ function serveBrokerSocket(socket, connection, token) {
     const abort = new AbortController();
     let received = Buffer.alloc(0);
     let submitted = false;
+    let streaming = false;
     const deadline = setTimeout(() => socket.destroy(), 5_000);
     socket.on("error", () => socket.destroy());
     socket.on("close", () => {
@@ -52,6 +54,8 @@ function serveBrokerSocket(socket, connection, token) {
         abort.abort();
     });
     socket.on("data", (chunk) => {
+        if (streaming)
+            return;
         if (submitted) {
             socket.destroy();
             return;
@@ -78,6 +82,22 @@ function serveBrokerSocket(socket, connection, token) {
             socket.destroy();
             return;
         }
+        if (isHostRecord(input) && input.kind === "observe") {
+            if (!hasBrokerAuthorization(input, token) || input.version !== 1) {
+                socket.end(JSON.stringify(brokerFailure("host_not_authorized")) + "\n");
+                return;
+            }
+            try {
+                streaming = true;
+                serveObservationSubscription(socket, connection, input);
+            }
+            catch (error) {
+                socket.end(JSON.stringify(brokerFailure(error instanceof Error
+                    ? error.message
+                    : "host_observation_failed")) + "\n");
+            }
+            return;
+        }
         void dispatchBrokerRequest(input, connection, token, abort.signal).then((result) => {
             if (!socket.destroyed)
                 socket.end(JSON.stringify(result) + "\n");

package/dist/{plugins/system/source → src/computer-access}/companion/connection.d.ts

@@ -1,15 +1,21 @@
 import WebSocket from "ws";
-import { type ToolImplementationOutput } from "../../../../src/plugin-sdk/index.js";
+import { type ToolImplementationOutput } from "../../plugin-sdk/index.js";
 import { type HostOperation, type HostStatus } from "./protocol.js";
 import { HostPairingStore } from "./pairing-store.js";
+import { HostObservationConnection } from "./observation-connection.js";
 export declare class HostConnection {
     private readonly store;
+    private readonly connectionChanged;
+    readonly observations: HostObservationConnection;
     private client?;
     private connectionId?;
+    private observedCompanion?;
+    private capabilities;
     private readonly sockets;
     private readonly pending;
-    constructor(store: HostPairingStore);
+    constructor(store: HostPairingStore, connectionChanged?: () => void);
     status(): HostStatus;
+    private releaseForPairedHost;
     accept(client: WebSocket, token: string): void;
     private acceptHello;
     private acceptResult;