Skip to content

Open-source AI coworkers that each get a computer of their own: a browser, files and tools, with every action decided before it happens and recorded after. Bring any AG-UI agent.

14.7 KB
Raw Blame
import { randomUUID } from "node:crypto";
import {
  type ApprovalGate,
  currentApprovalContext,
  type HostCommandPolicy,
} from "../approvals/types";
import {
  HOST_ACCESS_DESKTOP_LEASE_MS,
  type HostAccessDesktopOperation,
  type HostAccessDesktopPollResponse,
  type HostAccessDesktopResult,
  type HostAccessGrant,
  type HostAccessStatus,
} from "./schema";

export class HostAccessRefusedError extends Error {
  constructor(message: string) {
    super(message);
    this.name = "HostAccessRefusedError";
  }
}

type TimerHandle = ReturnType<typeof setTimeout>;

type OperationState = {
  operation: HostAccessDesktopOperation;
  actorId: string;
  botId: string;
  grantId?: string;
  leasedUntil: number | null;
  expiresAt: number | null;
  expiryTimer: TimerHandle | null;
  resolve: (value: unknown) => void;
  reject: (error: Error) => void;
  settled: boolean;
};

type HostAccessBrokerOptions = {
  approvalGate?: ApprovalGate;
  /**
   * The member's command policy after the team cap (the stricter applies): ask every time, always
   * allow, or never. `never` is refused here before anything reaches the computer. `ask` and `allow`
   * are carried to the desktop with the operation; the server's gate (safety requirements, rules,
   * auto-review) still applies to both. Absent means ask.
   */
  commandPolicy?: (actorId: string) => Promise<HostCommandPolicy>;
  desktopLeaseMs?: number;
  operationTtlMs?: number;
};

export type HostAccessBroker = ReturnType<typeof createHostAccessBroker>;

