pi-roundtable-web 0.7.19 → 0.9.0

package/src/conversations.ts

@@ -9,8 +9,12 @@ import {
 	statSync,
 } from "node:fs";
 import { join } from "node:path";
-import type { ChannelKey } from "pi-roundtable";
-import { textOf } from "pi-roundtable/kit";
+import {
+	type ChannelKey,
+	type ConversationRecord,
+	parseChannelKey,
+} from "pi-roundtable";
+import { channelSegment, textOf } from "pi-roundtable/kit";
 import type { TranscriptEntry } from "./api-types.ts";
 
 const FIRST_MESSAGE_CHARS = 80;
@@ -41,8 +45,11 @@ export interface ConversationFiles {
 	lastActive?: string;
 }
 
-/** The kinds of session directory the console reads. */
-export type StoredKind = "discord" | "group" | "mcp";
+/**
+ * The kinds of session directory the console reads: the three it recognises by name, and any
+ * other conversation the host's registry records.
+ */
+export type StoredKind = "discord" | "group" | "mcp" | "registered";
 
 /** An owner, agent, group-member, or outside-agent conversation found on disk. */
 export interface StoredConversation extends ConversationFiles {
@@ -52,9 +59,11 @@ export interface StoredConversation extends ConversationFiles {
 	id: string;
 	/** Group conversations only: the agent whose conversation inside the group this is. */
 	member?: string;
-	/** Outside-agent conversations only. */
+	/** Outside-agent and registered conversations only. */
 	firstMessage?: string;
 	startedAt?: string;
+	/** Registered conversations only: the name the registry gives it. */
+	title?: string;
 }
 
 /** The session directory a channel key names, or undefined when the key is not one the console reads. */
@@ -253,6 +262,41 @@ export function storedConversations(
 	);
 }
 
