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.

38.7 KB
Raw Blame
import type { Context, MiddlewareHandler } from "hono";
import { Hono } from "hono";
import type { AuditEventType, AuditStore } from "../audit";
import { recordAuditEvent } from "../audit";
import type { AppVariables } from "../auth/guards";
import { afterExposureChange } from "../plugins/exposure-change";
import type { SharedUseStore } from "../plugins/shared-use-store";
import { testAgentConnection } from "./connection-test";
import { checkAgentEndpoint } from "./endpoint";
import { isolationState, mayIsolate } from "./isolation";
import { isManagedEndpoint } from "./managed-endpoint";
import { canManageAgent } from "./profile-policy";
import {
  AgentAssignedError,
  AgentNotFoundError,
  AgentNotManageableError,
  type AgentProfileStore,
  IsolationRefusedError,
  ManagedAgentUnavailableError,
  ProtectedAgentError,
} from "./profile-store";
import type {
  AgentActor,
  AgentProfile,
  CreateAgentInput,
} from "./profile-types";

type AgentInputParseResult =
  | { ok: true; value: CreateAgentInput }
  | { ok: false; error: string };

type AgentInputObject = {
  name?: unknown;
  title?: unknown;
  roleDescription?: unknown;
  visibility?: unknown;
  endpoint?: unknown;
  auth?: unknown;
  isolated?: unknown;
};

/**
 * Parse and validate what a user typed into the agent form.
 *
 * `allowPrivateHosts` is passed in rather than read from configuration here so this stays a pure
 * function: a developer's own agent lives on localhost, and a hosted deployment must refuse exactly
 * that, so the answer depends on the deployment and the test suite needs to exercise both.
 */
export function parseAgentInput(
  input: unknown,
  allowPrivateHosts = false,
  /** Private addresses this deployment named as acceptable. Empty is the default posture. */
  allowedHosts: ReadonlySet<string> = new Set(),
): AgentInputParseResult {
  if (!isAgentInputObject(input)) {
    return { ok: false, error: "Agent input must be a JSON object." };
  }

  const name = boundedText(
    input.name,
    80,
    "Name must be text between 1 and 80 characters.",
  );
  if (typeof name !== "string") return name;

  if (typeof input.title !== "string" || input.title.trim().length > 120) {
    return {
      ok: false,
      error: "Title must be text of 120 characters or fewer.",
    };
  }
  const title = input.title.trim();

  const roleDescription = boundedText(
    input.roleDescription,
    1000,
    "What it does must be text between 1 and 1000 characters.",
  );
  if (typeof roleDescription !== "string") return roleDescription;

  if (typeof input.visibility !== "string") {
    return { ok: false, error: "Visibility must be public or private." };
  }
  const visibility = input.visibility.trim();
  if (visibility !== "public" && visibility !== "private") {
    return { ok: false, error: "Visibility must be public or private." };
  }

  // The endpoint is optional and checked. Absent means the Bot in the box, which is what most people
  // want on their first go. Present means this server will POST to an address a person chose, so it
  // goes through the same target check as navigation before it is allowed anywhere near the database.
  let endpoint: string | undefined;
  if (input.endpoint !== undefined && input.endpoint !== "") {
    const verdict = checkAgentEndpoint(input.endpoint, {
      allowPrivateHosts,
      allowedHosts,
    });
    if (!verdict.allowed) return { ok: false, error: verdict.reason };
    endpoint = verdict.url;
  }

  // The key is optional and write-only. An absent field leaves an existing key alone; sending one
  // replaces it. There is no way to read one back, here or anywhere.
  let auth: { header: string; value: string } | undefined;
  if (input.auth !== undefined && input.auth !== null) {
    const supplied = input.auth as { header?: unknown; value?: unknown };
    const value =
      typeof supplied.value === "string" ? supplied.value.trim() : "";
    if (value) {
      const header =
        typeof supplied.header === "string" && supplied.header.trim()
          ? supplied.header.trim()
          : "Authorization";
      if (!/^[A-Za-z0-9-]+$/.test(header)) {
        return { ok: false, error: "That is not a valid header name." };
      }
      // Refused here rather than discovered on the first run. This value is encrypted and stored,
      // and then sent as a header on every turn the Bot takes; one that cannot be a header value
      // throws inside `fetch` every one of those times, long after the form said it was saved.
      const unsendable = unsendableHeaderValue(value);
      if (unsendable) {
        return {
          ok: false,
          error: `That key contains ${unsendable}, so it cannot be sent as a header.`,
        };
      }
      auth = { header, value };
    }
  }

  // Absent is "leave it as it is", so only a present value is checked. A string "true" is refused
  // rather than read as yes: this decides which computer a Bot runs on.
  if (input.isolated !== undefined && typeof input.isolated !== "boolean") {
    return { ok: false, error: "Isolated must be true or false." };
  }
  const isolated = input.isolated;

  return {
    ok: true,
    value: {
      name,
      title,
      roleDescription,
      visibility,
      endpoint,
      auth,
      ...(isolated === undefined ? {} : { isolated }),
    },
  };
}

