pi-roundtable 0.24.2 → 0.25.0

package/CHANGELOG.md

@@ -5,6 +5,17 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.25.0] - 2026-10-29
+
+### Added
+
+- The agent team can be edited by an owner outside an agent turn, with the operations the agent tools use. `AgentTeam` gains `createAgent(speaker, input)` (the fields of `agent_create`, `NewAgent`, plus `model` and `thinking`, checked before a picture or channel is made; without a `task` the agent only exists, and `openIn` names the surface whose room runs the opening task), `archive(caller | undefined, name)` (an owner has no calling agent), `restore(name)` and `remove(name, cleanup?)` for an archived agent or group (`cleanup` is the caller's part of the delete: it runs once the checks have passed and before anything is deleted, and one that throws leaves the target in place to delete again), and `createGroup` and `updateGroup`. Restoring moves a Discord channel back out of Archive (a new channel replaces one deleted meanwhile); an agent does not rejoin the groups it left, and a group needs all its members active. A group that an agent's archive would leave with fewer than two members is archived whole, its members kept, and restores once they are all active again. Removing frees the name, detaches the agent's skills, clears its group cursors and a group's messages, makes the runtime forget the conversations the name kept (an agent's own, its seats in every group, a group's members' seats), and leaves a Discord channel under Archive; an agent the host's seeds name is refused, since the next start would seed it again. Editing a group starts the seats of the members it removes over. `AgentTurnRunner` (the part of the runtime the agent team drives) gains `deleteConversation`, so a hand-built runner for the team must set it. The store gains `restoreAgent`, `restoreGroup`, `checkRestorableGroup`, `deleteAgent` and `deleteGroup`. `AgentTeam` has new required methods, so code that builds an `AgentTeam` by hand (a test stand-in) must set them.
+- `pi-roundtable-web`: make, archive and arrange agents from the app. The **+** button of the room list and the drawer opens New agent (name, permanent name, prompt, model, optional opening task and a look from the creator; the new agent's room opens), New group and Archived. The agent sheet gains a Skills section (a switch per skill of the host's catalog; built-in ones stay on) and Archive; a group has a sheet for its name, members and host. Archive asks first and names the agent or group, and Archived lists what was archived with Restore and Delete, which asks first too and frees the name. New owner-only routes carry it: `POST agents`, `POST agents/<name>/archive` and `restore`, `DELETE agents/<name>`, `GET`/`PUT agents/<name>/skills`, `POST groups`, `GET`/`PATCH`/`DELETE groups/<name>`, `POST groups/<name>/archive` and `restore`, and `GET archive`. The new sheets load on demand. The package's changelog has the detail.
+- Prompt texts and skills the owner edits outside an agent turn. A new built-in `prompts` plugin provides `PROMPTS` (`PromptDocuments`): named prompt documents, each with a file version, an override stored in PostgreSQL (additive migrations `prompt-overrides` and `prompt-history`) and a history of who changed what and when. `register(spec)` (`PromptDocumentSpec`: `id`, `label`, `description?`, `default` as a string or a function read at each use, `maxChars?`) returns a `PromptHandle` whose `text()` a plugin reads when it builds a prompt; `set(id, text, by, base?)` stores the override, which wins while it is set and applies from the next turn without a restart; `revert(id, by, base?)` returns to the file version; a `base` that is not the text in force when the write takes its turn in the queue refuses it with `PromptConflictError` (carrying the current document), so two saves from one text give one write; a function `default` that throws is an `AgentError` when the document is registered, and later (the file was removed) makes `text(id)` throw naming the document and log an error, ends the run that read it (a persona or an agent's prompt) instead of leaving it with the old text, and marks the document `broken` in `list()` and `get()` (empty `fileText`, `set` and `revert` refused) without failing the others; `list`, `get` and `history` read it (`PromptDocumentView`, `PromptVersion`). The core registers `shared` (`prompts.shared`) and `guest` (`prompts.guest`); a plugin registers its own, such as a persona's prompt. It is on by default because nothing is overridden until the owner saves a text and the file stays the default; at start the host logs one warning per document that differs from its file version, naming who set it and when. A directory agent keeps its stored prompt as the source (seeds do not overwrite an existing row): `AgentTeam.update(name, change, by?)` now records who changed the prompt, and `AgentTeam.promptHistory(name, limit?)` lists the versions. `SkillRegistry` gains `document(name)`, `saveDocument(name, text, baseHash, by)`, `createDocument(text, by)` and `documentHistory(name)` (`SkillDocument`, `SkillVersion`): an agent-written skill's whole SKILL.md with its SHA-256 hash, saved against that hash with the skill tools' frontmatter rules, refused with `SkillConflictError` (carrying the current document) when it changed meanwhile, and kept as versions. `skill_create` and `skill_update` take their turn in the same queue as an owner's save, so neither overwrites the other unseen, and they record the agent's name as the author of a version. `AgentTeam` has the new required `promptHistory`, and `SkillRegistry` four new required methods, so a hand-built stand-in must set them. See [`PROMPTS`](docs/plugins.md#prompts-prompt-texts-the-owner-edits).
+- `pi-roundtable-web`: edit the main prompts and skills from the app. **Main prompts** (linked from Settings) lists the prompt documents (`shared`, `guest` and a plugin's own) with a "differs from the file version" badge, and edits one in a full-screen sheet with a diff to read before saving, a history (read a version against the one before, take it into the editor) and **Revert to the file version**, which asks first. The agent sheet gains History for the agent's prompt. The Skills page edits an agent-written skill's whole SKILL.md and makes a new skill, with the same frontmatter rules as the skill tools, a diff to read, a history and a conflict check (`409`, the diff read again against what is there now); built-in, package and linked skills show a lock and where they come from. Deleting a skill is not offered here. Owner-only routes: `GET api/prompts`, `GET`/`PUT api/prompts/<id>`, `POST api/prompts/<id>/revert`, `GET api/prompts/<id>/history`, `GET api/agents/<name>/prompt-history`, `GET`/`PUT api/skill-docs/<name>`, `POST api/skill-docs`, `GET api/skill-docs/<name>/history`. The package's changelog has the detail.
+- `pi-roundtable-web`: pins and folders for the room list, shared by every owner and device, with drag to reorder and move, a menu for each, and a mute for a whole folder. Three additive tables (`web_room_folders`, `web_room_folder_rooms`, `web_room_pins`) and owner-only routes carry it; the package's changelog has the detail.
+- `pi-roundtable-web`: choose who sits at the round table. A button in the page's header lists every agent with a switch; an agent that leaves the table has its room's push muted, and a seat that leaves or joins plays a short show. The package's changelog has the detail.
+
 ## [0.24.2] - 2026-10-29
 
 ### Added

package/docs/plugins.md

@@ -239,7 +239,8 @@ The built-in plugins provide these, from the main entry:
 | `MODES` | `ConversationModes` | `modes` | Each conversation's modes, stored per key and kept across restarts: `peek(channel)` gives its `ConversationMode` (`yolo` and `longRunning`, both off by default; `changedBy?`, `changedAt?`) from memory, `set(channel, { yolo?, longRunning? }, speaker)` changes them and throws `PluginError` unless the speaker is an owner other than `SYSTEM_PRINCIPAL`, `onChange(listener)` hears each change, and `autoApproved(entry)` with `onAutoApproved(listener)` report a held call that yolo mode approved. See [Conversation modes](#conversation-modes-modes) |
 | `RUNTIME` | `AgentRuntime` | `runtime` | The runtime every conversation turn runs on, the agent server's and `context.turns`': the `runtime` slot's when a plugin fills it, Pi's otherwise |
 | `AGENTS` | `AgentServer` | `agent-server` | The `team` (`AgentTeam`), the read-only `directory` (`AgentDirectory`), the `runtime` every agent turn runs on (the same one `RUNTIME` provides), `approvals` (whether the owner's reply approves held actions), `avatars` (`AvatarStudio`), and `workspace` (`AgentWorkspace`: the agents' `workDir` and, when set, `scratchDir`) |
-| `SKILLS` | `SkillRegistry` | `skills` (an addon) | What agents carry: `carried`, `carriedNames`, `describeCarried`, `catalog`, `list`, `linkedFrom`, `checkRegistered`, `link`, `attach` |
+| `PROMPTS` | `PromptDocuments` | `prompts` | The prompt texts the owner edits in the app, each with a file version, an override and a history: `register`, `text`, `list`, `get`, `set`, `revert`, `history`. Always on; read it with `get`. See [`PROMPTS`: prompt texts the owner edits](#prompts-prompt-texts-the-owner-edits) |
+| `SKILLS` | `SkillRegistry` | `skills` (an addon) | What agents carry: `carried`, `carriedNames`, `describeCarried`, `catalog`, `list`, `linkedFrom`, `checkRegistered`, `link`, `attach`, and the owner's whole-SKILL.md edits `document`, `saveDocument`, `createDocument`, `documentHistory` |
 | `SCHEDULES` | `ScheduleStore` | `schedule-store` | The stored schedules: `create`, `createWithin`, `get`, `forChannel`, `all`, `update`, `remove`, `due`, `claim`, `recordStatus` |
 | `PRECHECKS` | `PrecheckRegistry` | `prechecks` | The host's named [prechecks](#prechecks-wake-a-schedule-only-when-it-has-work): `register`, `get`, `list`; and the runner of agents' precheck scripts: `useScriptRunner`, `scriptRunner` |
 | `MEMORY` | `MemoryStore` | `memory` (an addon) | `forSpeaker(principalId)` gives that principal's `SpeakerMemory`: `list`, `forPrompt`, `add`, `search`, `update`, `removeById`, `remove`; `MEMORY_KINDS` is `core`, `note`, `event` |
@@ -1093,6 +1094,37 @@ const shell = shellHoldRuleFor({
 });
 ```
 
+### `PROMPTS`: prompt texts the owner edits
+
+A prompt that comes from a file or the configuration can be made editable by the owner without touching the file.
+Register a document during `setup`; read its text with `text()` whenever you build a prompt:
+
+```ts
+import { definePlugin, PROMPTS } from "pi-roundtable";
+
+export const persona = definePlugin({
+	name: "persona",
+	setup: ({ services }) => {
+		const merlin = services.get(PROMPTS).register({
+			id: "merlin",
+			label: "Merlin's prompt",
+			description: "Who Merlin is in the owner's conversations.",
+			default: () => readFileSync("persona/merlin.md", "utf8"),
+		});
+		return { personas: [{ kind: "owner", prompt: () => merlin.text() }] };
+	},
+});
+```
+
+- `default` is the file version: a string, or a function called at each read so a default that follows a file is current. The id is 1 to 32 lowercase letters, digits and hyphens; a repeated or unusable id is an `AgentError`, and so is a function `default` that throws when the document is registered, so the host does not start with it. `maxChars` defaults to 20,000.
+- The core registers `shared` (`prompts.shared`, the base every agent's prompt starts with) and `guest` (`prompts.guest`, used when the speaker is not the owner). A plugin's own documents are registered by that plugin; the plugin that registers them is set up after `prompts`, so it can `get` the service.
+- **The override.** `set(id, text, by, base?)` stores the owner's text in PostgreSQL (`prompt_overrides`, with `prompt_history` beside it; both are additive migrations). While an override is set it wins over the file version, and it is read at every turn, so a change applies from the next turn without a restart. `revert(id, by, base?)` drops it and the file version is back. Text equal to the file version reverts instead of storing a copy. A document has `text`, `fileText`, `overridden`, `differs` (set and not equal to the file) and `override: { by, at }`.
+- **Edits from a stale view.** `base` is the text the change was edited from. When it is given, it is compared with the text in force inside the write queue, where the write takes its turn, so two saves from the same text give one write; the other is refused with `PromptConflictError`, whose `current` is the document as it is now. A call without `base` writes as before.
+- **A file that stops reading.** When a function `default` throws later (the file was removed), nothing quietly carries on with an old text: `text(id)` throws an `AgentError` naming the document unless an override is set, and logs an error with the document's id; the persona or agent prompt that asked stops the run it was read for (an error in the log, the turn gets no reply) instead of running with the text it was built with, or with none. `list()` and `get()` still answer for every document: the broken one has `broken` (the reason), an empty `fileText` and `differs: false`, and `set` and `revert` refuse it until the file reads again.
+- **History.** `history(id, limit?)` lists each change newest first: `action` (`set` or `revert`), `text`, the `previous` text, `by` and `at`. An agent's own prompt keeps the same kind of history through `AgentTeam.promptHistory(name)`; `AgentTeam.update(name, change, by?)` records `by`. A directory agent has no override layer: its stored row is the source, and a seed does not overwrite an existing row.
+- **On by default.** The override layer is always on, because nothing is overridden until the owner saves one and the file stays the default. The host logs one warning per document that differs from its file version when it starts, naming who set it and when, and the web app shows a "differs from the file version" badge. Deleting the rows (or using **Revert to the file version**) returns the host to its files.
+- `PromptDocuments.set` and `revert` do not check who calls: the owner-only check belongs to the caller, as the web app's routes do it.
+
 ### `prompt`: text added to every agent turn
 
 Each section's `build` gets the agent, the speaker (undefined between turns), and the turn's scope.
@@ -3247,6 +3279,7 @@ A host that keeps Discord may write it as an adapter instead, as [`adapters`](#a
 - No channel is made, checked or arranged, and the dashboard (a Discord message) does not exist. `channel_arrange` and `channel_read` answer that the host has no Discord channels. `agent_create` and `group_create` make no channel, and a new agent starts its opening task in its room on the first surface that hosts rooms. Archiving an agent or group stops its rooms from answering.
 - An agent's pictures have no public address unless `http.publicUrl` is set: `AGENTS.avatars.url(hash)` is then the path `/avatars/<hash>.png`, which the surface serves itself through `AGENTS.avatars.serve(pathname)` under its own origin, as the web console does. With `http.publicUrl` they are served on the `public` listener as with Discord.
 - `AgentTeam.channelOf(name, near?)` answers with the agent's room on the surface of `near` (the asker's own conversation) when that surface hosts rooms, so `schedule_list` from a room reads the room's schedules; for an agent with no Discord channel it falls back to its room on the first surface that hosts rooms. The status the dashboard and the web read counts an agent's schedules, waiting turns and context use across its Discord channel and its rooms.
+- A surface that lets the owner edit the team uses the same operations the agent tools do, from outside any agent turn: `AgentTeam.createAgent(speaker, input)` (the fields of `agent_create`, plus `model` and `thinking`, which are checked before anything is made; without a `task` the agent only exists, and `openIn` names the surface whose room runs the opening task instead of the Discord channel), `archive(undefined, name)` (an owner has no calling agent, so only the coordinator is protected), `restore(name)`, `remove(name, cleanup?)` (an archived agent or group only, and never an agent the host's seeds name, which the next start would seed again; it runs `cleanup`, your surface's part of the delete, after its checks and before deleting anything, so a cleanup that throws leaves the target in place to try again; then it frees the name, detaches the agent's skills, clears its group cursors and makes the runtime forget the conversations the name kept, and leaves a Discord channel under Archive), and `createGroup` and `updateGroup`. All of them throw `AgentError` with the reason, and fire the team's change signal.
 - Breaking: `AgentGroup.channelId` is optional (`string | undefined`), and so is `GroupStatus.channelId`; a plugin that reads them handles a group without a Discord channel. The `agent_groups.channel_id` column drops its `NOT NULL` in a migration of the agent server (`agent-groups-channel-optional`), and `AgentServerOptions.guildId` and `entryChannelId` are optional, with `coordinator` added. `AvatarStudioOptions.publicUrl` is optional.
 
 <!-- example: examples/headless.ts -->
@@ -4061,6 +4094,7 @@ Import from the entries listed below; source area files are internal.
 | `AvatarMode` | `pi-roundtable` | type |
 | `AgentWorkspace` | `pi-roundtable` | type |
 | `AvatarStudio` | `pi-roundtable` | type |
+| `PROMPTS` | `pi-roundtable` | value |
 | `characterOf` | `pi-roundtable` | value |
 | `BACKGROUND_TURNS` | `pi-roundtable` | value |
 | `CONVERSATIONS` | `pi-roundtable` | value |
@@ -4162,6 +4196,7 @@ Import from the entries listed below; source area files are internal.
 | `ModeChange` | `pi-roundtable` | type |
 | `ModelImage` | `pi-roundtable` | type |
 | `NO_ATTACHMENTS` | `pi-roundtable` | value |
+| `NewAgent` | `pi-roundtable` | type |
 | `NewSchedule` | `pi-roundtable` | type |
 | `NotLinkedError` | `pi-roundtable` | value |
 | `OWNER_TARGET` | `pi-roundtable` | value |
@@ -4178,10 +4213,15 @@ Import from the entries listed below; source area files are internal.
 | `PluginIdentity` | `pi-roundtable` | type |
 | `PluginError` | `pi-roundtable` | value |
 | `Principal` | `pi-roundtable` | type |
+| `PromptDocumentSpec` | `pi-roundtable` | type |
+| `PromptDocuments` | `pi-roundtable` | type |
+| `PromptDocumentView` | `pi-roundtable` | type |
+| `PromptHandle` | `pi-roundtable` | type |
 | `PromptMemory` | `pi-roundtable` | type |
 | `PromptScope` | `pi-roundtable` | type |
 | `PromptSection` | `pi-roundtable` | type |
 | `PromptTurn` | `pi-roundtable` | type |
+| `PromptVersion` | `pi-roundtable` | type |
 | `PromptWait` | `pi-roundtable` | type |
 | `Prompts` | `pi-roundtable` | type |
 | `Pronouns` | `pi-roundtable` | type |
@@ -4224,6 +4264,9 @@ Import from the entries listed below; source area files are internal.
 | `PrecheckScriptRunner` | `pi-roundtable` | type |
 | `PrecheckTool` | `pi-roundtable` | type |
 | `PRECHECK_SCRIPT_CHARS` | `pi-roundtable` | value |
+| `PromptConflictError` | `pi-roundtable` | value |
+| `SkillConflictError` | `pi-roundtable` | value |
+| `SkillDocument` | `pi-roundtable` | type |
 | `SKILLS` | `pi-roundtable` | value |
 | `SINGLE_QUESTION` | `pi-roundtable` | value |
 | `Schedule` | `pi-roundtable` | type |
@@ -4244,6 +4287,7 @@ Import from the entries listed below; source area files are internal.
 | `SessionToolSnapshot` | `pi-roundtable` | type |
 | `SkillCatalogEntry` | `pi-roundtable` | type |
 | `SkillRegistry` | `pi-roundtable` | type |
+| `SkillVersion` | `pi-roundtable` | type |
 | `WorkerSessions` | `pi-roundtable` | type |
 | `WorkerSessionRequest` | `pi-roundtable` | type |
 | `WORKER_SESSIONS` | `pi-roundtable` | value |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable",
-	"version": "0.24.2",
+	"version": "0.25.0",
 	"description": "A plugin-driven Pi agent server for one owner, reached through Discord or the web",
 	"type": "module",
 	"license": "MIT",

package/src/core/agents/agent-book.ts

@@ -0,0 +1,155 @@
+import { AgentError } from "../domain/errors.ts";
+import type { Agent, AgentGroup } from "./agent-rules.ts";
+import {
+	checkAgentName,
+	checkDisplayName,
+	MAX_GROUP_MEMBERS,
+	MIN_GROUP_MEMBERS,
+} from "./agent-rules.ts";
+import {
+	type AgentRow,
+	type GroupRow,
+	toAgent,
+	toGroup,
+} from "./agent-schema.ts";
+
+/**
+ * The agents and groups a guild holds in memory, and the checks that read them: every inbound
+ * message asks, and only this process changes them. The store writes the rows and keeps these
+ * maps in step.
+ */
+export abstract class AgentBook {
+	protected readonly agentMap = new Map<string, Agent>();
+	/** Agents whose character column holds a value, readable or not. */
+	protected readonly dressed = new Set<string>();
+	protected readonly groupMap = new Map<string, AgentGroup>();
+
+	agents(): Agent[] {
+		return [...this.agentMap.values()];
+	}
+
+	agent(name: string): Agent | undefined {
+		return this.agentMap.get(name);
+	}
+
+	/** The active agent with that name, or an error the caller can show. */
+	activeAgent(name: string): Agent {
+		const agent = this.agentMap.get(name);
+		if (!agent)
+			throw new AgentError(
+				`There is no agent "${name}". Active agents: ${this.activeNames()}.`,
+			);
+		if (agent.status !== "active")
+			throw new AgentError(
+				`Agent "${name}" is archived. Active agents: ${this.activeNames()}.`,
+			);
+		return agent;
+	}
+
+	agentByChannel(channelId: string): Agent | undefined {
+		for (const agent of this.agentMap.values())
+			if (agent.channelId === channelId && agent.status === "active")
+				return agent;
+		return undefined;
+	}
+
+	groups(): AgentGroup[] {
+		return [...this.groupMap.values()];
+	}
+
+	group(name: string): AgentGroup | undefined {
+		return this.groupMap.get(name);
+	}
+
+	groupByChannel(channelId: string): AgentGroup | undefined {
+		for (const group of this.groupMap.values())
+			if (group.channelId === channelId && group.status === "active")
+				return group;
+		return undefined;
+	}
+
+	protected activeNames(): string {
+		return (
+			this.agents()
+				.flatMap((a) => (a.status === "active" ? [a.name] : []))
+				.join(", ") || "none"
+		);
+	}
+
+	/** Names are shared between agents and groups, archived ones included. */
+	protected checkFree(name: string): void {
+		if (this.agentMap.has(name) || this.groupMap.has(name))
+			throw new AgentError(
+				`The name "${name}" is taken, archived agents and groups included.`,
+			);
+	}
+
+	/** A name that createAgent would accept, checked before its channel is made. */
+	checkNewName(name: string): void {
+		checkAgentName(name);
+		this.checkFree(name);
+	}
+
+	protected keepAgent(row: AgentRow | undefined): Agent {
+		if (!row) throw new AgentError("the agent was not found");
+		return this.keepAgentRow(row);
+	}
+
+	protected keepAgentRow(row: AgentRow): Agent {
+		const agent = toAgent(row);
+		this.agentMap.set(agent.name, agent);
+		if (row.character !== null && row.character !== undefined)
+			this.dressed.add(agent.name);
+		else this.dressed.delete(agent.name);
+		return agent;
+	}
+
+	/** Whether the stored column holds a character, even one this version cannot read. */
+	hasStoredCharacter(name: string): boolean {
+		return this.dressed.has(name);
+	}
+
+	protected checkMembers(members: readonly string[], host: string): void {
+		if (
+			new Set(members).size !== members.length ||
+			members.length < MIN_GROUP_MEMBERS ||
+			members.length > MAX_GROUP_MEMBERS
+		)
+			throw new AgentError(
+				`A group has ${MIN_GROUP_MEMBERS} to ${MAX_GROUP_MEMBERS} different members.`,
+			);
+		for (const member of members) this.activeAgent(member);
+		if (!members.includes(host))
+			throw new AgentError(`The host "${host}" must be one of the members.`);
+	}
+
+	/** Checks a new group before its channel is made; a `displayName` is checked too. */
+	checkNewGroup(
+		name: string,
+		members: readonly string[],
+		host: string,
+		displayName?: string,
+	): void {
+		checkAgentName(name);
+		if (displayName !== undefined) checkDisplayName(displayName);
+		this.checkFree(name);
+		this.checkMembers(members, host);
+	}
+
+	/** The archived group, when it could be restored now; otherwise the error that says why not. */
+	checkRestorableGroup(name: string): AgentGroup {
+		const current = this.groupMap.get(name);
+		if (!current) throw new AgentError(`There is no group "${name}".`);
+		if (current.status === "active")
+			throw new AgentError(`"${name}" is not archived.`);
+		this.checkMembers(current.members, current.host);
+		return current;
+	}
+
+	protected keepGroup(row: GroupRow | undefined): AgentGroup {
+		if (!row) throw new AgentError("the group was not found");
+		const group = toGroup(row);
+		this.groupMap.set(group.name, group);
+		return group;
+	}
+}

package/src/core/agents/agent-ports.ts

@@ -7,7 +7,11 @@ export type { ContextUse };
 /** The part of the runtime the agent team drives. */
 export type AgentTurnRunner = Pick<
 	AgentRuntime,
-	"runTurn" | "heldActions" | "startFresh" | "contextUsage"
+	| "runTurn"
+	| "heldActions"
+	| "startFresh"
+	| "deleteConversation"
+	| "contextUsage"
 >;
 
 /** One agent's message in a channel, posted under its name and avatar. */

package/src/core/agents/agent-schema.ts

@@ -2,6 +2,7 @@ import { readCharacter } from "../../characters/index.ts";
 import { scopeToGuild } from "../db/guild-scope.ts";
 import type { Migration } from "../db/migrations.ts";
 import type { ThinkingLevel } from "../models.ts";
+import { promptHistoryMigration } from "../modules/prompts/prompt-history.ts";
 import type { Agent, AgentGroup, AgentStatus } from "./agent-rules.ts";
 
 export interface AgentRow {
@@ -133,5 +134,7 @@ export function agentMigrations(guildId: string): Migration[] {
 				await sql`ALTER TABLE agents ADD COLUMN IF NOT EXISTS character jsonb`;
 			},
 		},
+		// The change history of the agents' prompts; the prompts plugin creates the same table for its documents.
+		promptHistoryMigration("agent-prompt-history"),
 	];
 }

package/src/core/agents/agent-statements.ts

@@ -0,0 +1,179 @@
+import type { SQL } from "bun";
+import type { CharacterSpec } from "../../characters/index.ts";
+import type { AgentStatus } from "./agent-rules.ts";
+import type { AgentRow, GroupRow } from "./agent-schema.ts";
+
+/**
+ * The SQL the agent store runs for one guild. The store holds the rows in memory and decides
+ * what may change; each method here only writes the statement and returns the rows it touched.
+ */
+export class AgentStatements {
+	readonly #sql: SQL;
+	readonly #guild: string;
+
+	constructor(sql: SQL, guildId: string) {
+		this.#sql = sql;
+		this.#guild = guildId;
+	}
+
+	/** Inserts a seed agent unless one of that name exists; no row comes back when one does. */
+	insertSeed(seed: {
+		name: string;
+		displayName: string;
+		prompt: string;
+		avatarPrompt: string;
+		channelId: string | null;
+	}): Promise<AgentRow[]> {
+		return this.#sql`
+				INSERT INTO agents (guild_id, name, display_name, prompt, avatar_prompt, channel_id)
+				VALUES (${this.#guild}, ${seed.name}, ${seed.displayName}, ${seed.prompt}, ${seed.avatarPrompt},
+					${seed.channelId})
+				ON CONFLICT DO NOTHING
+				RETURNING *`;
+	}
+
+	insertAgent(agent: {
+		name: string;
+		displayName: string;
+		prompt: string;
+		avatarPrompt: string;
+		channelId: string | null;
+		avatarHash: string | null;
+		character: CharacterSpec | null;
+	}): Promise<AgentRow[]> {
+		return this.#sql`
+			INSERT INTO agents (guild_id, name, display_name, prompt, avatar_prompt, channel_id, avatar_hash, character)
+			VALUES (${this.#guild}, ${agent.name}, ${agent.displayName}, ${agent.prompt}, ${agent.avatarPrompt},
+				${agent.channelId}, ${agent.avatarHash},
+				${agent.character}::jsonb)
+			RETURNING *`;
+	}
+
+	/** Writes every column of an agent; `characterSet` false leaves the stored character alone. */
+	updateAgent(
+		name: string,
+		row: {
+			displayName: string;
+			prompt: string;
+			avatarPrompt: string;
+			avatarHash: string | null;
+			characterSet: boolean;
+			character: CharacterSpec | null;
+			channelId: string | null;
+			model: string | null;
+			thinking: string | null;
+		},
+	): Promise<AgentRow[]> {
+		return this.#sql`
+			UPDATE agents SET
+				display_name = ${row.displayName},
+				prompt = ${row.prompt},
+				avatar_prompt = ${row.avatarPrompt},
+				avatar_hash = ${row.avatarHash},
+				character = CASE WHEN ${row.characterSet} THEN ${row.character}::jsonb ELSE character END,
+				channel_id = ${row.channelId},
+				model = ${row.model},
+				thinking = ${row.thinking},
+				updated_at = now()
+			WHERE guild_id = ${this.#guild} AND name = ${name}
+			RETURNING *`;
+	}
+
+	archiveAgent(name: string): Promise<AgentRow[]> {
+		return this.#sql`
+			UPDATE agents SET status = 'archived', updated_at = now()
+			WHERE guild_id = ${this.#guild} AND name = ${name} RETURNING *`;
+	}
+
+	restoreAgent(name: string, channelId: string | null): Promise<AgentRow[]> {
+		return this.#sql`
+			UPDATE agents SET status = 'active', channel_id = ${channelId},
+				updated_at = now()
+			WHERE guild_id = ${this.#guild} AND name = ${name}
+			RETURNING *`;
+	}
+
+	/** Deletes the agent's row, its group cursors and its prompt history together. */
+	async deleteAgent(name: string): Promise<void> {
+		await this.#sql.begin(async (tx) => {
+			await tx`DELETE FROM agent_group_cursors WHERE guild_id = ${this.#guild} AND agent_name = ${name}`;
+			await tx`DELETE FROM prompt_history WHERE guild_id = ${this.#guild} AND kind = 'agent' AND name = ${name}`;
+			await tx`DELETE FROM agents WHERE guild_id = ${this.#guild} AND name = ${name}`;
+		});
+	}
+
+	/** Gives an agent a character and picture only while it has no character. */
+	dressIfUndressed(
+		name: string,
+		character: CharacterSpec,
+		avatarHash: string,
+	): Promise<AgentRow[]> {
+		return this.#sql`
+			UPDATE agents SET character = ${character}::jsonb, avatar_hash = ${avatarHash}, updated_at = now()
+			WHERE guild_id = ${this.#guild} AND name = ${name} AND character IS NULL
+			RETURNING *`;
+	}
+
+	/** Sets the picture only while the agent is active and still wears `character`. */
+	setAvatarIfLook(
+		name: string,
+		character: CharacterSpec,
+		avatarHash: string,
+	): Promise<AgentRow[]> {
+		return this.#sql`
+			UPDATE agents SET avatar_hash = ${avatarHash}, updated_at = now()
+			WHERE guild_id = ${this.#guild} AND name = ${name} AND status = 'active'
+				AND character = ${character}::jsonb
+			RETURNING *`;
+	}
+
+	insertGroup(group: {
+		name: string;
+		displayName: string;
+		channelId: string | null;
+		members: readonly string[];
+		host: string;
+	}): Promise<GroupRow[]> {
+		return this.#sql`
+			INSERT INTO agent_groups (guild_id, name, display_name, channel_id, members, host)
+			VALUES (${this.#guild}, ${group.name}, ${group.displayName}, ${group.channelId},
+				${group.members.join(",")}, ${group.host})
+			RETURNING *`;
+	}
+
+	updateGroup(
+		name: string,
+		row: {
+			displayName: string;
+			members: readonly string[];
+			host: string;
+			status: AgentStatus;
+		},
+	): Promise<GroupRow[]> {
+		return this.#sql`
+			UPDATE agent_groups SET
+				display_name = ${row.displayName},
+				members = ${row.members.join(",")},
+				host = ${row.host},
+				status = ${row.status}
+			WHERE guild_id = ${this.#guild} AND name = ${name}
+			RETURNING *`;
+	}
+
+	restoreGroup(name: string, channelId: string | null): Promise<GroupRow[]> {
+		return this.#sql`
+			UPDATE agent_groups SET status = 'active', channel_id = ${channelId}
+			WHERE guild_id = ${this.#guild} AND name = ${name}
+			RETURNING *`;
+	}
+
+	/** Deletes the group's row, messages and cursors, in the Discord channel's log and each room's. */
+	async deleteGroup(name: string): Promise<void> {
+		const rooms = `${name}@%`;
+		await this.#sql.begin(async (tx) => {
+			await tx`DELETE FROM agent_group_cursors WHERE guild_id = ${this.#guild} AND (group_name = ${name} OR group_name LIKE ${rooms})`;
+			await tx`DELETE FROM agent_group_messages WHERE guild_id = ${this.#guild} AND (group_name = ${name} OR group_name LIKE ${rooms})`;
+			await tx`DELETE FROM agent_groups WHERE guild_id = ${this.#guild} AND name = ${name}`;
+		});
+	}
+}