Skip to content

armgit / qm

Public Imported from GitHub
0

Multiplayer agent harness for work.

19.5 KB
Raw Blame
import { isCronRuntime } from "../../cron/runtime.ts";
import type { Cron } from "../../types.ts";
import type { CreateCronInput, CronPatch } from "../../cron/cron-store.ts";
import { describeRunNowRefusal } from "../../cron/scheduler.ts";
import { DEFAULT_CRON_TIMEZONE, userScheduleFromBody } from "../../cron/schedule.ts";
import type { CapabilityClaims } from "../../auth/capability-token.ts";
import { errMessage } from "../../util/errors.ts";
import { sendJson } from "../http.ts";
import { isObj } from "./shared.ts";
import { notifyOwnerOfCronEdit } from "../../triggers/edit-notice.ts";
import { canAdministerCron } from "../control-service.ts";
import { CRON_PATCH_NOTHING_TO_CHANGE } from "../control-service.ts";
import { withActor, type ApiCtx, type Route } from "./route.ts";

function defaultTimezoneFor(capability: CapabilityClaims | null): string {
  return typeof capability?.timezone === "string" && capability.timezone.trim()
    ? capability.timezone
    : DEFAULT_CRON_TIMEZONE;
}

function isCreateCron(b: unknown): b is CreateCronInput {
  return (
    isObj(b) &&
    isCronRuntime(b.runtime) &&
    userScheduleFromBody(b.schedule) !== null &&
    (typeof b.action === "string" || typeof (b as { message?: unknown }).message === "string") &&
    (b as { unattendedGrants?: unknown }).unattendedGrants === undefined &&
    typeof b.ownerScopeId === "string" &&
    typeof b.owner === "string" &&
    typeof b.createdBy === "string" &&
    ((b as { title?: unknown }).title === undefined || typeof (b as { title?: unknown }).title === "string") &&
    (b.destination === undefined || isObj(b.destination))
  );
}

type CapabilityCronBody = {
  runtime?: unknown;
  schedule?: unknown;
  title?: unknown;
  task?: unknown;
  text?: unknown;
  action?: unknown;
  message?: unknown;
  destinationKey?: unknown;
  recipient?: unknown;
  channel?: unknown;
  participants?: unknown;
  scope?: unknown;
  unfurlLinks?: unknown;
  unattendedGrants?: unknown;
  session?: unknown;
};

function taskText(b: CapabilityCronBody): string | undefined {
  if (typeof b.action === "string") return b.action;
  if (typeof b.task === "string") return b.task;
  return undefined;
}

function exactText(b: CapabilityCronBody): string | undefined {
  if (typeof b.message === "string") return b.message;
  if (typeof b.text === "string") return b.text;
  return undefined;
}

function withoutFireLog<T extends Cron>(cron: T): Omit<T, "fireLog"> {
  const { fireLog: _fireLog, ...rest } = cron;
  return rest;
}

async function gateSourceCron(ctx: ApiCtx, id: string): Promise<Cron | null> {
  const { res, app, url } = ctx;
  const cron = await app.getCron(id);
  if (!cron) {
    sendJson(res, 404, { error: "not_found" });
    return null;
  }
  const principalId = url.searchParams.get("principalId");
  if (!principalId) return cron;
  if (await canAdministerCron(app, cron, principalId)) return cron;
  sendJson(res, 404, { error: "not_found" });
  return null;
}

async function gateSourceCronRead(ctx: ApiCtx, id: string): Promise<Cron | null> {
  const { res, app, url } = ctx;
  const cron = await app.getCron(id);
  if (!cron) {
    sendJson(res, 404, { error: "not_found" });
    return null;
  }
  const principalId = url.searchParams.get("principalId");
  if (!principalId || (await canAdministerCron(app, cron, principalId))) return cron;
  const { visible } = await app.listCronsForViewer(principalId);
  if (visible.some((candidate) => candidate.id === id)) return cron;
  sendJson(res, 404, { error: "not_found" });
  return null;
}

