pi-roundtable 0.24.2 → 0.26.0

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 {
@@ -25,6 +27,10 @@ import type {
 	MemoryKind,
 	PromptMemory,
 } from "./modules/memory/owner-memory-store.ts";
+import type {
+	PromptDocuments,
+	PromptVersion,
+} from "./modules/prompts/prompt-documents.ts";
 import type {
 	PrecheckFinding,
 	PrecheckRegistry,
@@ -34,11 +40,9 @@ import type {
 	Schedule,
 	ScheduleChange,
 } from "./modules/schedules/schedule-store.ts";
-import type {
-	SkillCatalogEntry,
-	SkillSet,
-} from "./modules/skills/skill-rules.ts";
+import type { SkillRegistry } from "./modules/skills/skill-contract.ts";
 import type { AgentTurnScope, ChannelKey } from "./sessions.ts";
+import type { Speaker } from "./speakers.ts";
 import type { DispatchThreads } from "./threads/dispatch-threads.ts";
 
 // The services the built-in plugins provide, and the ports they keep to. Each port is an
@@ -51,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
@@ -90,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",
@@ -145,6 +156,16 @@ export const SKILLS: ServiceKey<SkillRegistry> = serviceKey<SkillRegistry>(
 	},
 );
 
+/**
+ * The prompt texts the owner edits in the app, each with a file version, an override and a
+ * history. Provided by the built-in `prompts` plugin, which registers `shared` and `guest` (the
+ * prompts of the agent server) and which every plugin set up after it may register more with; a
+ * plugin reads a document's `text()` when it builds a prompt, so an override applies from the next
+ * turn. Read it with `get`: the plugin is always on.
+ */
+export const PROMPTS: ServiceKey<PromptDocuments> =
+	serviceKey<PromptDocuments>("roundtable.prompts");
+
 /** What the agent server builds, for the plugins set up after it. */
 export interface AgentServer {
 	team: AgentTeam;
@@ -209,6 +230,29 @@ export interface AgentDirectory {
 	groupByChannel(channelId: string): AgentGroup | undefined;
 }
 
+/** What an owner gives to create an agent: the fields of `agent_create`, with the settings `update` takes. */
+export interface NewAgent {
+	/** Permanent: lowercase letters, digits and dashes, 1 to 32. */
+	name: string;
+	displayName: string;
+	prompt: string;
+	/** Fields of its look; any left out come from the look its role suggests. */
+	character?: CharacterInput;
+	/** Its opening task; without it the agent only exists. */
+	task?: string;
+	/**
+	 * The surface whose room the opening task runs in, so the person who asked sees it start
+	 * there. Without it, or for a surface that hosts no rooms, the task runs where `agent_create`
+	 * runs it: the agent's Discord channel, else its first room.
+	 */
+	openIn?: string;
+	category?: string;
+	/** Skills it carries; refused when the skills addon is off. */
+	skills?: string[];
+	model?: string;
+	thinking?: string;
+}
+
 /** What an agent's settings may change, as `update` takes it. */
 export interface AgentChange {
 	displayName?: string;
@@ -259,8 +303,54 @@ export interface AgentTeam {
 	postAs(caller: AgentTurnScope, text: string): Promise<void>;
 	/** The assistant's own notice, posted in the coordinator's channel under its name. */
 	announce(text: string): Promise<void>;
-	/** Changes an agent's display name, prompt, model, or thinking level; a model must be one the host runs. */
-	update(name: string, change: AgentChange): Promise<string>;
+	/**
+	 * Changes an agent's display name, prompt, model, or thinking level; a model must be one the
+	 * host runs. `by` names who asks; a changed prompt is kept in the agent's prompt history under it.
+	 */
+	update(name: string, change: AgentChange, by?: string): Promise<string>;
+	/** The changes of an agent's prompt, newest first: who made each, when, and the text it replaced. */
+	promptHistory(name: string, limit?: number): Promise<PromptVersion[]>;
+	/**
+	 * Creates an agent for an owner, outside any agent turn: the checks, picture, channel and
+	 * opening task of `agent_create`, with `speaker` as the one who asked. `model` and `thinking`
+	 * take what `update` takes and are checked before anything is made; `task` is optional, and
+	 * without it the agent waits in its room. Throws AgentError for a bad or taken name, an
+	 * unusable model or an unknown skill.
+	 */
+	createAgent(speaker: Speaker, input: NewAgent): Promise<Agent>;
+	/**
+	 * Archives an agent or group like the `archive` tool: it stops answering, its schedules are
+	 * cancelled, an agent leaves its groups, and its history is kept. `caller` is the agent that
+	 * asks, which cannot archive itself; an owner's request has none. The coordinator cannot be
+	 * archived.
+	 */
+	archive(caller: AgentTurnScope | undefined, name: string): Promise<string>;
+	/**
+	 * Returns an archived agent or group to the active ones. An agent rejoins no group; a group
+	 * needs all its members active. Throws AgentError for an unknown or active name.
+	 */
+	restore(name: string): Promise<string>;
+	/**
+	 * Deletes an archived agent or group for good and frees its name. Throws AgentError for an
+	 * unknown name, for an active one (archive it first), and for an agent the host's seeds name,
+	 * which the next start would seed again. `cleanup` is a surface's own part of the delete (what
+	 * it kept under the name): it runs once the checks have passed and before anything is deleted,
+	 * and one that throws leaves the agent or group in place, so the delete can be tried again.
+	 */
+	remove(name: string, cleanup?: () => Promise<void>): Promise<string>;
+	/** Creates a group of 2 to 6 agents; the host is the first member unless given. */
+	createGroup(input: {
+		name: string;
+		displayName: string;
+		members: string[];
+		host?: string;
+		category?: string;
+	}): Promise<string>;
+	/** Changes a group's display name, members (all of them) or host. */
+	updateGroup(
+		name: string,
+		change: { displayName?: string; members?: string[]; host?: string },
+	): Promise<string>;
 	/**
 	 * Changes an agent's look: `input` is resolved over its current character (a new class keeps
 	 * its colors unless the input gives a palette or colors), rendered, and stored with the new
@@ -406,30 +496,4 @@ export interface SpeakerMemory {
 	remove(text: string): Promise<string[]>;
 }
 
-/** The skills agents carry: built in, linked from repositories, or written by an agent. */
-export interface SkillRegistry {
-	/** The built-in skills plus the named registered ones, resolved to their files. */
-	resolve(names: readonly string[]): SkillSet;
-	/** What an agent carries, built-in skills included. */
-	carried(agent: string): SkillSet;
-	/** The registered skills an agent carries, as the dashboard lists them. */
-	carriedNames(agent: string): string[];
-	/** An agent's skills as `agent_get` shows them. */
-	describeCarried(agent: string): string;
-	/** Every skill, built-in ones first. */
-	catalog(): SkillCatalogEntry[];
-	/** Every skill, or those of a group or matching a query, as the `skill_list` tool shows them. */
-	list(filter?: { group?: string; query?: string }): string;
-	/** The skills linked from a managed repository. */
-	linkedFrom(repo: string): string[];
-	/** Throws AgentError when a name is not registered; built-in names are carried already. */
-	checkRegistered(names: readonly string[]): void;
-	/** Links the skill at a repository path, or every child folder with a SKILL.md. */
-	link(repo: string, path: string): Promise<string>;
-	/** Adds and removes an agent's registered skills together, or changes nothing; returns what it carries after. */
-	attach(
-		agent: string,
-		add: readonly string[],
-		remove: readonly string[],
-	): Promise<string[]>;
-}
+export type { SkillRegistry } from "./modules/skills/skill-contract.ts";

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,
@@ -264,6 +278,14 @@ export type {
 	PromptMemory,
 } from "./core/modules/memory/owner-memory-store.ts";
 export { MEMORY_KINDS } from "./core/modules/memory/owner-memory-store.ts";
+export type {
+	PromptDocumentSpec,
+	PromptDocuments,
+	PromptDocumentView,
+	PromptHandle,
+	PromptVersion,
+} from "./core/modules/prompts/prompt-documents.ts";
+export { PromptConflictError } from "./core/modules/prompts/prompt-documents.ts";
 export type { PrecheckTool } from "./core/modules/schedules/precheck-tools.ts";
 export type {
 	Precheck,
@@ -291,10 +313,15 @@ export type {
 export type {
 	ResolvedSkill,
 	SkillCatalogEntry,
+	SkillDocument,
 	SkillSet,
 	SkillSource,
+	SkillVersion,
 } from "./core/modules/skills/skill-rules.ts";
+export { SkillConflictError } from "./core/modules/skills/skill-rules.ts";
 export type {
+	ActionEvent,
+	AgentTools,
 	Contribution,
 	EventHandlers,
 	EventSink,
@@ -339,6 +366,7 @@ export type {
 	DelegationRequest,
 	Delegator,
 	MemoryStore,
+	NewAgent,
 	ScheduleStore,
 	SkillRegistry,
 	SpeakerMemory,
@@ -348,6 +376,7 @@ export type {
 export {
 	AGENTS,
 	BACKGROUND_TURNS,
+	CHANNEL_CONTEXT,
 	CONVERSATIONS,
 	DELEGATION,
 	IDENTITY,
@@ -355,6 +384,8 @@ export {
 	MEMORY,
 	MODES,
 	PRECHECKS,
+	PROFILES,
+	PROMPTS,
 	RUNTIME,
 	SCHEDULES,
 	SKILLS,

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`.