@abot-ai/runtime 1.4.0 → 1.5.0

package/plugins/system/source/companion/broker-location.ts

@@ -1,89 +0,0 @@
-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";
-
-export type HostBrokerLocation = {
-  ownerId: string;
-  token: string;
-  socketPath: string;
-};
-function brokerRecordPath(rootDir: string): string {
-  return join(hostStateDirectory(rootDir), "broker.json");
-}
-function brokerSocketPath(rootDir: string): string {
-  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: unknown): value is HostBrokerLocation {
-  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: string,
-): HostBrokerLocation | undefined {
-  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: string): HostBrokerLocation {
-  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: string): void {
-  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 as NodeJS.ErrnoException).code !== "ENOENT") throw error;
-  }
-}
-/** Call only after acquiring the installation lease and listener. */
-export function publishBrokerLocation(
-  rootDir: string,
-  owner: HostBrokerLocation,
-): void {
-  writeHostPrivateJson(brokerRecordPath(rootDir), owner);
-}
-/** Release the receipt before the listener, while successors cannot acquire it. */
-export function releaseBrokerLocation(
-  rootDir: string,
-  owner: HostBrokerLocation,
-): void {
-  const current = readBrokerLocation(rootDir);
-  if (current?.ownerId !== owner.ownerId) return;
-  unlinkSync(brokerRecordPath(rootDir));
-}

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

@@ -1,169 +0,0 @@
-import { createHash, timingSafeEqual } from "node:crypto";
-import { createServer, type Server, type Socket } from "node:net";
-import type { HostConnection } from "./connection.js";
-import {
-  createBrokerLocation,
-  publishBrokerLocation,
-  releaseBrokerLocation,
-} from "./broker-location.js";
-import {
-  HOST_WIRE_MAX_BYTES,
-  isHostIdentifier,
-  isHostOperation,
-  isHostRecord,
-} from "./protocol.js";
-
-function hasBrokerAuthorization(
-  input: Record<string, unknown>,
-  token: string,
-): boolean {
-  if (typeof input.token !== "string") return false;
-  const digest = (text: string) => createHash("sha256").update(text).digest();
-  return timingSafeEqual(digest(input.token), digest(token));
-}
-function brokerFailure(error: string) {
-  return { ok: false, error };
-}
-async function dispatchBrokerRequest(
-  input: unknown,
-  connection: HostConnection,
-  token: string,
-  signal: AbortSignal,
-): Promise<unknown> {
-  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: Socket,
-  connection: HostConnection,
-  token: string,
-): void {
-  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: Buffer) => {
-    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: unknown;
-    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: string,
-  connection: HostConnection,
-  acquireOwnership: () => Promise<() => Promise<void>>,
-): Promise<{ close(): Promise<void> }> {
-  const releaseOwnership = await acquireOwnership();
-  let owner: ReturnType<typeof createBrokerLocation>;
-  try {
-    owner = createBrokerLocation(rootDir);
-  } catch (error) {
-    await releaseOwnership();
-    throw error;
-  }
-  const sockets = new Set<Socket>();
-  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<void>((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: Promise<void> | undefined;
-  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: Server): Promise<void> {
-  if (!server.listening) return;
-  await new Promise<void>((resolve, reject) =>
-    server.close((error) => (error ? reject(error) : resolve())),
-  );
-}

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.",
-    );
-}