function isCronPatch(b: unknown): b is {
  runtime?: Cron["runtime"];
  title?: string;
  task?: string;
  action?: string;
  schedule?: unknown;
  enabled?: boolean;
  archived?: boolean;
  unfurlLinks?: boolean;
  unattendedGrants?: string[];
  session?: boolean;
} {
  if (!isObj(b) || !isCronRuntime(b.runtime)) return false;
  if (!hasCronPatchFields(b)) return true;
  const hasTitle = b.title !== undefined;
  const hasAction = b.action !== undefined;
  const hasTask = b.task !== undefined;
  const hasSchedule = b.schedule !== undefined;
  const hasEnabled = b.enabled !== undefined;
  const hasArchived = b.archived !== undefined;
  const hasUnfurlLinks = b.unfurlLinks !== undefined;
  const hasUnattendedGrants = b.unattendedGrants !== undefined;
  if (hasTitle && typeof b.title !== "string") return false;
  if (hasAction && typeof b.action !== "string") return false;
  if (hasTask && typeof b.task !== "string") return false;
  if (hasEnabled && typeof b.enabled !== "boolean") return false;
  if (hasArchived && typeof b.archived !== "boolean") return false;
  if (hasUnfurlLinks && typeof b.unfurlLinks !== "boolean") return false;
  if (
    hasUnattendedGrants &&
    (!Array.isArray(b.unattendedGrants) || !b.unattendedGrants.every((grant) => typeof grant === "string"))
  )
    return false;
  if (hasSchedule && userScheduleFromBody(b.schedule) === null) return false;
  if (b.session !== undefined && typeof b.session !== "boolean") return false;
  return true;
}

function hasCronPatchFields(b: Record<string, unknown>): boolean {
  return (
    b.runtime !== undefined ||
    b.title !== undefined ||
    b.action !== undefined ||
    b.task !== undefined ||
    b.schedule !== undefined ||
    b.enabled !== undefined ||
    b.archived !== undefined ||
    b.unfurlLinks !== undefined ||
    b.unattendedGrants !== undefined ||
    b.session !== undefined
  );
}

const CRON_ERROR_STATUS: Record<string, number> = {
  bad_request: 400,
  recipient_not_found: 404,
  ambiguous_recipient: 409,
  channel_not_found: 404,
  ambiguous_channel: 409,
  group_not_found: 404,
  not_a_member: 403,
  identity_unverified: 403,
  unknown_destination: 400,
  cron_create_failed: 400,
  not_found: 404,
  forbidden: 403,
  unavailable: 404,
  cron_update_failed: 400,
  already_running: 409,
};

async function createCron(ctx: ApiCtx): Promise<void> {
  const { res, app, body, capability } = ctx;
  if (capability) {
    const b = body as CapabilityCronBody;
    if (
      b.unattendedGrants !== undefined &&
      (!Array.isArray(b.unattendedGrants) || !b.unattendedGrants.every((grant) => typeof grant === "string"))
    ) {
      return sendJson(res, 400, {
        error: "bad_request",
        message: "unattendedGrants must be an array of recognized grant strings",
      });
    }
    const schedule = userScheduleFromBody(b.schedule, defaultTimezoneFor(capability));
    const task = taskText(b);
    const text = exactText(b);
    if (!schedule || (task === undefined && text === undefined)) {
      return sendJson(res, 400, {
        error: "bad_request",
        message:
          "schedule.cron (5-field expression) or schedule.everyMs/firstFireAt, plus task (what to do) or text (exact text to send), required",
      });
    }
    if (!isCronRuntime(b.runtime)) return sendJson(res, 400, { error: "bad_request", message: "invalid cron runtime" });
    const result = await ctx.deps.control.createCron(
      {
        schedule,
        ...(b.runtime !== undefined ? { runtime: b.runtime } : {}),
        ...(task !== undefined ? { action: task } : {}),
        ...(text !== undefined ? { text } : {}),
        ...(typeof b.title === "string" ? { title: b.title } : {}),
        ...(typeof b.recipient === "string" ? { recipient: b.recipient } : {}),
        ...(typeof b.channel === "string" ? { channel: b.channel } : {}),
        ...(Array.isArray(b.participants)
          ? { participants: b.participants.filter((p): p is string => typeof p === "string") }
          : {}),
        ...(b.scope === "personal" ? { scope: "personal" as const } : {}),
        ...(typeof b.destinationKey === "string" ? { destinationKey: b.destinationKey } : {}),
        ...(typeof b.unfurlLinks === "boolean" ? { unfurlLinks: b.unfurlLinks } : {}),
        ...(Array.isArray(b.unattendedGrants) ? { unattendedGrants: b.unattendedGrants } : {}),
        ...(typeof b.session === "boolean" ? { session: b.session } : {}),
      },
      capability,
    );
    if (!result.ok) {
      const candidates = result.candidates?.map((c) =>
        result.code === "ambiguous_recipient"
          ? { principalId: c.id, displayName: c.label }
          : { channelId: c.id, name: c.label },
      );
      return sendJson(res, CRON_ERROR_STATUS[result.code] ?? 400, {
        error: result.code,
        message: result.message,
        ...(candidates ? { candidates } : {}),
      });
    }
    return sendJson(res, 200, {
      cron: withoutFireLog(result.cron),
      ...(result.recipient ? { recipient: result.recipient } : {}),
      ...(result.channel ? { channel: result.channel } : {}),
      ...(result.group ? { group: result.group } : {}),
    });
  }
  if (!isCreateCron(body)) return sendJson(res, 400, { error: "bad_request", message: "expected a CreateCronInput" });
  try {
    const cron = await app.createCron(body);
    return sendJson(res, 200, { cron: withoutFireLog(cron) });
  } catch (e) {
    return sendJson(res, 400, { error: "cron_create_failed", message: errMessage(e) });
  }
}

