pi-roundtable-web 0.24.2 → 0.25.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,21 @@ import type {
 	WorkspaceSave,
 } from "../api-types.ts";
 import type { Authenticated } from "../auth/authenticator.ts";
+import { type ConsolePresentation, message } from "../features.ts";
 import { json } from "../http.ts";
 import type { PushMutes } from "../push/mutes.ts";
-import { readLimited } from "../request-body.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,31 +55,59 @@ 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">;
 	/** Present when the schedules pane is served. */
 	schedules?: Pick<ScheduleStore, "all" | "remove">;
-	directory: Pick<AgentDirectory, "agent">;
+	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">;
 	/** Present when the workspace pane is served. */
 	workspace?: WorkspaceFiles;
@@ -89,19 +122,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 +203,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 +211,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,6 +256,42 @@ 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;
@@ -238,12 +302,17 @@ export class AppApi {
 				[
 					"session",
 					"rooms",
+					"folders",
 					"uploads",
 					"files",
 					"schedules",
 					"agents",
+					"groups",
+					"archive",
 					"models",
 					"workspace",
+					"prompts",
+					"skill-docs",
 				].includes(second ?? ""));
 		if (!mine) return undefined;
 		try {
@@ -305,6 +374,8 @@ export class AppApi {
 				models: await this.#options.team.usableModels(),
 			} satisfies ModelsView);
 		if (area === "rooms") return this.#rooms(request, parts, admission);
+		if (area === "folders")
+			return this.#layout.folders(request, parts, admission);
 		if (area === "uploads" && method === "POST" && !id) {
 			const owner = await this.#owner(admission);
 			return json(
@@ -321,8 +392,21 @@ export class AppApi {
 			return this.#file(id);
 		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.");
 	}
 
@@ -333,6 +417,8 @@ export class AppApi {
 			surface: this.#options.surface.surface,
 			auth: this.#options.authMode,
 			push: true,
+			...(this.#options.prompts ? { prompts: true } : {}),
+			...(this.#options.skills ? { skillEdit: true } : {}),
 			...(this.#options.quietHours
 				? { quietHours: this.#options.quietHours }
 				: {}),
@@ -352,7 +438,10 @@ export class AppApi {
 		const { rooms, log, cards, modes, mutes, conversations } = this.#options;
 		if (!key) {
 			if (method !== "GET") throw new HttpError(405, "Method not allowed.");
-			return json({ rooms: await rooms.list() } satisfies RoomsView);
+			return json({
+				rooms: await rooms.list(),
+				...(await this.#layout.view()),
+			} satisfies RoomsView);
 		}
 		const room = await rooms.resolve(key);
 		if (!room) throw notFound();
@@ -404,6 +493,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();
@@ -582,75 +677,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}`,
-		};
-	}
 }

package/src/app/skill-doc-routes.ts

@@ -0,0 +1,122 @@
+import type { SkillDocument, SkillRegistry } from "pi-roundtable";
+import { SkillConflictError } from "pi-roundtable";
+import type {
+	SkillConflict,
+	SkillDocCreate,
+	SkillDocSave,
+	SkillDocView,
+	SkillHistoryView,
+	SkillView,
+} from "../api-types.ts";
+import { json } from "../http.ts";
+import { bad, bodyOf, HttpError } from "./api-http.ts";
+import type { OwnerOf } from "./team-routes.ts";
+
+/** The largest body of a save: a SKILL.md of 12,000 characters may be four bytes each, with its frontmatter. */
+const MAX_SKILL_BYTES = 64 * 1024;
+
+export interface SkillDocApiOptions {
+	skills: Pick<
+		SkillRegistry,
+		"document" | "saveDocument" | "createDocument" | "documentHistory"
+	>;
+	/** The catalog the page lists, so a name it does not list is a 404 before the registry is asked. */
+	catalog(): SkillView[];
+}
+
+const viewOf = (document: SkillDocument): SkillDocView => ({
+	name: document.name,
+	source: document.source,
+	text: document.text,
+	hash: document.hash,
+	writable: document.writable,
+});
+
+/**
+ * The app's REST for a skill's SKILL.md: reading it whole, saving an agent-written skill's, making a
+ * skill and listing the versions kept. The frontmatter rules are the skill tools': the registry
+ * checks them, and a refusal is a 400 with its words. Every call is an owner's; a save names the
+ * hash it was edited from, and a skill that changed meanwhile answers 409 with what is there now.
+ */
+export class SkillDocApi {
+	readonly #options: SkillDocApiOptions;
+
+	constructor(options: SkillDocApiOptions) {
+		this.#options = options;
+	}
+
+	async handle(
+		request: Request,
+		parts: string[],
+		owner: OwnerOf,
+	): Promise<Response> {
+		const { method } = request;
+		const [, , name, action] = parts;
+		const { skills } = this.#options;
+		if (!name) {
+			if (method !== "POST") throw new HttpError(405, "Method not allowed.");
+			const speaker = await owner();
+			const body = await bodyOf(request, MAX_SKILL_BYTES);
+			if (typeof body.text !== "string") throw bad("text must be text.");
+			const made: SkillDocCreate = { text: body.text };
+			return json(
+				viewOf(await skills.createDocument(made.text, speaker.name)),
+				201,
+			);
+		}
+		// The tier is read before the name is looked up, so a person below the owner learns of no skill.
+		const speaker = await owner();
+		if (!this.#options.catalog().some((skill) => skill.name === name))
+			throw new HttpError(404, "There is no such skill.");
+		if (!action && method === "GET")
+			return json(viewOf(await skills.document(name)));
+		if (!action && method === "PUT") {
+			const body = await bodyOf(request, MAX_SKILL_BYTES);
+			const { text, baseHash } = body;
+			if (typeof text !== "string") throw bad("text must be text.");
+			if (typeof baseHash !== "string" || !/^[0-9a-f]{64}$/.test(baseHash))
+				throw bad("baseHash must be the hash the skill was read with.");
+			const save: SkillDocSave = { text, baseHash };
+			try {
+				return json(
+					viewOf(
+						await skills.saveDocument(
+							name,
+							save.text,
+							save.baseHash,
+							speaker.name,
+						),
+					),
+				);
+			} catch (error) {
+				if (error instanceof SkillConflictError) {
+					const refused = new HttpError(
+						409,
+						"This skill changed while you were editing it.",
+					);
+					return json(
+						{
+							error: refused.message,
+							conflict: "changed",
+							current: viewOf(error.current),
+						} satisfies SkillConflict,
+						refused.status,
+					);
+				}
+				throw error;
+			}
+		}
+		if (action === "history" && method === "GET" && parts.length === 4) {
+			return json({
+				versions: (await skills.documentHistory(name)).map((version) => ({
+					id: version.id,
+					text: version.text,
+					hash: version.hash,
+					by: version.by,
+					at: version.at.toISOString(),
+				})),
+			} satisfies SkillHistoryView);
+		}
+		throw new HttpError(404, "There is no such API.");
+	}
+}