Skip to content

armgit / qm

Public Imported from GitHub
0

Multiplayer agent harness for work.

13.4 KB
Raw Blame
import { fromJSONSchema, z, ZodObject } from "zod";
import type { ClientToolDeclaration, TurnOrigin, TurnRequest } from "../../types.ts";
import { resolveTurnOrigin } from "../../core/turn-origin.ts";
import { samePerson } from "../../directory/person.ts";
import { sendJson } from "../http.ts";
import { isObj } from "./shared.ts";
import { type ApiCtx, type Route } from "./route.ts";

function isTurnRequest(body: unknown): body is TurnRequest {
  return (
    isObj(body) &&
    typeof body.text === "string" &&
    isObj(body.actor) &&
    typeof body.actor.externalId === "string" &&
    body.actor.externalId !== "" &&
    isObj(body.conversation)
  );
}

const MAX_CLIENT_TOOL_SCHEMA_CHARS = 16_000;

function convertsToObjectSchema(schema: Record<string, unknown>): boolean {
  try {
    return fromJSONSchema(schema as Parameters<typeof fromJSONSchema>[0]) instanceof ZodObject;
  } catch {
    return false;
  }
}

const clientToolInputSchema = z
  .looseObject({
    type: z.literal("object"),
    properties: z.record(z.string(), z.unknown()).optional(),
    required: z.array(z.string()).optional(),
  })
  .refine((schema) => JSON.stringify(schema).length <= MAX_CLIENT_TOOL_SCHEMA_CHARS, {
    message: `must be at most ${MAX_CLIENT_TOOL_SCHEMA_CHARS} characters of JSON`,
    abort: true,
  })
  .refine(convertsToObjectSchema, { message: "must convert to a plain object schema" });

const clientToolsSchema = z
  .array(
    z.object({
      name: z.string().regex(/^ui__[a-z0-9_]{1,60}$/),
      description: z
        .string()
        .max(2_000)
        .refine((description) => description.trim() !== "", { message: "must not be blank" }),
      inputSchema: clientToolInputSchema,
      timeoutMs: z.int().min(1_000).max(60_000).optional(),
    }),
  )
  .max(32)
  .refine((tools) => new Set(tools.map((tool) => tool.name)).size === tools.length, {
    message: "names must be unique",
  });

const clientResultSchema = z.object({
  callId: z.string().min(1).max(256),
  result: z.object({
    content: z.string(),
    structured: z.unknown().optional(),
    isError: z.boolean().optional(),
    images: z
      .array(
        z.object({
          data: z.string().max(4_000_000).base64(),
          mimeType: z.enum(["image/png", "image/jpeg"]),
        }),
      )
      .max(4)
      .optional(),
  }),
});

function zodMessage(field: string, error: z.ZodError): string {
  const issue = error.issues[0]!;
  return `${[field, ...issue.path.map(String)].join(".")}: ${issue.message}`;
}

function publicOrigin(origin: TurnOrigin | undefined): TurnOrigin | undefined {
  if (origin?.kind !== "automation") return origin;
  const { useOwnerKeychain: _internalOnly, ...safe } = origin;
  return safe;
}

function publicTurnOrigin(body: TurnRequest): { origin?: TurnOrigin; error?: string } {
  const typed = publicOrigin(body.origin);
  if (
    typed?.kind === "automation" &&
    body.triggered === true &&
    typed.screenData !== undefined &&
    body.securityScreenData !== undefined &&
    typed.screenData !== body.securityScreenData
  ) {
    return { error: "conflicting typed and legacy automation screen data" };
  }
  return { origin: resolveTurnOrigin({ ...body, ...(typed ? { origin: typed } : { origin: undefined }) }) };
}

function sanitizedTurnRequest(body: TurnRequest): { request: TurnRequest } | { error: string } {
  const {
    slackSource: _slackSource,
    externalSlack: _externalSlack,
    ownerKeychainUnion: _ownerKeychainUnion,
    spawned: _spawned,
    unattendedGrants: _unattendedGrants,
    redeliveryKey: _redeliveryKey,
    ...safeBody
  } = body;
  if (typeof safeBody.idempotencyKey === "string" && safeBody.idempotencyKey.startsWith("slack:"))
    return { error: "idempotencyKey must not use the reserved slack: prefix" };
  const resolvedOrigin = publicTurnOrigin(safeBody);
  if (resolvedOrigin.error) return { error: resolvedOrigin.error };
  const origin = resolvedOrigin.origin;
  const { clientTools: rawClientTools, ...rest } = safeBody;
  if (rest.desktopClientId !== undefined && !z.uuid().safeParse(rest.desktopClientId).success)
    return { error: "desktopClientId must be a UUID" };
  let clientTools: ClientToolDeclaration[] | undefined;
  if (rawClientTools !== undefined) {
    const parsed = clientToolsSchema.safeParse(rawClientTools);
    if (!parsed.success) return { error: zodMessage("clientTools", parsed.error) };
    clientTools = parsed.data;
  }
  return { request: { ...rest, ...(origin ? { origin } : {}), ...(clientTools?.length ? { clientTools } : {}) } };
}