async function listCrons(ctx: ApiCtx): Promise<void> {
  const { res, app, url, capability } = ctx;
  if (capability) {
    const { crons, visible } = await ctx.deps.control.listCrons(capability);
    return sendJson(res, 200, { crons: crons.map(withoutFireLog), visible: visible.map(withoutFireLog) });
  }
  const viewer = url.searchParams.get("viewer");
  if (!viewer) return sendJson(res, 200, { crons: (await app.listCrons()).map(withoutFireLog) });
  const { owned, visible } = await app.listCronsForViewer(viewer);
  const decorate = async (cron: Cron) => ({
    ...withoutFireLog(cron),
    permission: (await canAdministerCron(app, cron, viewer)) ? "manage" : "read",
  });
  return sendJson(res, 200, {
    crons: await Promise.all(owned.map(decorate)),
    visible: await Promise.all(visible.map(decorate)),
  });
}

async function disableCron(ctx: ApiCtx): Promise<void> {
  const { res, app, capability } = ctx;
  const id = ctx.params.id!;
  if (capability) {
    const r = await ctx.deps.control.setCronEnabled(id, false, capability);
    if (!r.ok) return sendJson(res, CRON_ERROR_STATUS[r.code] ?? 400, { error: r.code, message: r.message });
    return sendJson(res, 200, { ok: true });
  }
  if (!(await gateSourceCron(ctx, id))) return;
  await app.setCronEnabled(id, false);
  return sendJson(res, 200, { ok: true });
}

async function retargetCron(ctx: ApiCtx): Promise<void> {
  const { res, body, capability } = ctx;
  const id = ctx.params.id!;
  if (!capability)
    return sendJson(res, 403, { error: "forbidden", message: "retarget requires an agent capability token" });
  const dk = isObj(body) ? body.destinationKey : undefined;
  if (typeof dk !== "string")
    return sendJson(res, 400, { error: "bad_request", message: "destinationKey (string) required" });
  const r = await ctx.deps.control.retargetCron(id, dk, capability);
  if (!r.ok) return sendJson(res, CRON_ERROR_STATUS[r.code] ?? 400, { error: r.code, message: r.message });
  return sendJson(res, 200, { cron: withoutFireLog(r.cron) });
}

async function noteCron(ctx: ApiCtx): Promise<void> {
  const { res, body, capability } = ctx;
  const id = ctx.params.id!;
  if (!capability)
    return sendJson(res, 403, { error: "forbidden", message: "note requires an agent capability token" });
  const note = isObj(body) ? body.note : undefined;
  if (typeof note !== "string") return sendJson(res, 400, { error: "bad_request", message: "note (string) required" });
  const r = await ctx.deps.control.noteCron(id, note, capability);
  if (!r.ok) return sendJson(res, CRON_ERROR_STATUS[r.code] ?? 400, { error: r.code, message: r.message });
  return sendJson(res, 200, { ok: true, applied: r.applied });
}