function isAgentInputObject(input: unknown): input is AgentInputObject {
  return typeof input === "object" && input !== null && !Array.isArray(input);
}

/**
 * What in this value stops it being a header, or null when nothing does.
 *
 * `new Headers()` refuses a line break, a NUL, and any code point above U+00FF, and it refuses them
 * by throwing a TypeError from inside `fetch` — which is not a decision this deployment gets to
 * take part in. Both surfaces below take a header value from the same box on the same form and
 * neither looked, so the throw arrived somewhere that reads as something else entirely: on the
 * connection test it lands in the catch written for a dead host, and the person is told "this server
 * could not reach that address", which sends them to their tunnel and their firewall over a key
 * they had just pasted with a wrapped line in it. A hyphen a document turned into an en dash does
 * the same thing, and looks like nothing at all in a password box.
 *
 * The description never contains the value. This is asked of a credential on one of the two paths,
 * and one character of a secret in an error message is one character too many.
 */
function unsendableHeaderValue(value: string): string | null {
  for (const character of value) {
    const code = character.codePointAt(0) ?? 0;
    if (code === 0x0a || code === 0x0d) return "a line break";
    if (code === 0) return "a null character";
    if (code > 0xff) return "a character that cannot go in a header value";
  }
  return null;
}

/**
 * Parse and validate the headers a person attaches to a connection test.
 *
 * Unvalidated, the route cast any object straight into the probe `fetch`, so an array value, a
 * nested object, or a `__proto__` key travelled into the network call and threw a TypeError 500 —
 * or probed header handling the deployment never meant to exercise. Names follow the same rule as
 * the stored agent auth header; values must be strings; the whole map is capped so a pasted dump
 * cannot balloon the probe.
 */
export function parseConnectionHeaders(
  input: unknown,
):
  | { ok: true; value: Record<string, string> | undefined }
  | { ok: false; error: string } {
  if (input === undefined) return { ok: true, value: undefined };
  if (typeof input !== "object" || input === null || Array.isArray(input)) {
    return { ok: false, error: "Headers must be an object of name to value." };
  }
  /*
   * A JSON body carrying `__proto__` does not arrive as an own property: `JSON.parse` sets the
   * object's prototype instead, so `Object.entries` never sees it and a name block-list below
   * would pass it straight through into the probe fetch. Refuse any headers object whose prototype
   * is not a plain one before reading entries.
   */
  if (Object.getPrototypeOf(input) !== Object.prototype) {
    return { ok: false, error: "Headers must be an object of name to value." };
  }
  const entries = Object.entries(input);
  if (entries.length > 32) {
    return { ok: false, error: "Headers must have at most 32 entries." };
  }
  const headers: Record<string, string> = {};
  for (const [name, value] of entries) {
    if (
      name === "__proto__" ||
      name === "constructor" ||
      name === "prototype" ||
      !/^[A-Za-z0-9-]+$/.test(name) ||
      name.length > 64
    ) {
      return {
        ok: false,
        error: `That is not a valid header name: ${name.slice(0, 64)}.`,
      };
    }
    if (typeof value !== "string") {
      return {
        ok: false,
        error: `Header "${name}" must be a string value.`,
      };
    }
    if (value.length > 4096) {
      return {
        ok: false,
        error: `Header "${name}" must be at most 4096 characters.`,
      };
    }
    const unsendable = unsendableHeaderValue(value);
    if (unsendable) {
      return {
        ok: false,
        error: `Header "${name}" contains ${unsendable}, so it cannot be sent.`,
      };
    }
    headers[name] = value;
  }
  return { ok: true, value: entries.length === 0 ? undefined : headers };
}

/**
 * The local development actor, which is not a row in `users`.
 *
 * The audit table has a foreign key to that table, so writing this id would fail the constraint and
 * lose the row entirely. Who it was is in the payload either way.
 */
