@abot-ai/runtime 1.3.0 → 1.4.0

package/dist/plugins/system/source/companion/native-session.js

@@ -0,0 +1,205 @@
+import WebSocket from "ws";
+import { createSystemHandlers } from "../handlers.js";
+import { resolveNativeRuntimeAddress, } from "./native-address.js";
+import { assertNativeOperationTarget, NativeOperationInputError, readNativeServerMessage, } from "./native-messages.js";
+import { HOST_PROTOCOL_VERSION, HOST_WIRE_MAX_BYTES, } from "./protocol.js";
+function operationFailure(message, code) {
+    return {
+        ok: false,
+        output: message,
+        errorCode: code,
+        producedNewInformation: false,
+    };
+}
+function hasHeaderSafeAuthorization(value) {
+    if (value.length < 6 || value.length > 256)
+        return false;
+    return /^[A-Za-z0-9_-]+$/u.test(value);
+}
+/** One connection lifetime. Its pending actions are never retried or replayed. */
+export async function connectNativeHost(options) {
+    if (!hasHeaderSafeAuthorization(options.authorization))
+        throw new Error("Invalid host pairing credential.");
+    options.signal.throwIfAborted();
+    const endpoint = await resolveNativeRuntimeAddress(options.url, options.resolveHost);
+    options.signal.throwIfAborted();
+    const handlers = options.handlers ?? createSystemHandlers();
+    return new Promise((resolve) => {
+        const socket = new WebSocket(endpoint.url, {
+            headers: { Authorization: `Bearer ${options.authorization}` },
+            followRedirects: false,
+            handshakeTimeout: 10_000,
+            maxPayload: HOST_WIRE_MAX_BYTES,
+            perMessageDeflate: false,
+            family: endpoint.address.family,
+            lookup: (_hostname, _lookupOptions, callback) => {
+                callback(null, endpoint.address.address, endpoint.address.family);
+            },
+        });
+        const active = new Map();
+        const seen = new Set();
+        let hostId = options.hostId;
+        let ready = false;
+        let stopped = false;
+        let retiring = false;
+        let outcome = "disconnected";
+        let incoming = Promise.resolve();
+        let awaitingPong = false;
+        let retirement;
+        const handshake = setTimeout(() => stop("protocol_rejected"), 12_000);
+        const heartbeat = setInterval(() => {
+            if (socket.readyState !== WebSocket.OPEN)
+                return;
+            if (awaitingPong) {
+                stop("disconnected");
+                return;
+            }
+            awaitingPong = true;
+            socket.ping();
+        }, options.heartbeatMs ?? 15_000);
+        function stop(reason) {
+            if (stopped)
+                return;
+            stopped = true;
+            outcome = reason;
+            clearTimeout(handshake);
+            clearInterval(heartbeat);
+            if (retirement)
+                clearTimeout(retirement);
+            for (const controller of active.values())
+                controller.abort();
+            socket.terminate();
+        }
+        const abort = () => stop("stopped");
+        options.signal.addEventListener("abort", abort, { once: true });
+        function send(value) {
+            if (stopped || socket.readyState !== WebSocket.OPEN)
+                return;
+            socket.send(JSON.stringify(value));
+        }
+        function sendResult(id, result) {
+            const envelope = { type: "result", id, result };
+            if (Buffer.byteLength(JSON.stringify(envelope)) <= HOST_WIRE_MAX_BYTES) {
+                send(envelope);
+                return;
+            }
+            send({
+                type: "result",
+                id,
+                result: operationFailure("The native operation settled but its result exceeded the transport limit. Inspect the target before repeating an action.", "system_host_result_too_large"),
+            });
+        }
+        function retireConnection(id) {
+            retiring = true;
+            retirement = setTimeout(() => stop("disconnected"), 1_000);
+            socket.send(JSON.stringify({
+                type: "result",
+                id,
+                result: operationFailure("The host connection reached its operation limit. This operation was not dispatched; the companion is reconnecting for future work.", "system_host_connection_refresh"),
+            }), () => socket.close(1012, "operation_limit"));
+        }
+        function execute(message) {
+            if (!ready || message.hostId !== hostId)
+                throw new Error("Unbound native operation.");
+            if (seen.has(message.id))
+                throw new Error("Repeated native operation identity.");
+            if (seen.size >= (options.operationLimit ?? 4_096)) {
+                retireConnection(message.id);
+                return;
+            }
+            seen.add(message.id);
+            if (active.size >= 4) {
+                sendResult(message.id, operationFailure("The host companion is busy.", "system_host_busy"));
+                return;
+            }
+            try {
+                assertNativeOperationTarget(message, options.identity.os);
+            }
+            catch (error) {
+                if (!(error instanceof NativeOperationInputError))
+                    throw error;
+                sendResult(message.id, operationFailure(error.message, error.code));
+                return;
+            }
+            const handler = handlers[message.operation];
+            if (!handler)
+                throw new Error("Native operation handler is unavailable.");
+            const controller = new AbortController();
+            active.set(message.id, controller);
+            void Promise.resolve()
+                .then(() => {
+                controller.signal.throwIfAborted();
+                return handler(message.params, { abortSignal: controller.signal });
+            })
+                .then((result) => sendResult(message.id, result), () => {
+                sendResult(message.id, operationFailure("Native operation observation failed; inspect the target before retrying.", "system_host_native_failed"));
+            })
+                .finally(() => active.delete(message.id));
+        }
+        async function receive(text) {
+            const message = readNativeServerMessage(text);
+            // A pairing receipt already received on the socket must reach private storage
+            // even if its server closes while the asynchronous write is still pending.
+            if ((stopped || retiring) && message.type !== "paired")
+                return;
+            if (message.type === "paired") {
+                if (hostId || ready)
+                    throw new Error("Unexpected native pairing response.");
+                hostId = message.hostId;
+                await options.onPaired(message.hostId, message.credential);
+                return;
+            }
+            if (message.type === "ready") {
+                if (ready || hostId !== message.hostId)
+                    throw new Error("Native readiness identity mismatch.");
+                ready = true;
+                clearTimeout(handshake);
+                await options.onReady(message.hostId);
+                return;
+            }
+            if (message.type === "cancel") {
+                active.get(message.id)?.abort();
+                return;
+            }
+            execute(message);
+        }
+        socket.on("open", () => send({
+            type: "hello",
+            version: HOST_PROTOCOL_VERSION,
+            identity: options.identity,
+            ...(hostId ? { hostId } : {}),
+        }));
+        socket.on("message", (data, binary) => {
+            if (binary) {
+                stop("protocol_rejected");
+                return;
+            }
+            incoming = incoming
+                .then(() => receive(data.toString()))
+                .catch(() => {
+                outcome = "protocol_rejected";
+                stop("protocol_rejected");
+            });
+        });
+        socket.on("pong", () => {
+            awaitingPong = false;
+        });
+        socket.on("unexpected-response", (_request, response) => {
+            const rejected = response.statusCode === 401 || response.statusCode === 403;
+            response.destroy();
+            stop(rejected ? "authorization_rejected" : "protocol_rejected");
+        });
+        socket.on("error", () => stop("disconnected"));
+        socket.on("close", (code, reason) => {
+            if (!stopped && code === 1008) {
+                const revoked = ["host_disconnected", "host_revoked"].includes(reason.toString());
+                outcome = revoked ? "authorization_rejected" : "protocol_rejected";
+            }
+            stop(outcome);
+            options.signal.removeEventListener("abort", abort);
+            void incoming.then(() => resolve(outcome));
+        });
+        if (options.signal.aborted)
+            abort();
+    });
+}