async function runCronNow(ctx: ApiCtx): Promise<void> {
  const { res, deps, capability } = ctx;
  const id = ctx.params.id!;
  if (capability) {
    const r = await ctx.deps.control.runCron(id, capability);
    if (!r.ok) return sendJson(res, CRON_ERROR_STATUS[r.code] ?? 400, { error: r.code, message: r.message });
    return sendJson(res, 200, { ok: true, fireKey: r.fireKey });
  }
  const cron = await gateSourceCron(ctx, id);
  if (!cron) return;
  if (!deps.scheduler) return sendJson(res, 404, { error: "not_found", message: "scheduler not wired" });
  if (cron.archived || !cron.enabled)
    return sendJson(res, 400, {
      error: "bad_request",
      message: `cron ${id} is ${cron.archived ? "archived" : "paused"} — enable it before firing it on demand`,
    });
  const result = await deps.scheduler.runNow(id);
  if (!result.started) {
    const refusal = describeRunNowRefusal(id, result)!;
    return sendJson(res, CRON_ERROR_STATUS[refusal.error] ?? 400, refusal);
  }
  return sendJson(res, 200, { ok: true, fireKey: result.fireKey });
}

async function cronRuns(ctx: ApiCtx): Promise<void> {
  const { res, url, capability, app } = ctx;
  const id = ctx.params.id!;
  const rawLimit = url.searchParams.get("limit");
  const limit = rawLimit === null ? undefined : Number(rawLimit);
  if (capability) {
    const r = await ctx.deps.control.getCronRuns(id, limit !== undefined ? { limit } : {}, capability);
    if (!r.ok) return sendJson(res, CRON_ERROR_STATUS[r.code] ?? 400, { error: r.code, message: r.message });
    return sendJson(res, 200, { cron: withoutFireLog(r.cron), runs: r.runs, total: r.total });
  }
  const cron = await gateSourceCron(ctx, id);
  if (!cron) return;
  if (limit !== undefined && (!Number.isInteger(limit) || limit < 1)) {
    return sendJson(res, 400, { error: "bad_request", message: "limit must be a positive integer" });
  }
  const { runs, total } = await app.listCronFires(id, limit !== undefined ? { limit } : {});
  return sendJson(res, 200, { cron: withoutFireLog(cron), runs, total });
}

const CRON_PATCH_BAD_REQUEST =
  "expected a cron patch: title (string), task (string), schedule, enabled (boolean), archived (boolean), unfurlLinks (boolean), unattendedGrants (string[]), and/or session (boolean)";

