@abot-ai/runtime 1.3.1 → 1.5.0

package/dist/src/computer-access/companion/local-setup-process.js

@@ -0,0 +1,127 @@
+import { spawn } from "node:child_process";
+import { NATIVE_RUNTIME_INSTALLATION_FAILURE } from "./native-runtime-installation.js";
+const SETUP_MESSAGES = {
+    host_local_setup_unavailable: "Local computer setup is available only on a Mac running ABot.",
+    host_local_setup_unsafe_cache: "The companion installation could not be verified. Check its private installation folder before trying again.",
+    host_local_setup_timeout: "Computer setup timed out. Check the computer connection in ABot Settings before trying again.",
+    host_local_setup_failed: "Computer setup did not complete. Check the computer connection in ABot Settings before trying again.",
+};
+const KNOWN_SETUP_FAILURES = new Set([
+    NATIVE_RUNTIME_INSTALLATION_FAILURE,
+    "A Runtime is already paired. Use 'abot host disconnect' before pairing another.",
+    "The paired computer connection is missing. Reconnect from ABot Settings.",
+    "This upgrade belongs to a different paired computer connection.",
+    "Pairing did not complete. Check ABot Settings and use a fresh pairing code.",
+    "The updated host companion did not connect. The saved pairing is preserved; run setup again to retry.",
+]);
+export class LocalCompanionSetupError extends Error {
+    code;
+    constructor(code, message = SETUP_MESSAGES[code]) {
+        super(message);
+        this.code = code;
+        this.name = "LocalCompanionSetupError";
+    }
+}
+function safeSetupFailure(stderr) {
+    const finalLine = stderr.trim().split(/\r?\n/u).at(-1);
+    const knownMessage = finalLine && KNOWN_SETUP_FAILURES.has(finalLine);
+    return new LocalCompanionSetupError("host_local_setup_failed", knownMessage ? finalLine : undefined);
+}
+function terminateSetupProcessGroup(child, dependencies) {
+    if (child.pid === undefined) {
+        child.kill("SIGKILL");
+        return;
+    }
+    const killGroup = dependencies.killProcessGroup ??
+        ((pid) => {
+            process.kill(-pid, "SIGKILL");
+        });
+    try {
+        killGroup(child.pid);
+    }
+    catch {
+        child.kill("SIGKILL");
+    }
+}
+/** Only the bundled setup entry sees pairing data; the parent never logs output. */
+export async function runLocalCompanionSetup(input, dependencies) {
+    const launch = dependencies.spawn ?? spawn;
+    let child;
+    try {
+        child = launch(process.execPath, [input.bundlePath, "setup"], {
+            cwd: input.homeDir,
+            stdio: ["pipe", "pipe", "pipe"],
+            windowsHide: true,
+            detached: true,
+        });
+    }
+    catch {
+        throw new LocalCompanionSetupError("host_local_setup_failed");
+    }
+    await new Promise((resolve, reject) => {
+        let settled = false;
+        let outputBytes = 0;
+        let stderr = "";
+        let stoppingError;
+        let terminationDeadline;
+        const deadline = setTimeout(() => stop(new LocalCompanionSetupError("host_local_setup_timeout")), dependencies.timeoutMs ?? 120_000);
+        function finish(error) {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(deadline);
+            clearTimeout(terminationDeadline);
+            stderr = "";
+            if (error) {
+                reject(error);
+                return;
+            }
+            resolve();
+        }
+        function stop(error) {
+            if (settled)
+                return;
+            if (stoppingError)
+                return;
+            stoppingError = error;
+            clearTimeout(deadline);
+            stderr = "";
+            terminationDeadline = setTimeout(() => finish(error), dependencies.terminationTimeoutMs ?? 2_000);
+            terminateSetupProcessGroup(child, dependencies);
+            child.stdin.destroy();
+            child.stdout.destroy();
+            child.stderr.destroy();
+        }
+        function acceptOutput(chunk) {
+            if (settled)
+                return false;
+            if (stoppingError)
+                return false;
+            outputBytes += chunk.length;
+            if (outputBytes <= 65_536)
+                return true;
+            stop(new LocalCompanionSetupError("host_local_setup_failed"));
+            return false;
+        }
+        child.stdout.on("data", (chunk) => acceptOutput(chunk));
+        child.stderr.on("data", (chunk) => {
+            if (!acceptOutput(chunk))
+                return;
+            stderr += chunk.toString("utf8");
+        });
+        child.once("error", () => stop(new LocalCompanionSetupError("host_local_setup_failed")));
+        child.once("close", (code) => {
+            if (stoppingError) {
+                finish(stoppingError);
+                return;
+            }
+            if (code === 0) {
+                finish();
+                return;
+            }
+            finish(safeSetupFailure(stderr));
+        });
+        child.stdin.on("error", () => stop(new LocalCompanionSetupError("host_local_setup_failed")));
+        child.stdin.end(input.payload);
+    });
+}