package/dist/plugins/system/source/companion/native-state.d.ts

@@ -0,0 +1,22 @@
+import type { Stats } from "node:fs";
+export type NativeHostConnection = Readonly<{
+    version: 1;
+    url: string;
+    hostId: string;
+    credential: string;
+}>;
+export type NativePrivateAccess = Readonly<{
+    ensureDirectory(path: string): Promise<void>;
+    assertFile(path: string, stat: Stats): Promise<void>;
+}>;
+export type NativeHostState = ReturnType<typeof createNativeHostState>;
+export declare function isNativeCredential(value: unknown): value is string;
+export declare function hasSameNativeConnection(a: NativeHostConnection, b: NativeHostConnection): boolean;
+export declare function createNativeHostState(directory: string, access: NativePrivateAccess): {
+    directory: string;
+    read: () => Promise<NativeHostConnection | undefined>;
+    write(connection: NativeHostConnection): Promise<void>;
+    remove(expected?: NativeHostConnection): Promise<void>;
+    setStatus(hostId: string, connected: boolean): Promise<void>;
+    isConnected(hostId: string): Promise<boolean>;
+};

package/dist/plugins/system/source/companion/native-state.js

@@ -0,0 +1,126 @@
+import { randomUUID } from "node:crypto";
+import { lstat, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { normalizeNativeRuntimeUrl } from "./native-address.js";
+import { isHostIdentifier, isHostRecord } from "./protocol.js";
+export function isNativeCredential(value) {
+    if (typeof value !== "string")
+        return false;
+    return /^[A-Za-z0-9_-]{32,256}$/u.test(value);
+}
+function readConnection(value) {
+    if (!isHostRecord(value))
+        throw new Error("Invalid saved host connection.");
+    if (value.version !== 1)
+        throw new Error("Unsupported saved host connection version.");
+    if (!isHostIdentifier(value.hostId))
+        throw new Error("Invalid saved host identity.");
+    if (!isNativeCredential(value.credential))
+        throw new Error("Invalid saved host credential.");
+    if (typeof value.url !== "string")
+        throw new Error("Missing saved Runtime URL.");
+    return {
+        version: 1,
+        url: normalizeNativeRuntimeUrl(value.url),
+        hostId: value.hostId,
+        credential: value.credential,
+    };
+}
+export function hasSameNativeConnection(a, b) {
+    if (a.url !== b.url)
+        return false;
+    if (a.hostId !== b.hostId)
+        return false;
+    return a.credential === b.credential;
+}
+function isAbsentFile(error) {
+    return isHostRecord(error) && error.code === "ENOENT";
+}
+export function createNativeHostState(directory, access) {
+    const connectionPath = join(directory, "connection.json");
+    const statusPath = join(directory, "status.json");
+    async function inspectPrivate(path) {
+        await access.ensureDirectory(directory);
+        const stat = await lstat(path).catch((error) => {
+            if (isAbsentFile(error))
+                return undefined;
+            throw error;
+        });
+        if (!stat)
+            return undefined;
+        if (!stat.isFile() || stat.isSymbolicLink())
+            throw new Error("Host companion state must be a private regular file.");
+        await access.assertFile(path, stat);
+        return stat;
+    }
+    async function readPrivate(path) {
+        const stat = await inspectPrivate(path);
+        if (!stat)
+            return undefined;
+        if (stat.size > 16_384)
+            throw new Error("Host companion state exceeds its size limit.");
+        return JSON.parse(await readFile(path, "utf8"));
+    }
+    async function writePrivate(path, value) {
+        await access.ensureDirectory(directory);
+        await readPrivate(path);
+        const temporary = `${path}.${randomUUID()}.tmp`;
+        try {
+            await writeFile(temporary, JSON.stringify(value) + "\n", {
+                encoding: "utf8",
+                mode: 0o600,
+                flag: "wx",
+            });
+            await access.assertFile(temporary, await lstat(temporary));
+            await rename(temporary, path);
+        }
+        finally {
+            await unlink(temporary).catch((error) => {
+                if (!isAbsentFile(error))
+                    throw error;
+            });
+        }
+    }
+    async function read() {
+        const value = await readPrivate(connectionPath);
+        return value === undefined ? undefined : readConnection(value);
+    }
+    return {
+        directory,
+        read,
+        async write(connection) {
+            await writePrivate(connectionPath, readConnection(connection));
+        },
+        async remove(expected) {
+            if (!expected) {
+                if (await inspectPrivate(connectionPath))
+                    await unlink(connectionPath);
+                return;
+            }
+            const current = await read();
+            if (!current)
+                return;
+            if (!hasSameNativeConnection(current, expected))
+                return;
+            await unlink(connectionPath);
+        },
+        async setStatus(hostId, connected) {
+            await writePrivate(statusPath, {
+                hostId,
+                connected,
+                pid: process.pid,
+                observedAt: Date.now(),
+            });
+        },
+        async isConnected(hostId) {
+            const value = await readPrivate(statusPath);
+            if (!isHostRecord(value))
+                return false;
+            if (value.hostId !== hostId || value.connected !== true)
+                return false;
+            if (typeof value.observedAt !== "number")
+                return false;
+            return Date.now() - value.observedAt < 5_000;
+        },
+    };
+}

package/dist/plugins/system/source/companion/native-supervisor.d.ts

@@ -0,0 +1,10 @@
+import { type NativeSessionOptions, type NativeSessionOutcome } from "./native-session.js";
+import { type NativeHostState } from "./native-state.js";
+import type { HostIdentity } from "./protocol.js";
+export declare function runNativeHostSupervisor(options: Readonly<{
+    state: NativeHostState;
+    identity: HostIdentity;
+    signal: AbortSignal;
+    connect?: (options: NativeSessionOptions) => Promise<NativeSessionOutcome>;
+    reconnectDelayMs?: number;
+}>): Promise<void>;

package/dist/plugins/system/source/companion/native-supervisor.js

@@ -0,0 +1,93 @@
+import { setTimeout as delay } from "node:timers/promises";
+import { connectNativeHost, } from "./native-session.js";
+import { hasSameNativeConnection, } from "./native-state.js";
+function isTransientNativeLookupError(error) {
+    if (error === null)
+        return false;
+    if (typeof error !== "object")
+        return false;
+    if (!("code" in error))
+        return false;
+    if (error.code === "EAI_AGAIN")
+        return true;
+    return error.code === "ENOTFOUND";
+}
+export async function runNativeHostSupervisor(options) {
+    const initial = await options.state.read();
+    if (!initial)
+        return;
+    const controller = new AbortController();
+    const stop = () => controller.abort();
+    options.signal.addEventListener("abort", stop, { once: true });
+    let checking = false;
+    let connected = false;
+    const checkState = async () => {
+        if (checking || controller.signal.aborted)
+            return;
+        checking = true;
+        try {
+            const current = await options.state.read();
+            if (!current || !hasSameNativeConnection(initial, current)) {
+                stop();
+                return;
+            }
+            await options.state.setStatus(initial.hostId, connected);
+        }
+        catch {
+            stop();
+        }
+        finally {
+            checking = false;
+        }
+    };
+    const poll = setInterval(() => {
+        void checkState();
+    }, 1_000);
+    let reconnectDelay = options.reconnectDelayMs ?? 500;
+    try {
+        if (options.signal.aborted)
+            stop();
+        while (!controller.signal.aborted) {
+            const outcome = await (options.connect ?? connectNativeHost)({
+                url: initial.url,
+                authorization: initial.credential,
+                hostId: initial.hostId,
+                identity: options.identity,
+                signal: controller.signal,
+                onPaired: async () => {
+                    throw new Error("A saved native connection cannot pair again.");
+                },
+                onReady: async () => {
+                    connected = true;
+                    reconnectDelay = options.reconnectDelayMs ?? 500;
+                    await options.state.setStatus(initial.hostId, true);
+                },
+            }).catch((error) => {
+                if (controller.signal.aborted)
+                    return "stopped";
+                if (isTransientNativeLookupError(error))
+                    return "disconnected";
+                throw error;
+            });
+            connected = false;
+            await options.state.setStatus(initial.hostId, false);
+            if (outcome === "authorization_rejected") {
+                await options.state.remove(initial);
+                return;
+            }
+            if (outcome === "protocol_rejected" || outcome === "stopped")
+                return;
+            // Only the connection is restored. No operation survives this boundary.
+            await delay(reconnectDelay, undefined, {
+                signal: controller.signal,
+            }).catch(() => { });
+            reconnectDelay = Math.min(reconnectDelay * 2, 10_000);
+        }
+    }
+    finally {
+        clearInterval(poll);
+        stop();
+        options.signal.removeEventListener("abort", stop);
+        await options.state.setStatus(initial.hostId, false);
+    }
+}

package/dist/plugins/system/source/companion/pairing-store.d.ts

@@ -0,0 +1,22 @@
+import { type HostIdentity } from "./protocol.js";
+export declare class HostPairingStore {
+    private readonly now;
+    private readonly path;
+    constructor(rootDir: string, now?: () => number);
+    private read;
+    host(): {
+        hostId: string;
+        identity: HostIdentity;
+        credentialDigest: string;
+    } | undefined;
+    begin(lifetimeMs?: number): {
+        code: string;
+        expiresAt: string;
+    };
+    authenticate(token: string): "pairing" | "credential" | undefined;
+    consume(code: string, identity: HostIdentity): {
+        hostId: string;
+        credential: string;
+    };
+    revoke(): void;
+}

package/dist/plugins/system/source/companion/pairing-store.js

@@ -0,0 +1,102 @@
+import { createHash, randomBytes, randomUUID, timingSafeEqual, } from "node:crypto";
+import { join } from "node:path";
+import { isHostIdentifier, isHostIdentity, isHostRecord, } from "./protocol.js";
+import { hostStateDirectory, readHostPrivateJson, writeHostPrivateJson, } from "./private-store.js";
+function tokenDigest(token) {
+    return createHash("sha256").update(token).digest("hex");
+}
+function matchesToken(token, digest) {
+    if (!/^[a-f0-9]{64}$/u.test(digest))
+        return false;
+    return timingSafeEqual(Buffer.from(tokenDigest(token), "hex"), Buffer.from(digest, "hex"));
+}
+function isBoundedPairingLifetime(lifetimeMs) {
+    if (!Number.isSafeInteger(lifetimeMs))
+        return false;
+    if (lifetimeMs < 1)
+        return false;
+    return lifetimeMs <= 15 * 60_000;
+}
+function isStoredPairing(value) {
+    if (!isHostRecord(value))
+        return false;
+    if (value.version !== 1)
+        return false;
+    if (value.pending !== undefined) {
+        if (!isHostRecord(value.pending))
+            return false;
+        if (typeof value.pending.digest !== "string")
+            return false;
+        if (typeof value.pending.expiresAt !== "number")
+            return false;
+    }
+    if (value.host === undefined)
+        return true;
+    if (!isHostRecord(value.host))
+        return false;
+    if (!isHostIdentifier(value.host.hostId))
+        return false;
+    if (!isHostIdentity(value.host.identity))
+        return false;
+    return typeof value.host.credentialDigest === "string";
+}
+export class HostPairingStore {
+    now;
+    path;
+    constructor(rootDir, now = Date.now) {
+        this.now = now;
+        this.path = join(hostStateDirectory(rootDir), "pairing.json");
+    }
+    read() {
+        const value = readHostPrivateJson(this.path);
+        if (value === undefined)
+            return { version: 1 };
+        if (!isStoredPairing(value))
+            throw new Error("host_pairing_state_invalid");
+        return value;
+    }
+    host() {
+        return this.read().host;
+    }
+    begin(lifetimeMs = 5 * 60_000) {
+        if (!isBoundedPairingLifetime(lifetimeMs))
+            throw new Error("host_pairing_lifetime_invalid");
+        if (this.host())
+            throw new Error("host_already_paired");
+        const code = randomBytes(32).toString("base64url");
+        const expiresAt = this.now() + lifetimeMs;
+        writeHostPrivateJson(this.path, {
+            version: 1,
+            pending: { digest: tokenDigest(code), expiresAt },
+        });
+        return { code, expiresAt: new Date(expiresAt).toISOString() };
+    }
+    authenticate(token) {
+        if (!/^[A-Za-z0-9_-]{43}$/u.test(token))
+            return undefined;
+        const record = this.read();
+        if (record.host && matchesToken(token, record.host.credentialDigest))
+            return "credential";
+        if (!record.pending)
+            return undefined;
+        if (record.pending.expiresAt <= this.now())
+            return undefined;
+        if (matchesToken(token, record.pending.digest))
+            return "pairing";
+        return undefined;
+    }
+    consume(code, identity) {
+        if (this.authenticate(code) !== "pairing")
+            throw new Error("host_pairing_expired");
+        const hostId = randomUUID();
+        const credential = randomBytes(32).toString("base64url");
+        writeHostPrivateJson(this.path, {
+            version: 1,
+            host: { hostId, identity, credentialDigest: tokenDigest(credential) },
+        });
+        return { hostId, credential };
+    }
+    revoke() {
+        writeHostPrivateJson(this.path, { version: 1 });
+    }
+}

package/dist/plugins/system/source/companion/private-store.d.ts

@@ -0,0 +1,4 @@
+export declare function hostStateDirectory(rootDir: string): string;
+export declare function ensureHostStateDirectory(directory: string): void;
+export declare function readHostPrivateJson(path: string): unknown | undefined;
+export declare function writeHostPrivateJson(path: string, value: unknown): void;

package/dist/plugins/system/source/companion/private-store.js

@@ -0,0 +1,59 @@
+import { randomUUID } from "node:crypto";
+import { lstatSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+export function hostStateDirectory(rootDir) {
+    return join(rootDir, ".runtime", "system-host");
+}
+export function ensureHostStateDirectory(directory) {
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const stat = lstatSync(directory);
+    if (!stat.isDirectory())
+        throw new Error("host_state_directory_invalid");
+    if (process.platform === "win32")
+        return;
+    if (stat.uid !== process.getuid?.())
+        throw new Error("host_state_owner_invalid");
+    if ((stat.mode & 0o077) !== 0)
+        throw new Error("host_state_directory_not_private");
+}
+export function readHostPrivateJson(path) {
+    try {
+        const stat = lstatSync(path);
+        if (!stat.isFile())
+            throw new Error("host_state_file_invalid");
+        if (process.platform !== "win32") {
+            if (stat.uid !== process.getuid?.())
+                throw new Error("host_state_owner_invalid");
+            if ((stat.mode & 0o077) !== 0)
+                throw new Error("host_state_file_not_private");
+        }
+        if (stat.size > 16_384)
+            throw new Error("host_state_file_too_large");
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+export function writeHostPrivateJson(path, value) {
+    ensureHostStateDirectory(dirname(path));
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+        writeFileSync(temporary, JSON.stringify(value), {
+            flag: "wx",
+            mode: 0o600,
+        });
+        renameSync(temporary, path);
+    }
+    finally {
+        try {
+            unlinkSync(temporary);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+}

package/dist/plugins/system/source/companion/process-owner-identity.d.ts

@@ -0,0 +1,22 @@
+type IdentityCommandOptions = Readonly<{
+    env: NodeJS.ProcessEnv;
+    windowsHide: true;
+    timeout: number;
+    maxBuffer: number;
+}>;
+export type ProcessOwnerIdentityDependencies = Readonly<{
+    platform: NodeJS.Platform;
+    currentPid: number;
+    readText(path: string): Promise<string>;
+    execute(file: string, args: readonly string[], options: IdentityCommandOptions): Promise<string>;
+    processIsAlive(pid: number): boolean;
+}>;
+export declare function createProcessOwnerIdentityProbe(dependencies: ProcessOwnerIdentityDependencies): {
+    readProcessOwnerIdentity: (pid: number) => Promise<string | undefined>;
+    isProcessOwnerAlive: (pid: number, ownerIdentity?: string) => Promise<boolean>;
+    requireCurrentProcessOwnerIdentity: () => Promise<string>;
+};
+export declare const readProcessOwnerIdentity: (pid: number) => Promise<string | undefined>;
+export declare const isProcessOwnerAlive: (pid: number, ownerIdentity?: string) => Promise<boolean>;
+export declare const requireCurrentProcessOwnerIdentity: () => Promise<string>;
+export {};