const DEV_ACTOR_EMAIL = "[email protected]";

export function createAgentRoutes(
  store: AgentProfileStore,
  requireUser: MiddlewareHandler<{ Variables: AppVariables }>,
  /** Whether this deployment may talk to its own network. True on a laptop, false when hosted. */
  allowPrivateHosts = false,
  /** Where a Bot's own refusal is recorded. Absent in tests that do not care about the trail. */
  auditStore?: AuditStore,
  /**
   * Private addresses this deployment named as acceptable for an agent to live at.
   *
   * Separate from `allowPrivateHosts` on purpose: that one opens the network, this one opens an
   * address. A hosted deployment sets this and leaves the other off.
   */
  allowedHosts: ReadonlySet<string> = new Set(),
  /**
   * Which Bots a Bot may hand work to, for the screen that grants it.
   *
   * A named object rather than another positional argument: every parameter above this one is
   * optional, so a misplaced one typechecks and silently does nothing, and this list is already at
   * the length where that stops being hypothetical.
   *
   * Absent in a deployment with no plugin store, which is a deployment where no Bot may address any
   * other. The screen is then told the capability is off rather than shown a control that grants
   * nothing.
   */
  handoff?: {
    /** Whether the deployment's own caps leave the capability switched on at all. */
    enabled: boolean;
    /** The Bots this one may address today, read per call so a revoked grant stops showing. */
    reachableFrom: (agentId: string) => Promise<readonly string[]>;
    /**
     * Whether this Bot can be a grantee at all: any Bot that exists, built in or at its own
     * endpoint, since both reach the same handoff desk. Optional so a caller without a plugin store
     * answers "no" rather than crashing the read.
     */
    canHandOn?: (agentId: string) => Promise<boolean | undefined>;
  },
  /**
   * Whether a coworker can run on this deployment's own Bot, i.e. be created with no endpoint.
   *
   * The store already refuses such a create on a deployment with no managed Bot; this exists so a
   * screen can say so before somebody fills in three steps of a form that was always going to fail.
   */
  builtInAvailable = false,
  /**
   * The managed Bot's own address, so a coworker created without an endpoint can be told apart.
   *
   * Creation bakes this address into the coworker's stored configuration, and afterwards nothing in
   * the row says whether a person supplied it. The difference matters to exactly one screen: a
   * coworker running here calls tools back with the deployment's own credential and needs no setup,
   * while one a person hosts needs a callback token put into their process. Without this flag the
   * dialog nagged built-in coworkers about a credential they never needed.
   */
  managedEndpoint?: string,
  /**
   * Where a Bot's shared accounts live, so making a Bot public can say what that means for them.
   *
   * Absent in a deployment with no plugin store, which is a deployment where `afterExposureChange`
   * already reports nothing rather than reach for a store that is not there.
   */
  sharedUse?: SharedUseStore,
  /**
   * The deployment's own token and the addresses it belongs to, so a connection test against one of
   * them knocks the way a real run will.
   *
   * A named object rather than two more positional strings, for the reason the handoff parameter
   * gives: everything above it is optional, and a misplaced string typechecks.
   *
   * `endpoints` is every address this deployment runs — the Bot in the box and any harness picked
   * during setup — because the run path had to learn that same lesson: matching only the first left
   * the picked harness answering 401 to everything.
   */
  managedRun?: { token: string; endpoints: readonly (string | URL)[] },
  /**
   * Whether this deployment can give one Bot a computer of its own (`deploymentCanIsolate`).
   *
   * Absent is no: a deployment that never said it can make a second computer is not trusted to.
   */
  isolation?: { available: boolean },
) {
  const isolationAvailable = isolation?.available ?? false;
  /** The dto with the one fact only this closure knows: whether the coworker runs on our own Bot. */
  const dto = (actor: AgentActor, agent: AgentProfile) => ({
    ...agentDto(actor, agent),
    // A string comparison on purpose: two absent values must not read as "runs on our Bot".
    builtIn:
      typeof agent.endpoint === "string" && agent.endpoint === managedEndpoint,
  });
  /**
   * The dtos, each with whether its computer of its own is in effect now.
   *
   * Asked of the OWNER's switch, read now, so an administrator withdrawing "Isolated Bots" shows on
   * the Bot's page at its next load without anybody editing the Bot. Read once per owner and one
   * owner at a time, and only for Bots that asked: a roster is mostly people's own Bots, and most of
   * those are not isolated.
   */
  const dtos = async (actor: AgentActor, list: readonly AgentProfile[]) => {
    const owners = new Map<string, boolean>();
    for (const agent of list) {
      if (!agent.isolated || !agent.ownerUserId) continue;
      if (owners.has(agent.ownerUserId)) continue;
      owners.set(agent.ownerUserId, await mayIsolate(agent.ownerUserId));
    }
    return list.map((agent) => ({
      ...dto(actor, agent),
      ...isolationState(
        agent,
        isolationAvailable,
        agent.ownerUserId ? (owners.get(agent.ownerUserId) ?? false) : false,
      ),
    }));
  };
  const dtoOf = async (actor: AgentActor, agent: AgentProfile) =>
    (await dtos(actor, [agent]))[0];
  const routes = new Hono<{ Variables: AppVariables }>();

  /**
   * The Bot declined something, and says so.
   *
   * The audit trail records what a Bot did, decided by the gateway on the way to an action. A model
   * that refuses before calling any tool takes no action, so this records the attempted request.
   *
   * Self-reported, and said so in the row. The Bot calls this because its tool description tells it
   * to, so a model that declines without a tool call still writes nothing. This is evidence, not enforcement:
   * nothing is prevented by it, and a reader must not mistake an empty list for an untroubled Bot.
   */
  routes.post("/:agentId/declined", requireUser, async (context) => {
    const agentId = context.req.param("agentId");
    const body = (await context.req.json().catch(() => null)) as {
      reason?: unknown;
      request?: unknown;
    } | null;

    const reason = typeof body?.reason === "string" ? body.reason.trim() : "";
    if (!reason) {
      return context.json({ error: "A reason is required." }, 400);
    }

    /*
     * The same question every other route here asks first: is this a Bot the caller may reach?
     *
     * The row says "reportedBy: the Bot itself", and the Bot reports through the person's session,
     * so the trail's only way of knowing the report came from a Bot is that the person could have
     * been talking to that Bot. Without this check, any signed-in person could write a decline
     * against any id at all, a coworker they cannot see included, and an administrator reading the
     * trail would take it for something the Bot said. Not found rather than forbidden, as the store
     * answers everywhere else, so the check does not confirm which ids exist.
     */
    const agent = await store.get(context.var.actor, agentId);
    if (!agent) {
      return context.json({ error: "Couldn't find that Bot." }, 404);
    }

    if (auditStore) {
      const actor = context.var.actor;
      await recordAuditEvent(auditStore, {
        eventType: "bot.declined",
        targetType: "agent",
        targetId: agentId,
        ...(actor?.id && actor.email !== DEV_ACTOR_EMAIL
          ? { actorUserId: actor.id }
          : {}),
        payload: {
          bot: agentId,
          actor: actor?.email ?? "unknown",
          reason: reason.slice(0, 500),
          // What it was asked, in the Bot's own words and only if it offered them. Truncated for the
          // same reason every other payload here is: a trail is not a transcript.
          ...(typeof body?.request === "string" && body.request.trim()
            ? { request: body.request.trim().slice(0, 500) }
            : {}),
          reportedBy: "the Bot itself",
        },
      });
    }

    return context.json({ recorded: true });
  });

  routes.get("/", requireUser, async (context) => {
    try {
      const hidden = context.req.query("hidden") === "true";
      const agents = await store.list(context.var.actor, hidden);
      return context.json({
        agents: await dtos(context.var.actor, agents),
      });
    } catch (error) {
      return mapStoreError(context, error);
    }
  });

  /**
   * What kinds of coworker this deployment can create, for the screen that asks.
   *
   * Static per process: whether a managed Bot exists is deployment configuration, not data. Above
   * the parameterised route on purpose, so "capabilities" can never be read as an agent id.
   */
  routes.get("/capabilities", requireUser, (context) =>
    context.json({
      capabilities: {
        builtInAvailable,
        // Whether this person may tick it is a switch, read from `/api/admin/enterprise/me`.
        isolationAvailable,
      },
    }),
  );

  routes.get("/:agentId", requireUser, async (context) => {
    // A whitespace id would reach the store query and answer 500 on some backends instead of a
    // 400 for a malformed call. Existence stays a 404; shape is checked here.
    if (!context.req.param("agentId").trim()) {
      return context.json({ error: "A Bot id is required." }, 400);
    }
    try {
      const agent = await store.get(
        context.var.actor,
        context.req.param("agentId"),
      );
      if (!agent) {
        return context.json({ error: "Couldn't find that Bot." }, 404);
      }
      return context.json({ agent: await dtoOf(context.var.actor, agent) });
    } catch (error) {
      return mapStoreError(context, error);
    }
  });

  /**
   * Try an endpoint before saving it.
   *
   * Deliberately not part of create: a person needs to know whether their agent answers before they
   * commit to it, and they need to be able to try again without creating dead
   * Bots on the way. It runs the same target check as saving, so it cannot probe addresses that
   * registration would refuse.
   */
  routes.post("/test-connection", requireUser, async (context) => {
    const body = (await context.req.json().catch(() => null)) as {
      endpoint?: unknown;
      headers?: unknown;
    } | null;
    const parsed = parseConnectionHeaders(body?.headers);
    if (!parsed.ok) {
      return context.json({ error: parsed.error }, 400);
    }
    /*
     * An address this deployment runs is knocked on with this deployment's token.
     *
     * Nobody types that token — the run path attaches it by recognising the address — so a test
     * that left it off reported "The agent refused this request. If it needs a key, add it as a
     * header." for the Bot in the box and for the harness picked during setup. Both work; the
     * advice was to break them.
     *
     * The person's own headers are applied over these rather than under, because a header they
     * typed is a thing they can see and change, and this one is not.
     */
    const ours =
      managedRun &&
      typeof body?.endpoint === "string" &&
      isManagedEndpoint(body.endpoint, managedRun.endpoints);
    const headers = {
      ...(ours ? { "x-openbot-agent-token": managedRun.token } : {}),
      ...parsed.value,
    };
    const result = await testAgentConnection(body?.endpoint, {
      // Absent rather than empty when there is nothing to send, so a deployment with no managed Bot
      // probes exactly as it did before this.
      ...(Object.keys(headers).length > 0 ? { headers } : {}),
      allowPrivateHosts,
      allowedHosts,
    });
    // 200 either way: the request succeeded, and the verdict is the payload. A failed connection test
    // is an answer, not an error, and a 4xx here would have the surface render it as a broken button.
    return context.json(result);
  });

  /**
   * Record something that changed a Bot.
   *
   * One helper rather than eight copies, because the eight routes below all answer the same question
   * and the payload has to be the same shape for a reader filtering the trail.
   *
   * Never fatal. The change is already made and the caller has been told so; a trail that is briefly
   * unavailable is not a reason to report a failure that did not happen.
   */
  const record = async (
    context: Context<{ Variables: AppVariables }>,
    eventType: Extract<AuditEventType, `bot.${string}`>,
    /** Undefined only for a Bot that was refused before it existed. */
    agentId: string | undefined,
    payload: Record<string, unknown> = {},
  ): Promise<void> => {
    if (!auditStore) return;
    const actor = context.var.actor;
    try {
      await recordAuditEvent(auditStore, {
        eventType,
        targetType: "agent",
        ...(agentId ? { targetId: agentId } : {}),
        ...(actor?.id && actor.email !== DEV_ACTOR_EMAIL
          ? { actorUserId: actor.id }
          : {}),
        payload: {
          bot: agentId ?? null,
          actor: actor?.email ?? "unknown",
          ...payload,
        },
      });
    } catch (error) {
      console.error(
        JSON.stringify({
          type: "bot-audit-write-failed",
          eventType,
          agentId,
          error: String(error),
        }),
      );
    }
  };

  /**
   * A computer of its own, asked for and refused, on the trail and in the answer.
   *
   * Recorded because nothing else would be: the Bot is unchanged, or was never made, so the row is
   * the only evidence of the attempt. Against the Bot it was asked for, or against no Bot on a create.
   * The answer has the shape the enterprise gate gives a refused capability, so a screen reads both
   * the same way.
   */
  const refuseIsolation = async (
    context: Context<{ Variables: AppVariables }>,
    reason: "capability" | "unowned" | "deployment",
    message: string,
    agentId: string | undefined,
    name: string,
  ): Promise<Response> => {
    await record(context, "bot.isolation_refused", agentId, {
      reason,
      name,
      ...(agentId ? {} : { attempted: "create" }),
    });
    return context.json(
      {
        error: message,
        ...(reason === "capability" ? { capability: "isolatedComputers" } : {}),
      },
      reason === "deployment" ? 400 : 403,
    );
  };
  /** Said where a deployment's computers cannot make one more. */
  const NO_ISOLATION =
    "This OpenBot can't give a Bot a computer of its own, so it runs on yours.";

  routes.post("/", requireUser, async (context) => {
    // Malformed JSON is a recoverable client-input error and is validated by the same parser.
    const parsed = parseAgentInput(
      await context.req.json().catch(() => null),
      allowPrivateHosts,
      allowedHosts,
    );
    if (!parsed.ok) return context.json({ error: parsed.error }, 400);
    if (parsed.value.isolated === true && !isolationAvailable) {
      return refuseIsolation(
        context,
        "deployment",
        NO_ISOLATION,
        undefined,
        parsed.value.name,
      );
    }

    try {
      /*
       * A coworker with no address runs here, on the text this form already requires.
       *
       * "Agent endpoint (optional)" was not optional on the recommended one-container image: with
       * nothing to bind to, `create` refused with "This deployment has no managed Bot", so a person
       * could not make a coworker at all on the image the README tells them to deploy. The role
       * description is what such a coworker runs on — the same field a `built_in` Bot in the tenant
       * package carries, for the same purpose — and passing it only when no endpoint was given keeps
       * every other path exactly as it was: give an address and it is a remote Bot, as before.
       */
      const agent = await store.create(context.var.actor, {
        ...parsed.value,
        ...(parsed.value.endpoint
          ? {}
          : { systemPrompt: parsed.value.roleDescription }),
      });
      /*
       * The endpoint, because that is where conversation content will be sent, and whether a key was
       * attached, because "this Bot authenticates" is a fact and the key itself never is.
       *
       * And who may reach it. `visibility` is not a display preference: `accessFilter` admits a
       * `public` coworker to every signed-in person, and `canRunAgent` is `canAccessAgent`, so public
       * means everybody in the deployment may act as this Bot and spend the grants it holds. A row
       * that cannot say which it was cannot reconstruct who could use this coworker at the time.
       */
      await record(context, "bot.created", agent.id, {
        name: parsed.value.name,
        visibility: parsed.value.visibility,
        ...(parsed.value.endpoint ? { endpoint: parsed.value.endpoint } : {}),
        hasKey: Boolean(parsed.value.auth),
        // Which computer it runs on is who it can reach, so a computer of its own is worth naming.
        ...(parsed.value.isolated ? { isolated: true } : {}),
      });
      return context.json(
        { agent: await dtoOf(context.var.actor, agent) },
        201,
      );
    } catch (error) {
      if (error instanceof IsolationRefusedError) {
        return refuseIsolation(
          context,
          error.reason,
          error.message,
          undefined,
          parsed.value.name,
        );
      }
      return mapStoreError(context, error);
    }
  });

  routes.patch("/:agentId", requireUser, async (context) => {
    // Malformed JSON is a recoverable client-input error and is validated by the same parser.
    const parsed = parseAgentInput(
      await context.req.json().catch(() => null),
      allowPrivateHosts,
      allowedHosts,
    );
    if (!parsed.ok) return context.json({ error: parsed.error }, 400);
    if (parsed.value.isolated === true && !isolationAvailable) {
      return refuseIsolation(
        context,
        "deployment",
        NO_ISOLATION,
        context.req.param("agentId"),
        parsed.value.name,
      );
    }

    try {
      const agent = await store.update(
        context.var.actor,
        context.req.param("agentId"),
        parsed.value,
      );
      /*
       * What changed, not the new values. Repointing the endpoint is the dangerous edit and is worth
       * naming; a replaced key is worth knowing about and is never worth recording.
       *
       * `visibility` is carried the way `name` is — on every row, whether or not this edit moved it —
       * because it is the second dangerous edit and the route has no before to compare against.
       * Public admits every signed-in person to this coworker, and `canRunAgent` is `canAccessAgent`,
       * so it hands them the right to act as it and spend what it was granted. Without the value on
       * each row, an edit that opened a coworker to the whole deployment is byte-identical to one
       * that corrected its title, and the trail cannot say when it was opened or by whom. Recorded on
       * every row rather than only on the row that changed it, so reading the trail forward tells you
       * what was reachable at any point, which is what an incident asks.
       */
      await record(context, "bot.updated", agent.id, {
        name: parsed.value.name,
        visibility: parsed.value.visibility,
        ...(parsed.value.endpoint ? { endpoint: parsed.value.endpoint } : {}),
        ...(parsed.value.auth ? { keyReplaced: true } : {}),
        // Only when the edit said, since absent leaves it as it was and the route has no before.
        ...(parsed.value.isolated === undefined
          ? {}
          : { isolated: parsed.value.isolated }),
      });
      /*
       * Publishing is the owner's call, and a wider audience can outrun what an administrator
       * approved for a shared account this Bot holds. Reported only on the edit that opens a Bot to
       * everybody, so a screen can offer to ask rather than let the first refused call be how anybody
       * finds out.
       */
      return context.json({
        agent: await dtoOf(context.var.actor, agent),
        ...(parsed.value.visibility === "public"
          ? {
              sharedApps: await afterExposureChange(
                sharedUse,
                context.var.actor,
                agent.id,
              ),
            }
          : {}),
      });
    } catch (error) {
      if (error instanceof IsolationRefusedError) {
        return refuseIsolation(
          context,
          error.reason,
          error.message,
          context.req.param("agentId"),
          parsed.value.name,
        );
      }
      return mapStoreError(context, error);
    }
  });

  routes.post("/:agentId/duplicate", requireUser, async (context) => {
    if (!context.req.param("agentId").trim()) {
      return context.json({ error: "A Bot id is required." }, 400);
    }
    try {
      const agent = await store.duplicate(
        context.var.actor,
        context.req.param("agentId"),
      );
      // Recorded against the copy, naming the original: a duplicate inherits an endpoint, so the
      // reader needs to know a second Bot now points at it.
      await record(context, "bot.duplicated", agent.id, {
        copiedFrom: context.req.param("agentId"),
        // Kept only when the person duplicating may give it a computer of its own.
        ...(agent.isolated ? { isolated: true } : {}),
      });
      return context.json(
        { agent: await dtoOf(context.var.actor, agent) },
        201,
      );
    } catch (error) {
      return mapStoreError(context, error);
    }
  });

  routes.post("/:agentId/hide", requireUser, async (context) => {
    try {
      await store.setHidden(
        context.var.actor,
        context.req.param("agentId"),
        true,
      );
      await record(context, "bot.hidden", context.req.param("agentId"));
      return context.body(null, 204);
    } catch (error) {
      return mapStoreError(context, error);
    }
  });

  routes.post("/:agentId/unhide", requireUser, async (context) => {
    try {
      await store.setHidden(
        context.var.actor,
        context.req.param("agentId"),
        false,
      );
      await record(context, "bot.unhidden", context.req.param("agentId"));
      return context.body(null, 204);
    } catch (error) {
      return mapStoreError(context, error);
    }
  });

  routes.post("/:agentId/pin", requireUser, async (context) => {
    try {
      await store.setPinned(
        context.var.actor,
        context.req.param("agentId"),
        true,
      );
      await record(context, "bot.pinned", context.req.param("agentId"));
      return context.body(null, 204);
    } catch (error) {
      return mapStoreError(context, error);
    }
  });

  routes.post("/:agentId/unpin", requireUser, async (context) => {
    try {
      await store.setPinned(
        context.var.actor,
        context.req.param("agentId"),
        false,
      );
      await record(context, "bot.unpinned", context.req.param("agentId"));
      return context.body(null, 204);
    } catch (error) {
      return mapStoreError(context, error);
    }
  });

  /*
   * Issue this agent its callback credential, and show it once.
   *
   * A POST because it writes and because it replaces: calling it again rotates, which is how a leaked
   * token is retired. The token is in the response and nowhere else, ever again, and it is not written
   * to the audit payload either: a trail that records credentials is a credential store with worse
   * access control.
   */
  routes.post("/:agentId/callback-token", requireUser, async (context) => {
    try {
      const token = await store.issueCallbackToken(
        context.var.actor,
        context.req.param("agentId"),
      );
      // That one was issued, never what it is. A trail that records credentials is a credential
      // store with worse access control.
      await record(
        context,
        "bot.callback_token_issued",
        context.req.param("agentId"),
      );
      return context.json({ token }, 201);
    } catch (error) {
      return mapStoreError(context, error);
    }
  });

  /** Take it away. The agent may still hold a conversation; it may not reach anything outside one. */
  routes.delete("/:agentId/callback-token", requireUser, async (context) => {
    try {
      await store.revokeCallbackToken(
        context.var.actor,
        context.req.param("agentId"),
      );
      await record(
        context,
        "bot.callback_token_revoked",
        context.req.param("agentId"),
      );
      return context.body(null, 204);
    } catch (error) {
      return mapStoreError(context, error);
    }
  });

  routes.delete("/:agentId", requireUser, async (context) => {
    if (!context.req.param("agentId").trim()) {
      return context.json({ error: "A Bot id is required." }, 400);
    }
    try {
      await store.softDelete(context.var.actor, context.req.param("agentId"));
      await record(context, "bot.deleted", context.req.param("agentId"));
      return context.body(null, 204);
    } catch (error) {
      return mapStoreError(context, error);
    }
  });

  /**
   * Which Bots this Bot may hand work to.
   *
   * On the Bot's own screen rather than under the connector catalogue, because it is a fact about
   * this Bot and not about a vendor: the catalogue's entries have a fixed list of tools, and the
   * Bots a deployment has are whatever somebody made.
   *
   * `enabled` is reported separately from the grants, because the two fail differently. A grant with
   * the capability switched off is a row in the database that will never be read, and a screen that
   * offered it without saying so would be a switch wired to nothing.
   */
  routes.get("/:agentId/handoff", requireUser, async (context) => {
    const agentId = context.req.param("agentId");
    if (!agentId.trim()) {
      return context.json({ error: "A Bot id is required." }, 400);
    }
    try {
      // Asked of the store, so a Bot somebody may not see is "not found" here as everywhere else,
      // rather than a list of who it can reach.
      const agent = await store.get(context.var.actor, agentId);
      if (!agent)
        return context.json({ error: "Couldn't find that Bot." }, 404);
      return context.json({
        handoff: {
          enabled: handoff?.enabled ?? false,
          // Granting is an administrator's, the same as it is on every other grant.
          canGrant: context.var.actor.role === "admin",
          reachable: handoff ? await handoff.reachableFrom(agentId) : [],
          // Whether this Bot can hold such a grant at all; the write path refuses one that cannot,
          // and the screen should say so before a person flips switches that can only bounce.
          grantable: handoff?.canHandOn
            ? ((await handoff.canHandOn(agentId)) ?? false)
            : false,
        },
      });
    } catch (error) {
      return mapStoreError(context, error);
    }
  });

  return routes;
}

