pi-roundtable 0.28.0 → 0.29.1

package/CHANGELOG.md

@@ -5,6 +5,31 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.29.1] - 2026-10-31
+
+### Added
+
+- Queued messages can be listed, edited and cancelled. A message sent while a turn runs that the turn did not take waits in the channel's queue (`QUEUED_MARK`); until its own turn starts, `ConversationPort.queued(channel)` lists it (`QueuedMessage`: `messageId`, `principalId`, `text`, `queuedAt`), `cancelQueued(channel, messageId, by)` makes its turn never run (the claim's `Admission.dropped` is called and the mark comes off), and `editQueued(channel, messageId, by, text)` admits it again with the new text, so the turn runs on that. `by` is the author's principal (`QueuedBy`); anyone else gets `forbidden`, and a message that started, was steered or was cancelled is `unknown` (`QueuedChange`). The three are optional on the port type, as `messageDeleted` is. A surface that reports a deleted queued message cancels it, and one that reports an edited one changes its text, through `SurfaceMessageEvents` as before: on Discord, deleting a queued message cancels it and editing it changes what its turn uses. `QUEUED_MARK` and `STEERED_MARK` are exported from the main entry.
+
+## [0.29.0] - 2026-10-31
+
+### Added
+
+- `SkillRegistry.groups()`, `setGroup(name, description, skills)` and `deleteGroup(name)` are part of the skill registry interface (`SkillGroup`: `name`, `description`, `skills`), so a host surface can manage skill groups. A group stays a filter and a list to apply once: an agent carries skills, not groups. `SkillRegistry` has three new required methods, so a hand-built stand-in must set them.
+- `helperSurface` tells the surface a temp knight was made on, read off its stored origin. `AgentOps.reach` readies a message's place before `message_agent` delivers it.
+
+### Changed
+
+- Delivery follows the conversation the work came from. One delivery router (`src/core/presence/delivery-router.ts`) decides where a notice or run for a person goes from its origin: a provider on the origin's surface first, another surface only when none there reaches the person, logged with both surfaces. A schedule made in a web room that calls `notify` now notices in the web app (Home notice and push) instead of a Discord direct message. The web app's push mirror of a notice Discord delivered stays, to the same person only.
+- Breaking: `DirectChannels.reach`, `known`, and `notify` take the origin `ChannelKey` first (`reach(origin, principalId)`, `notify(origin, principalId, text)`), and `DirectChannels` no longer extends `Notifier`. `DirectChannelProvider.surface` (optional, default `name`) names the surface a provider reaches; the Discord, web, and webchat providers set it.
+- `message_agent` without `conversation` reaches the target's place on the sender's surface (`routing.agents.<name>.agentMessage` default `origin-surface`), never the conversation it used most recently on another surface; with no place there it lands in the primary place, logged. `latest` now follows only on the sender's surface. `RoutingTable.of(agent, "agentMessage", origin)` requires the origin.
+- The notify tool's description says it goes out on the conversation's own surface.
+- A temp knight lives only on the surface of the conversation that made it. One made in the web app gets no Discord thread at creation; the thread is made once, when a `message_agent` call from a turn that may message it names `conversation: "discord"`, or names no conversation from a Discord turn (where an unnamed message goes), and restoring it reopens the thread it had but never makes a new one. Archiving one without a thread works as before. A temp knight made before its origin was kept is placed as before. See pi-roundtable-web for the rooms of temp knights made on Discord.
+
+### Fixed
+
+- A group seat outside its running turn, such as after a start-over, stays in the group's room on its own surface instead of falling out to the group's Discord channel.
+
 ## [0.28.0] - 2026-10-31
 
 ### Added

package/docs/plugins.md

