pi-roundtable 0.25.0 → 0.26.0

package/src/core/plugin.ts

@@ -107,10 +107,30 @@ export interface EventHandlers {
 	turnProgress?(event: TurnProgressEvent): Promise<void> | void;
 	/** The team changed: an agent or group was created, edited, arranged, archived, or started over. */
 	changed?(): Promise<void> | void;
+	/**
+	 * Something a person did through a plugin's surface, reported by any plugin through
+	 * `context.events.action`: for example a support inbox's "assign", "reply" or "close". It names
+	 * the kind, who did it and whether it worked, never the content.
+	 */
+	action?(event: ActionEvent): Promise<void> | void;
 	/** The shutdown drain ended, before any service stops; `left` is the work it gave up on. */
 	shutdown?(left: readonly string[]): Promise<void> | void;
 }
 
+/** One thing a person did through a plugin's surface, as a handler hears of it. */
+export interface ActionEvent {
+	/** What was done, in the reporting plugin's words, such as "assign" or "close". */
+	kind: string;
+	/** The `Speaker.id` of who did it. */
+	actor: string;
+	principalId: string;
+	/** The conversation or page it concerns, when there is one. */
+	channel?: ChannelKey | `page:${string}`;
+	/** Whether it worked. */
+	ok: boolean;
+	at: Date;
+}
+
 /** What the core reports to the plugins' handlers. */
 export interface EventSink {
 	turnStarted(turn: TurnEvent): void;
@@ -118,6 +138,8 @@ export interface EventSink {
 	/** Optional, so a sink of your own written before it still fits. */
 	turnProgress?(event: TurnProgressEvent): void;
 	changed(): void;
+	/** Optional, as `turnProgress` is: a sink of your own written before it still fits. */
+	action?(event: ActionEvent): void;
 }
 
 /** What a prompt section is built for: one agent's turn. */
@@ -265,6 +287,12 @@ export interface LinkedSessions {
 	agentSelection(): ToolSelection;
 }
 
+/**
+ * What the agents' turns may use of the machine: "full" gives them the shell and file tools, and
+ * "chat-only" none of them, as `agentServer: { tools: "chat-only" }` configures.
+ */
+export type AgentTools = "full" | "chat-only";
+
 /** The host's own locale and time zone, as its plugins read them. */
 export interface HostEnv {
 	readonly locale: Locale;
@@ -284,6 +312,12 @@ export interface HostEnv {
 	 * agent wears the same ones.
 	 */
 	readonly characterSkins: readonly Hex[];
+	/**
+	 * Whether the agents' turns carry the shell and file tools. A plugin whose tools reach the host
+	 * checks it before it offers them to agents; under "chat-only" the host refuses to start with a
+	 * plugin that declares `hostAccess`.
+	 */
+	readonly agentTools: AgentTools;
 }
 
 /** What the host gives every plugin. */
@@ -391,6 +425,12 @@ export interface RoundtablePlugin {
 	 * dropped plugin provides a service this one does not replace.
 	 */
 	replaces?: readonly ServiceKey<unknown>[];
+	/**
+	 * Marks a plugin whose tools reach the host's machine, such as one that runs shells or edits
+	 * its files for the agents. A host that configures `agentServer: { tools: "chat-only" }`
+	 * refuses to start with one registered, with a ConfigError that names the plugin.
+	 */
+	hostAccess?: true;
 	setup(context: PluginContext): Promise<Contribution> | Contribution;
 	/**
 	 * Runs once every plugin is set up and linked, before any service starts; a failure stops the

package/src/core/registry/contributions.ts

@@ -25,6 +25,7 @@ import {
 	type DirectChannelProvider,
 	directChannelsPort,
 } from "../presence/direct-channels.ts";
+import { refuseShellTools } from "../runtime/chat-only.ts";
 import {
 	compileSessionPlan,
 	type SessionTool,
@@ -451,8 +452,14 @@ export async function collectContributions(
 				registry.holdRules.push(tool.hold);
 			}
 		}
-		if (contribution.agentSelection)
+		if (contribution.agentSelection) {
+			if (context.env.agentTools === "chat-only")
+				refuseShellTools(
+					contribution.agentSelection().tools,
+					`plugin ${plugin.name}: agentSelection`,
+				);
 			registry.agentSelections.push(contribution.agentSelection);
+		}
 		if (events) registry.handlers.push({ plugin: plugin.name, events });
 		registry.routes.push(...http);
 		registry.holdRules.push(...holdRules);

package/src/core/runtime/chat-only.ts

@@ -0,0 +1,32 @@
+import { ConfigError } from "../domain/errors.ts";
+import { SHELL_TOOLS } from "../modules/host-shell/shell-policy.ts";
+import type { RoundtablePlugin } from "../plugin.ts";
+
+const CHAT_ONLY = 'agentServer: { tools: "chat-only" }';
+
+/** The shell and file tools among these names. */
+export function shellToolsIn(names: Iterable<string>): string[] {
+	const shell: readonly string[] = SHELL_TOOLS;
+	return [...new Set(names)].filter((name) => shell.includes(name));
+}
+
+/**
+ * Refuses names that carry the machine's shell and file tools: the one place a chat-only host
+ * checks, where a selection turns into active tools. `where` says whose selection it is.
+ */
+export function refuseShellTools(names: Iterable<string>, where: string): void {
+	const found = shellToolsIn(names);
+	if (found.length > 0)
+		throw new ConfigError(
+			`${where} names ${found.join(", ")}, which ${CHAT_ONLY} withholds from every turn. Take the tool out of the selection, or remove tools: "chat-only" from agentServer to give the agents the shell.`,
+		);
+}
+
+/** Refuses, at start, a plugin whose tools reach the host: an agent of a chat-only host must not. */
+export function refuseHostAccess(plugins: readonly RoundtablePlugin[]): void {
+	const reaching = plugins.find((plugin) => plugin.hostAccess === true);
+	if (reaching)
+		throw new ConfigError(
+			`plugin ${reaching.name} declares hostAccess: its tools reach the host's machine, and the configuration says ${CHAT_ONLY}. Remove the plugin, or remove tools: "chat-only" from agentServer.`,
+		);
+}

package/src/core/runtime/conversation-sessions.ts

@@ -102,7 +102,8 @@ export class ConversationSessions {
 				this.#factory.link().holds,
 				this.#options.owner,
 				await this.#options.confirmations.load(key),
-				agents
+				// A chat-only host's agents have no shell, so their gate judges no workspace.
+				agents && this.#options.agentTools !== "chat-only"
 					? {
 							workspace: agents.workDir,
 							...(agents.scratchDir ? { scratchDir: agents.scratchDir } : {}),

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

@@ -199,6 +199,7 @@ export function runtimePlugin(
 						},
 						...turnPolicy(options),
 						sessions: context.sessions,
+						agentTools: context.env.agentTools,
 						agentDir: options.agentDir,
 						modelRuntime: options.modelRuntime,
 						dataDir: options.dataDir,

package/src/core/runtime/runtime-types.ts

@@ -16,7 +16,7 @@ import type { Logger } from "../log.ts";
 import type { EffortPolicy, ThinkingLevel, ThinkingPicker } from "../models.ts";
 import type { Autonomy } from "../modes/autonomy.ts";
 import type { ConversationModes } from "../modes/conversation-modes.ts";
-import type { LinkedSessions } from "../plugin.ts";
+import type { AgentTools, LinkedSessions } from "../plugin.ts";
 import {
 	planOrder,
 	type SessionContext,
@@ -75,6 +75,8 @@ export interface PiAgentRuntimeOptions {
 	sessions: () => LinkedSessions;
 	/** The agent server's sessions: their shared workspace, model, and skills. */
 	agents?: AgentSessions;
+	/** "chat-only": no turn carries the shell and file tools, and agent sessions have no workspace; default "full". */
+	agentTools?: AgentTools;
 	/**
 	 * The prompts of a channel for an interactive turn's scope, made from its speaker and its
 	 * conversation's visibility; undefined for a channel that cannot show them. Without it every

package/src/core/runtime/session-factory.ts

@@ -3,14 +3,11 @@ import { join } from "node:path";
 import {
 	type AgentSession,
 	createAgentSession,
-	createBashToolDefinition,
 	DefaultResourceLoader,
 	type ModelRuntime,
 	type SessionManager,
-	type ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
 import { channelSegment } from "../attachments/attachment-dir.ts";
-import type { ImageDrawer } from "../contract/providers.ts";
 import type { ClientPort } from "../domain/client.ts";
 import type { ChannelKey } from "../domain/conversation.ts";
 import { ConfigError } from "../domain/errors.ts";
@@ -29,16 +26,13 @@ import {
 	ATTACH_FILE_TOOL,
 	attachFileExtension,
 } from "../shared/attach-file-tool.ts";
-import {
-	GENERATE_IMAGE_TOOL,
-	generateImageExtension,
-} from "../shared/generate-image-tool.ts";
+import { GENERATE_IMAGE_TOOL } from "../shared/generate-image-tool.ts";
 import { packageDir } from "../shared/package-dir.ts";
 import { readAttachmentExtension } from "../shared/read-attachment-tool.ts";
-import type { WorkspaceRoots } from "../shared/workspace-files.ts";
 import { type Speaker, THE_SPEAKER } from "../speakers.ts";
 import { currentToolNames } from "../tool-tiers.ts";
 import { toolTurn } from "../tool-turn.ts";
+import { refuseShellTools } from "./chat-only.ts";
 import {
 	CompactionTiers,
 	compactionEngine,
@@ -64,7 +58,6 @@ import type { PromptSlot } from "./prompt-slot.ts";
 import type {
 	ChannelSession,
 	CompactionEnd,
-	CoreExtensions,
 	PiAgentRuntimeOptions,
 } from "./runtime-types.ts";
 import {
@@ -78,6 +71,9 @@ import {
 	sessionAddressee,
 	turnAddressee,
 } from "./session-conversation.ts";
+import { imageTools, scratchBash } from "./session-helpers.ts";
+
+export { imageTools, scratchBash };
 
 /** What a session factory asks of the runtime that owns the turns. */
 export interface SessionFactoryDeps {
@@ -139,11 +135,22 @@ export class SessionFactory {
 		);
 	}
 
+	/** Whether the host's agents carry no shell or file tools. */
+	get chatOnly(): boolean {
+		return this.#options.agentTools === "chat-only";
+	}
+
 	get plan(): SessionPlan {
 		return this.link().plan;
 	}
 
+	/**
+	 * The tools a selection turns into. A chat-only host refuses a selection that names a shell or
+	 * file tool, whatever built it (the agent team, `context.turns`, a plugin), so the turn fails
+	 * closed before any session runs it.
+	 */
 	toolsFor(selection: ToolSelection): string[] {
+		if (this.chatOnly) refuseShellTools(selection.tools, "a tool selection");
 		const groups = planOrder(this.plan).flatMap(
 			(tool) => tool.snapshot().groups ?? [],
 		);
@@ -360,7 +367,8 @@ export class SessionFactory {
 			},
 			conversation,
 			addressee,
-			...(agents
+			// A chat-only host's agents work in no workspace.
+			...(agents && !this.chatOnly
 				? {
 						workspace: {
 							workspace: cwd,
@@ -450,7 +458,7 @@ export class SessionFactory {
 			cwd,
 			agentDir,
 			// Pi's bash under its own name, run with TMPDIR at the agents' scratch dir.
-			...(agents?.scratchDir
+			...(agents?.scratchDir && !this.chatOnly
 				? { customTools: [scratchBash(cwd, agents.scratchDir)] }
 				: {}),
 			thinkingLevel: thinking,
@@ -479,22 +487,3 @@ export class SessionFactory {
 		return Object.assign(state, { session });
 	}
 }
-
-/** `generate_image` for a session of a host with an image provider; nothing without one. */
-export function imageTools(
-	images: ImageDrawer | undefined,
-	roots: WorkspaceRoots,
-): Pick<CoreExtensions, "generateImage"> {
-	return images ? { generateImage: generateImageExtension(images, roots) } : {};
-}
-
-/** Pi's bash tool with TMPDIR set to `scratchDir`, so tools that read TMPDIR and GNU `mktemp` write there (BSD `mktemp` needs `-p "$TMPDIR"`). */
-export function scratchBash(cwd: string, scratchDir: string): ToolDefinition {
-	// SAFETY: Pi's bash definition is a ToolDefinition typed by its own parameter schema, which the session takes as any custom tool.
-	return createBashToolDefinition(cwd, {
-		spawnHook: (context) => ({
-			...context,
-			env: { ...context.env, TMPDIR: scratchDir },
-		}),
-	}) as unknown as ToolDefinition;
-}

package/src/core/runtime/session-helpers.ts

@@ -0,0 +1,27 @@
+import {
+	createBashToolDefinition,
+	type ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import type { ImageDrawer } from "../contract/providers.ts";
+import { generateImageExtension } from "../shared/generate-image-tool.ts";
+import type { WorkspaceRoots } from "../shared/workspace-files.ts";
+import type { CoreExtensions } from "./runtime-types.ts";
+
+/** `generate_image` for a session of a host with an image provider; nothing without one. */
+export function imageTools(
+	images: ImageDrawer | undefined,
+	roots: WorkspaceRoots,
+): Pick<CoreExtensions, "generateImage"> {
+	return images ? { generateImage: generateImageExtension(images, roots) } : {};
+}
+
+/** Pi's bash tool with TMPDIR set to `scratchDir`, so tools that read TMPDIR and GNU `mktemp` write there (BSD `mktemp` needs `-p "$TMPDIR"`). */
+export function scratchBash(cwd: string, scratchDir: string): ToolDefinition {
+	// SAFETY: Pi's bash definition is a ToolDefinition typed by its own parameter schema, which the session takes as any custom tool.
+	return createBashToolDefinition(cwd, {
+		spawnHook: (context) => ({
+			...context,
+			env: { ...context.env, TMPDIR: scratchDir },
+		}),
+	}) as unknown as ToolDefinition;
+}

package/src/core/services.ts

@@ -3,6 +3,7 @@ import type { CharacterInput, CharacterSpec } from "../characters/index.ts";
 import type { Agent, AgentGroup } from "./agents/agent-rules.ts";
 import type { AvatarMode } from "./agents/agent-tools.ts";
 import type { TeamStatus } from "./agents/team-status.ts";
+import type { ChannelContexts } from "./contract/channel-context.ts";
 import type {
 	BackgroundRunsAs,
 	ScheduledOutcome,
@@ -14,6 +15,7 @@ import type { PendingConfirmation } from "./domain/conversation.ts";
 import type { HttpRoute } from "./http/listeners.ts";
 import type { IdentityLinks } from "./identity/identity-links.ts";
 import type { IdentityService } from "./identity/identity-service.ts";
+import type { PersonProfiles } from "./identity/profiles.ts";
 import type { ThinkingLevel, ThinkingSetting } from "./models.ts";
 import type { ConversationModes } from "./modes/conversation-modes.ts";
 import type {
@@ -53,6 +55,10 @@ import type { DispatchThreads } from "./threads/dispatch-threads.ts";
  */
 export const IDENTITY: ServiceKey<IdentityService> =
 	serviceKey<IdentityService>("roundtable.identity");
+/** How the core names a person (linked accounts' names and pictures, the chosen one, plugin sources); from the `identity` plugin. */
+export const PROFILES: ServiceKey<PersonProfiles> = serviceKey<PersonProfiles>(
+	"roundtable.profiles",
+);
 /**
  * Links a person's own account to their principal, which `IDENTITY` cannot. Provided by the
  * `identity` plugin only when the configuration lists providers in `access.selfLink`; read it with
@@ -92,6 +98,9 @@ export const MODES: ServiceKey<ConversationModes> =
  */
 export const THREADS: ServiceKey<DispatchThreads> =
 	serviceKey<DispatchThreads>("roundtable.threads");
+/** The channel context of any surface, chosen by the message's channel key as `THREADS` is; provided by the `channel-context` plugin, which every host registers. */
+export const CHANNEL_CONTEXT: ServiceKey<ChannelContexts> =
+	serviceKey<ChannelContexts>("roundtable.channel-context");
 /** The agent server: its team, its directory, the runtime that runs every agent turn. Provided by the agent-server plugin. */
 export const AGENTS: ServiceKey<AgentServer> = serviceKey<AgentServer>(
 	"roundtable.agents",

package/src/index.ts

@@ -47,7 +47,9 @@ export type {
 	RoundtableConfig,
 	TierConfig,
 } from "./core/config/config.ts";
+export type { ConversationsConfig } from "./core/config/conversations.ts";
 export type { LimitsConfig } from "./core/config/limits.ts";
+export type { ProfilesConfig } from "./core/config/profiles.ts";
 export type { SkillsConfig } from "./core/config/skills-config.ts";
 export type {
 	AttachmentPort,
@@ -58,6 +60,12 @@ export type {
 	TurnAttachmentOptions,
 } from "./core/contract/attachments.ts";
 export { AttachmentRefusal } from "./core/contract/attachments.ts";
+export type {
+	ChannelContextSource,
+	ChannelContextSourceAttachment,
+	ChannelContexts,
+	ChannelContextVerdict,
+} from "./core/contract/channel-context.ts";
 export type {
 	Admission,
 	AttachmentContent,
@@ -213,6 +221,12 @@ export type {
 	RoleSource,
 } from "./core/identity/principal-store.ts";
 export { SYSTEM_PRINCIPAL } from "./core/identity/principal-store.ts";
+export type {
+	PersonDisplay,
+	PersonProfiles,
+	ProfileRules,
+	ProfileSource,
+} from "./core/identity/profiles.ts";
 export type {
 	Approval,
 	ApprovalDetails,
@@ -306,6 +320,8 @@ export type {
 } from "./core/modules/skills/skill-rules.ts";
 export { SkillConflictError } from "./core/modules/skills/skill-rules.ts";
 export type {
+	ActionEvent,
+	AgentTools,
 	Contribution,
 	EventHandlers,
 	EventSink,
@@ -360,6 +376,7 @@ export type {
 export {
 	AGENTS,
 	BACKGROUND_TURNS,
+	CHANNEL_CONTEXT,
 	CONVERSATIONS,
 	DELEGATION,
 	IDENTITY,
@@ -367,6 +384,7 @@ export {
 	MEMORY,
 	MODES,
 	PRECHECKS,
+	PROFILES,
 	PROMPTS,
 	RUNTIME,
 	SCHEDULES,

package/src/kit/index.ts

@@ -116,6 +116,7 @@ export {
 	SCHEDULE_TOOLS,
 	scheduleToolSpecs,
 } from "./mirror.ts";
+export { oidcIdentity, oidcProvider } from "./oidc.ts";
 export type {
 	OpsAlertKind,
 	OpsAlertsOptions,

package/src/kit/oidc.ts

@@ -0,0 +1,16 @@
+/**
+ * The identity provider of an OpenID issuer, as `access.owners[].identities`, `selfLink.providers`
+ * and `ActorFacts.provider` write it: `oidc:<base64url(issuer)>`. The issuer is encoded so its own
+ * colons stay apart from the subject's.
+ */
+export function oidcProvider(issuer: string): string {
+	return `oidc:${Buffer.from(issuer).toString("base64url")}`;
+}
+
+/**
+ * The identity of one OpenID subject, `oidcProvider(issuer)` and the subject: the form
+ * `roundtable principal link` and `access.owners[].identities` take, and the 0.8 web speaker id.
+ */
+export function oidcIdentity(issuer: string, subject: string): string {
+	return `${oidcProvider(issuer)}:${subject}`;
+}

package/src/testing.ts

@@ -455,6 +455,7 @@ export async function testPlugin(
 		timeZone: "UTC",
 		now: () => new Date(),
 		characterSkins: CATALOG.skins,
+		agentTools: "full",
 		...options.env,
 	};
 	// What the agent server does with the slot: the provider's runtime serves `context.turns`.