async function postTurn(ctx: ApiCtx): Promise<void> {
  const { res, app, url, body } = ctx;
  if (!isTurnRequest(body)) {
    return sendJson(res, 400, { error: "bad_request", message: "expected a TurnRequest" });
  }
  const wantAsync = url.searchParams.get("async") === "1" || body.async === true;
  const sanitized = sanitizedTurnRequest(body);
  if ("error" in sanitized) return sendJson(res, 400, { error: "bad_request", message: sanitized.error });
  const result = await app.turn({ ...sanitized.request, async: wantAsync });
  if (result.status === "queued") return sendJson(res, 202, result);
  const status = result.status === "refused" ? 403 : 200;
  return sendJson(res, status, result);
}

async function getApproval(ctx: ApiCtx): Promise<void> {
  const { res, app, actor } = ctx;
  const id = ctx.params.id!;
  if (!id || id.includes("/")) return sendJson(res, 404, { error: "not_found" });
  const record = await app.getApproval(id, actor?.p);
  return record ? sendJson(res, 200, record) : sendJson(res, 404, { error: "not_found" });
}

async function getPendingApproval(ctx: ApiCtx): Promise<void> {
  const { res, app, url, actor } = ctx;
  const threadRef = url.searchParams.get("threadRef") ?? "";
  if (!threadRef) return sendJson(res, 400, { error: "bad_request", message: "threadRef required" });
  return sendJson(res, 200, { pending: await app.pendingApprovalForThread(threadRef, actor?.p) });
}

async function postRunDeliveryState(ctx: ApiCtx): Promise<void> {
  const { res, app, body } = ctx;
  const id = ctx.params.id!;
  const editRef = isObj(body) && typeof body.editRef === "string" ? body.editRef : "";
  if (!id || !editRef) return sendJson(res, 400, { error: "bad_request", message: "editRef required" });
  const found = await app.setRunDeliveryState(id, { editRef });
  if (!found) return sendJson(res, 404, { error: "not_found" });
  return sendJson(res, 200, { ok: true });
}

async function postRunSignal(ctx: ApiCtx): Promise<void> {
  const { res, app, body, actor } = ctx;
  const id = ctx.params.id!;
  const kind = isObj(body) && typeof body.kind === "string" ? body.kind : "";
  if (kind !== "abort" && kind !== "steer" && kind !== "client_result") {
    return sendJson(res, 400, { error: "bad_request", message: "kind must be abort, steer or client_result" });
  }
  if (kind === "client_result") {
    const run = await ctx.deps.runs?.get(id);
    if (run?.request.desktopClientId && (!isObj(body) || body.desktopClientId !== run.request.desktopClientId))
      return sendJson(res, 403, { error: "wrong_desktop_client" });
    const parsed = clientResultSchema.safeParse(body);
    if (!parsed.success)
      return sendJson(res, 400, { error: "bad_request", message: zodMessage("client_result", parsed.error) });
    const outcome = await app.signalRun(id, { kind, ...parsed.data }, actor?.p);
    if (outcome.accepted) return sendJson(res, 200, outcome);
    if (outcome.reason === "not_found") return sendJson(res, 404, { error: "not_found" });
    return sendJson(res, 409, outcome);
  }
  const text = isObj(body) && typeof body.text === "string" ? body.text : undefined;
  const queuedRunId = isObj(body) && typeof body.queuedRunId === "string" ? body.queuedRunId : undefined;
  const ts = isObj(body) && typeof body.ts === "string" && body.ts ? body.ts : undefined;
  let request: TurnRequest | undefined;
  if (isObj(body) && body.request !== undefined) {
    if (!isTurnRequest(body.request)) {
      return sendJson(res, 400, { error: "bad_request", message: "request must be a TurnRequest" });
    }
    if (actor && !samePerson(body.request.actor.externalId, actor.p)) {
      return sendJson(res, 403, { error: "forbidden", message: "portal identity does not match the requested actor" });
    }
    const sanitized = sanitizedTurnRequest(body.request);
    if ("error" in sanitized) return sendJson(res, 400, { error: "bad_request", message: sanitized.error });
    request = sanitized.request;
  }
  const outcome = await app.signalRun(
    id,
    {
      kind,
      ...(text !== undefined ? { text } : {}),
      ...(ts ? { ts } : {}),
      ...(request ? { request } : {}),
      ...(queuedRunId ? { queuedRunId } : {}),
    },
    actor?.p,
  );
  if (outcome.accepted) return sendJson(res, 200, outcome);
  if (outcome.reason === "not_found") return sendJson(res, 404, { error: "not_found" });
  if (outcome.reason === "text_required")
    return sendJson(res, 400, { error: "bad_request", message: "text required", ...outcome });
  if (outcome.reason === "conversation_mismatch")
    return sendJson(res, 400, {
      error: "bad_request",
      message: "request conversation does not match the run",
      ...outcome,
    });
  return sendJson(res, 409, outcome);
}

