@abot-ai/runtime 1.4.0 → 1.6.0

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

@@ -1,211 +0,0 @@
-import { randomUUID } from "node:crypto";
-import WebSocket from "ws";
-import {
-  failureResult,
-  type ToolImplementationOutput,
-} from "../../../../src/plugin-sdk/index.js";
-import { attachHostEvidence } from "../host-evidence.js";
-import {
-  hasMatchingHostIdentity,
-  isHostIdentifier,
-  isHostIdentity,
-  isHostRecord,
-  isHostToolResult,
-  type HostOperation,
-  type HostStatus,
-} from "./protocol.js";
-import { HostPairingStore } from "./pairing-store.js";
-import { monitorHostLiveness } from "./liveness.js";
-
-function unavailable(message: string) {
-  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 {
-  private client?: WebSocket;
-  private connectionId?: string;
-  private readonly sockets = new Set<WebSocket>();
-  private readonly pending = new Map<
-    string,
-    { finish(result: ToolImplementationOutput): void }
-  >();
-  constructor(private readonly store: HostPairingStore) {}
-  status(): HostStatus {
-    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: WebSocket, token: string): void {
-    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()) as unknown;
-        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");
-      }
-    });
-  }
-  private acceptHello(
-    client: WebSocket,
-    token: string,
-    message: Record<string, unknown>,
-  ): boolean {
-    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;
-  }
-  private acceptResult(
-    client: WebSocket,
-    message: Record<string, unknown>,
-  ): void {
-    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: {
-    hostId: string;
-    connectionId: string;
-    operation: HostOperation;
-    params: Record<string, unknown>;
-    abortSignal?: AbortSignal;
-  }): Promise<ToolImplementationOutput> {
-    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: ToolImplementationOutput) => {
-        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(): void {
-    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(): void {
-    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/plugins/system/source/companion/liveness.ts

@@ -1,23 +0,0 @@
-import WebSocket from "ws";
-
-/** A half-open transport cannot retain host ownership or report connected forever. */
-export function monitorHostLiveness(
-  socket: WebSocket,
-  intervalMs = 15_000,
-): void {
-  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/plugins/system/source/companion/native-address.ts

@@ -1,55 +0,0 @@
-import { lookup as lookupHost } from "node:dns/promises";
-import { isIP } from "node:net";
-import { HOST_SOCKET_PATH } from "./protocol.js";
-
-export type NativeAddress = Readonly<{ address: string; family: number }>;
-export type NativeHostResolver = (
-  hostname: string,
-) => Promise<readonly NativeAddress[]>;
-
-export function isNativeLoopbackAddress(value: string): boolean {
-  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: string): string {
-  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: string,
-  resolveHost: NativeHostResolver = (hostname) =>
-    lookupHost(hostname, { all: true }),
-): Promise<Readonly<{ url: string; address: NativeAddress }>> {
-  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/plugins/system/source/companion/native-identity.ts

@@ -1,26 +0,0 @@
-import { homedir, hostname, userInfo } from "node:os";
-import { isHostIdentity, type HostIdentity } from "./protocol.js";
-
-export function readNativeHostIdentity(): HostIdentity {
-  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: NodeJS.Platform): HostIdentity["os"] {
-  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/plugins/system/source/companion/native-messages.ts

@@ -1,100 +0,0 @@
-import { isNativeCredential } from "./native-state.js";
-import {
-  isHostIdentifier,
-  isHostOperation,
-  isHostRecord,
-  type HostServerMessage,
-} from "./protocol.js";
-
-function hasOnlyFields(
-  value: Record<string, unknown>,
-  fields: readonly string[],
-): boolean {
-  return Object.keys(value).every((key) => fields.includes(key));
-}
-
-export function readNativeServerMessage(text: string): HostServerMessage {
-  const value: unknown = 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"],
-} as const;
-
-export class NativeOperationInputError extends Error {
-  constructor(
-    readonly code: string,
-    message: string,
-  ) {
-    super(message);
-  }
-}
-
-export function assertNativeOperationTarget(
-  message: Extract<HostServerMessage, { type: "execute" }>,
-  os: string,
-): void {
-  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/plugins/system/source/companion/native-session.ts

@@ -1,268 +0,0 @@
-import WebSocket from "ws";
-import type {
-  ToolImplementation,
-  ToolImplementationOutput,
-} from "../../../../src/plugin-sdk/index.js";
-import { createSystemHandlers } from "../handlers.js";
-import {
-  resolveNativeRuntimeAddress,
-  type NativeHostResolver,
-} from "./native-address.js";
-import {
-  assertNativeOperationTarget,
-  NativeOperationInputError,
-  readNativeServerMessage,
-} from "./native-messages.js";
-import {
-  HOST_PROTOCOL_VERSION,
-  HOST_WIRE_MAX_BYTES,
-  type HostIdentity,
-  type HostServerMessage,
-} 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;
-}>;
-
-function operationFailure(
-  message: string,
-  code: string,
-): ToolImplementationOutput {
-  return {
-    ok: false,
-    output: message,
-    errorCode: code,
-    producedNewInformation: false,
-  };
-}
-
-function hasHeaderSafeAuthorization(value: string): boolean {
-  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: NativeSessionOptions,
-): Promise<NativeSessionOutcome> {
-  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<string, AbortController>();
-    const seen = new Set<string>();
-    let hostId = options.hostId;
-    let ready = false;
-    let stopped = false;
-    let retiring = false;
-    let outcome: NativeSessionOutcome = "disconnected";
-    let incoming = Promise.resolve();
-    let awaitingPong = false;
-    let retirement: ReturnType<typeof setTimeout> | undefined;
-    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: NativeSessionOutcome): void {
-      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: unknown): void {
-      if (stopped || socket.readyState !== WebSocket.OPEN) return;
-      socket.send(JSON.stringify(value));
-    }
-    function sendResult(id: string, result: ToolImplementationOutput): void {
-      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: string): void {
-      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: Extract<HostServerMessage, { type: "execute" }>,
-    ): void {
-      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: string): Promise<void> {
-      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();
-  });
-}