pi-roundtable 0.8.0 → 0.9.1

package/src/index.ts

@@ -20,8 +20,14 @@ export {
 	AGENT_SERVER_PLUGIN,
 	AGENT_TEAM_SERVICE,
 } from "./core/builtin/agent-server.ts";
+export type {
+	AccessConfig,
+	AccessOwnerConfig,
+	AccessTierConfig,
+} from "./core/config/access.ts";
 export type {
 	AdapterConfig,
+	BackgroundConfig,
 	DiscordConfig,
 	Pronouns,
 	RoundtableConfig,
@@ -30,6 +36,7 @@ export type {
 export type {
 	Admission,
 	AttachmentRef,
+	BackgroundRunsAs,
 	BackgroundTarget,
 	BackgroundTurn,
 	ChannelClaim,
@@ -93,6 +100,7 @@ export {
 	AgentRunError,
 	ConfigError,
 	DelegationError,
+	IdentityError,
 	MemoryError,
 	ScheduleError,
 } from "./core/domain/errors.ts";
@@ -101,17 +109,11 @@ export type {
 	InterimPosts,
 	InterimTextMode,
 } from "./core/domain/interim.ts";
-export type {
-	Approval,
-	AskOption,
-	OwnerAnswer,
-	OwnerPrompts,
-	OwnerQuestion,
-} from "./core/domain/owner-prompts.ts";
-export type { TurnRequest } from "./core/domain/ports.ts";
+export type { TurnConversation, TurnRequest } from "./core/domain/ports.ts";
 export type { TurnProgress } from "./core/domain/progress.ts";
 export type { DrainOptions } from "./core/drain.ts";
 export {
+	HostStoppingError,
 	JudgeError,
 	MigrationError,
 	NotLinkedError,
@@ -133,9 +135,39 @@ export type {
 	WebSocketSendResult,
 } from "./core/http/websocket.ts";
 export type { Locale } from "./core/i18n/index.ts";
+export type {
+	AccessOwner,
+	AccessRules,
+	AccessTier,
+} from "./core/identity/access-policy.ts";
+export type { ActorFacts } from "./core/identity/actor-facts.ts";
+export type { IdentityService } from "./core/identity/identity-service.ts";
+export type {
+	IdentityLink,
+	IdentityRef,
+	LinkSource,
+	Principal,
+	RoleGrant,
+	RoleSource,
+} from "./core/identity/principal-store.ts";
+export { SYSTEM_PRINCIPAL } from "./core/identity/principal-store.ts";
+export type {
+	Approval,
+	AskOption,
+	OwnerAnswer,
+	OwnerPrompts,
+	OwnerQuestion,
+	PromptScope,
+	Prompts,
+} from "./core/interactions/prompts.ts";
+export { promptScope } from "./core/interactions/prompts.ts";
 export type { JudgeModel } from "./core/judging/model-judge.ts";
 export type { LogEntry, LogFn, Logger } from "./core/log.ts";
 export type { ThinkingLevel, ThinkingSetting } from "./core/models.ts";
+export {
+	PERSONAL_TARGET,
+	type PerPrincipalLimits,
+} from "./core/modules/background/personal-target.ts";
 export type {
 	DelegationJob,
 	DelegationOutcome,
@@ -184,6 +216,7 @@ export type {
 	LinkedSessions,
 	Persona,
 	PluginContext,
+	PluginIdentity,
 	PromptSection,
 	PromptTurn,
 	RoundtablePlugin,
@@ -194,6 +227,11 @@ export type {
 	TurnEvent,
 	TurnProgressEvent,
 } from "./core/plugin.ts";
+export type {
+	DirectChannelProvider,
+	DirectChannels,
+	DirectReach,
+} from "./core/presence/direct-channels.ts";
 export {
 	attachReplyFile,
 	REPLY_FILE_LIMITS,
@@ -223,6 +261,7 @@ export {
 	BACKGROUND_TURNS,
 	CONVERSATIONS,
 	DELEGATION,
+	IDENTITY,
 	MEMORY,
 	PRECHECKS,
 	RUNTIME,
@@ -233,6 +272,7 @@ export type {
 	AgentTurnScope,
 	ChannelKey,
 	SessionContext,
+	SessionConversation,
 	SessionPlan,
 	SessionTool,
 	SessionToolSnapshot,

package/src/kit/compaction.ts

@@ -12,3 +12,16 @@ export {
 	HARD_COMPACT_TOKENS,
 	SOFT_COMPACT_TOKENS,
 } from "../core/runtime/compaction-tiers.ts";
+export type { MemoryView } from "../core/runtime/extensions/private-memory.ts";
+export {
+	hidesPrivateExchange,
+	memoryProjection,
+	privateCompaction,
+	summaryProjection,
+} from "../core/runtime/extensions/private-memory.ts";
+export {
+	bridgeHistoryHidesMemory,
+	carriesMemory,
+	MEMORY_TURN_ENTRY,
+	recordMemoryTurn,
+} from "../core/runtime/reader-history.ts";

package/src/kit/index.ts

@@ -18,13 +18,22 @@ export type {
 	CompactionEngine,
 	CompactionHistory,
 	LatestCompaction,
+	MemoryView,
 } from "./compaction.ts";
 export {
+	bridgeHistoryHidesMemory,
 	COMPACT_HEADROOM_TOKENS,
 	CompactionTiers,
+	carriesMemory,
 	compactionEngine,
 	HARD_COMPACT_TOKENS,
+	hidesPrivateExchange,
+	MEMORY_TURN_ENTRY,
+	memoryProjection,
+	privateCompaction,
+	recordMemoryTurn,
 	SOFT_COMPACT_TOKENS,
+	summaryProjection,
 } from "./compaction.ts";
 export { scrubDiagnostic } from "./diagnostics.ts";
 export type {
@@ -122,6 +131,7 @@ export type {
 	DashboardBoard,
 	DelegationWorker,
 	GroupMessage,
+	Notifier,
 	OwnerNotifier,
 	SpeakerFacts,
 	SpeakerPolicy,

package/src/kit/support.ts

@@ -13,7 +13,7 @@ export type {
 export type { Backlog, GroupMessage } from "../core/agents/agent-rules.ts";
 export type { AgentOps } from "../core/agents/agent-tools.ts";
 export type { ThreadHost } from "../core/discord/dispatch-threads.ts";
-export type { OwnerNotifier } from "../core/domain/ports.ts";
+export type { Notifier, OwnerNotifier } from "../core/domain/ports.ts";
 export type { ThinkingPicker } from "../core/models.ts";
 export type { DelegationWorker } from "../core/modules/delegation/delegator.ts";
 export type { AgentChannelLookup } from "../core/modules/schedules/schedules.ts";

package/src/testing.ts

@@ -3,8 +3,8 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { SQL } from "bun";
-import { agentClaim, OWNER_TARGET } from "./core/agents/agent-claim.ts";
-import { DISCORD } from "./core/builtin/discord.ts";
+import { agentClaim } from "./core/agents/agent-claim.ts";
+import { DISCORD, type DiscordServices } from "./core/builtin/discord.ts";
 import type {
 	ConversationPort,
 	InboundMessage,
@@ -24,7 +24,10 @@ import type {
 	CommandRegistrar,
 	InteractionContribution,
 } from "./core/discord/interaction-module.ts";
-import { OwnerGuard, ownerRootCommand } from "./core/discord/owner-command.ts";
+import {
+	commandGuard,
+	ownerRootCommand,
+} from "./core/discord/owner-command.ts";
 import type {
 	PendingConfirmation,
 	ReplyFile,
@@ -32,10 +35,12 @@ import type {
 import { NotLinkedError, PluginError } from "./core/errors.ts";
 import { EventBus } from "./core/events.ts";
 import type { HoldCheck } from "./core/holds.ts";
+import { contactsOf } from "./core/identity/identity-view.ts";
 import type { OwnerIdentity } from "./core/identity.ts";
 import { ConfirmationJudge } from "./core/judging/confirmation-judge.ts";
 import { silentLogger } from "./core/log.ts";
 import { ConversationBackgroundTurns } from "./core/modules/background/background-turns.ts";
+import { PERSONAL_TARGET } from "./core/modules/background/personal-target.ts";
 import type {
 	Contribution,
 	HostEnv,
@@ -69,10 +74,12 @@ import {
 	type AgentServer,
 	BACKGROUND_TURNS,
 	CONVERSATIONS,
+	IDENTITY,
 	RUNTIME,
 } from "./core/services.ts";
 import type { ChannelKey, SessionContext } from "./core/sessions.ts";
-import { type Speaker, speakerPolicy } from "./core/speakers.ts";
+import { type Speaker, THE_SPEAKER } from "./core/speakers.ts";
+import { mapIdentity } from "./core/testing/map-identity.ts";
 import { type ToolTierTable, toolTiers } from "./core/tool-tiers.ts";
 
 // Fixtures for plugin tests.
@@ -107,6 +114,7 @@ export type {
 } from "./core/testing/recording-logger.ts";
 export { recordingLogger } from "./core/testing/recording-logger.ts";
 export type {
+	SurfaceContractAnswerer,
 	SurfaceContractFailure,
 	SurfaceContractSubject,
 	SurfaceObservation,
@@ -155,20 +163,30 @@ export interface FakeDiscord {
 /**
  * A `DISCORD` service for a plugin that adds slash commands, without a Discord connection: the
  * plugin's `commands.add` calls are recorded, and `compose()` shows the tree Discord would get.
- * `rootCommand` is the root command's name, `roundtable` by default. Only `commands` and `guard` are given; reading another member throws.
+ * `rootCommand` is the root command's name, `roundtable` by default. `channelContext` is what
+ * `DISCORD.channelContext` answers, by default no context, as on a host with it off. Only
+ * `commands`, `guard`, and `channelContext` are given; reading another member throws.
  */
 export function fakeDiscord(
-	options: { ownerId?: string; rootCommand?: string } = {},
+	options: {
+		ownerId?: string;
+		rootCommand?: string;
+		channelContext?: DiscordServices["channelContext"];
+	} = {},
 ): FakeDiscord {
 	const collection = new CommandCollection();
 	const { rootCommand = "roundtable" } = options;
-	const guard = new OwnerGuard(
-		options.ownerId ?? "owner",
-		silentLogger(),
-		rootCommand,
-	);
+	const guard = commandGuard({
+		ownerId: options.ownerId ?? "owner",
+		root: rootCommand,
+		logger: silentLogger(),
+	});
 	return {
-		service: servicePair(DISCORD, { commands: collection.registrar, guard }),
+		service: servicePair(DISCORD, {
+			commands: collection.registrar,
+			guard,
+			channelContext: options.channelContext ?? (async () => undefined),
+		}),
 		commands: collection.registrar,
 		guard,
 		added: () => collection.added(),
@@ -201,7 +219,9 @@ export interface TestPluginOptions {
 	 * host supplies anyway: `BACKGROUND_TURNS`, the real background turns over the test's router,
 	 * and, once `AGENTS` is given, its `approvals` (the real confirmation judge over
 	 * `providers.judge`, when the test gives a judge). Giving `AGENTS` a `team` adds the agent
-	 * server's own claim to the router, answering as the host's would for the `owner`.
+	 * server's own claim to the router, answering as the host's would for the `owner`. The router
+	 * resolves who wrote each message through a given `IDENTITY`; without one only the `owner` is
+	 * anyone, at the owner tier, their principal their id.
 	 */
 	services?: readonly ServicePair[];
 	/**
@@ -333,6 +353,7 @@ export async function testPlugin(
 			(router ?? unlinked("conversations")).handle(message),
 		background: async (turn) =>
 			(router ?? unlinked("conversations")).background(turn),
+		runsAs: async (turn) => (router ?? unlinked("conversations")).runsAs(turn),
 		target: (name) => (router ?? unlinked("conversations")).target(name),
 		startFresh: async (channel) =>
 			(router ?? unlinked("conversations")).startFresh(channel),
@@ -344,6 +365,8 @@ export async function testPlugin(
 		owns: (channel) => (router ?? unlinked("conversations")).owns(channel),
 		takesBackground: (channel) =>
 			(router ?? unlinked("conversations")).takesBackground(channel),
+		takesSystemReports: (channel) =>
+			(router ?? unlinked("conversations")).takesSystemReports(channel),
 		...options.conversations,
 	};
 	const surfaces = surfacePort(() =>
@@ -463,7 +486,7 @@ export async function testPlugin(
 			}),
 		);
 	services.checkRequires();
-	const context: Omit<PluginContext, "services"> = {
+	const context: Omit<PluginContext, "services" | "directChannels"> = {
 		logger,
 		env,
 		sessions: () => linked ?? unlinked("sessions"),
@@ -496,13 +519,17 @@ export async function testPlugin(
 	const team = given.get(AGENTS.id)?.given;
 	const agentServer = team && "team" in team ? services.get(AGENTS) : undefined;
 	const attachmentDir = mkdtempSync(join(tmpdir(), "roundtable-test-plugin-"));
+	const identity = services.find(IDENTITY);
+	// Who wrote a message, and whom a background turn runs as: by the given IDENTITY, else the owner alone, at the owner tier.
+	const people = mapIdentity({ owners: [owner.id] });
 	router = new ChannelRouter({
+		contacts: identity ? contactsOf(identity) : people,
+		principals: identity ?? people,
 		claims: [
 			...(agentServer
 				? [
 						agentClaim({
 							owner,
-							speakers: speakerPolicy({ owners: [owner.id] }),
 							// SAFETY: the claim reads the concrete team's members (guildId, owns, answerOwner, answerGroup, answerBackground, startFresh), which a test that gives a team for it supplies.
 							team: agentServer.team as unknown as Parameters<
 								typeof agentClaim
@@ -514,6 +541,13 @@ export async function testPlugin(
 							surface: surfaces,
 							attachmentDir: () => attachmentDir,
 							logger,
+							// As on a host: the given DISCORD's channel context, when the test gives one.
+							channelContext: async (message) =>
+								(
+									given.get(DISCORD.id)?.given as
+										| Partial<DiscordServices>
+										| undefined
+								)?.channelContext?.(message),
 						}),
 					]
 				: []),
@@ -521,7 +555,9 @@ export async function testPlugin(
 		],
 		targets: (name) =>
 			registry.backgroundTargets.find((t) => t.name === name) ??
-			(agentServer && name === OWNER_TARGET.name ? OWNER_TARGET : undefined),
+			(agentServer && name === PERSONAL_TARGET.name
+				? PERSONAL_TARGET
+				: undefined),
 		queue,
 		logger,
 		...(options.forwardJoinMs === undefined
@@ -586,6 +622,9 @@ export async function testPlugin(
 				homeChannel: channel,
 				turnChannel: channel,
 				compaction: { wrap: (factory) => factory },
+				conversation: { visibility: "shared" },
+				addressee: THE_SPEAKER,
+				memory: "speaker",
 				speaker: () => runOptions?.speaker,
 				runTask: async () => {
 					throw new Error("test session cannot run tasks");

package/templates/.env.example

@@ -7,7 +7,7 @@ DISCORD_TOKEN=
 DISCORD_GUILD_ID=
 DISCORD_ENTRY_CHANNEL_ID=
 
-# You: the one owner who can change everything (right-click your name, Copy User ID).
+# You: the owner, who can change everything; OWNER_ID is your Discord user id (right-click your name, Copy User ID).
 OWNER_ID=
 OWNER_NAME=
 

package/templates/adapters/web/README.md

@@ -9,6 +9,13 @@ People your OpenID Connect provider signs in chat with the assistant in private
 
 The chat is under `/chat`: a web page gets a one-time ticket from `POST /chat/tickets` with the person's token, and opens `/chat/socket` with it.
 The protocol is in `node_modules/pi-roundtable-webchat/README.md`.
+Core `access` in `roundtable.config.ts` decides admission; token roles are prefixed with `web:role:` there.
+New admitted users get principals, and linked Discord/web identities share private memory and quotas.
+Link identities with `bunx roundtable principal link <principal> <identity>`; use `principal list` to inspect them.
+
+The private inbox is `GET /chat/notices`, with `POST /chat/notices/<id>/read` to acknowledge an entry.
+Online connections also receive additive `notice` frames.
+Schedules and delegated reports can answer in their creator's private conversation; enable their tools in the persona selection only where intended and allowed by tier.
 
 `roundtable.config.ts` holds the settings and lists the plugins; `plugins/` holds yours, and `persona/assistant.md` is the assistant's prompt.
 Add another plugin with `bunx roundtable add plugin <name>`, and test it with `bun test`.

package/templates/adapters/web/roundtable.config.ts

@@ -14,8 +14,17 @@ const list = (name: string): string[] =>
 
 export default {
 	name: "Roundtable",
-	// The operator who runs this host. People sign in through your OpenID Connect provider instead.
-	owner: { id: "operator", name: env("OWNER_NAME") },
+	// The operator who runs this host, as the host's owner. People sign in through your OpenID
+	// Connect provider instead; core access maps their verified, surface-prefixed roles to tiers.
+	access: {
+		owners: [{ name: env("OWNER_NAME"), principal: "operator" }],
+		members: {
+			roles: list("CHAT_MEMBER_ROLES").map((role) => `web:role:${role}`),
+		},
+		admins: {
+			roles: list("CHAT_ADMIN_ROLES").map((role) => `web:role:${role}`),
+		},
+	},
 	database: { url: env("DATABASE_URL") },
 	// Paths are relative to the project directory, where the roundtable command runs.
 	dataDir: "./data",
@@ -33,20 +42,15 @@ export default {
 				issuers: [env("OIDC_ISSUER")],
 				audiences: [env("OIDC_AUDIENCE")],
 			}),
-			// Members and admins come from the token's roles; owners only from speaker ids you list.
-			access: {
-				members: { roles: list("CHAT_MEMBER_ROLES") },
-				admins: { roles: list("CHAT_ADMIN_ROLES") },
-			},
 			origins: list("CHAT_ORIGINS"),
 			personas: [
 				{
 					kind: "assistant",
 					label: "Assistant",
 					prompt: () => readFileSync("./persona/assistant.md", "utf8"),
-					// The tools of its turns, by name. Leave out schedule_* and delegate_task, which a web
-					// conversation cannot hear back from, and web_search and fetch_content unless people
-					// may make this server fetch any address, internal ones included.
+					// The tools of its turns, by name. Schedules, delegated reports and notify can reach
+					// this private conversation; add those tools only where intended and permitted by tier.
+					// Leave out web_search and fetch_content unless people may make the server fetch any address.
 					selection: { tools: ["hello_greet"], groups: [] },
 				},
 			],

package/templates/roundtable.config.ts

@@ -8,7 +8,18 @@ const env = (name: string): string => process.env[name] ?? "";
 
 export default {
 	name: "Roundtable",
-	owner: { id: env("OWNER_ID"), name: env("OWNER_NAME") },
+	// Who the host serves. You are the owner: your principal and your Discord identity are your
+	// Discord user id. Add admins and members by Discord user or role, such as
+	// members: { roles: ["discord:role:<role id>"] }.
+	access: {
+		owners: [
+			{
+				name: env("OWNER_NAME"),
+				principal: env("OWNER_ID"),
+				identities: [`discord:${env("OWNER_ID")}`],
+			},
+		],
+	},
 	discord: {
 		token: env("DISCORD_TOKEN"),
 		guild: env("DISCORD_GUILD_ID"),

package/src/core/domain/owner-prompts.ts

@@ -1,45 +0,0 @@
-import type { Tier } from "../speakers.ts";
-/**
- * The owner answering inside a running turn: a card in the turn's channel that only they may
- * answer. Unanswered cards expire; a stopped turn cancels its open cards.
- */
-export type Approval = "approved" | "declined" | "expired" | "cancelled";
-
-export interface AskOption {
-	label: string;
-	description?: string;
-}
-
-export interface OwnerQuestion {
-	question: string;
-	/** Up to 25; none means a free-text answer. */
-	options: readonly AskOption[];
-	/** More than one option may be chosen. */
-	multi: boolean;
-	/** They may write an answer of their own besides the options. */
-	allowOther: boolean;
-}
-
-export interface OwnerAnswer {
-	/** The chosen options' labels, in the order they were offered. */
-	choices: string[];
-	/** What they wrote himself, if anything. */
-	text?: string;
-}
-
-export interface OwnerPrompts {
-	/** Asks them to approve an action; `signal` cancels the card when the turn stops. */
-	confirm(
-		title: string,
-		message: string,
-		signal?: AbortSignal,
-		/** The tier the turn's speaker needs to approve it themselves; the owner may always approve, and only the owner when absent. */
-		minTier?: Tier,
-	): Promise<Approval>;
-	/** Asks them a question; undefined when it expired or was cancelled. */
-	ask(
-		title: string,
-		question: OwnerQuestion,
-		signal?: AbortSignal,
-	): Promise<OwnerAnswer | undefined>;
-}