package/dist/src/computer-access/companion/native-address.d.ts

@@ -0,0 +1,12 @@
+export type NativeAddress = Readonly<{
+    address: string;
+    family: number;
+}>;
+export type NativeHostResolver = (hostname: string) => Promise<readonly NativeAddress[]>;
+export declare function isNativeLoopbackAddress(value: string): boolean;
+export declare function normalizeNativeRuntimeUrl(value: string): string;
+/** Resolve once, reject mixed/public answers, then pin only these addresses at connect. */
+export declare function resolveNativeRuntimeAddress(value: string, resolveHost?: NativeHostResolver): Promise<Readonly<{
+    url: string;
+    addresses: readonly NativeAddress[];
+}>>;

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

@@ -0,0 +1,58 @@
+import { lookup as lookupHost } from "node:dns/promises";
+import { isIP } from "node:net";
+import { HOST_SOCKET_PATH } from "./protocol.js";
+export function isNativeLoopbackAddress(value) {
+    const address = value.replace(/^\[|\]$/gu, "");
+    const family = isIP(address);
+    if (family === 4)
+        return address.startsWith("127.");
+    if (family !== 6)
+        return false;
+    const normalized = new URL(`http://[${address}]`).hostname;
+    if (normalized === "[::1]")
+        return true;
+    return /^\[::ffff:7f[0-9a-f]{2}:/u.test(normalized);
+}
+export function normalizeNativeRuntimeUrl(value) {
+    const url = new URL(value);
+    if (!["http:", "ws:", "https:", "wss:"].includes(url.protocol))
+        throw new Error("Use an HTTP or WebSocket URL for the local ABot Runtime.");
+    if (url.username || url.password || url.search || url.hash)
+        throw new Error("The Runtime URL must not contain credentials, a query, or a fragment.");
+    if (url.pathname !== "/")
+        throw new Error("Use the Runtime origin without a path.");
+    url.protocol = ["https:", "wss:"].includes(url.protocol) ? "wss:" : "ws:";
+    return url.origin;
+}
+function isLocalhostName(hostname) {
+    if (hostname === "localhost")
+        return true;
+    return hostname.endsWith(".localhost");
+}
+function hasValidLoopbackFamily(candidate) {
+    if (isIP(candidate.address) !== candidate.family)
+        return false;
+    return isNativeLoopbackAddress(candidate.address);
+}
+async function nativeAddressCandidates(hostname, resolveHost) {
+    if (isLocalhostName(hostname))
+        return [{ address: "127.0.0.1", family: 4 }, { address: "::1", family: 6 }];
+    const family = isIP(hostname);
+    if (family)
+        return [{ address: hostname, family }];
+    return resolveHost(hostname);
+}
+/** Resolve once, reject mixed/public answers, then pin only these addresses at connect. */
+export async function resolveNativeRuntimeAddress(value, resolveHost = (hostname) => lookupHost(hostname, { all: true })) {
+    const origin = normalizeNativeRuntimeUrl(value);
+    const url = new URL(origin);
+    const hostname = url.hostname.replace(/^\[|\]$/gu, "").toLowerCase().replace(/\.$/u, "");
+    const answers = await nativeAddressCandidates(hostname, resolveHost);
+    const addresses = Object.freeze(answers.map(({ address, family }) => Object.freeze({ address, family })));
+    if (addresses.length === 0)
+        throw new Error("The local Runtime address did not resolve.");
+    if (!addresses.every(hasValidLoopbackFamily))
+        throw new Error("The host companion connects only to a Runtime on this computer's loopback interface.");
+    url.pathname = HOST_SOCKET_PATH;
+    return { url: url.toString(), addresses };
+}

package/dist/src/computer-access/companion/native-build-identity.d.ts

@@ -0,0 +1,2 @@
+/** Identifies the exact entry bundle used by setup and the running companion. */
+export declare function readNativeCompanionBuildId(cliPath: string): Promise<string>;

package/dist/src/computer-access/companion/native-build-identity.js

@@ -0,0 +1,8 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+/** Identifies the exact entry bundle used by setup and the running companion. */
+export async function readNativeCompanionBuildId(cliPath) {
+    return createHash("sha256")
+        .update(await readFile(cliPath))
+        .digest("hex");
+}

package/dist/src/computer-access/companion/native-identity.d.ts

@@ -0,0 +1,2 @@
+import { type HostIdentity } from "./protocol.js";
+export declare function readNativeHostIdentity(): HostIdentity;

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

@@ -0,0 +1,23 @@
+import { homedir, hostname, userInfo } from "node:os";
+import { isHostIdentity } from "./protocol.js";
+export function readNativeHostIdentity() {
+    const os = nativeOperatingSystem(process.platform);
+    const identity = {
+        name: hostname(),
+        os,
+        user: userInfo().username,
+        homeDir: homedir(),
+    };
+    if (!isHostIdentity(identity))
+        throw new Error("The native user identity cannot be represented by the host protocol.");
+    return identity;
+}
+function nativeOperatingSystem(platform) {
+    if (platform === "win32")
+        return "windows";
+    if (platform === "darwin")
+        return "macos";
+    if (platform === "linux")
+        return "linux";
+    throw new Error("This operating system is not supported by the host companion.");
+}

package/dist/src/computer-access/companion/native-loopback-lookup.d.ts

@@ -0,0 +1,7 @@
+import type { TcpNetConnectOpts } from "node:net";
+import type { NativeAddress } from "./native-address.js";
+/** Socket-family selection is restricted to the resolver's immutable, vetted set. */
+export declare function nativeLoopbackSocketOptions(endpoint: Readonly<{
+    url: string;
+    addresses: readonly NativeAddress[];
+}>): Pick<TcpNetConnectOpts, "family" | "autoSelectFamily" | "autoSelectFamilyAttemptTimeout" | "lookup">;

package/dist/src/computer-access/companion/native-loopback-lookup.js

@@ -0,0 +1,33 @@
+function matchesLookupFamily(address, family) {
+    if (family === 4 || family === "IPv4")
+        return address.family === 4;
+    if (family === 6 || family === "IPv6")
+        return address.family === 6;
+    return family === undefined || family === 0;
+}
+/** Socket-family selection is restricted to the resolver's immutable, vetted set. */
+export function nativeLoopbackSocketOptions(endpoint) {
+    const expectedHostname = new URL(endpoint.url).hostname.toLowerCase();
+    return {
+        family: 0,
+        autoSelectFamily: true,
+        autoSelectFamilyAttemptTimeout: 250,
+        lookup(hostname, options, callback) {
+            const hasExpectedHostname = hostname.toLowerCase() === expectedHostname;
+            if (!hasExpectedHostname) {
+                callback(Object.assign(new Error("Unexpected Runtime lookup hostname."), { code: "ENOTFOUND" }), []);
+                return;
+            }
+            const addresses = endpoint.addresses.filter((address) => matchesLookupFamily(address, options.family));
+            if (addresses.length === 0) {
+                callback(Object.assign(new Error("No validated Runtime address for this family."), { code: "ENOTFOUND" }), []);
+                return;
+            }
+            if (options.all) {
+                callback(null, addresses.map(({ address, family }) => ({ address, family })));
+                return;
+            }
+            callback(null, addresses[0].address, addresses[0].family);
+        },
+    };
+}

package/dist/src/computer-access/companion/native-messages.d.ts

@@ -0,0 +1,9 @@
+import { type HostServerMessage } from "./protocol.js";
+export declare function readNativeServerMessage(text: string): HostServerMessage;
+export declare class NativeOperationInputError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare function assertNativeOperationTarget(message: Extract<HostServerMessage, {
+    type: "execute";
+}>, os: string): void;

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

@@ -0,0 +1,84 @@
+import { isNativeCredential } from "./native-state.js";
+import { isObservationControl } from "./observation-protocol.js";
+import { isHostIdentifier, isHostWireOperation, isHostRecord, } from "./protocol.js";
+function hasOnlyFields(value, fields) {
+    return Object.keys(value).every((key) => fields.includes(key));
+}
+export function readNativeServerMessage(text) {
+    const value = JSON.parse(text);
+    if (!isHostRecord(value))
+        throw new Error("Invalid host protocol message.");
+    if (isObservationControl(value))
+        return value;
+    if (value.type === "paired") {
+        if (!hasOnlyFields(value, ["type", "hostId", "credential"]))
+            throw new Error("Unexpected pairing fields.");
+        if (!isHostIdentifier(value.hostId))
+            throw new Error("Invalid paired host identity.");
+        if (!isNativeCredential(value.credential))
+            throw new Error("Invalid paired credential.");
+        return {
+            type: "paired",
+            hostId: value.hostId,
+            credential: value.credential,
+        };
+    }
+    if (value.type === "ready") {
+        if (!hasOnlyFields(value, ["type", "hostId"]))
+            throw new Error("Unexpected readiness fields.");
+        if (!isHostIdentifier(value.hostId))
+            throw new Error("Invalid ready host identity.");
+        return { type: "ready", hostId: value.hostId };
+    }
+    if (value.type === "cancel") {
+        if (!hasOnlyFields(value, ["type", "id"]))
+            throw new Error("Unexpected cancellation fields.");
+        if (!isHostIdentifier(value.id))
+            throw new Error("Invalid cancellation identity.");
+        return { type: "cancel", id: value.id };
+    }
+    if (value.type !== "execute")
+        throw new Error("Unsupported host protocol message.");
+    if (!hasOnlyFields(value, ["type", "id", "hostId", "operation", "params"]))
+        throw new Error("Unexpected execution fields.");
+    if (!isHostIdentifier(value.id))
+        throw new Error("Invalid operation identity.");
+    if (!isHostIdentifier(value.hostId))
+        throw new Error("Invalid operation host identity.");
+    if (!isHostWireOperation(value.operation))
+        throw new Error("Unsupported native operation.");
+    if (!isHostRecord(value.params))
+        throw new Error("Invalid native operation parameters.");
+    return {
+        type: "execute",
+        id: value.id,
+        hostId: value.hostId,
+        operation: value.operation,
+        params: value.params,
+    };
+}
+const NATIVE_OPERATION_FIELDS = {
+    desktop_notification: ["target", "notificationId", "title", "body", "url"],
+    system_targets: [],
+    system_command: ["target", "command", "cwd", "elevated", "timeout_ms"],
+    system_applications: ["target", "query", "limit"],
+    system_launch: ["target", "application_id", "arguments"],
+    computer_execute: ["target", "sessionId", "request"],
+    computer_frame: ["target", "sessionId", "frameId", "offset"],
+    computer_close: ["target", "sessionId"],
+};
+export class NativeOperationInputError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+export function assertNativeOperationTarget(message, os) {
+    if (!hasOnlyFields(message.params, NATIVE_OPERATION_FIELDS[message.operation]))
+        throw new NativeOperationInputError("system_command_invalid", "The native operation contains unsupported parameters.");
+    if (message.operation === "system_targets")
+        return;
+    if (message.params.target !== os)
+        throw new NativeOperationInputError("system_target_unavailable", "The operation must address this companion's native operating system.");
+}

package/dist/src/computer-access/companion/native-notifications.d.ts

@@ -0,0 +1,16 @@
+import { type ToolImplementation } from "../../plugin-sdk/index.js";
+import type { HostIdentity } from "./protocol.js";
+import { type DesktopNotification } from "./notification-protocol.js";
+import { type NotificationLocations } from "./notification-locations.js";
+export type NativeNotificationSession = Readonly<{
+    ready: boolean;
+    refreshReadiness?(signal: AbortSignal): Promise<boolean>;
+    handlers(): Record<string, ToolImplementation>;
+    close(): void | Promise<void>;
+}>;
+export type NativeNotificationRenderer = Readonly<{
+    send(notification: DesktopNotification, signal?: AbortSignal): Promise<void>;
+    close(): void | Promise<void>;
+}>;
+export declare function createNotificationSession(platform: HostIdentity["os"], runtimeUrl: string, ready: boolean, renderer: NativeNotificationRenderer, probe?: (signal: AbortSignal) => Promise<boolean>): NativeNotificationSession;
+export declare function createNativeNotificationSession(platform: HostIdentity["os"], runtimeUrl: string, locations?: NotificationLocations, signal?: AbortSignal): Promise<NativeNotificationSession>;

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

@@ -0,0 +1,84 @@
+import { failureResult, successResult, } from "../../plugin-sdk/index.js";
+import { readDesktopNotification, } from "./notification-protocol.js";
+import { defaultNotificationLocations, } from "./notification-locations.js";
+import { sendWindowsNotification } from "./notification-windows.js";
+import { sendMacNotification } from "./notification-macos.js";
+import { LinuxNotificationRenderer } from "./notification-linux.js";
+import { stopMacNotificationApp } from "./notification-installation.js";
+import { runNotificationProcess } from "./notification-process.js";
+import { hasDesktopNotificationSupport } from "./notification-readiness.js";
+import { NotificationReadinessState } from "./notification-readiness-state.js";
+function hasUnknownNotificationOutcome(error) {
+    if (!(error instanceof Error))
+        return false;
+    if (error.name === "AbortError")
+        return true;
+    if (error.message === "notification_native_timeout")
+        return true;
+    return error.message === "notification_cancelled";
+}
+export function createNotificationSession(platform, runtimeUrl, ready, renderer, probe) {
+    const readiness = new NotificationReadinessState(ready, probe);
+    return {
+        get ready() {
+            return readiness.ready;
+        },
+        refreshReadiness: (signal) => readiness.refresh(signal),
+        handlers: () => ({
+            desktop_notification: async (params, context) => {
+                if (!readiness.ready)
+                    return failureResult({
+                        errorCode: "notification_setup_required",
+                        message: "Desktop notifications are unavailable. Update Computer access setup and check the operating system notification settings.",
+                    });
+                try {
+                    const notification = readDesktopNotification(params, platform, runtimeUrl);
+                    context?.abortSignal?.throwIfAborted();
+                    await renderer.send(notification, context?.abortSignal);
+                    return successResult({
+                        output: "Notification submitted to the desktop notification service.",
+                        data: {
+                            notificationId: notification.notificationId,
+                            delivery: "submitted",
+                        },
+                    });
+                }
+                catch (error) {
+                    return failureResult({
+                        errorCode: hasUnknownNotificationOutcome(error)
+                            ? "notification_outcome_unknown"
+                            : "notification_native_failed",
+                        message: error instanceof Error
+                            ? error.message.slice(0, 1000)
+                            : "Desktop notification submission failed.",
+                    });
+                }
+            },
+        }),
+        close: () => renderer.close(),
+    };
+}
+export async function createNativeNotificationSession(platform, runtimeUrl, locations = defaultNotificationLocations(), signal) {
+    signal?.throwIfAborted();
+    const linux = new LinuxNotificationRenderer();
+    const ready = await hasDesktopNotificationSupport(platform, locations, runNotificationProcess, signal);
+    signal?.throwIfAborted();
+    const session = createNotificationSession(platform, runtimeUrl, ready, {
+        async send(notification, signal) {
+            if (platform === "windows")
+                return sendWindowsNotification(notification, signal);
+            if (platform === "macos")
+                return sendMacNotification(notification, locations, signal);
+            return linux.send(notification, signal);
+        },
+        async close() {
+            linux.close();
+            if (platform === "macos" && session.ready)
+                await stopMacNotificationApp(locations, runNotificationProcess).catch((error) => {
+                    console.warn("Desktop notification helper could not stop: " +
+                        (error instanceof Error ? error.message : String(error)));
+                });
+        },
+    }, (refreshSignal) => hasDesktopNotificationSupport(platform, locations, runNotificationProcess, refreshSignal));
+    return session;
+}

package/dist/src/computer-access/companion/native-observations.d.ts

@@ -0,0 +1,15 @@
+import type { PassiveCollectorEvent } from "../../shared/passive-observation.js";
+import { type DesktopCollector } from "./observation-process.js";
+import { type ObservationControl } from "./observation-protocol.js";
+export type ObservationCollectorFactory = (options: {
+    excludedApplications: readonly string[];
+    onEvent(event: PassiveCollectorEvent): void;
+}) => DesktopCollector;
+export declare class NativeObservationSession {
+    private readonly send;
+    private readonly start;
+    private lease?;
+    constructor(send: (message: unknown) => void, start?: ObservationCollectorFactory);
+    receive(control: ObservationControl): void;
+    close(): void;
+}

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

@@ -0,0 +1,67 @@
+import { startDesktopCollector, } from "./observation-process.js";
+import { OBSERVATION_LEASE_MS, } from "./observation-protocol.js";
+export class NativeObservationSession {
+    send;
+    start;
+    lease;
+    constructor(send, start = startDesktopCollector) {
+        this.send = send;
+        this.start = start;
+    }
+    receive(control) {
+        if (control.type === "observe_start") {
+            if (this.lease)
+                throw new Error("observation_lease_already_active");
+            const lease = {
+                ownerId: control.ownerId,
+                leaseId: control.leaseId,
+                collector: { close() { } },
+                deadline: setTimeout(() => this.close(), OBSERVATION_LEASE_MS),
+            };
+            this.lease = lease;
+            const onEvent = (event) => {
+                if (this.lease !== lease)
+                    return;
+                this.send({
+                    type: "observation_event",
+                    ownerId: lease.ownerId,
+                    leaseId: lease.leaseId,
+                    event,
+                });
+            };
+            try {
+                lease.collector = this.start({
+                    excludedApplications: control.excludedApplications ?? [],
+                    onEvent,
+                });
+            }
+            catch {
+                onEvent({
+                    type: "status",
+                    state: "failed",
+                    reason: "collector_start_failed",
+                });
+            }
+            return;
+        }
+        const lease = this.lease;
+        if (!lease ||
+            lease.ownerId !== control.ownerId ||
+            lease.leaseId !== control.leaseId)
+            return;
+        if (control.type === "observe_stop") {
+            this.close();
+            return;
+        }
+        clearTimeout(lease.deadline);
+        lease.deadline = setTimeout(() => this.close(), OBSERVATION_LEASE_MS);
+    }
+    close() {
+        const lease = this.lease;
+        if (!lease)
+            return;
+        this.lease = undefined;
+        clearTimeout(lease.deadline);
+        lease.collector.close();
+    }
+}

package/dist/src/computer-access/companion/native-replacement.d.ts

@@ -0,0 +1,19 @@
+import { readLockSnapshot } from "../../runtime/adapters/long-term-memory/file-lock/snapshot.js";
+import { isProcessOwnerAlive, readProcessOwnerIdentity } from "./process-owner-identity.js";
+export type NativeReplacementDependencies = Readonly<{
+    platform: NodeJS.Platform;
+    currentPid: number;
+    readLock: typeof readLockSnapshot;
+    readIdentity: typeof readProcessOwnerIdentity;
+    isAlive: typeof isProcessOwnerAlive;
+    signal(pid: number, signal: "SIGTERM"): void;
+    execute(file: string, args: readonly string[], options: {
+        windowsHide: true;
+        timeout: number;
+        maxBuffer: number;
+    }): Promise<void>;
+    now(): number;
+    delay(milliseconds: number): Promise<void>;
+}>;
+/** Retire only the lock's verified process incarnation; the new owner reclaims its own lock. */
+export declare function stopOwnedNativeCompanion(stateDir: string, overrides?: Partial<NativeReplacementDependencies>): Promise<void>;