pi-roundtable-web 0.25.0 → 0.26.1

package/src/api-types.ts

@@ -16,9 +16,24 @@ 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.
+ * The table is not among them: for a member it seats only the host rooms they may list.
+ */
+export const OWNER_ONLY_PANES = [
+	"overview",
+	"skills",
+	"connectors",
+	"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 +56,82 @@ 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 };
+}
+
+/**
+ * The icons a host may give a page or a kind of room: names from the console's own icon set. A
+ * name outside the list, or none, shows the default (a list for a page, no icon for a kind).
+ */
+export const HOST_ICONS = [
+	"chat",
+	"link",
+	"activity",
+	"users",
+	"megaphone",
+	"qr",
+	"settings",
+	"bell",
+	"file",
+	"list",
+	"shield",
+	"lock",
+	"sparkle",
+] as const;
+export type HostIconName = (typeof HOST_ICONS)[number];
+
+/**
+ * How a kind of host room words its two ways to write: `turn` is talking to the agent (the toggle's
+ * label, and the box's hint while it is on), `note` is a message for the room's people only.
+ */
+export interface SendWording {
+	note?: { placeholder?: string };
+	turn?: { label?: string; placeholder?: 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";
+	icon?: HostIconName;
+}
+
+/** A kind of host room, listed by its label. */
+export interface KindLinkView {
+	kind: string;
+	label: string;
+	icon?: HostIconName;
 }
 
 export type ChannelName =
@@ -300,6 +390,101 @@ 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;
+	/**
+	 * An internal note: written for the humans who read the room, never handed to the agent. Only
+	 * an `owner` message of an agent or group room that has `notes` can be one.
+	 */
+	note?: 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. */
@@ -324,6 +509,12 @@ export interface RoomView {
 	parent?: string;
 	/** A thread's room takes no messages from the page. */
 	readOnly: boolean;
+	/**
+	 * More than one person reads this agent or group room, so the composer offers `@AI` off: a
+	 * message sent with `mode: "note"` is kept for them and not given to the agent. Absent in a
+	 * room only one person reads.
+	 */
+	notes?: true;
 	/** A thread whose dispatch has ended; its room stays readable. */
 	closed?: boolean;
 	mode: RoomMode;
@@ -339,6 +530,18 @@ 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. */
@@ -360,6 +563,16 @@ export interface LayoutView {
 	folders: FolderView[];
 }
 
+/** `GET api/rooms/<key>` for a thread: its view, listed or dismissed from the list. */
+export interface RoomOneView {
+	room: RoomView;
+}
+
+/** What a dismissal removed from the room list: the finished threads that were listed. */
+export interface ThreadsDismissed {
+	dismissed: number;
+}
+
 export interface RoomsView extends LayoutView {
 	rooms: RoomView[];
 }
@@ -375,14 +588,22 @@ 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. */
@@ -419,6 +640,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;
@@ -799,7 +1099,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 =
@@ -816,8 +1121,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 or group room takes a `note` only where its view has `notes`. */
+			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 }
 	| {
@@ -839,6 +1163,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 }
@@ -882,7 +1208,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 =