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.
import type { MiddlewareHandler } from "hono";
import { Hono } from "hono";
import type { BotAccessCheck } from "../agents/profile-policy";
import type { AuditStore } from "../audit";
import { recordAuditEvent } from "../audit";
import type { AppVariables } from "../auth/guards";
import { requireAdmin } from "../auth/guards";
import { DATA_FUNCTIONS, dataFunction } from "./functions";
import {
SandboxedNotFoundError,
SandboxedPublicationRefusedError,
type SandboxedStore,
} from "./sandboxed";
import {
ComponentNotFoundError,
type ComponentStore,
SandboxedPublicationRequiredError,
} from "./store";
/**
* 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]";
/**
* Granting, publishing and asking whether a Bot may use a component.
*
* Reading is open to any signed-in person; changing is not. Which components a Bot holds is what the
* surface in front of that person is built from, and what a Bot may do is not a secret from the
* person talking to it. Deciding it is an administrator's job.
*
* The decision endpoint is the part that matters. The app already knows what it registered, so
* asking again before every render looks redundant, and is not. The list of tools a run is offered
* is a snapshot taken when that run started, so a grant revoked one second later is still in the
* model's hands. Asking at call time is what makes "revoke it and watch it go" true rather than
* nearly true, and it is where a refusal becomes a row somebody can see.
*/
export function createComponentRoutes(
store: ComponentStore,
requireUser: MiddlewareHandler<{ Variables: AppVariables }>,
auditStore: AuditStore | undefined,
/**
* Whether the caller may act as the Bot they named. What a Bot may draw, and the data a drawing
* reads, are facts about that Bot; an administrator granting one is a separate question and stays
* behind `requireAdmin`.
*/
canUseBot: BotAccessCheck,
/**
* The source half of a playground component's publication.
*
* The generic switch is the only publication UI for both kinds, so this route owns the choice to
* delegate. The component store still refuses a generic write for a sandboxed row, which keeps a
* caller that reaches `publish` directly from creating the same half-published state.
*/
sandboxedStore?: SandboxedStore,
) {
const routes = new Hono<{ Variables: AppVariables }>();
const audit = async (
context: { var: AppVariables },
eventType: Parameters<typeof recordAuditEvent>[1]["eventType"],
targetId: string,
payload: Record<string, unknown>,
) => {
if (!auditStore) return;
const actor = context.var.actor;
await recordAuditEvent(auditStore, {
eventType,
targetType: "component",
targetId,
...(actor?.id && actor.email !== DEV_ACTOR_EMAIL
? { actorUserId: actor.id }
: {}),
payload: { actor: actor?.email ?? "unknown", ...payload },
});
};
/** Everything a person needs to see the whole grant surface at once. */
routes.get("/", requireUser, async (context) =>
context.json({ components: await store.list() }),
);
/**
* A build announcing what it can draw.
*
* The build knows what exists; this deployment decides what it may do. A component is an ordinary
* React file, so the only thing that can truthfully enumerate them is the app that compiled them.
* A second list kept here would be a copy to keep in step, and the first thing to fall out of it.
* Drop a file in and it appears here, published, and any Bot may draw it until somebody says
* otherwise.
*
* Additive only, and not an administrator action: any signed-in person's browser announces it on
* load, and it cannot change who may use a component, its publication state or its description.
*/
routes.put("/catalogue", requireUser, async (context) => {
const body = (await context.req.json().catch(() => null)) as {
components?: unknown;
} | null;
const entries = Array.isArray(body?.components) ? body.components : null;
if (!entries) {
return context.json({ error: "A list of components is required." }, 400);
}
/*
* All or nothing, and a 400 names the entry. This used to drop malformed entries and
* answer 200 with whatever was left, so a deploy that typo'd `kind` as an object or
* sent a blank `description` got a success response while publishing nothing: `{added: []}`
* is also what "already in sync" looks like. The operator found out from a missing
* component, not from the API. A build announcing an empty catalogue sends `[]`, which
* still syncs to nothing and answers 200.
*/
const valid: {
name: string;
title: string;
kind: string;
description: string;
}[] = [];
for (const [index, entry] of entries.entries()) {
if (!entry || typeof entry !== "object") {
return context.json(
{
error: `Component at index ${index} needs a name, a title, a kind and a description.`,
},
400,
);
}
const { name, title, kind, description } = entry as Record<
string,
unknown
>;
if (
typeof name !== "string" ||
!name.trim() ||
typeof title !== "string" ||
!title.trim() ||
typeof kind !== "string" ||
!kind.trim() ||
typeof description !== "string" ||
!description.trim()
) {
return context.json(
{
error: `Component at index ${index} needs a name, a title, a kind and a description.`,
},
400,
);
}
// Trimmed, because that is the string the guard above just approved. A component's `name` is
// its identity -- `syncCatalogue` compares it against what is already published, `decide` and
// `listForAgent` look it up by it, and a grant names it -- so publishing " weatherPanel "
// adds a second component beside `weatherPanel` that nobody has granted and no Bot can be
// held back from by the name people use.
valid.push({
name: name.trim(),
title: title.trim(),
kind: kind.trim(),
description: description.trim(),
});
}
const { added } = await store.syncCatalogue(valid);
// Only arrivals are recorded. Announcing happens on every page load, and a row per load would
// bury the trail it is written into.
for (const name of added) {
await audit(context, "component.published", name, {
note: "First seen in a build, published and available to every Bot.",
});
}
return context.json({ added });
});
/**
* What one Bot holds. Polled by the app, which turns it into the tools that Bot is offered.
*
* Deliberately says nothing about the components this Bot does NOT hold. A list of everything it
* is missing would be a list the surface could accidentally register.
*/
routes.get("/for-agent/:agentId", requireUser, async (context) => {
const agentId = context.req.param("agentId");
if (!(await canUseBot(context.var.actor, agentId))) {
return context.json({ error: "There is no such Bot." }, 404);
}
return context.json({ components: await store.listForAgent(agentId) });
});
/**
* May this Bot use this component, right now?
*
* A POST because it writes: a refusal is recorded. Answering 200 with `allowed: false` rather than
* 403 is deliberate, the caller is the app asking a question on the Bot's behalf, and it is not
* itself forbidden from asking. The refusal travels in the body, where the handler turns it into
* something the model reads.
*/
routes.post("/:name/decision", requireUser, async (context) => {
const name = context.req.param("name");
const body = (await context.req.json().catch(() => null)) as {
agentId?: unknown;
functions?: unknown;
} | null;
const agentId =
typeof body?.agentId === "string" ? body.agentId.trim() : "";
if (!agentId) {
return context.json({ error: "The Bot is required." }, 400);
}
// Asked before the grant is, because the grant belongs to the Bot and says nothing about who is
// asking on its behalf.
if (!(await canUseBot(context.var.actor, agentId))) {
return context.json({ error: "There is no such Bot." }, 404);
}
/*
* Every entry, or a 400. This used to filter non-strings out, so
* `{"functions": [123, null, {}]}` became `[]`, the loop below never ran, and a
* governance question about X and Y was answered `allowed: true` because X and Y
* were not strings. A caller asking "may it call these" must get a verdict about the
* ones it named, not about none of them. Absent still means none.
*/
const rawFunctions = body?.functions;
if (
rawFunctions !== undefined &&
(!Array.isArray(rawFunctions) ||
rawFunctions.some(
(entry) => typeof entry !== "string" || !entry.trim(),
))
) {
return context.json(
{ error: "Functions must be a list of function names." },
400,
);
}
const functions = (
Array.isArray(rawFunctions) ? rawFunctions : []
) as string[];
const decision = await store.decide(name, agentId);
if (!decision.allowed) {
await audit(context, "component.refused", name, {
bot: agentId,
reason: decision.reason,
});
return context.json({ allowed: false, reason: decision.reason });
}
/*
* The data the component will read, decided here as well.
*
* Both decisions are enforced at `/call`, but that runs while the component renders, after
* whoever asked for it has been answered. A caller that says which functions the component
* needs gets one verdict covering what it will do, rather than one covering only its name.
*/
for (const functionName of functions) {
if (await store.mayCall(name, functionName)) continue;
const reason = `${name} can't use the function ${functionName}. An admin has to give it to this component.`;
await audit(context, "component.function_refused", name, {
bot: agentId,
function: functionName,
reason,
});
return context.json({ allowed: false, reason });
}
return context.json({ allowed: true });
});
/** The data functions this build ships, for an administrator deciding what to grant. */
routes.get("/functions", requireUser, (context) =>
context.json({
functions: DATA_FUNCTIONS.map((entry) => ({
name: entry.name,
description: entry.description,
reads: entry.reads,
})),
}),
);
/**
* A component fetching its own data.
*
* Permission is enforced here. A compiled React component has
* the whole application and could call any endpoint directly, so an allow-list held beside it in
* the browser is documentation. The only place that can refuse is the place holding the data.
*
* Two decisions are enforced: whether this Bot may use the component at all, and whether the
* component may call this particular function. Passing one is not passing the other.
*/
routes.post("/:name/call", requireUser, async (context) => {
const name = context.req.param("name");
const body = (await context.req.json().catch(() => null)) as {
function?: unknown;
args?: unknown;
agentId?: unknown;
} | null;
const functionName =
typeof body?.function === "string" ? body.function : "";
const agentId = typeof body?.agentId === "string" ? body.agentId : "";
if (!functionName || !agentId) {
return context.json(
{ error: "The function and the Bot are both required." },
400,
);
}
// A string `args` would reach `fn.run` and fail as a 502 data error instead of a malformed
// call. Arrays and prototype-polluted objects are refused for the same reason.
if (
body?.args !== undefined &&
(typeof body.args !== "object" ||
body.args === null ||
Array.isArray(body.args) ||
Object.getPrototypeOf(body.args) !== Object.prototype)
) {
return context.json(
{ error: "Function arguments must be an object." },
400,
);
}
// Before the grant, and before anything runs. This is the route that executes, so borrowing a
// Bot here borrows whatever its components were granted.
if (!(await canUseBot(context.var.actor, agentId))) {
return context.json({ error: "There is no such Bot." }, 404);
}
const refuse = async (reason: string) => {
await audit(context, "component.function_refused", name, {
bot: agentId,
function: functionName,
reason,
});
return context.json({ allowed: false, reason });
};
// The component itself, first. A component this Bot may not use may not read on its behalf.
const decision = await store.decide(name, agentId);
if (!decision.allowed) return refuse(decision.reason);
const fn = dataFunction(functionName);
if (!fn) {
// Named separately from a refusal so an administrator is not sent looking for a grant to give
// for something this build does not have.
return refuse(
`There is no data function called ${functionName} in this deployment.`,
);
}
if (!(await store.mayCall(name, functionName))) {
return refuse(
`${name} can't use the function ${functionName}. An admin has to give it to this component.`,
);
}
try {
const data = await store.callFunction(
functionName,
(body?.args ?? {}) as Record<string, unknown>,
);
await audit(context, "component.function_called", name, {
bot: agentId,
function: functionName,
reads: fn.reads,
});
return context.json({ allowed: true, data });
} catch (error) {
// A function that threw is not a refusal and must not read as one: nothing was forbidden, the
// read failed. Recorded as its own thing so a broken query is not filed as a policy event.
await audit(context, "component.function_failed", name, {
bot: agentId,
function: functionName,
failure: error instanceof Error ? error.message : "The read failed.",
});
return context.json(
{ allowed: true, error: "That data could not be read." },
502,
);
}
});
routes.post("/:name/functions", requireUser, async (context) => {
const forbidden = requireAdmin(context);
if (forbidden) return forbidden;
const name = context.req.param("name");
const body = (await context.req.json().catch(() => null)) as {
function?: unknown;
} | null;
const functionName =
typeof body?.function === "string" ? body.function : "";
if (!functionName || !dataFunction(functionName)) {
return context.json(
{ error: "A function this deployment ships is required." },
400,
);
}
try {
await store.grantFunction(name, functionName, context.var.actor.email);
} catch (error) {
if (error instanceof ComponentNotFoundError) {
return context.json({ error: error.message }, 404);
}
throw error;
}
await audit(context, "component.function_granted", name, {
function: functionName,
});
return context.json({ granted: true });
});
routes.delete("/:name/functions/:function", requireUser, async (context) => {
const forbidden = requireAdmin(context);
if (forbidden) return forbidden;
const name = context.req.param("name");
const functionName = context.req.param("function");
// An empty function name would revoke zero rows yet answer `revoked:true` with an audit row
// naming nothing. Refused at the edge like the grant path.
if (!functionName.trim()) {
return context.json({ error: "A function is required." }, 400);
}
try {
await store.revokeFunction(name, functionName);
} catch (error) {
if (error instanceof ComponentNotFoundError) {
return context.json({ error: error.message }, 404);
}
throw error;
}
await audit(context, "component.function_revoked", name, {
function: functionName,
});
return context.json({ revoked: true });
});
routes.post("/:name/grants", requireUser, async (context) => {
const forbidden = requireAdmin(context);
if (forbidden) return forbidden;
const name = context.req.param("name");
const body = (await context.req.json().catch(() => null)) as {
agentId?: unknown;
} | null;
// A whitespace-only id is truthy and would be written as a grant row naming nothing.
const agentId =
typeof body?.agentId === "string" ? body.agentId.trim() : "";
if (!agentId) {
return context.json({ error: "The Bot is required." }, 400);
}
try {
await store.grant(name, agentId);
} catch (error) {
if (error instanceof ComponentNotFoundError) {
return context.json({ error: error.message }, 404);
}
throw error;
}
await audit(context, "component.granted", name, { bot: agentId });
return context.json({ granted: true });
});
routes.delete("/:name/grants/:agentId", requireUser, async (context) => {
const forbidden = requireAdmin(context);
if (forbidden) return forbidden;
const name = context.req.param("name");
const agentId = context.req.param("agentId");
// Revoking `" "` would delete zero rows yet answer `revoked:true` with an audit row.
if (!agentId.trim()) {
return context.json({ error: "The Bot is required." }, 400);
}
try {
await store.revoke(name, agentId, context.var.actor.email);
} catch (error) {
if (error instanceof ComponentNotFoundError) {
return context.json({ error: error.message }, 404);
}
throw error;
}
await audit(context, "component.revoked", name, { bot: agentId });
return context.json({ revoked: true });
});
routes.post("/:name/publication", requireUser, async (context) => {
const forbidden = requireAdmin(context);
if (forbidden) return forbidden;
const name = context.req.param("name");
const body = (await context.req.json().catch(() => null)) as {
published?: unknown;
} | null;
/*
* A real boolean, not truthiness. This used to read `body?.published !== false`, so an
* empty body, invalid JSON, `{}`, `"no"`, `0` and `null` all evaluated to true and
* *published* the component with a 200 and a `component.published` audit row. A toggle
* that publishes on malformed input fails open on the endpoint that decides what every
* Bot may draw, and the sibling toggles (`PUT /routines/:id/enabled`, channel pin/busy)
* all answer 400 on non-boolean. Only an explicit true or false moves anything.
*/
if (typeof body?.published !== "boolean") {
return context.json({ error: "published must be true or false." }, 400);
}
const published = body.published;
let recordedBySource = false;
try {
if (published) {
await store.publish(name, context.var.actor.email);
} else {
await store.unpublish(name, context.var.actor.email);
}
} catch (error) {
if (error instanceof SandboxedPublicationRequiredError) {
if (!sandboxedStore) {
return context.json(
{
error:
"The playground source is unavailable, so the component was not published.",
},
409,
);
}
try {
if (published) {
await sandboxedStore.publish(name, context.var.actor.email);
} else {
await sandboxedStore.unpublish(name, context.var.actor.email);
}
recordedBySource = true;
} catch (sourceError) {
if (sourceError instanceof SandboxedPublicationRefusedError) {
return context.json({ error: sourceError.message }, 409);
}
if (sourceError instanceof SandboxedNotFoundError) {
return context.json({ error: sourceError.message }, 404);
}
throw sourceError;
}
} else if (error instanceof ComponentNotFoundError) {
return context.json({ error: error.message }, 404);
} else {
throw error;
}
}
if (recordedBySource) return context.json({ published });
await audit(
context,
published ? "component.published" : "component.unpublished",
name,
{},
);
return context.json({ published });
});
/**
* Edit the draft. Changes nothing a model can see until it is published, which is the point of
* having a draft at all.
*/
routes.put("/:name/draft", requireUser, async (context) => {
const forbidden = requireAdmin(context);
if (forbidden) return forbidden;
const name = context.req.param("name");
const body = (await context.req.json().catch(() => null)) as {
description?: unknown;
} | null;
const description =
typeof body?.description === "string" ? body.description.trim() : "";
if (!description) {
return context.json({ error: "A description is required." }, 400);
}
try {
await store.saveDraft(name, description, context.var.actor.email);
} catch (error) {
if (error instanceof ComponentNotFoundError) {
return context.json({ error: error.message }, 404);
}
throw error;
}
await audit(context, "component.draft_saved", name, {});
return context.json({ saved: true });
});
return routes;
}