Skip to content

armgit / qm

Public Imported from GitHub
0

Multiplayer agent harness for work.

11.7 KB
Raw Blame
import { randomUUID } from "node:crypto";
import { isTerminal } from "../../runs/run-store.ts";
import { waitForClientResult } from "../../runs/run-signal-store.ts";
import type { UiSignal } from "../../runs/session-state-bus.ts";
import {
  readUiCanvas,
  uiObserveKey,
  UiCanvasTooLargeError,
  ALWAYS_ON_CANVAS,
  writeUiCanvas,
  type UiCanvas,
  type UiCanvasPatch,
} from "../../surfaces/ui-canvas.ts";
import { uiStateId, UI_STATE_MAX_BYTES } from "../../surfaces/ui-state.ts";
import { scopeId } from "../../types.ts";
import { sendJson } from "../http.ts";
import { conversationRef } from "./pins.ts";
import { samePerson } from "../../directory/person.ts";
import { audit, isObj } from "./shared.ts";
import { swallow } from "../../util/errors.ts";
import type { ApiCtx, Route } from "./route.ts";

const OBSERVE_TIMEOUT_MS = 15_000;
const MAX_SELECTOR_CHARS = 500;

interface UiTurn {
  actorId: string;
  sessionId: string;
  threadRef: string;
  runId: string;
  personal: boolean;
}

async function liveWebTurn(ctx: ApiCtx): Promise<UiTurn | null> {
  const { res, deps } = ctx;
  const threadRef = await conversationRef(ctx);
  if (!threadRef) return null;
  const cap = ctx.capability!;
  if (!deps.uiState || !deps.runs || !deps.sessions) {
    sendJson(res, 404, { error: "not_available", message: "this deployment has no UI state store" });
    return null;
  }
  if ((await deps.featureFlags?.enabled("ui_canvas", scopeId("personal", cap.actorId))) !== true) {
    sendJson(res, 403, {
      error: "feature_disabled",
      message: "The ui_canvas feature flag is off for this person. An org admin can enable it under feature flags.",
    });
    return null;
  }
  if (cap.surface !== "web" || !cap.liveActor || cap.triggered || cap.botActor) {
    sendJson(res, 403, {
      error: "not_live_web_turn",
      message: "Only available during a turn the person started from the web UI.",
    });
    return null;
  }
  const run = cap.runId ? await deps.runs.get(cap.runId) : null;
  if (!run || isTerminal(run.status)) {
    sendJson(res, 409, { error: "turn_ended", message: "The turn that issued this token has ended." });
    return null;
  }
  const session = await deps.sessions.getByThread(threadRef);
  if (!session) {
    sendJson(res, 404, { error: "not_found", message: "no such conversation" });
    return null;
  }
  return {
    actorId: cap.actorId,
    sessionId: session.id,
    threadRef,
    runId: run.id,
    personal: cap.scopeId === scopeId("personal", cap.actorId),
  };
}

function signalBrowser(ctx: ApiCtx, turn: Pick<UiTurn, "actorId" | "sessionId" | "threadRef">, ui: UiSignal): void {
  ctx.deps.sessionStateBus?.emit({
    threadRef: turn.threadRef,
    sessionId: turn.sessionId,
    participants: [turn.actorId],
    state: "ui",
    at: Date.now(),
    ui,
  });
}

function canvasSummary(canvas: UiCanvas | null): Record<string, unknown> | null {
  if (!canvas) return null;
  return {
    rev: canvas.rev,
    pinned: canvas.pinned,
    bytes: { html: canvas.html.length, css: canvas.css.length, js: canvas.js.length },
  };
}

function flag(ctx: ApiCtx, name: string): boolean {
  const b = isObj(ctx.body) ? ctx.body : {};
  const q = ctx.url.searchParams.get(name);
  return b[name] === true || q === "true" || q === "1";
}

function canvasTarget(ctx: ApiCtx, turn: Pick<UiTurn, "sessionId">): string {
  return flag(ctx, "alwaysOn") ? ALWAYS_ON_CANVAS : turn.sessionId;
}

async function getCanvas(ctx: ApiCtx): Promise<void> {
  const turn = await liveWebTurn(ctx);
  if (!turn) return;
  return sendJson(ctx.res, 200, {
    canvas: await readUiCanvas(ctx.deps.uiState!, turn.actorId, canvasTarget(ctx, turn)),
  });
}

