pi-roundtable 0.7.19 → 0.9.0

package/src/core/contract/channels.ts

@@ -1,6 +1,7 @@
 import type { Locale } from "../i18n/index.ts";
+import type { ActorFacts } from "../identity/actor-facts.ts";
 import type { ChannelKey } from "../sessions.ts";
-import type { Tier } from "../speakers.ts";
+import type { Speaker, Tier } from "../speakers.ts";
 
 /** A file attached to a chat message, as the surface reports it; nothing is downloaded yet. */
 export interface AttachmentRef {
@@ -16,6 +17,21 @@ export interface InboundMessage {
 	channel: ChannelKey;
 	/** Unique per surface; keeps the files of different messages apart. */
 	messageId: string;
+	/**
+	 * Who wrote it, as the surface reports them: the router resolves them to `speaker` through the
+	 * identity service. A surface that leaves it out has it read from `authorId`, `authorName`, and
+	 * `authorRoleIds` under its own name as the provider, with a `deprecated` warning; that goes
+	 * away in 1.0.
+	 */
+	actor?: ActorFacts;
+	/**
+	 * Who the author is, with their principal and tier, as the router resolved them before any
+	 * claim admits the message: undefined when the access rules serve no one by them, and for a bot
+	 * or an integration, which are not resolved. Only the router sets it; a surface's own value is
+	 * dropped. A claim that serves only people the host serves answers only when it is set.
+	 */
+	speaker?: Speaker;
+	/** The id the surface knows the author by; who they are to the host is `speaker`. */
 	authorId: string;
 	/** How the author appears in the channel, for example a server nickname. */
 	authorName: string;
@@ -77,10 +93,22 @@ export interface BackgroundTarget {
 	name: string;
 	/** How lists such as `/<root> schedule` name it, in the host's locale. */
 	label(locale: Locale): string;
-	/** Limits of the schedules made for it; absent, nothing may be scheduled for it. */
-	schedules?: { perChannel: number; promptChars: number; aheadDays: number };
-	/** Limits of the delegated tasks reporting to it; absent, nothing may be delegated to it. */
-	delegation?: { maxRunning: number };
+	/**
+	 * Limits of the schedules made for it; absent, nothing may be scheduled for it. `perPrincipal`,
+	 * when set, holds each person to that many of its schedules across all their conversations.
+	 */
+	schedules?: {
+		perChannel: number;
+		perPrincipal?: number;
+		promptChars: number;
+		aheadDays: number;
+	};
+	/**
+	 * Limits of the delegated tasks reporting to it; absent, nothing may be delegated to it.
+	 * `maxRunningPerPrincipal`, when set, holds each person to that many running at once across
+	 * all their conversations.
+	 */
+	delegation?: { maxRunning: number; maxRunningPerPrincipal?: number };
 }
 
 /** A turn nobody wrote in the channel: a schedule's, or a report of work done elsewhere. */
@@ -91,18 +119,31 @@ export interface BackgroundTurn {
 	 * plugin contributes, and a claim skips one it does not serve.
 	 */
 	target: string;
-	author: { id: string; name: string };
 	/**
-	 * The tier the turn runs at, which is its creator's when a person set it up; absent for
-	 * the operator's own automation, which runs at the owner's.
+	 * Whom the turn is for: the principal who set up the work, and the id and name they are shown
+	 * by, such as the identity they spoke as. The system principal is the host's alone.
+	 */
+	author: { principalId: string; id: string; name: string };
+	/**
+	 * The tier the turn asks to run at, its creator's when they set it up. It runs at that tier or
+	 * the principal's own now, whichever is lower.
 	 */
-	tier?: Tier;
+	tier: Tier;
 	turnId: string;
 	text: string;
 	/** It delivers a report the owner is waiting for, so it may ask them on cards. */
 	report?: boolean;
+	/**
+	 * Who the turn runs as, set by the router alone once it checked the author: their principal
+	 * exists and is not disabled, and the tier is capped at theirs. A claim runs the turn as this
+	 * speaker; one the caller sets is replaced.
+	 */
+	speaker?: Speaker;
 }
 
+/** Who a background turn runs as, once checked; or why it may not run now. */
+export type BackgroundRunsAs = { speaker: Speaker } | { skipped: string };
+
 /**
  * Whose conversation a channel holds, as the claim that owns it names it when `startFresh` says
  * whose it was: any string, such as "owner" or "study". The host reads none of them, so a plugin
@@ -125,6 +166,12 @@ export type Admission =
 			};
 			/** The turn, run in the channel's queue. */
 			run(): Promise<void>;
+			/**
+			 * Called instead of `run` when the router drops the message the claim admitted, because
+			 * its author, once recorded, was not who they were when admitted; frees what the claim
+			 * holds for it.
+			 */
+			dropped?(): void;
 			/** The log line when the turn throws. */
 			failure: string;
 	  }
@@ -161,13 +208,32 @@ export interface ChannelClaim {
 	deleteConversation?(channel: ChannelKey): Promise<void>;
 	/** Reports of work started in an owned channel stay in it instead of opening a thread. */
 	postsInPlace?: boolean;
+	/**
+	 * Whether the claim's `background` answers the host's own turns (`SYSTEM_PRINCIPAL`), such as
+	 * `ops.conversation`'s error reports, in its conversations; true when left out. A claim whose
+	 * conversations are each private to the person who opened them, such as the web chat's, says
+	 * false, and a host whose `ops.conversation` names one of them does not start.
+	 */
+	takesSystemReports?: boolean;
 }
 
 /** The conversations of every claimed channel, through the channel queue. */
 export interface ConversationPort {
 	/** Never rejects; resolves when the message's turn is done or dropped. */
 	handle(message: InboundMessage): Promise<void>;
+	/**
+	 * Runs a turn nobody wrote, as its author's principal at the lower of its tier and theirs; it
+	 * is skipped, with the reason, when the principal is unknown, disabled, holds no tier, or was
+	 * last seen too long ago (`access.backgroundStaleDays`), or when the turn names no principal or
+	 * tier. Never rejects.
+	 */
 	background(turn: BackgroundTurn): Promise<ScheduledOutcome>;
+	/**
+	 * Who a background turn would run as now, checked as `background` checks it, without running
+	 * it: for work that must not happen for an author who may not run the turn, such as a
+	 * schedule's precheck. Throws when the identity service cannot tell.
+	 */
+	runsAs(turn: BackgroundTurn): Promise<BackgroundRunsAs>;
 	/** A contributed background target, read when used; undefined when no plugin contributes it. */
 	target(name: string): BackgroundTarget | undefined;
 	/** Waits for the channel's running turn, then starts its conversation over; says whose it was. */
@@ -178,6 +244,12 @@ export interface ConversationPort {
 	stop(channel: ChannelKey): boolean;
 	/** Whether reports of work started in the channel stay in it, by its owner's policy. */
 	postsInPlace(channel: ChannelKey): boolean;
+	/** Whether a claim owns the channel, so its messages and background turns reach a conversation. */
+	owns(channel: ChannelKey): boolean;
+	/** Whether the claim that owns the channel runs background turns there; false when none owns it. */
+	takesBackground(channel: ChannelKey): boolean;
+	/** Whether the claim that owns the channel takes the host's own turns; false when none owns it. */
+	takesSystemReports(channel: ChannelKey): boolean;
 }
 
 /** The host's channel queue, as plugins use it. */

package/src/core/contract/providers.ts

@@ -68,8 +68,9 @@ export interface Providers {
 	images: ImageDrawer;
 	/**
 	 * Builds the runtime that runs the agent server's conversations and every turn run through
-	 * `context.turns`, in place of the Pi runtime. The default refuses: the agent server builds the
-	 * Pi runtime itself when no plugin fills this slot, so check `filled` before calling it.
+	 * `context.turns`, in place of the Pi runtime. The default refuses: the host's runtime plugin
+	 * builds the Pi runtime itself when no plugin fills this slot. Read the running runtime from
+	 * `services.get(RUNTIME)` rather than calling this.
 	 */
 	runtime: RuntimeFactory;
 }

package/src/core/contract/runtime.ts

@@ -5,8 +5,8 @@ import type {
 	TranscriptEntry,
 	TurnResult,
 } from "../domain/conversation.ts";
-import type { OwnerPrompts } from "../domain/owner-prompts.ts";
 import type { TurnRequest } from "../domain/ports.ts";
+import type { PromptScope, Prompts } from "../interactions/prompts.ts";
 import type { Logger } from "../log.ts";
 import type { ThinkingSetting } from "../models.ts";
 import type { HostEnv, LinkedSessions } from "../plugin.ts";
@@ -51,11 +51,18 @@ export interface AgentRuntime {
 	startFresh(conversation: ChannelKey): Promise<void>;
 	/** Like `startFresh`, but removes the conversation and every archive of it for good; called between turns. */
 	deleteConversation(conversation: ChannelKey): Promise<void>;
-	/** The conversation's held actions known in memory since startup. */
+	/**
+	 * The conversation's held actions known in memory: those of a turn run since startup, and those
+	 * `heldActions` or `recentTranscript` restored from the store for it. After a restart, ask one of
+	 * those first.
+	 */
 	pendingConfirmation(
 		conversation: ChannelKey,
 	): PendingConfirmation | undefined;
-	/** The conversation's held actions, restored from the store after a restart. */
+	/**
+	 * The conversation's held actions, restored from the store after a restart, so that
+	 * `pendingConfirmation` knows them too, as `recentTranscript` does. Expired ones count as none.
+	 */
 	heldActions(
 		conversation: ChannelKey,
 	): Promise<PendingConfirmation | undefined>;
@@ -96,6 +103,13 @@ export interface AgentSessions {
 	modelOf(name: string): { model: string; thinking: ThinkingSetting };
 	/** The channel the scope's turns run in: the group's for a seat in one, else the agent's own. */
 	turnChannel(scope: AgentTurnScope): ChannelKey;
+	/**
+	 * Whose turns in an agent's conversation load memory: `"everyone"` (the default) lets each
+	 * speaker read their own, `"owners"` only the owners, so a speaker below the owner tier gets no
+	 * memory in their prompt and no memory tools, and their turn never carries private memory into
+	 * the conversation's history.
+	 */
+	memory?: "everyone" | "owners";
 }
 
 /** Where a runtime keeps each conversation's held actions, so they survive a restart. */
@@ -109,7 +123,7 @@ export interface HeldActionStore {
 	): Promise<void>;
 }
 
-/** What the agent server hands a runtime provider when it builds the runtime. */
+/** What the host's runtime plugin hands a runtime provider when it builds the runtime. */
 export interface RuntimeDeps {
 	logger: Logger;
 	/** The host's locale and time zone. */
@@ -124,20 +138,26 @@ export interface RuntimeDeps {
 	/** What each tool needs; plugin tools are added when the host links, so ask at use time. */
 	toolTiers: ToolTiers;
 	/**
-	 * The owner's approval and question prompts in a conversation, from its chat surface; undefined
-	 * when the surface has none, and the action then waits for the owner's next message.
+	 * The approval and question prompts in a conversation for a turn's scope, made with
+	 * `promptScope(speaker, visibility)`, from its chat surface; undefined when the surface has
+	 * none, and the action then waits for a message that approves it. A `Speaker`, the 0.8 form,
+	 * is read as theirs in a shared conversation, with a deprecation warning, until 1.0.
 	 */
 	prompts(
 		conversation: ChannelKey,
-		speaker?: Speaker,
-	): OwnerPrompts | undefined;
-	/** The agent server's per-agent settings, for agent turns. */
-	agents: AgentSessions;
+		scope?: PromptScope | Speaker,
+	): Prompts | undefined;
+	/**
+	 * The agent server's per-agent settings, for agent turns. The runtime is built before the agent
+	 * server, so read this when a turn runs, not in the factory; it stays undefined on a host without
+	 * the agent server, where no agent turn runs.
+	 */
+	readonly agents?: AgentSessions;
 	/** Where held actions persist across restarts. */
 	confirmations: HeldActionStore;
 	/** The host's judge, resolved from the `judge` slot. */
 	judge: Judge;
 }
 
-/** Builds the runtime, once, when the agent server sets up. */
+/** Builds the runtime, once, when the host's runtime plugin sets up. */
 export type RuntimeFactory = (deps: RuntimeDeps) => AgentRuntime;

package/src/core/contract/surface.ts

@@ -1,7 +1,8 @@
 import type { OutboundReply } from "../domain/conversation.ts";
 import type { InterimPosts } from "../domain/interim.ts";
-import type { OwnerPrompts } from "../domain/owner-prompts.ts";
+import type { TurnProgress } from "../domain/progress.ts";
 import { PluginError } from "../errors.ts";
+import type { PromptScope, Prompts } from "../interactions/prompts.ts";
 import type { ChannelKey } from "../sessions.ts";
 import type { Speaker } from "../speakers.ts";
 import type { InboundMessage } from "./channels.ts";
@@ -57,6 +58,13 @@ export interface ChatSurface {
 	 * `conversations.stop(channel)` when used. Absent = none shown.
 	 */
 	showStop?(channel: ChannelKey): () => void;
+	/**
+	 * Marks in the channel, publicly, that its conversation just started over, so what a reader of
+	 * the channel's history would take for the conversation's context ends there; called after the
+	 * claim's `startFresh` succeeded. A rejection is logged and the restart still counts. Absent =
+	 * nothing is posted.
+	 */
+	markFresh?(channel: ChannelKey): Promise<void>;
 	/** Adds or removes the bot's reaction on a message; failures are logged, never thrown. */
 	react?(channel: ChannelKey, messageId: string, emoji: string): Promise<void>;
 	unreact?(
@@ -65,15 +73,23 @@ export interface ChatSurface {
 		emoji: string,
 	): Promise<void>;
 	/**
-	 * How the owner approves held actions or answers ask_user in a running turn; undefined, or
-	 * absent, = the action is held until the owner's next message.
+	 * How those the scope names approve held actions or answer ask_user in a running turn: the
+	 * scope's speaker, and in a shared conversation the owners; see `Prompts` and `PromptScope`.
+	 * Without a scope the prompts are the owners'. Undefined, or absent, = the action is held
+	 * until a message approves it.
 	 */
-	prompts?(channel: ChannelKey, speaker?: Speaker): OwnerPrompts | undefined;
+	prompts?(channel: ChannelKey, scope?: PromptScope): Prompts | undefined;
 	/**
 	 * Where a running turn posts the text it writes before its final answer: ordinary messages it
 	 * may edit in place. Absent, or undefined, = only the final reply is posted.
 	 */
 	interim?(channel: ChannelKey): InterimPosts | undefined;
+	/**
+	 * Shows what a running turn writes and which tools it runs, as it goes, such as a live preview
+	 * in a web chat. Called between the turn's start and its reply; a rejection is logged and the
+	 * turn goes on. Absent = the surface shows only the final reply.
+	 */
+	progress?(channel: ChannelKey, event: TurnProgress): Promise<void> | void;
 }
 
 /**
@@ -91,8 +107,21 @@ export interface SurfacePort {
 	showStop(channel: ChannelKey): () => void;
 	react(channel: ChannelKey, messageId: string, emoji: string): Promise<void>;
 	unreact(channel: ChannelKey, messageId: string, emoji: string): Promise<void>;
-	/** The owner's prompts in the channel; undefined when its surface has none. */
-	prompts(channel: ChannelKey, speaker?: Speaker): OwnerPrompts | undefined;
+	/**
+	 * The prompts in the channel for the scope's turn; undefined when its surface has none. A
+	 * `Speaker`, the 0.8 form, is read as theirs in a shared conversation, with a deprecation
+	 * warning, until 1.0.
+	 */
+	prompts(
+		channel: ChannelKey,
+		scope?: PromptScope | Speaker,
+	): Prompts | undefined;
 	/** The channel's interim posts; undefined when its surface has none. */
 	interim(channel: ChannelKey): InterimPosts | undefined;
+	/**
+	 * Shows a running turn's progress; a no-op when no surface serves the channel or its surface
+	 * shows none. The host's port always has it; it is optional so a port written before 0.8 still
+	 * type-checks, and a turn run over one without it shows no progress.
+	 */
+	progress?(channel: ChannelKey, event: TurnProgress): Promise<void>;
 }

package/src/core/conversations/conversation-registry.ts

@@ -0,0 +1,56 @@
+import type { ChannelKey } from "../sessions.ts";
+
+/** Who may take part: `private` belongs to one principal, `shared` to whoever its claim admits. */
+export type ConversationVisibility = "private" | "shared";
+
+/** What the first turn of a conversation records about it. */
+export interface ConversationRegistration {
+	key: ChannelKey;
+	/** The conversation's kind, such as "study"; the persona its session runs. */
+	kind: string;
+	visibility: ConversationVisibility;
+	/** Whose conversation it is: the speaker's id, for a private one. */
+	principalId?: string;
+	/** A name to list it by. */
+	title?: string;
+}
+
+/** A conversation the host knows: who it belongs to and when it was last active. */
+export interface ConversationRecord extends ConversationRegistration {
+	/** The prefix of its key, such as "web". */
+	surface: string;
+	createdAt: Date;
+	lastActiveAt: Date;
+}
+
+/**
+ * The conversations run through `context.turns`, recorded at their first turn. Its kind,
+ * visibility, and principal are fixed then; each later turn only marks it active. Who may speak
+ * in it stays the claim's decision: the registry records, it does not refuse.
+ */
+export interface ConversationRegistry {
+	/** Records the conversation at its first turn, or marks a known one active; returns what is stored. */
+	register(entry: ConversationRegistration): Promise<ConversationRecord>;
+	get(key: ChannelKey): Promise<ConversationRecord | undefined>;
+	/** One principal's conversations, or every one; the most recently active first. */
+	list(filter?: { principal?: string }): Promise<ConversationRecord[]>;
+	/**
+	 * Only for migrating a conversation recorded before 0.9, when every turn run without a
+	 * visibility was recorded `shared` with no principal: makes such a conversation private to
+	 * `principalId`, as the plugin that hands over what 0.8 left behind decides, such as remote-mcp
+	 * giving 0.8's sessions to the primary owner. A conversation that is private or names a
+	 * principal never changes, so adopting is safe to repeat and to race: one principal wins.
+	 * Returns what is stored, or undefined when the key is unknown. Adopting a conversation 0.9 or
+	 * later recorded is outside this contract: today it changes one recorded shared like any other,
+	 * and a later version may refuse it.
+	 */
+	adopt(
+		key: ChannelKey,
+		principalId: string,
+	): Promise<ConversationRecord | undefined>;
+	/** Names a conversation, or clears its name; undefined when the key is unknown. */
+	setTitle(
+		key: ChannelKey,
+		title: string | undefined,
+	): Promise<ConversationRecord | undefined>;
+}

package/src/core/conversations/conversation-store.ts

@@ -0,0 +1,126 @@
+import type { SQL } from "bun";
+import { parseChannelKey } from "../contract/surface.ts";
+import type { Migration } from "../db/migrations.ts";
+import type { ChannelKey } from "../sessions.ts";
+import type {
+	ConversationRecord,
+	ConversationRegistration,
+	ConversationRegistry,
+	ConversationVisibility,
+} from "./conversation-registry.ts";
+
+interface Row {
+	key: string;
+	surface: string;
+	kind: string;
+	principal_id: string | null;
+	visibility: ConversationVisibility;
+	title: string | null;
+	created_at: Date;
+	last_active_at: Date;
+}
+
+function recordOf(row: Row): ConversationRecord {
+	return {
+		key: row.key as ChannelKey,
+		surface: row.surface,
+		kind: row.kind,
+		visibility: row.visibility,
+		...(row.principal_id === null ? {} : { principalId: row.principal_id }),
+		...(row.title === null ? {} : { title: row.title }),
+		createdAt: row.created_at,
+		lastActiveAt: row.last_active_at,
+	};
+}
+
+/** The conversation registry in the `conversations` table. */
+export class PgConversationRegistry implements ConversationRegistry {
+	readonly #sql: SQL;
+
+	private constructor(sql: SQL) {
+		this.#sql = sql;
+	}
+
+	/** The registry's table; the host runs this before the registry attaches. */
+	static readonly migration: Migration = {
+		name: "conversations",
+		up: async (sql) => {
+			await sql`
+				CREATE TABLE IF NOT EXISTS conversations (
+					key text PRIMARY KEY,
+					surface text NOT NULL,
+					kind text NOT NULL,
+					principal_id text,
+					visibility text NOT NULL CHECK (visibility IN ('private', 'shared')),
+					title text,
+					created_at timestamptz NOT NULL DEFAULT now(),
+					last_active_at timestamptz NOT NULL DEFAULT now()
+				)`;
+			await sql`
+				CREATE INDEX IF NOT EXISTS conversations_principal
+				ON conversations (principal_id, last_active_at DESC)`;
+		},
+	};
+
+	/** The registry over the host's migrated pool. */
+	static async attach(sql: SQL): Promise<PgConversationRegistry> {
+		return new PgConversationRegistry(sql);
+	}
+
+	async register(entry: ConversationRegistration): Promise<ConversationRecord> {
+		const { surface } = parseChannelKey(entry.key);
+		const rows: Row[] = await this.#sql`
+			INSERT INTO conversations (key, surface, kind, principal_id, visibility, title)
+			VALUES (${entry.key}, ${surface}, ${entry.kind}, ${entry.principalId ?? null},
+				${entry.visibility}, ${entry.title ?? null})
+			ON CONFLICT (key) DO UPDATE SET last_active_at = now()
+			RETURNING *`;
+		const [row] = rows;
+		if (!row) throw new Error(`conversation ${entry.key} was not recorded`);
+		return recordOf(row);
+	}
+
+	async get(key: ChannelKey): Promise<ConversationRecord | undefined> {
+		const rows: Row[] = await this.#sql`
+			SELECT * FROM conversations WHERE key = ${key}`;
+		const [row] = rows;
+		return row ? recordOf(row) : undefined;
+	}
+
+	async list(
+		filter: { principal?: string } = {},
+	): Promise<ConversationRecord[]> {
+		const rows: Row[] =
+			filter.principal === undefined
+				? await this.#sql`
+					SELECT * FROM conversations ORDER BY last_active_at DESC, key`
+				: await this.#sql`
+					SELECT * FROM conversations WHERE principal_id = ${filter.principal}
+					ORDER BY last_active_at DESC, key`;
+		return rows.map(recordOf);
+	}
+
+	async adopt(
+		key: ChannelKey,
+		principalId: string,
+	): Promise<ConversationRecord | undefined> {
+		// The row lock makes a racing adopt wait and then find the conversation no longer no one's.
+		const rows: Row[] = await this.#sql`
+			UPDATE conversations SET visibility = 'private', principal_id = ${principalId}
+			WHERE key = ${key} AND visibility = 'shared' AND principal_id IS NULL
+			RETURNING *`;
+		const [row] = rows;
+		return row ? recordOf(row) : this.get(key);
+	}
+
+	async setTitle(
+		key: ChannelKey,
+		title: string | undefined,
+	): Promise<ConversationRecord | undefined> {
+		const rows: Row[] = await this.#sql`
+			UPDATE conversations SET title = ${title ?? null} WHERE key = ${key}
+			RETURNING *`;
+		const [row] = rows;
+		return row ? recordOf(row) : undefined;
+	}
+}

package/src/core/conversations/conversations-plugin.ts

@@ -0,0 +1,29 @@
+import type { SQL } from "bun";
+import type { RoundtablePlugin } from "../plugin.ts";
+import { CONVERSATIONS } from "../services.ts";
+import type { ConversationRegistry } from "./conversation-registry.ts";
+import { PgConversationRegistry } from "./conversation-store.ts";
+
+/** The name of the conversation registry's plugin, as the migration ledger names it. */
+export const CONVERSATIONS_PLUGIN = "conversations";
+
+/**
+ * The conversation registry, provided as `CONVERSATIONS`: every conversation run through
+ * `context.turns`, recorded at its first turn. No session file moves; a conversation from before
+ * the registry is recorded at its next turn.
+ */
+export function conversationsPlugin(
+	/** Opens the registry; a test hands a stand-in, so the plugin sets up without a database. */
+	open: (sql: SQL) => Promise<ConversationRegistry> = (sql) =>
+		PgConversationRegistry.attach(sql),
+): RoundtablePlugin {
+	return {
+		name: CONVERSATIONS_PLUGIN,
+		migrations: [PgConversationRegistry.migration],
+		provides: [CONVERSATIONS],
+		setup: async ({ database, services }) => {
+			services.provide(CONVERSATIONS, await open(database()));
+			return {};
+		},
+	};
+}