pi-roundtable-web 0.24.2 → 0.26.0

package/src/api-types.ts

@@ -16,9 +16,22 @@ export const PANES = [
 	"schedules",
 	"table",
 	"workspace",
+	"profile",
 ] as const;
 export type PaneName = (typeof PANES)[number];
 
+/** The panes only an owner is served: they show the whole host, which a member's view never does. */
+export const OWNER_ONLY_PANES = [
+	"overview",
+	"skills",
+	"connectors",
+	"table",
+	"workspace",
+] as const satisfies readonly PaneName[];
+
+/** A person's tier in the app, as `IDENTITY` gives it. */
+export type AppTier = "owner" | "admin" | "member";
+
 /** What the page needs before it can draw anything. */
 export interface ConfigView {
 	title: string;
@@ -41,7 +54,50 @@ export interface ConfigView {
 		surface: string;
 		/** The WebSocket subprotocol to offer. */
 		protocol: string;
+		/** False when the host leaves the yolo and long-running switches out (`modes: false`). */
+		modes?: false;
 	};
+	/** The visitor's tier. Sent only where the host admits more than its owners (`admission: "access"`). */
+	tier?: AppTier;
+	/** The steps still undone before the app opens; present only while the gate is closed. */
+	gate?: GateStepView[];
+	/** The host's pages that are not rooms, as far as this visitor may see them. */
+	pages?: PageLinkView[];
+	/** The kinds of host room this visitor may list. */
+	kinds?: KindLinkView[];
+	/** Web Push for this visitor's tier: who may subscribe, and (for an external sender) where. */
+	push?: { tiers: AppTier[]; key?: string; subscribe?: string };
+}
+
+/** A step of onboarding the visitor still owes. */
+export interface GateStepView {
+	id: string;
+	label: string;
+	help?: string;
+	/**
+	 * Set on the steps the app makes itself, so the page words them in its own language: `link`
+	 * for `link:<provider>` (with the account's label in `label`), `push` for the notifications step.
+	 */
+	builtin?: "link" | "push";
+	/** A required step gates the app; a nudge is shown and never gates. */
+	required: boolean;
+	/** The page where the person completes it. */
+	open: { page: string };
+	/** The person may waive it; the label and the confirmation are what they are shown. */
+	waiver?: { label: string; confirm: string };
+}
+
+/** A host page that is not a room, in the places the shell lists it. */
+export interface PageLinkView {
+	id: string;
+	label: string;
+	place: "main" | "settings" | "hidden";
+}
+
+/** A kind of host room, listed by its label. */
+export interface KindLinkView {
+	kind: string;
+	label: string;
 }
 
 export type ChannelName =
@@ -300,6 +356,96 @@ export interface RoomMessage {
 	/** ISO time. */
 	at: string;
 	live?: string;
+	/**
+	 * Host rooms: what kind of author wrote it (`external` text is untrusted and shown as plain
+	 * text) and the label the host gives that kind, such as "Customer". Absent on the app's own.
+	 */
+	authorKind?: HostAuthorKind;
+	authorLabel?: string;
+	/** Host rooms: the author's picture, never an outside URL. */
+	picture?: PictureRef;
+	/** The text was changed after it was stored. */
+	edited?: true;
+	/** Files of the message that were deleted by retention. */
+	expiredFiles?: number;
+}
+
+/** The kinds of author a host room's messages come from. */
+export type HostAuthorKind = "external" | "member" | "assistant" | "notice";
+
+/** A picture the page may draw: a stored file, a person's picture, or initials; never an outside URL. */
+export type PictureRef =
+	| { file: string }
+	| { principal: string }
+	| { initials: string; color: string };
+
+/** A button a host card or header offers, and the form it opens first. */
+export interface HostActionView {
+	id: string;
+	label: string;
+	style?: "primary" | "secondary" | "danger";
+	confirm?: string;
+	form?: FormSpecView;
+}
+
+export interface FormSpecView {
+	title: string;
+	submit: string;
+	fields: FormFieldView[];
+}
+
+export type FormFieldView =
+	| {
+			name: string;
+			label: string;
+			type: "text" | "textarea" | "url";
+			required?: boolean;
+			max?: number;
+			initial?: string;
+			hint?: string;
+	  }
+	| {
+			name: string;
+			label: string;
+			type: "select" | "multiselect";
+			required?: boolean;
+			options: { value: string; label: string }[];
+			/** The value or values chosen when the form opens; a `select` takes one. */
+			initial?: string | readonly string[];
+			/** The page offers a filter box over the options, for a long list. */
+			search?: boolean;
+	  };
+
+/** A card a host puts in its room; its buttons call the host's `act`. */
+export interface HostCardView {
+	id: string;
+	room: string;
+	title: string;
+	body: string;
+	tone?: "note" | "ok" | "warn" | "risk";
+	state?: "open" | "working" | "done" | "superseded" | "expired";
+	links?: { label: string; url: string }[];
+	/** Only the buttons this viewer may press. */
+	buttons?: HostActionView[];
+	/** ISO times. */
+	at: string;
+	updatedAt: string;
+}
+
+/** A person-addressed notice, as the bell shows it. */
+export interface NoticeView {
+	tag: string;
+	title: string;
+	body?: string;
+	open?:
+		| { room: string; message?: number }
+		| { page: string; query?: Record<string, string> };
+	urgency: "normal" | "high";
+	ackable: boolean;
+	/** ISO time. */
+	raisedAt: string;
+	/** This person has handled it. */
+	acked?: true;
 }
 
 /** One entry of the room list. */
