@abot-ai/runtime 1.3.1 → 1.4.0

package/dist/plugins/system/source/companion/broker-location.js

@@ -0,0 +1,76 @@
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { lstatSync, realpathSync, unlinkSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { tmpdir } from "node:os";
+import { ensureHostStateDirectory, hostStateDirectory, readHostPrivateJson, writeHostPrivateJson, } from "./private-store.js";
+import { isHostIdentifier, isHostRecord } from "./protocol.js";
+function brokerRecordPath(rootDir) {
+    return join(hostStateDirectory(rootDir), "broker.json");
+}
+function brokerSocketPath(rootDir) {
+    if (process.platform !== "linux")
+        throw new Error("host_broker_requires_linux_runtime");
+    const key = createHash("sha256")
+        .update(realpathSync(rootDir))
+        .digest("hex")
+        .slice(0, 20);
+    return join(tmpdir(), `abot-host-${process.getuid?.()}-${key}`, "broker.sock");
+}
+function isBrokerLocation(value) {
+    if (!isHostRecord(value))
+        return false;
+    if (!isHostIdentifier(value.ownerId))
+        return false;
+    if (typeof value.token !== "string")
+        return false;
+    if (!/^[A-Za-z0-9_-]{43}$/u.test(value.token))
+        return false;
+    return typeof value.socketPath === "string";
+}
+export function readBrokerLocation(rootDir) {
+    const record = readHostPrivateJson(brokerRecordPath(rootDir));
+    if (record === undefined)
+        return undefined;
+    if (!isBrokerLocation(record))
+        throw new Error("host_broker_record_invalid");
+    if (record.socketPath !== brokerSocketPath(rootDir))
+        throw new Error("host_broker_path_invalid");
+    return record;
+}
+export function createBrokerLocation(rootDir) {
+    ensureHostStateDirectory(hostStateDirectory(rootDir));
+    const socketPath = brokerSocketPath(rootDir);
+    ensureHostStateDirectory(dirname(socketPath));
+    removeAbandonedBrokerSocket(socketPath);
+    return {
+        ownerId: randomUUID(),
+        token: randomBytes(32).toString("base64url"),
+        socketPath,
+    };
+}
+/** Called only while holding the installation's process-incarnation lease. */
+function removeAbandonedBrokerSocket(socketPath) {
+    try {
+        const stat = lstatSync(socketPath);
+        if (!stat.isSocket())
+            throw new Error("host_broker_socket_invalid");
+        if (stat.uid !== process.getuid?.())
+            throw new Error("host_broker_socket_owner_invalid");
+        unlinkSync(socketPath);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}
+/** Call only after acquiring the installation lease and listener. */
+export function publishBrokerLocation(rootDir, owner) {
+    writeHostPrivateJson(brokerRecordPath(rootDir), owner);
+}
+/** Release the receipt before the listener, while successors cannot acquire it. */
+export function releaseBrokerLocation(rootDir, owner) {
+    const current = readBrokerLocation(rootDir);
+    if (current?.ownerId !== owner.ownerId)
+        return;
+    unlinkSync(brokerRecordPath(rootDir));
+}

package/dist/plugins/system/source/companion/broker-server.d.ts

@@ -0,0 +1,4 @@
+import type { HostConnection } from "./connection.js";
+export declare function startHostBroker(rootDir: string, connection: HostConnection, acquireOwnership: () => Promise<() => Promise<void>>): Promise<{
+    close(): Promise<void>;
+}>;

package/dist/plugins/system/source/companion/broker-server.js

@@ -0,0 +1,147 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+import { createServer } from "node:net";
+import { createBrokerLocation, publishBrokerLocation, releaseBrokerLocation, } from "./broker-location.js";
+import { HOST_WIRE_MAX_BYTES, isHostIdentifier, isHostOperation, isHostRecord, } from "./protocol.js";
+function hasBrokerAuthorization(input, token) {
+    if (typeof input.token !== "string")
+        return false;
+    const digest = (text) => createHash("sha256").update(text).digest();
+    return timingSafeEqual(digest(input.token), digest(token));
+}
+function brokerFailure(error) {
+    return { ok: false, error };
+}
+async function dispatchBrokerRequest(input, connection, token, signal) {
+    if (!isHostRecord(input))
+        return brokerFailure("invalid_host_request");
+    if (!hasBrokerAuthorization(input, token))
+        return brokerFailure("host_not_authorized");
+    if (input.version !== 1)
+        return brokerFailure("host_protocol_version_mismatch");
+    if (input.kind === "status")
+        return { ok: true, status: connection.status() };
+    if (input.kind !== "execute")
+        return brokerFailure("invalid_host_operation");
+    if (!isHostIdentifier(input.hostId))
+        return brokerFailure("invalid_host_identity");
+    if (!isHostIdentifier(input.connectionId))
+        return brokerFailure("invalid_host_connection");
+    if (!isHostOperation(input.operation))
+        return brokerFailure("invalid_host_operation");
+    if (!isHostRecord(input.params))
+        return brokerFailure("invalid_host_params");
+    return {
+        ok: true,
+        result: await connection.execute({
+            hostId: input.hostId,
+            connectionId: input.connectionId,
+            operation: input.operation,
+            params: input.params,
+            abortSignal: signal,
+        }),
+    };
+}
+function serveBrokerSocket(socket, connection, token) {
+    const abort = new AbortController();
+    let received = Buffer.alloc(0);
+    let submitted = false;
+    const deadline = setTimeout(() => socket.destroy(), 5_000);
+    socket.on("error", () => socket.destroy());
+    socket.on("close", () => {
+        clearTimeout(deadline);
+        abort.abort();
+    });
+    socket.on("data", (chunk) => {
+        if (submitted) {
+            socket.destroy();
+            return;
+        }
+        received = Buffer.concat([received, chunk]);
+        if (received.length > HOST_WIRE_MAX_BYTES) {
+            socket.destroy();
+            return;
+        }
+        const boundary = received.indexOf(10);
+        if (boundary < 0)
+            return;
+        if (boundary !== received.length - 1) {
+            socket.destroy();
+            return;
+        }
+        submitted = true;
+        clearTimeout(deadline);
+        let input;
+        try {
+            input = JSON.parse(received.subarray(0, boundary).toString());
+        }
+        catch {
+            socket.destroy();
+            return;
+        }
+        void dispatchBrokerRequest(input, connection, token, abort.signal).then((result) => {
+            if (!socket.destroyed)
+                socket.end(JSON.stringify(result) + "\n");
+        }, () => {
+            if (!socket.destroyed)
+                socket.end(JSON.stringify(brokerFailure("host_request_failed")) + "\n");
+        });
+    });
+}
+export async function startHostBroker(rootDir, connection, acquireOwnership) {
+    const releaseOwnership = await acquireOwnership();
+    let owner;
+    try {
+        owner = createBrokerLocation(rootDir);
+    }
+    catch (error) {
+        await releaseOwnership();
+        throw error;
+    }
+    const sockets = new Set();
+    const server = createServer((socket) => {
+        if (sockets.size >= 32) {
+            socket.destroy();
+            return;
+        }
+        sockets.add(socket);
+        socket.once("close", () => sockets.delete(socket));
+        serveBrokerSocket(socket, connection, owner.token);
+    });
+    try {
+        await new Promise((resolve, reject) => {
+            server.once("error", reject);
+            server.listen(owner.socketPath, () => {
+                server.removeListener("error", reject);
+                resolve();
+            });
+        });
+        publishBrokerLocation(rootDir, owner);
+    }
+    catch (error) {
+        await closeBrokerListener(server);
+        await releaseOwnership();
+        throw error;
+    }
+    let closing;
+    return {
+        close() {
+            closing ??= (async () => {
+                for (const socket of sockets)
+                    socket.destroy();
+                try {
+                    releaseBrokerLocation(rootDir, owner);
+                }
+                finally {
+                    await closeBrokerListener(server);
+                    await releaseOwnership();
+                }
+            })();
+            return closing;
+        },
+    };
+}
+async function closeBrokerListener(server) {
+    if (!server.listening)
+        return;
+    await new Promise((resolve, reject) => server.close((error) => (error ? reject(error) : resolve())));
+}

package/dist/plugins/system/source/companion/connection.d.ts

@@ -0,0 +1,25 @@
+import WebSocket from "ws";
+import { type ToolImplementationOutput } from "../../../../src/plugin-sdk/index.js";
+import { type HostOperation, type HostStatus } from "./protocol.js";
+import { HostPairingStore } from "./pairing-store.js";
+export declare class HostConnection {
+    private readonly store;
+    private client?;
+    private connectionId?;
+    private readonly sockets;
+    private readonly pending;
+    constructor(store: HostPairingStore);
+    status(): HostStatus;
+    accept(client: WebSocket, token: string): void;
+    private acceptHello;
+    private acceptResult;
+    execute(input: {
+        hostId: string;
+        connectionId: string;
+        operation: HostOperation;
+        params: Record<string, unknown>;
+        abortSignal?: AbortSignal;
+    }): Promise<ToolImplementationOutput>;
+    disconnect(): void;
+    close(): void;
+}

package/dist/plugins/system/source/companion/connection.js

@@ -0,0 +1,182 @@
+import { randomUUID } from "node:crypto";
+import WebSocket from "ws";
+import { failureResult, } from "../../../../src/plugin-sdk/index.js";
+import { attachHostEvidence } from "../host-evidence.js";
+import { hasMatchingHostIdentity, isHostIdentifier, isHostIdentity, isHostRecord, isHostToolResult, } from "./protocol.js";
+import { monitorHostLiveness } from "./liveness.js";
+function unavailable(message) {
+    return failureResult({ errorCode: "system_host_unavailable", message });
+}
+function uncertain() {
+    return failureResult({
+        errorCode: "system_host_outcome_unknown",
+        message: "Host observation ended before a settled result. Effects or detached processes may remain. Inspect the same host before retrying; this operation was not replayed.",
+        data: { outcome: "unknown", retrySafe: false },
+    });
+}
+export class HostConnection {
+    store;
+    client;
+    connectionId;
+    sockets = new Set();
+    pending = new Map();
+    constructor(store) {
+        this.store = store;
+    }
+    status() {
+        const host = this.store.host();
+        if (!host)
+            return { paired: false, connected: false };
+        const identity = {
+            paired: true,
+            hostId: host.hostId,
+            identity: host.identity,
+        };
+        if (!this.connectionId)
+            return { ...identity, connected: false };
+        if (this.client?.readyState !== WebSocket.OPEN)
+            return { ...identity, connected: false };
+        return { ...identity, connected: true, connectionId: this.connectionId };
+    }
+    accept(client, token) {
+        this.sockets.add(client);
+        monitorHostLiveness(client);
+        let ready = false;
+        const helloDeadline = setTimeout(() => client.close(1008, "hello_required"), 5_000);
+        client.on("error", () => client.terminate());
+        client.on("close", () => {
+            clearTimeout(helloDeadline);
+            this.sockets.delete(client);
+            if (this.client !== client)
+                return;
+            this.client = undefined;
+            this.connectionId = undefined;
+            for (const operation of this.pending.values())
+                operation.finish(uncertain());
+        });
+        client.on("message", (bytes, binary) => {
+            try {
+                if (binary)
+                    throw new Error("binary_not_supported");
+                const message = JSON.parse(bytes.toString());
+                if (!isHostRecord(message))
+                    throw new Error("invalid_message");
+                if (!ready) {
+                    ready = this.acceptHello(client, token, message);
+                    if (ready)
+                        clearTimeout(helloDeadline);
+                    return;
+                }
+                this.acceptResult(client, message);
+            }
+            catch {
+                client.close(1008, "host_protocol_rejected");
+            }
+        });
+    }
+    acceptHello(client, token, message) {
+        if (message.type !== "hello")
+            throw new Error("hello_required");
+        if (message.version !== 1)
+            throw new Error("protocol_version_mismatch");
+        if (!isHostIdentity(message.identity))
+            throw new Error("host_identity_invalid");
+        const authorization = this.store.authenticate(token);
+        if (authorization === "pairing") {
+            const grant = this.store.consume(token, message.identity);
+            client.send(JSON.stringify({ type: "paired", ...grant }));
+            client.close(1000, "reconnect_with_credential");
+            return false;
+        }
+        if (authorization !== "credential")
+            throw new Error("host_not_authorized");
+        const host = this.store.host();
+        if (message.hostId !== host.hostId)
+            throw new Error("host_identity_mismatch");
+        if (!hasMatchingHostIdentity(host.identity, message.identity))
+            throw new Error("host_identity_mismatch");
+        if (this.client) {
+            client.close(1013, "host_connection_retiring");
+            return false;
+        }
+        this.client = client;
+        this.connectionId = randomUUID();
+        client.send(JSON.stringify({ type: "ready", hostId: host.hostId }));
+        return true;
+    }
+    acceptResult(client, message) {
+        if (this.client !== client)
+            throw new Error("host_connection_superseded");
+        if (message.type !== "result")
+            throw new Error("unexpected_message");
+        if (!isHostIdentifier(message.id))
+            throw new Error("operation_identity_invalid");
+        if (!isHostToolResult(message.result))
+            throw new Error("operation_result_invalid");
+        this.pending.get(message.id)?.finish(message.result);
+    }
+    execute(input) {
+        const host = this.store.host();
+        if (!host)
+            return Promise.resolve(unavailable("No computer is paired."));
+        if (host.hostId !== input.hostId)
+            return Promise.resolve(unavailable("The approved computer is not the paired computer."));
+        const client = this.client;
+        if (client?.readyState !== WebSocket.OPEN)
+            return Promise.resolve(unavailable("The paired computer is disconnected."));
+        if (this.connectionId !== input.connectionId)
+            return Promise.resolve(unavailable("The approved host connection is no longer current."));
+        if (input.abortSignal?.aborted)
+            return Promise.resolve(unavailable("Operation cancelled before host dispatch."));
+        if (this.pending.size >= 16)
+            return Promise.resolve(unavailable("The host connection is at its concurrent operation limit."));
+        const id = randomUUID();
+        return new Promise((resolve) => {
+            const finish = (result) => {
+                if (!this.pending.delete(id))
+                    return;
+                clearTimeout(deadline);
+                input.abortSignal?.removeEventListener("abort", cancel);
+                resolve(attachHostEvidence(result, host.hostId, host.identity));
+            };
+            const cancel = () => {
+                if (client.readyState === WebSocket.OPEN)
+                    client.send(JSON.stringify({ type: "cancel", id }));
+                finish(uncertain());
+            };
+            const deadline = setTimeout(cancel, 610_000);
+            this.pending.set(id, { finish });
+            input.abortSignal?.addEventListener("abort", cancel, { once: true });
+            client.send(JSON.stringify({
+                type: "execute",
+                id,
+                hostId: host.hostId,
+                operation: input.operation,
+                params: input.params,
+            }), (error) => {
+                if (error)
+                    finish(uncertain());
+            });
+        });
+    }
+    disconnect() {
+        for (const operation of this.pending.values())
+            operation.finish(uncertain());
+        this.client = undefined;
+        this.connectionId = undefined;
+        for (const socket of this.sockets)
+            socket.close(1008, "host_disconnected");
+    }
+    close() {
+        for (const operation of this.pending.values())
+            operation.finish(uncertain());
+        this.client = undefined;
+        this.connectionId = undefined;
+        for (const socket of this.sockets) {
+            socket.close(1012, "host_service_restarting");
+            const deadline = setTimeout(() => socket.terminate(), 1000);
+            deadline.unref();
+            socket.once("close", () => clearTimeout(deadline));
+        }
+    }
+}

package/dist/plugins/system/source/companion/liveness.d.ts

@@ -0,0 +1,3 @@
+import WebSocket from "ws";
+/** A half-open transport cannot retain host ownership or report connected forever. */
+export declare function monitorHostLiveness(socket: WebSocket, intervalMs?: number): void;

package/dist/plugins/system/source/companion/liveness.js

@@ -0,0 +1,20 @@
+import WebSocket from "ws";
+/** A half-open transport cannot retain host ownership or report connected forever. */
+export function monitorHostLiveness(socket, intervalMs = 15_000) {
+    let awaitingPong = false;
+    socket.on("pong", () => {
+        awaitingPong = false;
+    });
+    const timer = setInterval(() => {
+        if (socket.readyState !== WebSocket.OPEN)
+            return;
+        if (awaitingPong) {
+            socket.terminate();
+            return;
+        }
+        awaitingPong = true;
+        socket.ping();
+    }, intervalMs);
+    timer.unref();
+    socket.once("close", () => clearInterval(timer));
+}

package/dist/plugins/system/source/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 this exact address at connect. */
+export declare function resolveNativeRuntimeAddress(value: string, resolveHost?: NativeHostResolver): Promise<Readonly<{
+    url: string;
+    address: NativeAddress;
+}>>;

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

@@ -0,0 +1,41 @@
+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;
+}
+/** Resolve once, reject mixed/public answers, then pin this exact address 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();
+    const addresses = hostname === "localhost" || hostname.endsWith(".localhost")
+        ? [{ address: "127.0.0.1", family: 4 }]
+        : await resolveHost(hostname);
+    if (addresses.length === 0)
+        throw new Error("The local Runtime address did not resolve.");
+    if (!addresses.every(({ address }) => isNativeLoopbackAddress(address)))
+        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(), address: addresses[0] };
+}

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

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

package/dist/plugins/system/source/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/plugins/system/source/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/plugins/system/source/companion/native-messages.js

@@ -0,0 +1,77 @@
+import { isNativeCredential } from "./native-state.js";
+import { isHostIdentifier, isHostOperation, 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 (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 (!isHostOperation(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 = {
+    system_targets: [],
+    system_command: ["target", "command", "cwd", "elevated", "timeout_ms"],
+    system_applications: ["target", "query", "limit"],
+    system_launch: ["target", "application_id", "arguments"],
+};
+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/plugins/system/source/companion/native-session.d.ts

@@ -0,0 +1,19 @@
+import type { ToolImplementation } from "../../../../src/plugin-sdk/index.js";
+import { type NativeHostResolver } from "./native-address.js";
+import { type HostIdentity } from "./protocol.js";
+export type NativeSessionOutcome = "disconnected" | "authorization_rejected" | "protocol_rejected" | "stopped";
+export type NativeSessionOptions = Readonly<{
+    url: string;
+    authorization: string;
+    identity: HostIdentity;
+    hostId?: string;
+    signal: AbortSignal;
+    onPaired(hostId: string, credential: string): Promise<void>;
+    onReady(hostId: string): void | Promise<void>;
+    resolveHost?: NativeHostResolver;
+    handlers?: Record<string, ToolImplementation>;
+    heartbeatMs?: number;
+    operationLimit?: number;
+}>;
+/** One connection lifetime. Its pending actions are never retried or replayed. */
+export declare function connectNativeHost(options: NativeSessionOptions): Promise<NativeSessionOutcome>;