function boundedText(
  value: unknown,
  maximumLength: number,
  error: string,
): string | { ok: false; error: string } {
  if (typeof value !== "string") return { ok: false, error };
  const trimmed = value.trim();
  return trimmed.length > 0 && trimmed.length <= maximumLength
    ? trimmed
    : { ok: false, error };
}

function agentDto(actor: AgentActor, agent: AgentProfile) {
  return {
    id: agent.id,
    name: agent.name,
    title: agent.title,
    roleDescription: agent.roleDescription,
    avatarSeed: agent.avatarSeed,
    visibility: agent.visibility,
    hidden: agent.hidden,
    pinned: agent.pinned,
    systemOwned: agent.systemOwned,
    // Published so the edit form can show it. Safe to expose: it is an address the person supplied,
    // and any credential for it lives in the vault, never in this row.
    endpoint: agent.endpoint,
    hasAuth: agent.hasAuth,
    // Whether one exists, never what it is.
    hasCallbackToken: agent.hasCallbackToken,
    // What the owner asked for. Whether it is in effect is `isolationActive`, added by the route.
    isolated: agent.isolated,
    canManage: canManageAgent(actor, agent),
    // Ownership, kept separate from permission. `canManage` is also true for an administrator on
    // another user's coworker, so a roster that split "mine" on it would file other people's work
    // under yours, and only for administrators, who are the least likely to notice.
    mine: agent.ownerUserId === actor.id,
    assignedToMe: agent.assignedToMe ?? false,
  };
}

function mapStoreError(context: Context, error: unknown): Response {
  if (error instanceof AgentNotFoundError) {
    return context.json({ error: "Couldn't find that Bot." }, 404);
  }
  if (error instanceof AgentNotManageableError) {
    return context.json({ error: "You can't manage this Bot." }, 403);
  }
  if (error instanceof ProtectedAgentError) {
    return context.json(
      { error: "This Bot is built in and can't be changed." },
      403,
    );
  }
  if (error instanceof ManagedAgentUnavailableError) {
    return context.json({ error: error.message }, 400);
  }
  if (error instanceof AgentAssignedError) {
    return context.json({ error: error.message }, 409);
  }
  // Every route that can raise this records it first; this is the answer for any that is added later.
  if (error instanceof IsolationRefusedError) {
    return context.json(
      {
        error: error.message,
        ...(error.reason === "capability"
          ? { capability: "isolatedComputers" }
          : {}),
      },
      403,
    );
  }
  throw error;
}