@@ -182,7 +182,7 @@ A plugin that replaces `IDENTITY` replaces this too: the declarations are the bu
 | `surfaces` | Every contributed [chat surface](#surfaces-a-chat-network-of-your-own), chosen by the prefix of a channel key: `of`, `sendReply`, `startTyping`, `showStop`, `react`, `unreact`, `prompts` |
 | `turns` | Runs one turn of a conversation your claim owns, over the runtime and the surfaces: [`turns.run`](#personas-and-contextturns-conversations-of-a-kind-of-your-own) |
 | `observe(filter, observer)` | Hears inbound messages without owning or admitting them: [`observe`](#observe-hearing-messages-without-owning-them). Returns a function that stops it; may be called during `setup` |
-| `directChannels` | Every plugin's [direct channels](#directchannels-reaching-a-person-on-their-own): `providers()`, `reach(principalId)`, `known(principalId)`, and `notify(principalId, text)` |
+| `directChannels` | Every plugin's [direct channels](#directchannels-reaching-a-person-on-their-own): `providers()`, `reach(origin, principalId)`, `known(origin, principalId)`, and `notify(origin, principalId, text)`, each through the [delivery router](#where-things-are-delivered) |
 | `sessions()`, `conversations`, `surfaces`, `directChannels`, `turns`, `dashboard()` | Linked once every plugin has been set up; calling them during `setup` throws `NotLinkedError` |
 
 `sessions()`, `conversations`, `surfaces`, `directChannels`, `turns`, and `dashboard()` are available from a service's `start`, an event handler, a session tool, or a claim's turn.
@@ -258,7 +258,7 @@ The built-in plugins provide these, from the main entry:
 | `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`), `workspace` (`AgentWorkspace`: the agents' `workDir` and, when set, `scratchDir`), and `routes` (`RoutingTable`: where work no person started lands; see [Routing](#routing-where-work-no-person-started-lands)) |
 | `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` |
+| `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`, and the groups `groups`, `setGroup`, `deleteGroup` |
 | `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` |
@@ -2436,6 +2436,8 @@ When that record finds the author someone else than the claim admitted, such as
 
 A claim may also hear that a message it owns changed, through `onMessageDeleted(channel, messageId)` and `onMessageEdited(message)`, which a surface reports with the second argument of its `start` (`{ deleted, edited }`, a `SurfaceMessageEvents`). Discord reports both, including for a message the bot had not cached; a surface that cannot tell never calls them. The router delivers each as it comes, to the claim that owns the channel and no other, outside the channel's queue, so a running turn does not hold it up; a throw or rejection is logged and never fails the router. A delete carries only ids, and Discord's delete event does not say who wrote the message, so the claim hears the deletion of the bot's own messages too and ignores an id it does not know. An edit carries the message as it reads now, as an `InboundMessage`, without `speaker` or `peerBot` because nobody is resolved or admitted for it; the bot's own edits are not reported, nor is a change that leaves the text, the embeds and the attachments as they were, such as a pin. A bulk delete is reported as one delete per message.
 
+A message sent while a turn runs is first offered to that turn (`busy.steer`); one the turn does not take waits in the channel's queue with `QUEUED_MARK`, and until its own turn starts the conversation port can list, cancel and edit it: `queued(channel)` returns its waiting messages oldest first (`messageId`, the author's `principalId`, the `text` its turn will use, `queuedAt`); `cancelQueued(channel, messageId, { principalId })` makes its turn never run, calling the admission's `dropped` and removing the mark; `editQueued(channel, messageId, { principalId }, text)` admits the message again with the new text through the claim's `admit`, drops the old admission, and the turn runs on the new one. Only the message's author may (a different principal gets `forbidden`, and a message with no resolved author can be changed by no one). A message whose turn has started, was steered into the running turn, or was cancelled is `unknown`; an edit the claim would no longer admit is `refused` and the old text stays. The decision is made in one synchronous step, so a cancel or an edit and the start of the turn never both win. The surface's own copy of the message is the caller's to change. When a surface reports a queued message deleted or edited (`onMessageDeleted`, `onMessageEdited` above), the router cancels it or changes its text itself, without the author check since the surface says it happened: that is how deleting a queued Discord message cancels it. The three methods are optional on `ConversationPort`, as `messageDeleted` is.
+
 A claim may have `stop(channel)`, which stops the channel's running turn and returns whether one was running; the Stop button, `conversations.stop`, and every other stop go through it.
 The router calls only the owning claim's `stop`, returning `false` when that method is absent.
 Give `stop` to a claim whose conversations run turns that can be interrupted.
@@ -2999,6 +3001,7 @@ setup: ({ services }) => ({
 	directChannels: [
 		{
 			name: "inbox",
+			surface: "chat",
 			label: "a notice in the web chat's inbox",
 			reaches: async (principalId) => inboxOf(principalId),
 			deliver: async (principalId, text) => postNotice(principalId, text),
@@ -3010,23 +3013,36 @@ setup: ({ services }) => ({
 | Field | What it is |
 |---|---|
 | `name` | Unique across every plugin; a second provider of one name is a `PluginError` naming both plugins |
+| `surface` | Optional: the surface whose conversations it reaches, the key prefix of the channels `reaches` names, such as `discord` or the web app's `app`. Work from a conversation on that surface reaches the person here first. Without it, `name` |
 | `label` | How the `notify` tool names a notice sent through it, completing "Send Ada …", such as `a direct message on Discord` |
 | `reaches(principalId)` | The person's own conversation here, as a channel key, or `undefined` when they have none here. It may reach the network and throw |
 | `knows(principalId)` | Optional: whether the person has a conversation here, from the host's own records such as their linked identities, without the network. A session asks it when it decides whether to offer `notify` or the schedule and delegation tools, so an outage then does not take them away; without it the host asks `reaches` |
 | `deliver(principalId, text)` | Optional: sends the notice itself. Without it the host posts the text in the channel `reaches` names, through the surface that serves it |
-| `mirror(principalId, text)` | Optional: echoes a notice another provider delivered, such as a web app pushing to a phone that Discord's direct message already reached. `notify` calls it on every provider but the one that delivered, only after a delivery; a failure is logged and never changes the result |
+| `mirror(principalId, text)` | Optional: echoes a notice another provider delivered to the same person, such as a web app pushing to a phone that Discord's direct message already reached. `notify` calls it on every provider but the one that delivered, only after a delivery; a failure is logged and never changes the result |
 
-The host reaches a person through the first provider, in contribution order, that reaches them.
-`context.directChannels.reach(principalId)` resolves that provider and channel, or `undefined`; `known(principalId)` resolves the first provider that knows the person without the network; `notify(principalId, text)` sends a notice there and resolves `false` when no provider reaches the person.
+Every lookup takes the *origin*: the conversation the work came from. The host reaches a person through a provider on the origin's surface, and through another only when none there reaches them, as [Where things are delivered](#where-things-are-delivered) describes.
+`context.directChannels.reach(origin, principalId)` resolves that provider and channel, or `undefined`; `known(origin, principalId)` resolves the provider that knows the person without the network, in the same order; `notify(origin, principalId, text)` sends a notice there and resolves `false` when no provider reaches the person.
 The Discord plugin contributes one named `discord`: it finds a principal's Discord identities through `IDENTITY` and reaches the first one's direct messages, the primary owner's configured identity first, so a single owner is reached in the same direct messages as in 0.8.
 
 The `notify` tool, 0.8's `notify_owner`, sends such a notice. A session has it only when a provider is contributed, and a private conversation only when a provider knows its person; the channel itself is reached when a notice is sent.
 It notifies the conversation's person in a private conversation and the turn's speaker in a shared one, and refuses when no provider reaches them or when the speaker is not the private conversation's person; the host's own turns, such as a report's, notify the conversation's person in a private conversation and the primary owner elsewhere, as `notify_owner` did.
-Its description names the channels that can reach the person, so a host with only Discord reads `Send Ada a direct message on Discord. …` as 0.8 did.
+It sends on the conversation's own surface: from a web room the web app's notice and push, from Discord a Discord direct message. Its description names the channel on that surface that can reach the person, and says it goes out on the conversation's own surface, such as `Send Ada a direct message on Discord. It goes out on this conversation's own surface. …`.
 In a shared conversation it names the primary owner while only they can receive a notice (the host has no other owner, and only owners may use it), and "the speaker" otherwise; this is checked again before each turn, so an open session follows an owner granted or revoked meanwhile.
 Until 1.0 the name `notify_owner` still selects it in a selection or a profile and names it in a task's `exclude` and a plugin's `requiredTools`, and an operator's or a plugin's `toolTiers` entry for `notify_owner` applies to `notify` unless `notify` has its own.
 Using the old name logs a deprecation warning once per logger, whether in a selection or in `toolTiers`.
 
+### Where things are delivered
+
+Everything the host sends goes back where the work came from. Every turn knows its *origin*, the conversation it runs in (a `ChannelKey` whose prefix is its surface), and so does everything a turn leaves behind: a schedule keeps the conversation it was made in, a delegated or coding job its channel and origin, a kept agent message its target's conversation and the sender's, a dispatch thread its parent. Nothing chooses a destination from a global default: not the first provider contributed, not the conversation an agent used most recently, not an agent's Discord channel.
+
+- **Replies, cards, and threads** go through `SurfacePort`, which picks the surface by the channel key's prefix: an `ask_user` card, a timeout card, a message's request and answer cards, a job's thread and report all land in the origin's conversation, on its surface.
+- **The delivery router** (`src/core/presence/delivery-router.ts`) is the one place that decides where a notice or run for a *person* goes. Given the origin, it tries the direct channels on the origin's surface first: a web conversation reaches the web app's channel (a Home notice and a push), a Discord conversation a Discord direct message. Only when no provider on that surface reaches the person does it try another surface, and it logs that fallback with both surfaces (`from`, `to`). `notify`, `context.directChannels`, and the run channel of a schedule or delegated task made in a conversation no chat surface carries (`runChannelFor`) all go through it.
+- **Mirroring** is the provider's own declaration: after a delivery, each other provider that implements `mirror` echoes the notice to the *same person*, such as the web app pushing to their phone a notice Discord delivered. It never sends to anyone else and never posts in a conversation.
+- **`message_agent`** without `conversation` reaches the target's place on the *sender's* surface: from a web room, the target's room on that surface; from Discord, the target's Discord channel. When the target has no place there, it lands in the target's primary place, and the crossing is logged. A routing rule may pin it elsewhere; `latest` follows the conversation the target last used only on the sender's surface.
+- **A group seat** outside its running turn, such as after a start-over, posts in the group's room on its own surface and never falls out to the group's Discord channel.
+
+`scripts/delivery-scan.test.ts` fails the build when code outside the router asks a provider to reach someone, walks the providers to pick one, or reads an agent's Discord channel id outside the files listed there; `src/core/presence/cross-surface.test.ts` starts each outbound feature from a web and from a Discord conversation and checks the other surface received nothing.
+
 ### `surfaces`: a chat network of your own
 
 A chat surface connects the host to one chat network: it reports what people write, and it posts what the conversations answer.
@@ -3087,7 +3103,7 @@ An agent has a *place* on each surface that holds one: its Discord channel, and
 | `primary(agent)` | The primary place: the surface the rules name, and with `auto` the agent's Discord channel when it has one, else its room on the first surface that hosts rooms. Undefined for an unknown agent. |
 | `placeOn(agent, surface)` | The agent's place on a surface (`web` for the one surface that hosts rooms); undefined when it has none there. |
 | `of(agent, "integration", origin)` | Where the report turn of a foreign webhook's post made in `origin` runs; `origin` itself by default, and also when the destination has vanished. |
-| `of(agent, "agentMessage", from)` | The conversation a `message_agent` call that names none reaches: by default the agent's latest, never out of a room into Discord. Throws `AgentError` when the agent has no place. |
+| `of(agent, "agentMessage", from)` | The conversation a `message_agent` call that names none reaches: by default (`origin-surface`) the agent's place on the surface `from` is on, else its primary place, logged; it never crosses surfaces by recency. Throws `AgentError` when the agent has no place. |
 | `of(agent, "opening", origin?)` | Where an opening task runs: by default the agent's place on the surface `origin` is on, else its primary place; undefined when it has no place at all. |
 | `place("ops")` | A named place of the host: the conversation, or the primary place of the agent it names while that agent is active. |
 
@@ -3109,13 +3125,13 @@ It follows its knight's routing rules, and its yolo and long-running modes follo
 
 | Rule | What happens |
 |---|---|
-| Place | On Discord a temp knight lives in a thread under its knight's channel, whose posts go through the channel's webhook under the temp knight's own name and picture; a knight with no Discord channel gives it a room on a surface that hosts rooms. Archiving a temp knight archives and locks its thread, and restoring it unarchives the thread. |
+| Place | A temp knight lives on the surface of the conversation that made it, kept in `Agent.origin`; its place on the other surface is made only when someone uses it there. Made on Discord, it lives in a thread under its knight's channel, whose posts go through the channel's webhook under the temp knight's own name and picture; a surface's room list leaves its room out until the room has a message or someone opens it by its address. Made in a room, it gets no thread: the thread is made, once, when a `message_agent` call from a turn that may message it names `conversation: "discord"`, or names none from a Discord conversation, where an unnamed message goes. A knight with no Discord channel gives it a room on a surface that hosts rooms. Archiving a temp knight archives and locks its thread when it has one; restoring it unarchives the thread, and only one made on Discord gets a new thread when the old one is gone. A temp knight made before its origin was kept is placed as one made on Discord. |
 | Finished | Derived, never set by the knight: nothing runs, nothing is queued, no card waits for the owner and no message from its knight is still unanswered. `Agent.finishedAt` carries the stamp. |
 | Limits | `helpers.perParent` (default 4) and `helpers.perHost` (default 12) count active temp knights; depth is one, so a temp knight cannot make one. At a limit the knight's oldest finished temp knight is archived to make room, and the call is refused only when every one of them is busy. |
 | Cleanup | `helper_end`, the owner's clearing in a surface, a knight's own archive (which archives its temp knights first), and, after `helpers.archiveFinishedAfterHours` (default 24), an hourly sweep. An archived temp knight keeps its history and comes back with `restoreHelpers`. Deleting an archived knight deletes its temp knights. |
 
 `AgentTeam` offers `helpersOf(parent)`, `finishedHelpers(parents?)`, `archiveHelpers(names, by)`, `restoreHelpers(names)` (only a name that is still an archived temp knight of an active knight is restored) and `onHelpersEnded(listener)`, which hears a knight's own `helper_end` and nothing else, so a surface can offer the owner an undo.
-`isHelper(agent)` tells a temp knight, for a surface that lists agents; a group never takes one.
+`isHelper(agent)` tells a temp knight, for a surface that lists agents, and `helperSurface(agent)` the surface it was made on (undefined for one made before its origin was kept); a group never takes one.
 The `helpers` block of the configuration turns the limits and the sweep; `helpers: false` offers neither tool, and a value out of its range, or a `perParent` above `perHost`, stops the start with a `ConfigError`:
 
 ```ts
@@ -4403,6 +4419,7 @@ Import from the entries listed below; source area files are internal.
 | `AvatarStudio` | `pi-roundtable` | type |
 | `PROMPTS` | `pi-roundtable` | value |
 | `characterOf` | `pi-roundtable` | value |
+| `helperSurface` | `pi-roundtable` | value |
 | `isHelper` | `pi-roundtable` | value |
 | `BACKGROUND_TURNS` | `pi-roundtable` | value |
 | `CONVERSATIONS` | `pi-roundtable` | value |
@@ -4551,6 +4568,11 @@ Import from the entries listed below; source area files are internal.
 | `Provisioning` | `pi-roundtable` | type |
 | `ProvisioningRule` | `pi-roundtable` | type |
 | `QueuePort` | `pi-roundtable` | type |
+| `QueuedBy` | `pi-roundtable` | type |
+| `QueuedChange` | `pi-roundtable` | type |
+| `QueuedMessage` | `pi-roundtable` | type |
+| `QUEUED_MARK` | `pi-roundtable` | value |
+| `STEERED_MARK` | `pi-roundtable` | value |
 | `QUESTIONNAIRE_LIMITS` | `pi-roundtable` | value |
 | `Questionnaire` | `pi-roundtable` | type |
 | `QuestionnaireAnswer` | `pi-roundtable` | type |
@@ -4594,6 +4616,7 @@ Import from the entries listed below; source area files are internal.
 | `PromptConflictError` | `pi-roundtable` | value |
 | `SkillConflictError` | `pi-roundtable` | value |
 | `SkillDocument` | `pi-roundtable` | type |
+| `SkillGroup` | `pi-roundtable` | type |
 | `SKILLS` | `pi-roundtable` | value |
 | `SINGLE_QUESTION` | `pi-roundtable` | value |
 | `Schedule` | `pi-roundtable` | type |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable",
-	"version": "0.28.0",
+	"version": "0.29.1",
 	"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-messages.ts

@@ -15,6 +15,7 @@ import {
 	chainLimitReason,
 	deliveredMessagePost,
 } from "./agent-prompt.ts";
+import { answersTo } from "./agent-rules.ts";
 import type { Agent } from "./agent-store.ts";
 import { conversationLabel, messageTarget } from "./message-target.ts";
 import { discordIdOf, discordKey, scopeOf } from "./team-keys.ts";
@@ -78,13 +79,10 @@ export class AgentMessages {
 			);
 		// A temp knight talks only to the conversation it was made from (and to the owners), so one
 		// person's helper session is not open to another person's turn.
-		if (target.parent !== undefined && chain.speaker.tier !== "owner") {
-			const own = sender.name === target.parent && target.origin === parent;
-			if (!own)
-				throw new AgentError(
-					`"${target.name}" is a temp knight of "${target.parent}" and answers only the conversation that made it; ask "${target.parent}" there.`,
-				);
-		}
+		if (!answersTo(target, caller.name, parent, chain.speaker))
+			throw new AgentError(
+				`"${target.name}" is a temp knight of "${target.parent}" and answers only the conversation that made it; ask "${target.parent}" there.`,
+			);
 		chain.messages += 1;
 		// A temp knight is working from the moment a message is handed to it until it has answered.
 		this.#host.helpers.begin(target.name);

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

@@ -42,6 +42,33 @@ export interface Agent {
 export const isHelper = (agent: Pick<Agent, "parent"> | undefined): boolean =>
 	agent?.parent !== undefined;
 
+/**
+ * Whether `sender`, writing from `from` in a run `speaker` started, may message `target`: a temp
+ * knight answers only its knight in the conversation that made it, and the owners.
+ */
+export const answersTo = (
+	target: Pick<Agent, "parent" | "origin">,
+	sender: string,
+	from: string,
+	speaker: { tier: string },
+): boolean =>
+	target.parent === undefined ||
+	speaker.tier === "owner" ||
+	(sender === target.parent && target.origin === from);
+
+/**
+ * The surface a temp knight was made on, such as "discord" or the web app's, read off its origin;
+ * undefined for a permanent knight and for a temp knight made before the origin was kept. A temp
+ * knight lives on that surface; its place on another is made only when someone uses it there.
+ */
+export const helperSurface = (
+	agent: Pick<Agent, "parent" | "origin"> | undefined,
+): string | undefined => {
+	const origin = agent?.parent === undefined ? undefined : agent.origin;
+	const colon = origin?.indexOf(":") ?? -1;
+	return origin && colon > 0 ? origin.slice(0, colon) : undefined;
+};
+
 export interface AgentGroup {
 	name: string;
 	displayName: string;

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

@@ -19,6 +19,7 @@ import {
 import type { HelperTeam } from "./helper-ops.ts";
 import { type Routes, routesOf } from "./routes.ts";
 import { TeamEditing } from "./team-editing.ts";
+import type { TeamHelpers } from "./team-helpers.ts";
 import {
 	channelOwner,
 	coordinatorOf,
@@ -321,6 +322,10 @@ export class DiscordAgentTeam implements AgentOps, AgentTeam {
 		return this.#turns.message(...args);
 	}
 
+	reach(...args: Parameters<TeamHelpers["reach"]>): Promise<void> {
+		return this.#lifecycle.helpers.reach(...args);
+	}
+
 	async read(
 		channel: string,
 		around: string | undefined,

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

@@ -123,7 +123,7 @@ export interface AgentOps {
 	avatar(name: string, look: CharacterInput): Promise<string>;
 	/** Queues the message and returns at once. */
 	/**
-	 * Hands a request to another agent, in the conversation it used most recently, or in the
+	 * Hands a request to another agent, in its conversation on the sender's surface, or in the
 	 * `conversation` named: "discord", "web" (or a room surface's name), or one of its conversation keys.
 	 */
 	message(
@@ -132,6 +132,15 @@ export interface AgentOps {
 		text: string,
 		conversation?: string,
 	): string;
+	/**
+	 * Readies the place a message is about to reach: a temp knight made in the web app gets its
+	 * Discord thread when the caller may message it and names "discord". Never rejects.
+	 */
+	reach?(
+		caller: AgentTurnScope,
+		to: string,
+		conversation?: string,
+	): Promise<void>;
 	createGroup(input: {
 		name: string;
 		displayName: string;
@@ -425,24 +434,23 @@ function toolDefs(
 			name: MESSAGE_AGENT_TOOL,
 			label: "Message agent",
 			description:
-				'Send a self-contained request to another agent. It returns at once; the agent works in its own conversation and its answer comes back to you as a new turn, in the conversation you are writing from. An agent has one conversation on each surface (Discord, the web app); by default the request lands in the one it used most recently, so work it started in the web app is answered there. Give conversation to choose another: "discord", "web", or one of the conversation keys agent_get lists for it. The request shows in its conversation, and the request and the answer show as small cards in yours.',
+				'Send a self-contained request to another agent. It returns at once; the agent works in its own conversation and its answer comes back to you as a new turn, in the conversation you are writing from. An agent has one conversation on each surface (Discord, the web app); by default the request lands in its conversation on the surface you are writing from (its room from a web room, its Discord channel from Discord), so nothing crosses surfaces unless you name it. Give conversation to choose another: "discord", "web", or one of the conversation keys agent_get lists for it. The request shows in its conversation, and the request and the answer show as small cards in yours.',
 			parameters: Type.Object({
 				to: NAME,
 				text: Type.String({ minLength: 1, maxLength: 4000 }),
 				conversation: Type.Optional(
 					Type.String({
 						description:
-							'Which of the agent\'s conversations to deliver into: "discord", "web" (or the name of another surface that hosts rooms), or a key from agent_get. Leave it out to reach the one it used most recently.',
+							'Which of the agent\'s conversations to deliver into: "discord", "web" (or the name of another surface that hosts rooms), or a key from agent_get. Leave it out to reach its conversation on the surface you are writing from.',
 					}),
 				),
 			}),
-			run: (i) =>
-				ops.message(
-					scope,
-					requiredString(i, "to"),
-					requiredString(i, "text"),
-					optionalString(i, "conversation"),
-				),
+			run: async (i) => {
+				const to = requiredString(i, "to");
+				const conversation = optionalString(i, "conversation");
+				await ops.reach?.(scope, to, conversation);
+				return ops.message(scope, to, requiredString(i, "text"), conversation);
+			},
 		});
 	return defs;
 }

package/src/core/agents/message-target.ts

@@ -3,19 +3,22 @@ import { AgentError } from "../domain/errors.ts";
 import type { AgentDirectory } from "../services.ts";
 import type { Agent } from "./agent-store.ts";
 import { Routes } from "./routes.ts";
-import { agentRoomKey, discordKey, keysOf } from "./team-keys.ts";
+import { agentRoomKey, keysOf } from "./team-keys.ts";
 
 /** What the choice of a message's conversation reads. */
 export interface MessageTargetContext {
 	store: Pick<AgentDirectory, "agent" | "group">;
 	/** The surfaces that host agent rooms. */
 	roomSurfaces: readonly string[];
-	/** The conversation the target last ran a turn in, if it ran one since the host started. */
+	/**
+	 * The conversation the target last ran a turn in, if it ran one since the host started; read
+	 * only under the `"latest"` routing rule, and only on the sender's surface.
+	 */
 	latest: ChannelKey | undefined;
-	/** The conversation the sender writes from. */
+	/** The conversation the sender writes from: the origin whose surface the message stays on. */
 	from: ChannelKey;
 	/** The host's routing table; without it the defaults every host had before `routing`. */
-	routes?: Pick<Routes, "of">;
+	routes?: Pick<Routes, "of" | "placeOn">;
 }
 
 /** The word for the web app's conversation, accepted when exactly one surface hosts rooms. */
@@ -24,9 +27,8 @@ const WEB = "web";
 /**
  * The conversation of `target` that a message is delivered into. With `ask` (a surface name such
  * as "discord", "web", or the surface of a room, or one of the target's conversation keys) that
- * one; otherwise the conversation the routing table picks (`Routes.of`): by default the one the
- * target used most recently, which a message from a room never follows out to Discord, and, when
- * it has run none yet, the sender's own surface, so a message between rooms stays among the rooms.
+ * one; otherwise the conversation the routing table picks (`Routes.of`): by default the target's
+ * place on the sender's own surface, so a message never crosses surfaces unless named.
  */
 export function messageTarget(
 	ctx: MessageTargetContext,
@@ -35,25 +37,25 @@ export function messageTarget(
 ): ChannelKey {
 	const keys = keysOf(ctx.store, target.name, ctx.roomSurfaces);
 	const has = keys.length > 0 ? keys.join(", ") : "none";
-	if (ask === undefined || ask.trim() === "") {
-		const routes =
-			ctx.routes ??
-			new Routes({
-				store: ctx.store,
-				roomSurfaces: () => ctx.roomSurfaces,
-				latest: () => ctx.latest,
-			});
+	const routes =
+		ctx.routes ??
+		new Routes({
+			store: ctx.store,
+			roomSurfaces: () => ctx.roomSurfaces,
+			latest: () => ctx.latest,
+		});
+	if (ask === undefined || ask.trim() === "")
 		return routes.of(target.name, "agentMessage", ctx.from);
-	}
 	const wanted = ask.trim();
 	const exact = keys.find((key) => key === wanted);
 	if (exact !== undefined) return exact;
 	if (wanted === "discord") {
-		if (!target.channelId)
+		const place = routes.placeOn(target.name, "discord");
+		if (!place)
 			throw new AgentError(
 				`${target.name} has no Discord channel; its conversations: ${has}.`,
 			);
-		return discordKey(target.channelId);
+		return place;
 	}
 	const surface = ctx.roomSurfaces.includes(wanted)
 		? wanted

package/src/core/agents/routes.ts

@@ -37,7 +37,7 @@ export interface RoutingTable {
 	 * has none when the agent has no place at all.
 	 */
 	of(agent: string, kind: "integration", origin: ChannelKey): ChannelKey;
-	of(agent: string, kind: "agentMessage", origin?: ChannelKey): ChannelKey;
+	of(agent: string, kind: "agentMessage", origin: ChannelKey): ChannelKey;
 	of(
 		agent: string,
 		kind: RouteKind,
@@ -154,7 +154,7 @@ export class Routes implements RoutingTable {
 	 * when an `agentMessage` finds no place; undefined when an `opening` finds none.
 	 */
 	of(name: string, kind: "integration", origin: ChannelKey): ChannelKey;
-	of(name: string, kind: "agentMessage", origin?: ChannelKey): ChannelKey;
+	of(name: string, kind: "agentMessage", origin: ChannelKey): ChannelKey;
 	of(
 		name: string,
 		kind: RouteKind,
@@ -201,39 +201,57 @@ export class Routes implements RoutingTable {
 	}
 
 	/**
-	 * The conversation a message to the agent lands in when the sender names none: with `latest`
-	 * the one it last ran a turn in, except that a message from a room never follows it out to
-	 * Discord, since the room's text may be for the owners alone; with none yet, the sender's own
-	 * surface when it hosts rooms, so a message between rooms stays among them; otherwise its
-	 * primary place.
+	 * The conversation a message to the agent lands in when the sender names none. By default
+	 * (`"origin-surface"`) its place on the sender's own surface: its Discord channel for a message
+	 * from Discord, its room for one from a room. `"latest"` is the conversation it last ran a turn
+	 * in, but only on the sender's surface. A message never crosses surfaces by recency: when the
+	 * agent has no place on the sender's surface, or no sender is known, it lands in the agent's
+	 * primary place, and a crossing is logged with both surfaces.
 	 */
 	#agentMessage(name: string, from: ChannelKey | undefined): ChannelKey {
-		const { store, roomSurfaces, latest } = this.#options;
-		const to = this.rules(name).agentMessage ?? "latest";
-		if (to !== "latest") {
+		const { latest } = this.#options;
+		const to = this.rules(name).agentMessage ?? "origin-surface";
+		if (to !== "latest" && to !== "origin-surface") {
 			const key =
 				to === "primary" ? this.primary(name) : this.placeOn(name, to);
 			if (key) return key;
 			this.#warn(
 				`message:${name}`,
 				{ agent: name, to },
-				"the agent has no place for messages to it; the conversation it last ran a turn in is used",
+				"the agent has no place for messages to it; its place on the sender's surface is used",
 			);
 		}
-		const via = from === undefined ? undefined : roomSurfaceOf(from);
-		const last = latest?.(name);
-		const keys = keysOf(store, name, roomSurfaces());
-		const outward =
-			via !== undefined &&
-			last !== undefined &&
-			roomSurfaceOf(last) === undefined;
-		if (last !== undefined && keys.includes(last) && !outward) return last;
-		if (via === undefined) {
-			const primary = this.primary(name);
-			if (!primary) throw new AgentError(`${name} has no channel yet.`);
-			return primary;
+		const surface =
+			from === undefined ? undefined : parseChannelKey(from).surface;
+		if (to === "latest" && surface !== undefined) {
+			const last = latest?.(name);
+			const keys = keysOf(
+				this.#options.store,
+				name,
+				this.#options.roomSurfaces(),
+			);
+			if (
+				last !== undefined &&
+				keys.includes(last) &&
+				parseChannelKey(last).surface === surface
+			)
+				return last;
 		}
-		return agentRoomKey(via, name);
+		const own = surface === undefined ? undefined : this.placeOn(name, surface);
+		if (own) return own;
+		const primary = this.primary(name);
+		if (!primary) throw new AgentError(`${name} has no channel yet.`);
+		if (surface !== undefined)
+			this.#warn(
+				`message-cross:${name}:${surface}`,
+				{
+					agent: name,
+					from: surface,
+					to: parseChannelKey(primary).surface,
+				},
+				"the agent has no place on the sender's surface; the message lands in its primary place",
+			);
+		return primary;
 	}
 
 	/**

package/src/core/agents/team-editing.ts

@@ -220,9 +220,9 @@ export class TeamEditing {
 			creator: Agent | undefined;
 			/** The surface whose room runs the opening task. */
 			openIn?: string | undefined;
-			/** Makes the agent a temp knight of this knight: its place is a thread of the parent's channel, and it settles on the parent's model. */
+			/** Makes the agent a temp knight of this knight, which settles on the parent's model. */
 			parent?: Agent | undefined;
-			/** The conversation a temp knight is made from. */
+			/** The conversation a temp knight is made from: made on Discord, it lives in a thread of the parent's channel, made elsewhere in its rooms alone. */
 			origin?: string | undefined;
 		},
 		input: {
@@ -279,10 +279,10 @@ export class TeamEditing {
 		const suggested = suggestCharacter(input, taken);
 		const character = this.#resolve(wanted ?? {}, suggested);
 		const avatarHash = await studio.render(character);
-		// Without Discord channels the agent lives in its rooms, which exist as soon as it does. A
-		// temp knight lives in a thread of its parent's channel, or in rooms alone without one.
+		// Without Discord channels the agent lives in its rooms, which exist as soon as it does.
+		const onDiscord = who.origin?.startsWith("discord:") !== false;
 		const channelId = who.parent
-			? who.parent.channelId && channels?.createThread
+			? onDiscord && who.parent.channelId && channels?.createThread
 				? await channels.createThread(who.parent.channelId, input.displayName)
 				: undefined
 			: await channels?.createChannel(