export function createHostAccessBroker(
  now: () => number = Date.now,
  options: HostAccessBrokerOptions = {},
) {
  const desktopLeaseMs = options.desktopLeaseMs ?? HOST_ACCESS_DESKTOP_LEASE_MS;
  const operationTtlMs = options.operationTtlMs ?? 120_000;
  const grants = new Map<string, HostAccessGrant>();
  const operations = new Map<string, OperationState>();
  let desktopConnectedUntil: number | null = null;
  let desktopLeaseTimer: TimerHandle | null = null;

  function unrefTimer(timer: TimerHandle) {
    if (typeof timer === "object" && "unref" in timer) {
      (timer as { unref: () => void }).unref();
    }
  }

  function publicGrant(grant: HostAccessGrant): HostAccessGrant {
    return { ...grant };
  }

  function queueCancelFor(state: OperationState) {
    const cancelOperation: HostAccessDesktopOperation = {
      operationId: randomUUID(),
      targetOperationId: state.operation.operationId,
      kind: "cancel",
      botId: state.botId,
      actorId: state.actorId,
      ...(state.grantId ? { grantId: state.grantId } : {}),
    };
    const cancelState: OperationState = {
      operation: cancelOperation,
      actorId: state.actorId,
      botId: state.botId,
      grantId: state.grantId,
      leasedUntil: null,
      expiresAt: now() + operationTtlMs,
      expiryTimer: null,
      resolve: () => {},
      reject: () => {},
      settled: false,
    };
    // A cancel is addressed to a desktop that may never come back for it, and this map has no
    // other bound on it: nothing but `resolveDesktopOperation` ever removed one, so a worker that
    // did not return left the entry here for the life of the process, growing `operations` by one
    // per abandoned operation and leaving `statusFor` reporting it to the person as pending
    // forever. Expiring on the same clock as any other queued operation keeps the window open
    // long enough for a desktop that reconnects to still be told to stop, and gives up on one that
    // does not. Deleted rather than failed, because a cancel has nobody left to reject.
    cancelState.expiryTimer = setTimeout(() => {
      operations.delete(cancelOperation.operationId);
    }, operationTtlMs);
    unrefTimer(cancelState.expiryTimer);
    operations.set(cancelOperation.operationId, cancelState);
  }

  function queueStopFor(actorId: string) {
    const stopOperation: HostAccessDesktopOperation = {
      operationId: randomUUID(),
      kind: "stop",
      botId: "*",
      actorId,
    };
    const stopState: OperationState = {
      operation: stopOperation,
      actorId,
      botId: stopOperation.botId,
      leasedUntil: null,
      expiresAt: now() + operationTtlMs,
      expiryTimer: null,
      resolve: () => {},
      reject: () => {},
      settled: false,
    };
    // A stop is addressed to a desktop that may never come back for it, for the same reason a
    // cancel is: nothing but `resolveDesktopOperation` ever removed this entry, so a worker that
    // never polled left it here for the life of the process, growing `operations` by one per press
    // of Stop and leaving `statusFor` reporting it to the person as pending for ever. Deleted rather
    // than failed, because a stop has nobody left to reject: it used to be built by `enqueue` and
    // discarded with `void`, so it carried a promise nobody held, and a second Stop failed it
    // through that promise with no handler attached.
    stopState.expiryTimer = setTimeout(() => {
      operations.delete(stopOperation.operationId);
    }, operationTtlMs);
    unrefTimer(stopState.expiryTimer);
    operations.set(stopOperation.operationId, stopState);
  }

  function failOperation(state: OperationState, reason: string) {
    if (state.settled) return;
    state.settled = true;
    if (state.expiryTimer) clearTimeout(state.expiryTimer);
    operations.delete(state.operation.operationId);
    if (state.operation.kind !== "cancel" && state.operation.kind !== "stop") {
      queueCancelFor(state);
    }
    state.reject(new HostAccessRefusedError(reason));
  }

  function expireDesktopLeaseIfNeeded() {
    if (desktopConnectedUntil === null || desktopConnectedUntil > now()) return;
    if (desktopLeaseTimer) {
      clearTimeout(desktopLeaseTimer);
      desktopLeaseTimer = null;
    }
    desktopConnectedUntil = null;
    for (const grant of grants.values()) {
      grant.revoked = true;
    }
    const affected = [...operations.values()].filter(
      (state) =>
        state.operation.kind !== "cancel" && state.operation.kind !== "stop",
    );
    for (const state of affected) {
      failOperation(
        state,
        "The native host worker disconnected before the operation finished.",
      );
    }
  }

  function scheduleDesktopLeaseExpiry() {
    if (desktopLeaseTimer) clearTimeout(desktopLeaseTimer);
    desktopLeaseTimer = setTimeout(() => {
      expireDesktopLeaseIfNeeded();
    }, desktopLeaseMs);
    unrefTimer(desktopLeaseTimer);
  }

  function pendingOperations(actorId?: string): HostAccessDesktopOperation[] {
    return [...operations.values()]
      .filter((state) => !state.settled)
      .filter((state) => !actorId || state.actorId === actorId)
      .map((state) => ({ ...state.operation }));
  }

  function enqueue<T>(operation: HostAccessDesktopOperation): Promise<T> {
    const expiresAt =
      operation.kind === "cancel" || operation.kind === "stop"
        ? null
        : now() + operationTtlMs;
    const operationWithExpiry =
      expiresAt === null ? operation : { ...operation, expiresAt };
    return new Promise<T>((resolve, reject) => {
      const state: OperationState = {
        operation: operationWithExpiry,
        actorId: operation.actorId,
        botId: operation.botId,
        grantId: operation.grantId,
        leasedUntil: null,
        expiresAt,
        expiryTimer: null,
        resolve: resolve as (value: unknown) => void,
        reject,
        settled: false,
      };
      if (expiresAt !== null) {
        state.expiryTimer = setTimeout(() => {
          failOperation(
            state,
            "The native host approval expired before the operation finished.",
          );
        }, operationTtlMs);
        unrefTimer(state.expiryTimer);
      }
      operations.set(operation.operationId, state);
    });
  }

  function requireGrant(input: {
    grantId: string;
    botId: string;
    actorId: string;
  }) {
    const grant = grants.get(input.grantId);
    if (!grant || grant.revoked) {
      throw new HostAccessRefusedError(
        "That folder grant is no longer available.",
      );
    }
    if (grant.botId !== input.botId || grant.actorId !== input.actorId) {
      throw new HostAccessRefusedError(
        "That folder was not granted to this Bot and person.",
      );
    }
    return grant;
  }

  return {
    requestFolderGrant(input: {
      botId: string;
      botName: string;
      actorId: string;
      writable?: boolean;
    }): Promise<HostAccessGrant> {
      expireDesktopLeaseIfNeeded();
      return enqueue<HostAccessGrant>({
        operationId: randomUUID(),
        kind: "choose_folder",
        botId: input.botId,
        botName: input.botName,
        actorId: input.actorId,
        writable: input.writable === true,
      });
    },

    rememberGrant(grant: HostAccessGrant) {
      expireDesktopLeaseIfNeeded();
      grants.set(grant.id, publicGrant(grant));
    },

    async callHost(input: {
      kind: "list_files" | "read_file" | "write_file" | "run_command";
      botId: string;
      actorId: string;
      grantId: string;
      relativePath?: string;
      content?: string;
      command?: string;
      writable?: boolean;
    }): Promise<unknown> {
      expireDesktopLeaseIfNeeded();
      try {
        requireGrant({
          grantId: input.grantId,
          botId: input.botId,
          actorId: input.actorId,
        });
      } catch (error) {
        return Promise.reject(error);
      }
      const grant = requireGrant(input);
      // No await unless something is configured: the operation is then queued synchronously, which
      // is what a desktop poll racing this call relies on.
      const commandPolicy =
        input.kind !== "run_command"
          ? undefined
          : options.commandPolicy
            ? await options.commandPolicy(input.actorId)
            : "ask";
      if (commandPolicy === "never")
        throw new HostAccessRefusedError(
          "Commands on your computer are set to never run, by you or by your team. Change it in Settings → Approvals if you want Bots to run commands here.",
        );
      // Safety requirements, rules and auto-review apply whatever the command policy is.
      const approval =
        options.approvalGate &&
        (await options.approvalGate({
          actorId: input.actorId,
          botId: input.botId,
          toolRef: `host/${input.kind}`,
          effect:
            input.kind === "write_file" || input.kind === "run_command"
              ? "write"
              : "read",
          scope: input.grantId,
          args: input,
          target: {
            grantId: grant.id,
            displayName: grant.displayName,
            relativePath: input.relativePath ?? "",
          },
          continuation: currentApprovalContext(),
        }));
      if (approval && "replay" in approval) return approval.replay;
      // The owner may revoke the grant while approval storage was being consulted.
      requireGrant(input);
      const result = await enqueue<unknown>({
        operationId: randomUUID(),
        kind: input.kind,
        botId: input.botId,
        actorId: input.actorId,
        grantId: input.grantId,
        ...(input.relativePath ? { relativePath: input.relativePath } : {}),
        ...(input.content !== undefined ? { content: input.content } : {}),
        ...(input.command ? { command: input.command } : {}),
        ...(input.writable === true ? { writable: true } : {}),
        ...(commandPolicy ? { commandPolicy } : {}),
      });
      await approval?.complete(result);
      return result;
    },

    nextDesktopOperation(): HostAccessDesktopPollResponse | null {
      expireDesktopLeaseIfNeeded();
      const current = now();
      desktopConnectedUntil = current + desktopLeaseMs;
      scheduleDesktopLeaseExpiry();
      const available = [...operations.values()].find(
        (state) =>
          !state.settled &&
          (state.leasedUntil === null || state.leasedUntil <= current),
      );
      if (!available) return null;
      available.leasedUntil = current + desktopLeaseMs;
      return {
        leaseMs: desktopLeaseMs,
        operations: [{ ...available.operation }],
      };
    },

    resolveDesktopOperation(result: HostAccessDesktopResult) {
      expireDesktopLeaseIfNeeded();
      const state = operations.get(result.operationId);
      if (!state || state.settled) return;
      state.settled = true;
      if (state.expiryTimer) clearTimeout(state.expiryTimer);
      operations.delete(result.operationId);
      if (!result.ok) {
        state.reject(
          new HostAccessRefusedError(
            result.error ?? "The native host operation failed.",
          ),
        );
        return;
      }
      if (state.operation.kind === "choose_folder") {
        if (!result.grant) {
          state.reject(
            new HostAccessRefusedError(
              "The native host did not return a folder grant.",
            ),
          );
          return;
        }
        const grant: HostAccessGrant = {
          id: result.grant.grantId,
          botId: state.botId,
          actorId: state.actorId,
          displayName: result.grant.displayName,
          revoked: false,
        };
        grants.set(grant.id, grant);
        state.resolve(publicGrant(grant));
        return;
      }
      state.resolve(result.result ?? {});
    },

    revokeGrant(grantId: string, actorId: string) {
      expireDesktopLeaseIfNeeded();
      const grant = grants.get(grantId);
      if (!grant || grant.actorId !== actorId) {
        throw new HostAccessRefusedError(
          "That folder grant is not available to revoke.",
        );
      }
      grant.revoked = true;
      const affected = [...operations.values()].filter(
        (state) =>
          state.grantId === grantId && state.operation.kind !== "cancel",
      );
      for (const state of affected) {
        failOperation(
          state,
          "That folder grant was revoked before the operation finished.",
        );
      }
    },

    stop(actorId: string) {
      expireDesktopLeaseIfNeeded();
      for (const grant of grants.values()) {
        if (grant.actorId === actorId) grant.revoked = true;
      }
      const affected = [...operations.values()].filter(
        (state) =>
          state.actorId === actorId &&
          state.operation.kind !== "cancel" &&
          state.operation.kind !== "stop",
      );
      for (const state of affected) {
        failOperation(state, "Host access was stopped.");
      }
      queueStopFor(actorId);
    },

    statusFor(actorId: string): HostAccessStatus {
      expireDesktopLeaseIfNeeded();
      return {
        grants: [...grants.values()]
          .filter((grant) => grant.actorId === actorId)
          .map(publicGrant),
        pending: pendingOperations(actorId),
        connected:
          desktopConnectedUntil !== null && desktopConnectedUntil > now(),
      };
    },
  };
}