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.
/**
* The Bot profile's own routes: pause and resume, reset, notifications, update routing, Activity,
* and the attention badges the sidebar draws.
*
* EVERYTHING HERE IS THE CALLER'S OWN. Each route acts on the signed-in person's relationship with a
* Bot, never on the Bot for everybody: pausing a public coworker stops the work done in your name,
* and resetting it forgets what it knew about you. The Bot must be one the caller can reach, asked
* of the profile store the way every other Bot route asks; a Bot they cannot see is "not found".
*/
import type { Context, MiddlewareHandler } from "hono";
import { Hono } from "hono";
import type { ActivityStore } from "../activity/activity";
import type { AuditEventType, AuditStore } from "../audit";
import { recordAuditEvent } from "../audit";
import type { AppVariables } from "../auth/guards";
import {
type BotLifecycleStore,
type BotNotify,
UPDATE_KINDS,
UPDATE_TRANSPORTS,
type UpdateKind,
type UpdateTransport,
} from "./lifecycle";
import type { BotReset } from "./lifecycle-reset";
import type { AgentActor, AgentProfile } from "./profile-types";
import type { WakeUpStore } from "./wake-up";
/** The single-user developer's placeholder account, which has no users row to reference. */
const DEV_ACTOR_EMAIL = "[email protected]";
const NOTIFY_VALUES: readonly BotNotify[] = ["all", "needs_input", "none"];
export type BotLifecycleServices = {
lifecycle: BotLifecycleStore;
reset: BotReset;
activity: ActivityStore;
wakeUps: WakeUpStore;
profiles: {
get(actor: AgentActor, id: string): Promise<AgentProfile | null>;
};
auditStore?: AuditStore;
};
export function createBotLifecycleRoutes(
services: BotLifecycleServices,
requireUser: MiddlewareHandler<{ Variables: AppVariables }>,
) {
const { lifecycle, reset, activity, wakeUps, profiles, auditStore } =
services;
const routes = new Hono<{ Variables: AppVariables }>();
type C = Context<{ Variables: AppVariables }>;
const record = async (
context: C,
eventType: Extract<AuditEventType, `bot.${string}`>,
agentId: string,
payload: Record<string, unknown> = {},
) => {
if (!auditStore) return;
const actor = context.var.actor;
try {
await recordAuditEvent(auditStore, {
eventType,
targetType: "agent",
targetId: agentId,
...(actor?.id && actor.email !== DEV_ACTOR_EMAIL
? { actorUserId: actor.id }
: {}),
payload: { bot: agentId, actor: actor?.email ?? "unknown", ...payload },
});
} catch (error) {
console.error(
JSON.stringify({
type: "bot-audit-write-failed",
eventType,
agentId,
error: String(error),
}),
);
}
};
/** The Bot, if the caller may reach it; otherwise the route has already answered 404. */
const reachable = async (context: C): Promise<AgentProfile | Response> => {
const agentId = context.req.param("agentId") ?? "";
if (!agentId.trim())
return context.json({ error: "A Bot id is required." }, 400);
const agent = await profiles.get(context.var.actor, agentId);
if (!agent) return context.json({ error: "Couldn't find that Bot." }, 404);
return agent;
};
const body = async (context: C) =>
((await context.req.json().catch(() => null)) ?? {}) as Record<
string,
unknown
>;
/** Every Bot that needs the caller, or has something unread, or is paused by them. */
routes.get("/attention", requireUser, async (context) => {
const ownerUserId = context.var.actor.id;
const [counts, paused] = await Promise.all([
activity.attention(ownerUserId),
lifecycle.pausedFor(ownerUserId),
]);
const ids = [...new Set([...counts.map((row) => row.agentId), ...paused])];
const notify = await lifecycle.notifyFor(ownerUserId, ids);
const byId = new Map(counts.map((row) => [row.agentId, row]));
// Only Bots the caller can still reach: a count about a Bot they lost access to names it.
const bots = [];
for (const agentId of ids) {
const agent = await profiles.get(context.var.actor, agentId);
if (!agent) continue;
const row = byId.get(agentId);
bots.push({
agentId,
name: agent.name,
questions: row?.questions ?? 0,
approvals: row?.approvals ?? 0,
handoffs: row?.handoffs ?? 0,
unread: row?.unread ?? 0,
paused: paused.includes(agentId),
notify: notify[agentId] ?? "all",
});
}
return context.json({ bots });
});
routes.get("/routing", requireUser, async (context) =>
context.json({ routing: await lifecycle.routing(context.var.actor.id) }),
);
routes.put("/routing/:kind", requireUser, async (context) => {
const kind = context.req.param("kind") as UpdateKind;
if (!UPDATE_KINDS.includes(kind))
return context.json({ error: "Unknown kind of update." }, 400);
const { transports } = await body(context);
const value =
transports === "all"
? "all"
: Array.isArray(transports) &&
transports.every((transport) =>
UPDATE_TRANSPORTS.includes(transport as UpdateTransport),
)
? (transports as UpdateTransport[])
: null;
if (value === null)
return context.json(
{ error: "Choose slack, sms and push, or all of them." },
400,
);
await lifecycle.setRouting(context.var.actor.id, kind, value);
return context.json({
routing: await lifecycle.routing(context.var.actor.id),
});
});
routes.get("/:agentId/lifecycle", requireUser, async (context) => {
const agent = await reachable(context);
if (agent instanceof Response) return agent;
return context.json({
lifecycle: await lifecycle.get(context.var.actor.id, agent.id),
});
});
routes.post("/:agentId/pause", requireUser, async (context) => {
const agent = await reachable(context);
if (agent instanceof Response) return agent;
const stopped = await lifecycle.pause(context.var.actor.id, agent.id);
await record(context, "bot.paused", agent.id, { stoppedTurns: stopped });
return context.json({
lifecycle: await lifecycle.get(context.var.actor.id, agent.id),
stoppedTurns: stopped,
});
});
routes.post("/:agentId/resume", requireUser, async (context) => {
const agent = await reachable(context);
if (agent instanceof Response) return agent;
await lifecycle.resume(context.var.actor.id, agent.id);
await record(context, "bot.resumed", agent.id);
return context.json({
lifecycle: await lifecycle.get(context.var.actor.id, agent.id),
});
});
routes.put("/:agentId/notifications", requireUser, async (context) => {
const agent = await reachable(context);
if (agent instanceof Response) return agent;
const { notify } = await body(context);
if (!NOTIFY_VALUES.includes(notify as BotNotify))
return context.json({ error: "Choose all, needs_input or none." }, 400);
await lifecycle.setNotify(
context.var.actor.id,
agent.id,
notify as BotNotify,
);
await record(context, "bot.notifications_changed", agent.id, { notify });
return context.json({
lifecycle: await lifecycle.get(context.var.actor.id, agent.id),
});
});
/** The notice: what a reset would delete, per kind, before anything is. */
routes.get("/:agentId/reset", requireUser, async (context) => {
const agent = await reachable(context);
if (agent instanceof Response) return agent;
return context.json({
plan: await reset.plan(context.var.actor.id, agent.id),
});
});
routes.post("/:agentId/reset", requireUser, async (context) => {
const agent = await reachable(context);
if (agent instanceof Response) return agent;
const { confirm } = await body(context);
if (confirm !== true)
return context.json(
{ error: "A reset deletes data. Confirm it explicitly." },
400,
);
const deleted = await reset.execute(context.var.actor, agent.id);
await record(context, "bot.reset", agent.id, { deleted });
return context.json({ deleted });
});
routes.get("/:agentId/activity", requireUser, async (context) => {
const agent = await reachable(context);
if (agent instanceof Response) return agent;
return context.json({
activity: await activity.forBot(context.var.actor.id, agent.id),
});
});
routes.post(
"/:agentId/activity/handoffs/stop",
requireUser,
async (context) => {
const agent = await reachable(context);
if (agent instanceof Response) return agent;
const { id } = await body(context);
if (typeof id !== "string" || !id)
return context.json({ error: "Which delegated task?" }, 400);
const stopped = await activity.stopHandoff(
context.var.actor.id,
agent.id,
id,
);
if (!stopped)
return context.json(
{ error: "That delegated task is not running or queued." },
404,
);
await record(context, "bot.handoff_stopped", agent.id, {
hop: stopped.key,
to: stopped.toBotId,
});
return context.json({ stopped: true });
},
);
routes.post("/:agentId/follow-ups/cancel", requireUser, async (context) => {
const agent = await reachable(context);
if (agent instanceof Response) return agent;
const { id } = await body(context);
if (typeof id !== "string" || !id)
return context.json({ error: "Which follow-up?" }, 400);
const cancelled = await wakeUps.cancel(context.var.actor.id, agent.id, id);
if (!cancelled)
return context.json(
{ error: "That follow-up has already run or was cancelled." },
404,
);
return context.json({ cancelled: true });
});
return routes;
}