function parsePatch(body: unknown): UiCanvasPatch | string {
  const b = isObj(body) ? body : {};
  const patch: UiCanvasPatch = {};
  for (const field of ["html", "css", "js"] as const) {
    if (b[field] === undefined) continue;
    if (typeof b[field] !== "string") return `${field} must be a string`;
    patch[field] = b[field];
  }
  for (const field of ["pinned", "replace"] as const) {
    if (b[field] === undefined) continue;
    if (typeof b[field] !== "boolean") return `${field} must be a boolean`;
    patch[field] = b[field];
  }
  if (Object.keys(patch).length === 0) return "pass html, css, js, pinned, or replace";
  return patch;
}

async function applyCanvas(
  ctx: ApiCtx,
  turn: Pick<UiTurn, "actorId" | "sessionId" | "threadRef">,
  patch: UiCanvasPatch | null,
): Promise<void> {
  const target = canvasTarget(ctx, turn);
  let canvas: UiCanvas | null;
  try {
    canvas = await writeUiCanvas(ctx.deps.uiState!, turn.actorId, target, patch);
  } catch (error) {
    if (!(error instanceof UiCanvasTooLargeError)) throw error;
    return sendJson(ctx.res, 413, {
      error: "payload_too_large",
      message: `html, css and js together must stay under ${UI_STATE_MAX_BYTES} bytes`,
    });
  }
  if (patch && !canvas)
    return sendJson(ctx.res, 404, { error: "no_canvas", message: "there is no canvas yet; pass html, css or js" });
  audit(ctx.deps, {
    principalId: turn.actorId,
    action: patch ? "ui.canvas.write" : "ui.canvas.dismiss",
    resource: target === ALWAYS_ON_CANVAS ? "ui:always-on" : `session:${turn.sessionId}`,
    scopeLabel: scopeId("personal", turn.actorId),
    ...(canvas ? { detail: `rev ${canvas.rev}` } : {}),
  });
  signalBrowser(ctx, turn, { kind: "canvas" });
  return sendJson(ctx.res, 200, { canvas: canvasSummary(canvas) });
}

async function postCanvas(ctx: ApiCtx): Promise<void> {
  const turn = await liveWebTurn(ctx);
  if (!turn) return;
  const patch = parsePatch(ctx.body);
  if (typeof patch === "string") return sendJson(ctx.res, 400, { error: "bad_request", message: patch });
  return applyCanvas(ctx, turn, patch);
}

async function deleteCanvas(ctx: ApiCtx): Promise<void> {
  const turn = await liveWebTurn(ctx);
  if (!turn) return;
  return applyCanvas(ctx, turn, null);
}

async function observe(ctx: ApiCtx): Promise<void> {
  const { res, deps, body } = ctx;
  const turn = await liveWebTurn(ctx);
  if (!turn) return;
  if (!turn.personal) {
    return sendJson(res, 403, {
      error: "not_private",
      message: "UI observation is only available in the person's own web conversations, not shared ones.",
    });
  }
  if (!deps.signals) return sendJson(res, 404, { error: "not_available", message: "run signals are unavailable" });
  const b = isObj(body) ? body : {};
  const selector = typeof b.selector === "string" && b.selector.trim() ? b.selector.trim() : undefined;
  if (selector && selector.length > MAX_SELECTOR_CHARS)
    return sendJson(res, 400, { error: "bad_request", message: "selector is too long" });
  const callId = randomUUID();
  const pendingId = uiStateId(turn.actorId, uiObserveKey(callId));
  await deps.uiState!.put(pendingId, { value: { runId: turn.runId }, updatedAt: Date.now() });
  signalBrowser(ctx, turn, {
    kind: "observe",
    callId,
    ...(selector ? { selector } : {}),
    ...(b.css === true ? { css: true } : {}),
    ...(b.screenshot === true ? { screenshot: true } : {}),
  });
  let outcome: Awaited<ReturnType<typeof waitForClientResult>>;
  try {
    outcome = await waitForClientResult(deps.signals, turn.runId, callId, { timeoutMs: OBSERVE_TIMEOUT_MS });
  } finally {
    await deps.uiState!.delete(pendingId).catch((error: unknown) => swallow("ui observe pending cleanup", error));
  }
  audit(deps, {
    principalId: turn.actorId,
    action: "ui.observe",
    resource: `session:${turn.sessionId}`,
    scopeLabel: scopeId("personal", turn.actorId),
    status: typeof outcome === "string" ? outcome : "ok",
  });
  if (typeof outcome === "string") {
    return sendJson(res, 504, {
      error: "ui_not_open",
      message: `No open web UI tab answered within ${OBSERVE_TIMEOUT_MS / 1000}s. The person may have closed QM; ask them to open it and retry.`,
    });
  }
  return sendJson(res, 200, { snapshot: outcome.structured ?? null });
}