+/** The session directory of a conversation the registry records, by its key. */
+export function registeredDir(key: ChannelKey): string {
+	return channelSegment(key);
+}
+
+/**
+ * The conversations the host's registry records and the directory scan does not recognise, with
+ * their files; one whose first turn left no session file has nothing to read and is left out.
+ */
+export function registeredConversations(
+	sessionsDir: string,
+	records: readonly ConversationRecord[],
+	options: {
+		excluded: (key: ChannelKey) => boolean;
+		relayNotes: readonly string[];
+	},
+): StoredConversation[] {
+	const found: StoredConversation[] = [];
+	for (const record of records) {
+		if (parseKey(record.key) || options.excluded(record.key)) continue;
+		const dir = join(sessionsDir, registeredDir(record.key));
+		const files = conversationFiles(dir);
+		if (!files) continue;
+		found.push({
+			key: record.key,
+			kind: "registered",
+			id: parseChannelKey(record.key).id,
+			...files,
+			...opening(dir, options.relayNotes),
+			...(record.title === undefined ? {} : { title: record.title }),
+		});
+	}
+	return found;
+}
+
 /** The archive folders of a conversation, newest first. */
 export function archiveNames(dir: string): string[] {
 	const archiveDir = join(dir, "archive");

package/src/index.ts

@@ -18,6 +18,8 @@ export type {
 	OverviewView,
 	PaneName,
 	PartyView,
+	PrincipalName,
+	PrincipalsView,
 	SkillDetailView,
 	SkillView,
 	TranscriptEntry,
@@ -26,12 +28,15 @@ export type {
 } from "./api-types.ts";
 export { PANES } from "./api-types.ts";
 export type { CloudflareAccessOptions } from "./cloudflare-access.ts";
-export { cloudflareAccess } from "./cloudflare-access.ts";
+export {
+	cloudflareAccess,
+	cloudflareAccessIdentity,
+} from "./cloudflare-access.ts";
 /** Summary for a trusted host's separately stored party sessions. */
 export { conversationFiles as sessionSummary } from "./conversations.ts";
 export type { ConsoleFeatures, ConsolePresentation } from "./features.ts";
 export type { WebConsoleOptions } from "./options.ts";
 export { DEFAULT_RELAY_NOTE } from "./options.ts";
 export type { RequestVerifier, Verdict } from "./verifier.ts";
-export { admit, refuse } from "./verifier.ts";
+export { admit, admitAs, refuse } from "./verifier.ts";
 export { webConsole } from "./web-plugin.ts";

package/src/options.ts

@@ -14,8 +14,10 @@ export const DEFAULT_RELAY_NOTE =
 
 export interface WebConsoleOptions {
 	/**
-	 * Decides whether a request comes from the owner; required. `cloudflareAccess(...)` is the
-	 * built-in one. Without it the plugin refuses to start rather than serve without authentication.
+	 * Decides whether a request comes from someone the operator's proxy authenticated, and reports
+	 * who; required. `cloudflareAccess(...)` is the built-in one. Without it the plugin refuses to
+	 * start rather than serve without authentication. Only a person whose principal holds the owner
+	 * role gets in.
 	 */
 	verifier: RequestVerifier;
 	/** Host-specific data and actions, resolved against public plugin setup context. */
@@ -31,7 +33,11 @@ export interface WebConsoleOptions {
 	 * must carry it as their `Origin`, and the dashboard line links to it.
 	 */
 	origin: string;
-	/** The id memory notes are kept under: the owner's. Required when the `notes` pane is served. */
+	/**
+	 * Deprecated: the owner's principal that a verifier reporting no actor speaks for; default the
+	 * primary owner (the first of `access.owners`). The notes pane shows each visitor their own
+	 * notes, and any principal's on request.
+	 */
 	ownerId?: string;
 	/** The host's data directory, whose `sessions/` holds the conversations; default `./data`. */
 	dataDir?: string;
@@ -145,9 +151,9 @@ export function resolveOptions(options: WebConsoleOptions): ResolvedOptions {
 	}
 	const panes = checkPanes(options.panes);
 	const ownerId = options.ownerId?.trim();
-	if (panes.includes("notes") && !ownerId)
+	if (options.ownerId !== undefined && !ownerId)
 		fail(
-			"ownerId is required for the notes pane: it is the id the owner's memory is kept under. Set it, or leave `notes` out of panes",
+			"ownerId is empty. Leave it out: the console finds each visitor's principal, and a verifier that reports no actor speaks for the primary owner",
 		);
 	const title = options.title?.trim() ?? "Roundtable";
 	if (!title) fail("title is empty");

package/src/verifier.ts

@@ -1,6 +1,16 @@
+import type { ActorFacts } from "pi-roundtable";
+
 /** The verdict on one request: admitted, or refused with a reason for the log. */
 export type Verdict =
-	| { admitted: true }
+	| {
+			admitted: true;
+			/**
+			 * Who signed in, as the proxy vouched for them; the console finds their principal through
+			 * `IDENTITY` and admits only an owner. Without it, the request is taken as the primary
+			 * owner's, as before 0.9, and the console warns once.
+			 */
+			actor?: ActorFacts;
+	  }
 	| {
 			admitted: false;
 			/** Why, for the operator's log. It is never sent to the client, and it must not hold a secret. */
@@ -8,14 +18,22 @@ export type Verdict =
 	  };
 
 /**
- * Decides whether a request comes from the owner. The console asks it for every request under
- * its path, before anything else, and refuses with 403 when it says no, throws, or rejects.
- * A verifier reads the request's headers, which the operator's proxy set after authenticating the
- * owner, and must never trust a header a client can forge: see "Threat model" in the README.
+ * Decides whether a request comes from someone the operator's proxy authenticated, and who. The
+ * console asks it for every request under its path, before anything else, and refuses with 403
+ * when it says no, throws, or rejects; then it admits only a person whose principal holds the
+ * owner role. A verifier reads the request's headers, which the operator's proxy set after
+ * authenticating the person, and must never trust a header a client can forge: see "Threat model"
+ * in the README.
  */
 export type RequestVerifier = (request: Request) => Verdict | Promise<Verdict>;
 
+/** Admits the request without saying who it is from, as a verifier before 0.9 did. */
 export const admit = (): Verdict => ({ admitted: true });
+/** Admits the request as coming from the person these facts describe. */
+export const admitAs = (actor: ActorFacts): Verdict => ({
+	admitted: true,
+	actor,
+});
 export const refuse = (reason: string): Verdict => ({
 	admitted: false,
 	reason,

package/src/visitors.ts

@@ -0,0 +1,89 @@
+import type {
+	ActorFacts,
+	IdentityService,
+	Logger,
+	Principal,
+} from "pi-roundtable";
+
+/** Who a request the console admitted comes from: an owner's principal. */
+export interface Visitor {
+	principal: Principal;
+}
+
+/** The visitor of a request, or why it is refused, for the operator's log. */
+export type Identified = { visitor: Visitor } | { refusal: string };
+
+/** The reads of `IDENTITY` the console uses; none of them makes or changes a principal. */
+export type ConsoleIdentity = Pick<
+	IdentityService,
+	"principalOf" | "principal" | "tierOf" | "owners"
+>;
+
+export interface VisitorOptions {
+	/** Whom a request from a verifier that reports no actor stands for; default the primary owner. */
+	ownerId?: string;
+	logger: Logger;
+}
+
+/** The provider of the aliases 0.9 keeps for 0.8 ids; `IDENTITY.resolve` refuses it as no surface's. */
+const LEGACY_PROVIDER = "legacy";
+
+/** How many unlinked identities are remembered, so each is warned about once. */
+const WARNED_MAX = 100;
+
+/**
+ * Identifies the person behind each request the verifier admitted, by reading `IDENTITY` only, so
+ * a visitor never makes a principal: the principal their identity is linked to, who must hold the
+ * owner role. An identity linked to no one is refused on every host, however many owners it has:
+ * the verifier may vouch for members too, so only a link says whose an identity is. A verifier
+ * that reports no actor speaks for `ownerId`, default the primary owner, as in 0.8.
+ */
+export function consoleVisitors(
+	identity: ConsoleIdentity,
+	options: VisitorOptions,
+): (actor: ActorFacts | undefined) => Promise<Identified> {
+	const { logger } = options;
+	const warned = new Set<string>();
+	const warnOnce = (key: string, message: string) => {
+		if (warned.has(key) || warned.size >= WARNED_MAX) return;
+		warned.add(key);
+		logger.warn(`web-console: ${message}`);
+	};
+
+	const owner = async (id: string): Promise<Identified> => {
+		const principal = await identity.principal(id);
+		if (!principal) return { refusal: `there is no principal ${id}` };
+		if (principal.disabled) return { refusal: `principal ${id} is disabled` };
+		if ((await identity.tierOf(id)) !== "owner")
+			return { refusal: `principal ${id} holds no owner role` };
+		return { visitor: { principal } };
+	};
+
+	return async (actor) => {
+		if (!actor) {
+			warnOnce(
+				"",
+				"the verifier reports no actor, so the console takes every request it admits as the primary owner's. Have it report who signed in (cloudflareAccess does)",
+			);
+			const id = options.ownerId ?? (await identity.owners())[0]?.id;
+			return id === undefined
+				? { refusal: "the host has no owner" }
+				: owner(id);
+		}
+		const named = `${actor.provider}:${actor.subject}`;
+		if (actor.provider === LEGACY_PROVIDER)
+			return { refusal: `${named} is a 0.8 id, not an identity` };
+		let id: string | undefined;
+		try {
+			id = await identity.principalOf(named);
+		} catch {
+			return { refusal: "the verifier's actor is no identity" };
+		}
+		if (id !== undefined) return owner(id);
+		warnOnce(
+			named,
+			`${named} is linked to no principal, so the console refuses it. If it is an owner's, add "${named}" to that owner's access.owners[].identities, or run: roundtable principal link <owner's principal id> ${named}`,
+		);
+		return { refusal: `${named} is linked to no principal` };
+	};
+}

package/src/web-plugin.ts

@@ -1,6 +1,8 @@
 import {
 	AGENTS,
+	CONVERSATIONS,
 	definePlugin,
+	IDENTITY,
 	MEMORY,
 	type RoundtablePlugin,
 } from "pi-roundtable";
@@ -13,17 +15,20 @@ import {
 	resolveOptions,
 	type WebConsoleOptions,
 } from "./options.ts";
+import { consoleVisitors } from "./visitors.ts";
 
 /**
- * The owner-only web console: conversations, transcripts, memory notes, and the agent team,
- * served on a route of the host's listener and updated live. The options are checked here, so
- * a missing verifier or a bad setting throws when the config is loaded.
+ * The owners' web console: conversations, transcripts, memory notes, and the agent team, served
+ * on a route of the host's listener and updated live. Every request needs the verifier to vouch
+ * for the person and `IDENTITY` to name them an owner. The options are checked here, so a missing
+ * verifier or a bad setting throws when the config is loaded.
  */
 export function webConsole(options: WebConsoleOptions): RoundtablePlugin {
 	const settings = resolveOptions(options);
 	return definePlugin({
 		name: "web-console",
 		requires: [
+			IDENTITY,
 			...(settings.panes.includes("overview") ? [AGENTS] : []),
 			...(settings.panes.includes("notes") ? [MEMORY] : []),
 		],
@@ -45,6 +50,9 @@ async function build(settings: ResolvedOptions, context: Context) {
 	}
 	const team = services.find(AGENTS)?.team;
 	const connection = services.find(DISCORD)?.connection;
+	// Absent on a host without the registry: the console then lists conversations found by name only.
+	const registry = services.find(CONVERSATIONS);
+	const identity = services.get(IDENTITY);
 	const listeners: (() => void)[] = [];
 	const changed = () => {
 		for (const listener of listeners) listener();
@@ -61,10 +69,15 @@ async function build(settings: ResolvedOptions, context: Context) {
 		...(connection
 			? { channelName: (id: string) => connection.channelInfo(id) }
 			: {}),
-		...(settings.ownerId && settings.panes.includes("notes")
-			? { memory: services.get(MEMORY).forSpeaker(settings.ownerId) }
+		...(settings.panes.includes("notes")
+			? {
+					memoryOf: (principalId: string) =>
+						services.get(MEMORY).forSpeaker(principalId),
+				}
 			: {}),
+		people: identity,
 		...(settings.exclude ? { exclude: settings.exclude } : {}),
+		...(registry ? { registry } : {}),
 		relayNotes: settings.relayNotes,
 		changed,
 		logger,
@@ -76,6 +89,10 @@ async function build(settings: ResolvedOptions, context: Context) {
 		mount: settings.mount,
 		assets,
 		verifier: settings.verifier,
+		identify: consoleVisitors(identity, {
+			logger,
+			...(settings.ownerId ? { ownerId: settings.ownerId } : {}),
+		}),
 		origin: settings.origin,
 		pathRouting: settings.routing === "path",
 		...(settings.presentation ? { presentation: settings.presentation } : {}),