pi-roundtable-web 0.24.2 → 0.26.0

package/src/app/routes.ts

@@ -1,5 +1,4 @@
 import type {
-	AgentChange,
 	AgentDirectory,
 	AgentTeam,
 	AvatarStudio,
@@ -9,23 +8,22 @@ import type {
 	Logger,
 	ModeChange,
 	ScheduleStore,
+	SkillRegistry,
 	Speaker,
 } from "pi-roundtable";
-import { characterOf, PluginError } from "pi-roundtable";
-import { CharacterError, resolveCharacter } from "pi-roundtable/characters";
+import { PluginError } from "pi-roundtable";
+import { CharacterError } from "pi-roundtable/characters";
 import { AgentError } from "pi-roundtable/kit";
 import type {
-	AgentPatch,
-	AgentProfileView,
 	ApiError,
 	CharacterRefusal,
-	CharacterRequest,
 	MessagesView,
 	ModelsView,
 	RoomsView,
 	SchedulesView,
 	ScheduleView,
 	SessionView,
+	SkillView,
 	WorkspaceConflict,
 	WorkspaceNew,
 	WorkspaceRefusalBody,
@@ -34,14 +32,27 @@ import type {
 	WorkspaceSave,
 } from "../api-types.ts";
 import type { Authenticated } from "../auth/authenticator.ts";
+import { type ConsolePresentation, message } from "../features.ts";
+import type { Gate } from "../gate.ts";
+import type { HostApp } from "../host/host-app.ts";
+import type { RoomReads } from "../host/reads.ts";
+import { readsOf, withExpiredFiles } from "../host/room-views.ts";
 import { json } from "../http.ts";
+import type { ResolvedOptions } from "../options.ts";
 import type { PushMutes } from "../push/mutes.ts";
-import { readLimited } from "../request-body.ts";
+import { viewerOf, type WebAppRegistry } from "../web-app.ts";
+import { bad, bodyOf, HttpError, notFound } from "./api-http.ts";
 import type { CardLog } from "./card-log.ts";
 import { type FileDir, fileResponse, isFileId } from "./files.ts";
+import type { LayoutStore } from "./layout.ts";
+import { LayoutRoutes } from "./layout-routes.ts";
+import { PromptApi, type PromptApiOptions } from "./prompt-routes.ts";
 import { PAGE_LIMIT, type RoomLog } from "./room-log.ts";
 import type { Rooms } from "./rooms.ts";
+import { SkillDocApi } from "./skill-doc-routes.ts";
 import type { AppSurface } from "./surface.ts";
+import { TeamApi } from "./team-routes.ts";
+import type { WebThreads } from "./threads.ts";
 import { UploadRefusal, type Uploads } from "./uploads.ts";
 import {
 	EDIT_MAX_BYTES,
@@ -50,38 +61,82 @@ import {
 	WorkspaceRefusal,
 } from "./workspace-files.ts";
 
-/** The largest JSON body a write reads: 64 KiB. */
-const MAX_BODY_BYTES = 64 * 1024;
-/** The largest body of a character write: 4 KiB. */
-const MAX_CHARACTER_BYTES = 4 * 1024;
-
 export interface AppApiOptions {
+	/** The host's wording: a refusal reaches a client of the API in this locale when the catalog has it. */
+	presentation?: ConsolePresentation;
 	surface: AppSurface;
 	rooms: Rooms;
-	log: RoomLog;
-	cards: CardLog;
+	log: Pick<RoomLog, "page" | "lastOf" | "removeRoom">;
+	cards: Pick<CardLog, "during" | "removeRoom">;
 	uploads: Uploads;
 	/** Where stored files are read from. */
 	files: FileDir;
 	modes: Pick<ConversationModes, "set" | "peek">;
 	/** The rooms whose push the owners muted. */
-	mutes: Pick<PushMutes, "set">;
+	mutes: Pick<PushMutes, "set" | "setMany">;
+	/** The dispatch threads, which go with the room they hang under. */
+	threads: Pick<WebThreads, "under" | "removeUnder">;
+	/** The owners' shared arrangement of the room list: pins and folders. */
+	layout: LayoutStore;
 	conversations: Pick<ConversationPort, "startFresh">;
-	identity: Pick<IdentityService, "tierOf">;
+	identity: Pick<IdentityService, "principal">;
 	/** Present when the schedules pane is served. */
-	schedules?: Pick<ScheduleStore, "all" | "remove">;
-	directory: Pick<AgentDirectory, "agent">;
+	schedules?: Pick<ScheduleStore, "all" | "get" | "remove">;
+	directory: Pick<AgentDirectory, "agent" | "agents" | "group" | "groups">;
 	team: Pick<
 		AgentTeam,
-		"update" | "dress" | "usableModels" | "modelOf" | "defaultModel"
+		| "update"
+		| "promptHistory"
+		| "dress"
+		| "usableModels"
+		| "modelOf"
+		| "defaultModel"
+		| "createAgent"
+		| "archive"
+		| "restore"
+		| "remove"
+		| "createGroup"
+		| "updateGroup"
 	>;
+	/** Present when the host has the skills addon: the catalog an agent's skills are chosen from, and the change of what it carries. */
+	skills?: {
+		catalog(): SkillView[];
+		attach(
+			agent: string,
+			add: readonly string[],
+			remove: readonly string[],
+		): Promise<string[]>;
+		/** The registry's documents: a skill's SKILL.md read, saved and made, and its versions. */
+		documents: Pick<
+			SkillRegistry,
+			"document" | "saveDocument" | "createDocument" | "documentHistory"
+		>;
+	};
+	/** Present when the host has prompt documents (the prompts plugin): the main prompts the owner edits. */
+	prompts?: PromptApiOptions["prompts"];
 	avatars: Pick<AvatarStudio, "serve">;
+	/** The read cursors, for each room's unread count and who has read what. */
+	reads?: Pick<RoomReads, "unread" | "cursorOf" | "marks">;
+	/** Who may be served a file bound to a host room or a page. */
+	host?: Pick<HostApp, "mayRead">;
+	/** The name the app shows for a person. */
+	nameOf?(principalId: string): Promise<string>;
 	/** Present when the workspace pane is served. */
 	workspace?: WorkspaceFiles;
 	/** The mount, which a room's agent picture hangs under. */
 	mount: string;
 	/** How the console signs the person in, as the session reports it. */
 	authMode: SessionView["auth"];
+	/** Who the app admits; the session reports the person's tier only where it admits more than owners. */
+	admission?: ResolvedOptions["admission"];
+	/** The area handlers the pieces of the app plug in; without it the API is the owners' as in 0.25. */
+	registry?: Pick<WebAppRegistry, "areaFor">;
+	/** The onboarding gate; without it nobody is gated. */
+	gate?: Pick<Gate, "required">;
+	/** The tiers whose people may use push; default owners. */
+	pushTiers?: ResolvedOptions["push"]["tiers"];
+	/** Whether the yolo and long-running switches are served; `PUT rooms/<key>/mode` answers 404 without them. Default true. */
+	modeSwitches?: boolean;
 	/** The quiet hours of push, as the settings page shows them. */
 	quietHours?: NonNullable<SessionView["quietHours"]>;
 	/** Called after a change the other pages should refetch. */
@@ -89,19 +144,6 @@ export interface AppApiOptions {
 	logger: Logger;
 }
 
-class HttpError extends Error {
-	constructor(
-		readonly status: number,
-		message: string,
-	) {
-		super(message);
-	}
-}
-
-const bad = (message: string) => new HttpError(400, message);
-const notFound = () =>
-	new HttpError(404, "There is no such room, agent or file.");
-
 /** A refusal of the workspace pane as the HTTP error the owner reads. */
 function refusalOf(refusal: WorkspaceRefusal): HttpError {
 	const { status } = refusal;
@@ -183,33 +225,6 @@ export function partsOf(path: string): string[] | undefined {
 	}
 }
 
-async function bodyOf(
-	request: Request,
-	limit = MAX_BODY_BYTES,
-): Promise<Record<string, unknown>> {
-	const raw = await readLimited(request, limit);
-	if (!raw) throw new HttpError(413, "The body is too large.");
-	let value: unknown;
-	try {
-		value = JSON.parse(raw.toString("utf8"));
-	} catch {
-		throw bad("The body is not JSON.");
-	}
-	if (typeof value !== "object" || value === null || Array.isArray(value))
-		throw bad("The body is not an object.");
-	return value as Record<string, unknown>;
-}
-
-const optionalText = (
-	body: Record<string, unknown>,
-	key: string,
-): string | undefined => {
-	const value = body[key];
-	if (value === undefined) return undefined;
-	if (typeof value !== "string") throw bad(`${key} must be text.`);
-	return value;
-};
-
 /**
  * The owner app's REST under `<mount>/api/` and `<mount>/avatars/`. Every route is behind the
  * authenticator, which also checks the `Origin` of a write; a write also reads the person's tier
@@ -218,9 +233,44 @@ const optionalText = (
  */
 export class AppApi {
 	readonly #options: AppApiOptions;
+	readonly #team: TeamApi;
+	readonly #layout: LayoutRoutes;
+	readonly #prompts: PromptApi | undefined;
+	readonly #skillDocs: SkillDocApi | undefined;
 
 	constructor(options: AppApiOptions) {
 		this.#options = options;
+		this.#layout = new LayoutRoutes({
+			layout: options.layout,
+			mutes: options.mutes,
+			placeable: () => options.rooms.placeable(),
+			home: () => options.rooms.homeKey(),
+			owner: (admission) => this.#owner(admission),
+			changed: () => options.changed(),
+		});
+		this.#prompts = options.prompts
+			? new PromptApi({ prompts: options.prompts })
+			: undefined;
+		this.#skillDocs = options.skills
+			? new SkillDocApi({
+					skills: options.skills.documents,
+					catalog: () => options.skills?.catalog() ?? [],
+				})
+			: undefined;
+		this.#team = new TeamApi({
+			surface: options.surface.surface,
+			rooms: options.rooms,
+			directory: options.directory,
+			team: options.team,
+			skills: options.skills,
+			log: options.log,
+			cards: options.cards,
+			mutes: options.mutes,
+			modes: options.modes,
+			threads: options.threads,
+			layout: options.layout,
+			changed: () => options.changed(),
+		});
 	}
 
 	/** Answers a path of the app's, or undefined for any other. `rest` is what follows the mount. */
@@ -228,25 +278,76 @@ export class AppApi {
 		request: Request,
 		rest: string,
 		admission: Authenticated,
+	): Promise<Response | undefined> {
+		const response = await this.#answer(request, rest, admission);
+		return response && this.#options.presentation
+			? this.#worded(response, this.#options.presentation)
+			: response;
+	}
+
+	/** A refusal's `error` in the host's wording; the page words it again from the same catalog and finds the wording already there. */
+	async #worded(
+		response: Response,
+		presentation: ConsolePresentation,
+	): Promise<Response> {
+		if (response.status < 400) return response;
+		const body: unknown = await response
+			.clone()
+			.json()
+			.catch(() => undefined);
+		const error = (body as { error?: unknown } | undefined)?.error;
+		if (typeof error !== "string") return response;
+		const worded = message(presentation, error);
+		if (worded === error) return response;
+		const headers = new Headers(response.headers);
+		headers.delete("content-length");
+		return new Response(
+			JSON.stringify({ ...(body as object), error: worded }),
+			{
+				status: response.status,
+				headers,
+			},
+		);
+	}
+
+	async #answer(
+		request: Request,
+		rest: string,
+		admission: Authenticated,
 	): Promise<Response | undefined> {
 		const parts = partsOf(rest);
 		if (!parts) return undefined;
 		const [first, second] = parts;
+		const area =
+			first === "api" && second !== undefined
+				? this.#options.registry?.areaFor(second)
+				: undefined;
 		const mine =
+			area !== undefined ||
 			(first === "avatars" && parts.length === 2) ||
 			(first === "api" &&
 				[
 					"session",
 					"rooms",
+					"folders",
 					"uploads",
 					"files",
 					"schedules",
 					"agents",
+					"groups",
+					"archive",
 					"models",
 					"workspace",
+					"prompts",
+					"skill-docs",
 				].includes(second ?? ""));
 		if (!mine) return undefined;
 		try {
+			if (area)
+				return await area.handle(request, parts.slice(2), {
+					visitor: admission.visitor,
+					viewer: viewerOf(admission.visitor),
+				});
 			return await this.#route(request, parts, admission);
 		} catch (error) {
 			if (error instanceof HttpError || error instanceof UploadRefusal)
@@ -269,16 +370,13 @@ export class AppApi {
 		}
 	}
 
-	/** The owner who writes: their tier read again, as a speaker for the calls that need one. */
+	/** The owner who writes: the tier the request was admitted at, as a speaker for the calls that need one. */
 	async #owner(admission: Authenticated): Promise<Speaker> {
-		const { principal } = admission.visitor;
-		const tier = await this.#options.identity.tierOf(principal.id);
+		const { principal, tier, speakerId } = admission.visitor;
 		if (tier !== "owner")
 			throw new HttpError(403, "Only an owner may do this.");
 		return {
-			id: admission.actor
-				? `${admission.actor.provider}:${admission.actor.subject}`
-				: principal.id,
+			id: speakerId,
 			name: principal.displayName,
 			tier,
 			principalId: principal.id,
@@ -299,40 +397,67 @@ export class AppApi {
 				new Response("Not found", { status: 404 })
 			);
 		}
-		if (area === "session" && method === "GET") return this.#session(admission);
+		if (area === "session" && method === "GET")
+			return await this.#session(admission);
 		if (area === "models" && method === "GET")
 			return json({
 				models: await this.#options.team.usableModels(),
 			} satisfies ModelsView);
 		if (area === "rooms") return this.#rooms(request, parts, admission);
-		if (area === "uploads" && method === "POST" && !id) {
-			const owner = await this.#owner(admission);
+		if (area === "folders")
+			return this.#layout.folders(request, parts, admission);
+		// An upload is the sender's own, whoever they are; a file answers by the room it is bound to.
+		if (area === "uploads" && method === "POST" && !id)
 			return json(
-				await this.#options.uploads.receive(request, owner.principalId),
+				await this.#options.uploads.receive(
+					request,
+					admission.visitor.principal.id,
+				),
 			);
-		}
 		if (area === "uploads" && method === "DELETE" && id && !action) {
-			const owner = await this.#owner(admission);
-			if (!this.#options.uploads.discard(id, owner.principalId))
+			if (!this.#options.uploads.discard(id, admission.visitor.principal.id))
 				throw notFound();
 			return json({ ok: true });
 		}
 		if (area === "files" && method === "GET" && id && !action)
-			return this.#file(id);
+			return await this.#file(id, admission);
 		if (area === "workspace") return this.#workspace(request, parts, admission);
 		if (area === "schedules") return this.#schedules(method, id, admission);
-		if (area === "agents" && id)
-			return this.#agent(request, id, action, admission);
+		const owner = () => this.#owner(admission);
+		if (area === "agents") return this.#team.agents(request, parts, owner);
+		if (area === "groups") return this.#team.groups(request, parts, owner);
+		if (area === "archive" && method === "GET" && !id)
+			return this.#team.archived(owner);
+		if (area === "prompts") {
+			if (!this.#prompts)
+				throw new HttpError(404, "This host has no prompts to edit.");
+			return this.#prompts.handle(request, parts, owner);
+		}
+		if (area === "skill-docs") {
+			if (!this.#skillDocs)
+				throw new HttpError(404, "This host has no skills.");
+			return this.#skillDocs.handle(request, parts, owner);
+		}
 		throw new HttpError(404, "There is no such API.");
 	}
 
-	#session(admission: Authenticated): Response {
-		const { principal } = admission.visitor;
+	async #session(admission: Authenticated): Promise<Response> {
+		const { principal, tier } = admission.visitor;
+		const { admission: admits = "owners", gate } = this.#options;
+		const pushTiers = this.#options.pushTiers ?? ["owner"];
+		const owed =
+			admits === "access" && gate
+				? await gate.required(viewerOf(admission.visitor))
+				: [];
 		return json({
 			principal: { id: principal.id, name: principal.displayName },
 			surface: this.#options.surface.surface,
 			auth: this.#options.authMode,
-			push: true,
+			...(admits === "access" ? { tier } : {}),
+			...(owed.length > 0 ? { gate: owed } : {}),
+			...(pushTiers.includes(tier) ? { push: true as const } : {}),
+			...(this.#options.prompts ? { prompts: true } : {}),
+			...(this.#options.skills ? { skillEdit: true } : {}),
 			...(this.#options.quietHours
 				? { quietHours: this.#options.quietHours }
 				: {}),
@@ -350,9 +475,24 @@ export class AppApi {
 		const { method } = request;
 		const [, , key, action] = parts;
 		const { rooms, log, cards, modes, mutes, conversations } = this.#options;
+		// The agent rooms are the owners'; to anyone else this API does not exist.
+		if (admission.visitor.tier !== "owner") throw notFound();
 		if (!key) {
 			if (method !== "GET") throw new HttpError(405, "Method not allowed.");
-			return json({ rooms: await rooms.list() } satisfies RoomsView);
+			const listed = await rooms.list();
+			// What each room holds past this person's cursor; a room they never read starts from what it has now.
+			const unread = await this.#options.reads?.unread(
+				admission.visitor.principal.id,
+				listed.map((one) => one.key),
+				new Set(listed.map((one) => one.key)),
+			);
+			return json({
+				rooms: listed.map((one) => {
+					const count = unread?.get(one.key);
+					return count ? { ...one, unread: count } : one;
+				}),
+				...(await this.#layout.view()),
+			} satisfies RoomsView);
 		}
 		const room = await rooms.resolve(key);
 		if (!room) throw notFound();
@@ -372,17 +512,26 @@ export class AppApi {
 			// The cards stand among the messages by the time they opened; a page that has older
 			// messages leaves the cards before its first one to the older page.
 			const first = page.messages[0];
+			const { reads, nameOf } = this.#options;
+			const self = admission.visitor.principal.id;
+			const cursor = await reads?.cursorOf(room.key, self);
 			return json({
 				...page,
+				messages: withExpiredFiles(page.messages, this.#options.files),
 				cards: await cards.during(room.key, {
 					...(page.more && first ? { from: first.at } : {}),
 					...(beforeId === undefined ? {} : { before: beforeId }),
 				}),
+				...(reads && nameOf
+					? { reads: await readsOf(reads, room.key, self, nameOf) }
+					: {}),
+				...(cursor === undefined ? {} : { cursor }),
 			} satisfies MessagesView);
 		}
 		if (action === "mode" && method === "PUT" && parts.length === 4) {
 			// Only an agent's or group's room has modes; a thread runs no turn of the owner's.
-			if (room.readOnly) throw notFound();
+			if (room.readOnly || this.#options.modeSwitches === false)
+				throw notFound();
 			const owner = await this.#owner(admission);
 			const body = await bodyOf(request);
 			const change: ModeChange = {};
@@ -404,6 +553,12 @@ export class AppApi {
 			await conversations.startFresh(room.key);
 			return json({ ok: true });
 		}
+		if (
+			(action === "folder" || action === "pin") &&
+			method === "PUT" &&
+			parts.length === 4
+		)
+			return this.#layout.place(request, room, action, admission);
 		if (action === "mute" && method === "PUT" && parts.length === 4) {
 			// Only an agent's or group's room has a mute of its own; a thread's posts are its parent's business.
 			if (room.readOnly) throw notFound();
@@ -418,10 +573,20 @@ export class AppApi {
 		throw new HttpError(404, "There is no such API.");
 	}
 
-	#file(id: string): Response {
+	async #file(id: string, admission: Authenticated): Promise<Response> {
 		if (!isFileId(id)) throw notFound();
-		const meta = this.#options.files.meta(id);
-		const blob = this.#options.files.blob(id);
+		const { files, host } = this.#options;
+		// A file bound to a host room or page is for the people it is open to, owners too; every other stored file belongs to an agent room, which only owners read.
+		const bound = files.binding(id)?.room;
+		if (bound === undefined) {
+			if (admission.visitor.tier !== "owner") throw notFound();
+		} else if (
+			!host ||
+			!(await host.mayRead(viewerOf(admission.visitor), bound))
+		)
+			throw notFound();
+		const meta = files.meta(id);
+		const blob = files.blob(id);
 		if (!meta || !blob) throw notFound();
 		return fileResponse(meta, blob);
 	}
@@ -541,6 +706,18 @@ export class AppApi {
 		throw new HttpError(404, "There is no such API.");
 	}
 
+	/** Whether a schedule is the visitor's own: its creator id names their principal. */
+	async #ownSchedule(
+		createdById: string,
+		principalId: string,
+	): Promise<boolean> {
+		if (createdById === principalId) return true;
+		// A schedule from 0.8 names its creator by a user id that the backfill made a principal's id.
+		return (
+			(await this.#options.identity.principal(createdById))?.id === principalId
+		);
+	}
+
 	async #schedules(
 		method: string,
 		id: string | undefined,
@@ -548,11 +725,19 @@ export class AppApi {
 	): Promise<Response> {
 		const { schedules, rooms } = this.#options;
 		if (!schedules) throw new HttpError(404, "This pane is not served.");
+		const { tier, principal } = admission.visitor;
+		const owner = tier === "owner";
 		if (method === "GET" && !id) {
 			const all = await schedules.all();
 			const views: ScheduleView[] = [];
 			for (const schedule of all) {
-				const room = await rooms.resolve(schedule.channel);
+				// The owners see every schedule; anyone else sees their own, and no room of the owners.
+				if (
+					!owner &&
+					!(await this.#ownSchedule(schedule.createdById, principal.id))
+				)
+					continue;
+				const room = owner ? await rooms.resolve(schedule.channel) : undefined;
 				views.push({
 					id: schedule.id,
 					...(room ? { room: room.key } : {}),
@@ -572,9 +757,17 @@ export class AppApi {
 			return json({ schedules: views } satisfies SchedulesView);
 		}
 		if (method === "DELETE" && id) {
-			await this.#owner(admission);
 			const number = Number(id);
 			if (!Number.isInteger(number)) throw bad("The schedule id is a number.");
+			// Another person's schedule is not there to remove, for anyone but the owners.
+			if (!owner) {
+				const found = await schedules.get(number);
+				if (
+					!found ||
+					!(await this.#ownSchedule(found.createdById, principal.id))
+				)
+					throw new HttpError(404, "There is no such schedule.");
+			}
 			const removed = await schedules.remove(number);
 			if (!removed) throw new HttpError(404, "There is no such schedule.");
 			this.#options.changed();
@@ -582,75 +775,4 @@ export class AppApi {
 		}
 		throw new HttpError(405, "Method not allowed.");
 	}
-
-	async #agent(
-		request: Request,
-		name: string,
-		action: string | undefined,
-		admission: Authenticated,
-	): Promise<Response> {
-		const { directory, team } = this.#options;
-		const agent = directory.agent(name);
-		if (agent?.status !== "active") throw notFound();
-		if (!action && request.method === "GET") return json(this.#profile(name));
-		if (!action && request.method === "PATCH") {
-			await this.#owner(admission);
-			const body = await bodyOf(request);
-			const patch: AgentPatch = {};
-			for (const key of [
-				"displayName",
-				"prompt",
-				"model",
-				"thinking",
-			] as const) {
-				const value = optionalText(body, key);
-				if (value !== undefined) patch[key] = value;
-			}
-			const change: AgentChange = patch;
-			await team.update(name, change);
-			this.#options.changed();
-			return json(this.#profile(name));
-		}
-		if (action === "character" && request.method === "PUT") {
-			await this.#owner(admission);
-			const body = await bodyOf(request, MAX_CHARACTER_BYTES);
-			const { character } = body;
-			if (
-				typeof character !== "object" ||
-				character === null ||
-				Array.isArray(character)
-			)
-				throw bad("character must be an object.");
-			const asked: CharacterRequest = {
-				character: character as CharacterRequest["character"],
-			};
-			// `dress` words a refusal as an agent error; checking here first names the field.
-			resolveCharacter(asked.character, characterOf(agent));
-			await team.dress(name, asked.character);
-			this.#options.changed();
-			return json(this.#profile(name));
-		}
-		throw new HttpError(404, "There is no such API.");
-	}
-
-	#profile(name: string): AgentProfileView {
-		const { directory, team, rooms, surface } = this.#options;
-		const agent = directory.agent(name);
-		if (!agent) throw notFound();
-		const effective = team.modelOf(name);
-		return {
-			name: agent.name,
-			displayName: agent.displayName,
-			prompt: agent.prompt,
-			...(agent.model ? { model: agent.model } : {}),
-			...(agent.thinking ? { thinking: agent.thinking } : {}),
-			effective: {
-				model: effective.model,
-				thinking: String(effective.thinking),
-			},
-			avatar: rooms.avatarOf(agent),
-			character: characterOf(agent),
-			room: `${surface.surface}:agent.${agent.name}`,
-		};
-	}
 }