@abot-ai/runtime 1.4.0 → 1.5.0

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();
-  });
-}

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

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

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

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

@@ -1,58 +0,0 @@
-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;
-    }
-  }
-}