@abot-ai/runtime 1.3.1 → 1.4.0

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

@@ -0,0 +1,89 @@
+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

@@ -0,0 +1,169 @@
+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

@@ -0,0 +1,211 @@
+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

@@ -0,0 +1,23 @@
+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

@@ -0,0 +1,55 @@
+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

@@ -0,0 +1,26 @@
+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

@@ -0,0 +1,100 @@
+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.",
+    );
+}