async function observeResult(ctx: ApiCtx): Promise<void> {
  const { res, deps, body, params } = ctx;
  const b = isObj(body) ? body : {};
  const principalId = typeof b.principalId === "string" ? b.principalId : "";
  if (!principalId || !isObj(b.snapshot))
    return sendJson(res, 400, { error: "bad_request", message: "principalId and snapshot required" });
  if (!deps.uiState || !deps.signals) return sendJson(res, 404, { error: "not_found" });
  const pending = await deps.uiState.take(uiStateId(principalId, uiObserveKey(params.callId!)));
  const runId = isObj(pending?.value) && typeof pending.value.runId === "string" ? pending.value.runId : null;
  const run = runId ? await deps.runs?.get(runId) : null;
  if (!run || !samePerson(run.request.actor.id, principalId)) return sendJson(res, 404, { error: "not_found" });
  await deps.signals.send(run.id, {
    kind: "client_result",
    callId: params.callId!,
    result: { content: "web UI snapshot", structured: b.snapshot },
    dedupeKey: `ui-observe:${run.id}:${params.callId}`,
  });
  return sendJson(res, 200, { ok: true });
}

async function canvasEnabled(ctx: ApiCtx, principalId: string): Promise<boolean> {
  return (await ctx.deps.featureFlags?.enabled("ui_canvas", scopeId("personal", principalId))) === true;
}

async function isCanvasTarget(ctx: ApiCtx, target: string): Promise<boolean> {
  return target === ALWAYS_ON_CANVAS || Boolean(await ctx.deps.sessions?.get(target));
}

async function userCanvasContent(ctx: ApiCtx): Promise<void> {
  const { res, deps, url, params } = ctx;
  const principalId = url.searchParams.get("principalId") ?? "";
  if (!principalId || !(await isCanvasTarget(ctx, params.sessionId!)))
    return sendJson(res, 400, { error: "bad_request", message: "principalId and a session id required" });
  if (!deps.uiState || !(await canvasEnabled(ctx, principalId))) return sendJson(res, 404, { error: "not_found" });
  const canvas = await readUiCanvas(deps.uiState, principalId, params.sessionId!);
  return canvas ? sendJson(res, 200, { canvas }) : sendJson(res, 404, { error: "not_found" });
}

async function userCanvas(ctx: ApiCtx): Promise<void> {
  const { res, deps, body, params } = ctx;
  const b = isObj(body) ? body : {};
  const principalId = typeof b.principalId === "string" ? b.principalId : "";
  const sessionId = params.sessionId!;
  if (!principalId || !(await isCanvasTarget(ctx, sessionId)))
    return sendJson(res, 400, { error: "bad_request", message: "principalId and a session id required" });
  if (!deps.uiState || !(await canvasEnabled(ctx, principalId))) return sendJson(res, 404, { error: "not_found" });
  if (b.dismiss !== true && typeof b.pinned !== "boolean")
    return sendJson(res, 400, { error: "bad_request", message: "pass dismiss or pinned" });
  const patch = b.dismiss === true ? null : { pinned: b.pinned as boolean };
  const canvas = await writeUiCanvas(deps.uiState, principalId, sessionId, patch);
  if (patch && !canvas) return sendJson(res, 404, { error: "not_found" });
  const session = await deps.sessions?.get(sessionId);
  if (session)
    signalBrowser(ctx, { actorId: principalId, sessionId, threadRef: session.threadRef }, { kind: "canvas" });
  return sendJson(res, 200, { canvas: canvasSummary(canvas) });
}

export const uiCanvasRoutes: ReadonlyArray<Route<ApiCtx>> = [
  { method: "GET", path: "/v1/ui/canvas", auth: "either", handle: getCanvas },
  { method: "POST", path: "/v1/ui/canvas", auth: "either", handle: postCanvas },
  { method: "DELETE", path: "/v1/ui/canvas", auth: "either", handle: deleteCanvas },
  { method: "POST", path: "/v1/ui/observe", auth: "either", handle: observe },
  {
    method: "POST",
    path: "/v1/ui/observe/:callId/result",
    auth: "source",
    maxBodyBytes: 2_000_000,
    handle: observeResult,
  },
  { method: "GET", path: "/v1/ui/canvases/:sessionId", auth: "source", handle: userCanvasContent },
  { method: "POST", path: "/v1/ui/canvases/:sessionId", auth: "source", handle: userCanvas },
];