async function getRun(ctx: ApiCtx): Promise<void> {
  const { res, app, actor } = ctx;
  const id = ctx.params.id!;
  const run = await app.getRun(id, actor?.p);
  if (!run) return sendJson(res, 404, { error: "not_found" });
  return sendJson(res, 200, run);
}

async function getActiveRunForThread(ctx: ApiCtx): Promise<void> {
  const { res, app, url, actor } = ctx;
  const threadRef = url.searchParams.get("threadRef") ?? "";
  if (!threadRef) return sendJson(res, 400, { error: "bad_request", message: "threadRef required" });
  const active = await app.activeRunForThread(threadRef, actor?.p);
  return sendJson(res, 200, { runId: active?.runId ?? null, ...(active?.queued ? { queued: active.queued } : {}) });
}

async function patchQueuedRun(ctx: ApiCtx): Promise<void> {
  const { res, app, actor, body } = ctx;
  if (!isObj(body) || typeof body.text !== "string" || typeof body.expectedText !== "string")
    return sendJson(res, 400, { error: "bad_request", message: "text and expectedText required" });
  const outcome = await app.editQueuedRun(ctx.params.id!, body.text, body.expectedText, actor?.p);
  if (outcome.edited) return sendJson(res, 200, outcome);
  if (outcome.reason === "not_found") return sendJson(res, 404, { error: "not_found" });
  return sendJson(res, outcome.reason === "empty_text" ? 400 : 409, outcome);
}

async function postRunWithdraw(ctx: ApiCtx): Promise<void> {
  const { res, app, actor } = ctx;
  const outcome = await app.withdrawRun(ctx.params.id!, actor?.p);
  if (outcome.withdrawn) return sendJson(res, 200, outcome);
  if (outcome.reason === "not_found") return sendJson(res, 404, { error: "not_found" });
  return sendJson(res, 409, outcome);
}

async function listDeliveries(ctx: ApiCtx): Promise<void> {
  const { res, app, url } = ctx;
  const type = url.searchParams.get("type") ?? "";
  const claimMsRaw = Number(url.searchParams.get("claimMs") ?? 0);
  const claimMs = Number.isFinite(claimMsRaw) && claimMsRaw > 0 ? claimMsRaw : 0;
  return sendJson(res, 200, { deliveries: await app.pendingDeliveries(type, claimMs) });
}

async function ackDelivery(ctx: ApiCtx): Promise<void> {
  const { res, app, body } = ctx;
  const id = ctx.params.id!;
  const recipientThreadRef =
    isObj(body) && typeof body.recipientThreadRef === "string" ? body.recipientThreadRef : undefined;
  const slackApiMs =
    isObj(body) && typeof body.slackApiMs === "number" && Number.isFinite(body.slackApiMs) && body.slackApiMs >= 0
      ? body.slackApiMs
      : undefined;
  if (recipientThreadRef) await app.recordPrincipalDelivery(id, recipientThreadRef);
  await app.ackDelivery(id, slackApiMs);
  return sendJson(res, 200, { ok: true });
}

async function ackDeliveryByKey(ctx: ApiCtx): Promise<void> {
  const { res, app, body } = ctx;
  const idempotencyKey = isObj(body) && typeof body.idempotencyKey === "string" ? body.idempotencyKey : "";
  if (!idempotencyKey) return sendJson(res, 400, { error: "bad_request", message: "idempotencyKey required" });
  await app.ackDeliveryByKey(idempotencyKey);
  return sendJson(res, 200, { ok: true });
}

export const turnRoutes: ReadonlyArray<Route<ApiCtx>> = [
  { method: "POST", path: "/v1/turns", actor: "system", auth: "source", handle: postTurn },
  { method: "GET", path: "/v1/approvals/pending", actor: "person", auth: "source", handle: getPendingApproval },
  { method: "GET", path: "/v1/approvals/:id", actor: "person", auth: "source", handle: getApproval },
  {
    method: "POST",
    path: "/v1/runs/:id/delivery-state",
    actor: "system",
    auth: "source",
    handle: postRunDeliveryState,
  },
  { method: "POST", path: "/v1/runs/:id/signal", auth: "source", maxBodyBytes: 6_000_000, handle: postRunSignal },
  { method: "PATCH", path: "/v1/runs/:id/input", auth: "source", handle: patchQueuedRun },
  { method: "POST", path: "/v1/runs/:id/withdraw", auth: "source", handle: postRunWithdraw },
  { method: "GET", path: "/v1/runs/:id", actor: "person", auth: "source", handle: getRun },
  { method: "GET", path: "/v1/runs", actor: "person", auth: "source", handle: getActiveRunForThread },
  { method: "GET", path: "/v1/deliveries", auth: "source", handle: listDeliveries },
  { method: "POST", path: "/v1/deliveries/:id/ack", actor: "system", auth: "source", handle: ackDelivery },
  { method: "POST", path: "/v1/deliveries/ack-by-key", actor: "system", auth: "source", handle: ackDeliveryByKey },
];