@@ -310,8 +456,10 @@ export interface RoomView {
 	/** The agent's or group's name; a thread's id. */
 	name: string;
 	displayName: string;
-	/** The coordinator's room, where the page opens. */
+	/** The room where the page opens: the coordinator's, else the first active agent's. */
 	home: boolean;
+	/** The coordinator's room: the team's entry, which cannot be archived. */
+	coordinator?: true;
 	/** The agent's picture, a path under the mount, for notification icons; absent for groups and threads. */
 	avatar?: string;
 	/** An agent room's character; a group page looks its members' up in the agent rooms. */
@@ -337,9 +485,40 @@ export interface RoomView {
 	stoppable: boolean;
 	/** The newest stored message, if any. */
 	last?: RoomMessage;
+	/** Messages past this person's read cursor; absent when none. */
+	unread?: number;
+}
+
+/** Where one person has read a room up to, with the name the page shows for them. */
+export interface ReadMarkView {
+	principal: string;
+	name: string;
+	/** The id of the newest message they have read. */
+	upTo: number;
+	/** ISO time. */
+	at: string;
+}
+
+/** An owner-made folder of rooms, with its rooms in the owner's order. */
+export interface FolderView {
+	/** `folder.<uuid>`. */
+	id: string;
+	name: string;
+	/** Room keys in order. */
+	rooms: string[];
 }
 
-export interface RoomsView {
+/**
+ * The owners' shared arrangement of the room list: pinned rooms in their order, then the folders
+ * in theirs. A room is pinned, in one folder, or in neither; the rest are listed by latest activity.
+ */
+export interface LayoutView {
+	/** The pinned rooms' keys, in order. */
+	pins: string[];
+	folders: FolderView[];
+}
+
+export interface RoomsView extends LayoutView {
 	rooms: RoomView[];
 }
 
@@ -354,18 +533,30 @@ export interface MessagesView {
 	 * first; the page places each among the messages by `frame.at`.
 	 */
 	cards: ClosedCard[];
+	/** The other readers' cursors: how far each has read the room (the viewer's own is `cursor`). */
+	reads?: ReadMarkView[];
+	/** The viewer's own read cursor before they opened the room; absent when they never read it. */
+	cursor?: number;
 }
 
 /** Who the page is signed in as. */
 export interface SessionView {
 	principal: PrincipalName;
 	surface: string;
-	/** How the console signs the person in; the page offers Log out under `password`. */
-	auth: "none" | "password" | "verifier";
+	/** How the console signs the person in; the page offers Log out under `password` and `oidc`. */
+	auth: "none" | "password" | "verifier" | "oidc";
+	/** The visitor's tier. Sent only where the host admits more than its owners (`admission: "access"`). */
+	tier?: AppTier;
+	/** The steps still undone before the app opens; present only while the gate is closed. */
+	gate?: GateStepView[];
 	/** When the credential lapses, if it does. */
 	expiresAt?: string;
 	/** Web Push is available: the app serves the rooms and a key for it. */
 	push?: true;
+	/** The host has prompt documents the owner edits (`api/prompts`). */
+	prompts?: true;
+	/** The host has the skills addon, so an agent-written skill's SKILL.md can be edited and made here (`api/skill-docs`). */
+	skillEdit?: true;
 	/** When an agent's post and a notice are not pushed (a card still is); absent = at any hour. */
 	quietHours?: {
 		/** `HH:MM`, where the window begins. */
@@ -394,6 +585,85 @@ export interface PushDevicesView {
 	devices: PushDeviceView[];
 }
 
+/** A test push was queued; the device's receipt for `tag` completes the push step. */
+export interface PushTestView {
+	tag: string;
+}
+
+/** The person's own push preferences. */
+export interface PushPrefsView {
+	/** No push for a normal notice from `start` to `end` on the clock of `timeZone`; absent = none set. */
+	quiet?: { start: string; end: string; timeZone: string };
+}
+
+/** The person's notices that are not resolved, newest first, and the count the app icon shows. */
+export interface NoticesView {
+	notices: NoticeView[];
+	badge: number;
+}
+
+/** One account the person may link, as the profile page shows it. */
+export interface LinkView {
+	provider: string;
+	label: string;
+	/** What linking it is for this deployment: `required` gates the app, `nudge` asks; absent = optional. */
+	step?: "required" | "nudge";
+	/** Providers to link first, and those of them not linked yet (`issue` is refused until none is left). */
+	requires: string[];
+	blockedBy: string[];
+	linked?: {
+		displayName?: string;
+		/** ISO time. */
+		linkedAt: string;
+		/** The configuration or the CLI made the link, so it cannot be removed here. */
+		locked?: true;
+	};
+	pending?: {
+		request: string;
+		/** ISO time. */
+		expiresAt: string;
+		redeemedBy?: { displayName: string; picture?: PictureRef };
+	};
+}
+
+export interface LinksView {
+	links: LinkView[];
+}
+
+/** The code a person puts into the other service to prove an account. */
+export interface LinkIssuedView {
+	code: string;
+	request: string;
+	/** ISO time. */
+	expiresAt: string;
+	instructions: string;
+}
+
+/** How the person is shown, and which of their accounts they may pick to show. */
+export interface ProfileView {
+	name: string;
+	/** The account the name comes from; absent when it is the person's own name. */
+	source?: string;
+	/** A picture is served at `api/people/<principal>/picture`. */
+	picture: boolean;
+	principal: string;
+	tier?: AppTier;
+	/** The accounts the person linked that can name them; the page shows these as the choice. */
+	sources: { provider: string; label: string }[];
+}
+
+/** A step of onboarding as the page of steps shows it. */
+export interface OnboardingStepView extends GateStepView {
+	done: boolean;
+	waived: boolean;
+}
+
+export interface OnboardingView {
+	steps: OnboardingStepView[];
+	/** Push on the person's devices: how many are subscribed and when one last reported back. */
+	push: { devices: number; lastReceiptAt?: string; waived: boolean };
+}
+
 /** A schedule, labelled by the room it belongs to or else its channel. */
 export interface ScheduleView {
 	id: number;
@@ -445,6 +715,193 @@ export interface AgentPatch {
 	thinking?: string;
 }
 
+/** One change of a prompt, as `GET api/agents/<name>/prompt-history` and `GET api/prompts/<id>/history` list them, newest first. */
+export interface PromptVersionView {
+	id: number;
+	/** `set` put new text in force; `revert` took a document back to its file version. */
+	action: "set" | "revert";
+	/** The text in force after the change; for a revert, the file version it went back to. */
+	text: string;
+	/** The text the change replaced. */
+	previous: string;
+	/** Who made it. */
+	by: string;
+	/** ISO time. */
+	at: string;
+}
+
+export interface PromptHistoryView {
+	versions: PromptVersionView[];
+}
+
+/** A prompt document in the list of `GET api/prompts`: the owner-editable texts the host registered. */
+export interface PromptSummary {
+	id: string;
+	label: string;
+	description?: string;
+	/** The owner's text is in force and is not the file version. */
+	differs: boolean;
+	/** Who set it and when (ISO), while an override is in force. */
+	override?: { by: string; at: string };
+	/** Why the file version cannot be read; the document cannot be changed until it can, and the others are unaffected. */
+	broken?: string;
+}
+
+export interface PromptsView {
+	documents: PromptSummary[];
+}
+
+/** `GET api/prompts/<id>`: the document with its text in force and its file version. */
+export interface PromptView extends PromptSummary {
+	/** The text in force. */
+	text: string;
+	/** The file version, which `revert` returns to. */
+	fileText: string;
+	/** The most characters a save may have. */
+	maxChars: number;
+}
+
+/** The body of `PUT api/prompts/<id>`: the new text, and the text it was edited from. */
+export interface PromptSave {
+	text: string;
+	base: string;
+}
+
+/** The body of `POST api/prompts/<id>/revert`: the text in force that the owner saw when they asked. */
+export interface PromptRevert {
+	base: string;
+}
+
+/** A 409: the document is not as the writer saw it. */
+export interface PromptConflict extends ApiError {
+	conflict: "changed";
+	current: PromptView;
+}
+
+/** A skill's SKILL.md as `GET api/skill-docs/<name>` answers: the whole file, with the hash a save names. */
+export interface SkillDocView {
+	name: string;
+	source: SkillView["source"];
+	text: string;
+	hash: string;
+	/** An agent-written skill; the others are read-only here, for the reason their source gives. */
+	writable: boolean;
+}
+
+/** The body of `PUT api/skill-docs/<name>`: the whole file, and the hash it was edited from. */
+export interface SkillDocSave {
+	text: string;
+	baseHash: string;
+}
+
+/** The body of `POST api/skill-docs`, which makes a skill from a whole SKILL.md. */
+export interface SkillDocCreate {
+	text: string;
+}
+
+/** A 409: the skill is not as the writer saw it. */
+export interface SkillConflict extends ApiError {
+	conflict: "changed";
+	current: SkillDocView;
+}
+
+export interface SkillVersionView {
+	id: number;
+	text: string;
+	hash: string;
+	by: string;
+	/** ISO time. */
+	at: string;
+}
+
+export interface SkillHistoryView {
+	versions: SkillVersionView[];
+}
+
+/**
+ * The body of `POST api/agents`, which makes an agent: the fields of the `agent_create` tool, with
+ * its model and thinking level. `name` is permanent (lowercase letters, digits and dashes, 1 to 32).
+ * `task` is its opening task; without it the agent only exists. The 201 answer is its profile.
+ */
+export interface AgentCreate {
+	name: string;
+	displayName: string;
+	prompt: string;
+	model?: string;
+	thinking?: string;
+	task?: string;
+	/** Fields of its look; any left out come from the look its role suggests. */
+	character?: CharacterInput;
+	/** Skills it carries, as the Skills pane names them. */
+	skills?: string[];
+}
+
+/** A skill as the agent sheet offers it: the host's catalog, and whether this agent carries it. */
+export interface SkillChoiceView {
+	name: string;
+	description?: string;
+	source: "builtin" | "linked" | "written" | "package";
+	/** Built-in skills are carried by every agent and cannot be taken off. */
+	builtin: boolean;
+	carried: boolean;
+	/** Why its file cannot be read, for a skill that is listed but broken. */
+	missing?: string;
+}
+
+/** `GET api/agents/<name>/skills` and the answer of `PUT`: every skill the host has. */
+export interface AgentSkillsView {
+	skills: SkillChoiceView[];
+}
+
+/** The body of `PUT api/agents/<name>/skills`: the same fields as the `agent_skills` tool. */
+export interface AgentSkillsChange {
+	add?: string[];
+	remove?: string[];
+}
+
+/** A group as the app edits it. */
+export interface GroupProfileView {
+	name: string;
+	displayName: string;
+	/** Its members, by agent name, in speaking-tie order. */
+	members: string[];
+	/** The member who answers when nobody else fits. */
+	host: string;
+	room: string;
+}
+
+/** The body of `POST api/groups`; the host is the first member unless given. The 201 answer is the group. */
+export interface GroupCreate {
+	name: string;
+	displayName: string;
+	members: string[];
+	host?: string;
+}
+
+/** The body of `PATCH api/groups/<name>`; `members` is the whole new list. */
+export interface GroupPatch {
+	displayName?: string;
+	members?: string[];
+	host?: string;
+}
+
+/** An archived agent or group, kept with its history until it is restored or deleted. */
+export interface ArchivedEntry {
+	kind: "agent" | "group";
+	name: string;
+	displayName: string;
+	/** An agent's picture, a path under the mount. */
+	avatar?: string;
+	character?: CharacterSpec;
+	/** A group's members that are still on the team. */
+	members?: string[];
+}
+
+/** `GET api/archive`. */
+export interface ArchiveView {
+	entries: ArchivedEntry[];
+}
+
 /** The body of `PUT api/agents/<name>/character`: at most 4 KiB. */
 export interface CharacterRequest {
 	character: CharacterInput;
@@ -587,7 +1044,12 @@ export type RefusalCode =
 	| "unknown_upload"
 	| "empty"
 	| "too_long"
-	| "not_accepted";
+	| "not_accepted"
+	/** A required onboarding step stands undone, so the frame is not taken yet. */
+	| "gated";
+
+/** The values of a form a host action opened. */
+export type FormInput = Readonly<Record<string, string | readonly string[]>>;
 
 /** What the page sends: one JSON object per WebSocket text message. */
 export type ClientFrame =
@@ -604,8 +1066,27 @@ export type ClientFrame =
 			text: string;
 			/** Files uploaded with `POST api/uploads`, by the `id` each returned. */
 			uploads?: string[];
+			/** Host rooms: a `note` only records, a `turn` is also delivered to the host's claim. Default `turn`; an agent room takes only `turn`. */
+			mode?: "note" | "turn";
 	  }
 	| { type: "stop"; room: string }
+	/** Host rooms: follow a room's frames. At most 200 at once; the viewer must be able to read it. */
+	| { type: "subscribe"; room: string }
+	| { type: "unsubscribe"; room: string }
+	/** A host room's or page's action: a card's button, a header action, a form. */
+	| {
+			type: "act";
+			id: string;
+			room?: string;
+			page?: string;
+			action: string;
+			card?: string;
+			input?: FormInput;
+	  }
+	/** The person handled a notice. */
+	| { type: "ack"; tag: string }
+	/** The person has read a room up to this message (a cursor never moves back). */
+	| { type: "read"; room: string; upTo: number }
 	| { type: "approval"; prompt: string; approved: boolean }
 	| { type: "answer"; prompt: string; answer: PromptAnswer }
 	| {
@@ -627,6 +1108,8 @@ export type ServerFrame =
 			name: string;
 			/** The most files one message carries and the most bytes of one. */
 			uploads: { perMessage: number; maxBytes: number };
+			/** The required steps the person still owes, when there are any: the socket then carries only the gate and their notices. */
+			gate?: GateStepView[];
 	  }
 	/** The message `id` was taken into `room`; `message` is how it was stored. */
 	| { type: "accepted"; id: string; room: string; message: RoomMessage }
@@ -670,7 +1153,33 @@ export type ServerFrame =
 	/** Yolo mode approved a held call by itself. */
 	| { type: "auto_approved"; room: string; tool: string; action: string }
 	/** The team or the room list may differ: refetch. */
-	| { type: "changed" };
+	| { type: "changed" }
+	/** A host room's message, edit or removal, and its cards; sent to the sockets subscribed to the room. */
+	| { type: "host_message"; room: string; message: RoomMessage }
+	| { type: "host_edited"; room: string; message: RoomMessage }
+	| { type: "host_removed"; room: string; id: number }
+	| { type: "host_card"; room: string; card: HostCardView }
+	/** A host room's header or access may differ: refetch it. */
+	| { type: "room_changed"; room: string }
+	/** The list of a kind of host room may differ: refetch it. */
+	| { type: "list_changed"; kind: string }
+	| { type: "page_changed"; page: string }
+	| { type: "notice"; notice: NoticeView }
+	| { type: "notice_resolved"; tag: string }
+	/** The count the app icon shows: notices not handled. */
+	| { type: "badge"; count: number }
+	/** The steps still undone; empty when the gate opened. */
+	| { type: "gate"; steps: GateStepView[] }
+	/** Someone read a room up to a message; `name` and `at` let the page show them without asking. */
+	| {
+			type: "read";
+			room: string;
+			principal: string;
+			name: string;
+			upTo: number;
+			/** ISO time. */
+			at: string;
+	  };
 
 /** A turn's live view, as the core reports it. */
 export type AppProgress =

package/src/app/api-http.ts

@@ -0,0 +1,66 @@
+import { readLimited } from "../request-body.ts";
+
+/** The largest JSON body a write reads: 64 KiB. */
+export const MAX_BODY_BYTES = 64 * 1024;
+
+export class HttpError extends Error {
+	constructor(
+		readonly status: number,
+		message: string,
+	) {
+		super(message);
+	}
+}
+
+export const bad = (message: string) => new HttpError(400, message);
+export const notFound = () =>
+	new HttpError(404, "There is no such room, agent or file.");
+
+export 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>;
+}
+
+export 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;
+};
+
+export const requiredText = (
+	body: Record<string, unknown>,
+	key: string,
+): string => {
+	const value = body[key];
+	if (typeof value !== "string" || value.trim() === "")
+		throw bad(`${key} must be text.`);
+	return value;
+};
+
+/** A list of text, or undefined when the body does not name it. */
+export const optionalList = (
+	body: Record<string, unknown>,
+	key: string,
+): string[] | undefined => {
+	const value = body[key];
+	if (value === undefined) return undefined;
+	if (!Array.isArray(value) || value.some((one) => typeof one !== "string"))
+		throw bad(`${key} must be a list of text.`);
+	return value as string[];
+};