@abot-ai/runtime 1.3.1 → 1.4.0

package/plugins/system/source/companion/native-session.ts

@@ -0,0 +1,268 @@
+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();
+  });
+}

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

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

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

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

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

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

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

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