async function cronById(ctx: ApiCtx): Promise<void> {
  const { res, app, url, pathname, method, body, capability } = ctx;
  const id = decodeURIComponent(pathname.slice("/v1/crons/".length));
  if (capability) {
    if (method === "GET") {
      const r = await ctx.deps.control.getCron(id, capability);
      return r.ok
        ? sendJson(res, 200, { cron: withoutFireLog(r.cron) })
        : sendJson(res, CRON_ERROR_STATUS[r.code] ?? 400, { error: r.code, message: r.message });
    }
    if (method === "DELETE") {
      const r = await ctx.deps.control.deleteCron(id, capability);
      return r.ok
        ? sendJson(res, 200, { ok: true })
        : sendJson(res, CRON_ERROR_STATUS[r.code] ?? 400, { error: r.code, message: r.message });
    }
    if (!isCronPatch(body)) return sendJson(res, 400, { error: "bad_request", message: CRON_PATCH_BAD_REQUEST });
    if (!hasCronPatchFields(body)) {
      return sendJson(res, 400, { error: "bad_request", message: CRON_PATCH_NOTHING_TO_CHANGE });
    }
    const schedule =
      body.schedule !== undefined ? userScheduleFromBody(body.schedule, defaultTimezoneFor(capability))! : undefined;
    const task = body.action ?? body.task;
    const r = await ctx.deps.control.patchCron(
      id,
      {
        ...(body.runtime !== undefined ? { runtime: body.runtime } : {}),
        ...(body.title !== undefined ? { title: body.title } : {}),
        ...(task !== undefined ? { action: task } : {}),
        ...(schedule !== undefined ? { schedule } : {}),
        ...(body.enabled !== undefined ? { enabled: body.enabled } : {}),
        ...(body.archived !== undefined ? { archived: body.archived } : {}),
        ...(body.unfurlLinks !== undefined ? { unfurlLinks: body.unfurlLinks } : {}),
        ...(body.unattendedGrants !== undefined ? { unattendedGrants: body.unattendedGrants } : {}),
        ...(body.session !== undefined ? { session: body.session } : {}),
      },
      capability,
    );
    return r.ok
      ? sendJson(res, 200, { cron: withoutFireLog(r.cron) })
      : sendJson(res, CRON_ERROR_STATUS[r.code] ?? 400, { error: r.code, message: r.message });
  }
  if (method === "GET") {
    const cron = await gateSourceCronRead(ctx, id);
    if (!cron) return;
    return sendJson(res, 200, { cron: withoutFireLog(cron) });
  }
  const cron = await gateSourceCron(ctx, id);
  if (!cron) return;
  if (method === "DELETE") {
    await app.deleteCron(id);
    const editor = url.searchParams.get("principalId");
    if (editor) await notifyOwnerOfCronEdit(app, { cron, editorId: editor, changeSummary: ["deleted"] });
    return sendJson(res, 200, { ok: true });
  }
  if ((cron.unattendedGrants?.length ?? 0) > 0) {
    return sendJson(res, 403, {
      error: "forbidden",
      message: "a privileged cron may only be patched by its owner from a live turn",
    });
  }
  if (!isCronPatch(body)) return sendJson(res, 400, { error: "bad_request", message: CRON_PATCH_BAD_REQUEST });
  if (!hasCronPatchFields(body)) {
    return sendJson(res, 400, { error: "bad_request", message: CRON_PATCH_NOTHING_TO_CHANGE });
  }
  const schedule = body.schedule !== undefined ? userScheduleFromBody(body.schedule)! : undefined;
  const task = body.action ?? body.task;
  if (body.unfurlLinks !== undefined && !cron.destination) {
    return sendJson(res, 400, {
      error: "bad_request",
      message: "unfurlLinks can only be set on a cron with a delivery destination",
    });
  }
  const patch: CronPatch = {
    ...(body.runtime !== undefined ? { runtime: body.runtime } : {}),
    ...(body.title !== undefined ? { title: body.title } : {}),
    ...(task !== undefined ? { action: task } : {}),
    ...(schedule !== undefined ? { schedule } : {}),
    ...(body.enabled !== undefined ? { enabled: body.enabled } : {}),
    ...(body.archived !== undefined ? { archived: body.archived } : {}),
    ...(body.unfurlLinks !== undefined && cron.destination
      ? { destination: { ...cron.destination, unfurlLinks: body.unfurlLinks } }
      : {}),
  };
  try {
    const updated = await app.updateCron(id, patch);
    const editor = url.searchParams.get("principalId");
    if (updated && editor)
      await notifyOwnerOfCronEdit(app, {
        cron: updated,
        editorId: editor,
        changeSummary: [
          ...(body.runtime !== undefined ? ["runtime"] : []),
          ...(body.title !== undefined ? ["title"] : []),
          ...(task !== undefined ? ["task"] : []),
          ...(schedule !== undefined ? ["schedule"] : []),
          ...(body.enabled !== undefined ? [`enabled=${body.enabled}`] : []),
          ...(body.archived !== undefined ? [`archived=${body.archived}`] : []),
        ],
        ...(schedule !== undefined ? { detail: { schedule } } : {}),
      });
    return sendJson(res, 200, { cron: updated ? withoutFireLog(updated) : null });
  } catch (e) {
    return sendJson(res, 400, { error: "cron_update_failed", message: errMessage(e) });
  }
}

export const cronRoutes: ReadonlyArray<Route<ApiCtx>> = [
  { method: "POST", path: "/v1/crons", actor: "body.createdBy", auth: "either", handle: createCron },
  { method: "GET", path: "/v1/crons", actor: "query.viewer", auth: "either", handle: listCrons },
  { method: "POST", path: "/v1/crons/:id/note", auth: "either", handle: noteCron },
  ...withActor("query.principalId", [
    { method: "POST", path: "/v1/crons/:id/disable", auth: "either", handle: disableCron },
    { method: "POST", path: "/v1/crons/:id/destination", auth: "either", handle: retargetCron },
    { method: "POST", path: "/v1/crons/:id/run", auth: "either", handle: runCronNow },
    { method: "GET", path: "/v1/crons/:id/runs", auth: "either", handle: cronRuns },
    {
      match: (m, p) =>
        p.startsWith("/v1/crons/") &&
        !p.slice("/v1/crons/".length).includes("/") &&
        (m === "GET" || m === "PATCH" || m === "DELETE"),
      auth: "either",
      handle: cronById,
    },
  ]),
];