pi-roundtable 0.9.9 → 0.9.10

package/CHANGELOG.md

@@ -5,6 +5,12 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.10] - 2026-10-10
+
+### Added
+
+- `ToolTurn.origin`, `TurnRequest.origin`, `ConversationTurnInput.origin` and `SessionContext.origin()`: where a turn's request came from, as the transport that carried it reported it, such as the browser origin of a web chat connection (`https://chat.example.com`). A tool's `run` and its `hold` read it from the `ToolTurn` they receive, so a tool can label what it creates (an issue's source line) and fail closed when it is undefined. A claim passes it to `context.turns.run({ ..., origin })`; the runtime keeps it with the turn's speaker and clears it when the turn ends. Only the transport sets it, never the message text or the model. A turn whose channel gives none (Discord, a schedule, an agent's turn, the CLI) leaves it undefined, and `testPlugin().runTool` takes `origin` in its options. Additive: nothing changes for a claim or a tool that does not use it, and `SessionContext.origin` is optional on the type so a context built before this still type-checks.
+
 ## [0.9.9] - 2026-10-10
 
 ### Added

package/docs/plugins.md

@@ -589,6 +589,10 @@ The host logs counts only (`files`, `bytes`, `unattributedBytes`), never a file
 `run` receives the arguments, already typed, and the turn: the speaker, the channel, the agent, an abort signal, `workspace`, `attachFile`, and `attachment`.
 `turn.workspace` is `{ workspace, scratchDir? }` in a session with a shared workspace (an agent's), the same roots as `SessionContext.workspace`, and undefined elsewhere: a tool that makes a file can save it there, under the scratch dir when there is one, and name its path, so the model sends it on with `attach_file` or a `discord_send_message` file `path` instead of carrying its bytes.
 It returns the text the model reads.
+`turn.origin` is where the turn's request came from, as the transport that carried it reported it, and undefined when the channel gives none: the web chat sets it to the browser origin its connection opened with (`https://chat.example.com`, `chrome-extension://<id>`), a Discord message, a schedule or an agent's turn leave it undefined.
+Only a channel's transport sets it, never the message text or the model, so a tool may write it on a record it creates, such as an issue's source line; a tool that needs it fails closed when it is undefined.
+A claim passes it to `context.turns.run` as `origin`, and the hold of the same call sees it too, since `hold` receives the same `ToolTurn`.
+
 `turn.attachment(file)` opens a file someone attached to the conversation, by the name the turn's `## Attachments` block lists, and returns `{ file, name, contentType, size, bytes() }`: a tool passes a user's file on without the model carrying its bytes.
 Only the conversation's own files open; a path, a hidden name, or a missing file throws a `ToolRefusal` the model reads, and so does a file the host's [retention period](#retention-removing-used-files-after-a-period) removed, which says so.
 Throw `ToolRefusal` for a call the model should correct; any other error fails the call.
@@ -746,7 +750,7 @@ export const cleanup = definePlugin({
 #### A hold that looks things up
 
 A hold may need something it must fetch as the speaker before it can describe the call, such as the display name of the entity an id stands for, read with the speaker's own credentials.
-A tool's `hold` may then return a promise and takes the turn as a second argument: the `ToolTurn` its `run` receives, with the `speaker`, the `channel` and the `agent` of the turn that makes the call.
+A tool's `hold` may then return a promise and takes the turn as a second argument: the `ToolTurn` its `run` receives, with the `speaker`, the `channel`, the `agent` and the `origin` of the turn that makes the call.
 
 ```ts
 defineTool({
@@ -1861,6 +1865,7 @@ The factory gets the session's `SessionContext`, fixed when the session is made:
 - `addressee` is whom tool descriptions should name: the primary owner exactly as configured in their own private conversation, another person by their name and pronouns (their name alone when they gave none), and `THE_SPEAKER` in a shared conversation, or a private one of someone the host knows by no name yet.
 - `memory` is `"none"` for a persona that declares it, and `"speaker"` otherwise; a memory tool of your own loads nothing for `"none"`. A task the session runs with `runTask` keeps its conversation's `memory`.
 - `speaker()` is the running turn's speaker, undefined between turns; a tool reads it when it runs, never when the session is made, since a session outlives the turn it is built in.
+- `origin()` is where the running turn's request came from, as `TurnRequest.origin` says, and undefined between turns and for a turn whose transport gives none; read it when the tool runs, like `speaker()`. It is optional on the type so a context built before 0.9.10 still type-checks.
 
 The core's Jev compactor is one such extension:
 
@@ -2012,7 +2017,7 @@ Call `context.turns.run(input)` inside your claim's queue task to run a turn in
 It shows typing and the stop control on the channel's surface, runs the turn, and emits `turnStarted` and `turnEnded` with the turn's `kind`.
 It catches runtime errors as failed results and posts the answer, failure notice, or stopped notice through the surface.
 Supply `reply(result)` to handle the reply yourself.
-`input` has `channel`, `kind`, `text`, `speaker`, and optionally `attachments`, `selection` (by default the plugins' `agentSelection`), `steerable`, `interactive`, `confirmed`, `reply`, and `conversation`.
+`input` has `channel`, `kind`, `text`, `speaker`, and optionally `origin` (where the request came from, as your claim's transport knows it, such as a connection's browser origin; tools read it as `turn.origin`, so never fill it from message text), `attachments`, `selection` (by default the plugins' `agentSelection`), `steerable`, `interactive`, `confirmed`, `reply`, and `conversation`.
 It rejects with `NotLinkedError` during `setup`, and with a `PluginError` on a host whose runtime plugin has not provided a runtime.
 
 Before each turn runs, `context.turns.run` records its conversation in the host's registry, `CONVERSATIONS`: at the first turn its key, surface, kind, visibility, owner, and title, and at every later turn only that it was active.
@@ -2955,7 +2960,7 @@ It returns:
 | `contribution` | What the plugin added, as the host would collect it: `tools`, `prompt`, `seeds`, `events`, `services`, `http`, and the rest |
 | `tools`, `tiers` | The tool names, and the table that says what tier each needs |
 | `holds` | The plugin's `holdRules` chained as the host links them (`holdChain`): `holds(tool, input, { workspace?, scratchDir? })` returns the description of a call that must be approved first, or `undefined`; `holds.inTurn(tool, input, context, turn)` asks them as a turn does, and returns a promise when a hold looks things up |
-| `runTool(name, args, { speaker, channel, workspace }?)` | Runs a tool the way an agent's turn would, in the channel (default `test:1`) for the speaker, and returns the text the model reads; `workspace` (`{ workspace, scratchDir? }`) is the session's `turn.workspace` |
+| `runTool(name, args, { speaker, origin, channel, workspace }?)` | Runs a tool the way an agent's turn would, in the channel (default `test:1`) for the speaker, and returns the text the model reads; `origin` is the turn's `turn.origin`, and `workspace` (`{ workspace, scratchDir? }`) is the session's `turn.workspace` |
 | `files` | Accepted files from `runTool`, recorded as `{ channel, file: ReplyFile }`; inject a surface with `supportsFiles: true` and pass its channel to test attachment tools |
 | `events` | The events the plugin itself reported through `context.events`, and those of `context.turns` |
 | `conversations`, `turns`, `surfaces` | What the plugin sees as `context.conversations`, `context.turns`, and `context.surfaces`, for a test to drive its claims |

package/package.json

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

package/src/core/define.ts

@@ -26,6 +26,14 @@ export interface ToolTurn {
 	/** The agent whose turn it is. */
 	agent: AgentTurnScope | undefined;
 	signal: AbortSignal | undefined;
+	/**
+	 * Where the turn's request came from, as its transport reported it, such as the browser origin
+	 * of a web chat connection (`https://chat.example.com`); undefined for a turn whose channel gives
+	 * none, such as a Discord message or a schedule. Only the transport sets it, never the message
+	 * text or the model, so a tool may label a record with it; a tool that needs one fails closed
+	 * when it is undefined.
+	 */
+	origin?: string;
 	/**
 	 * The session's shared workspace and scratch dir, where a tool may save a file for the model to
 	 * pass on by path; undefined for a session without a workspace.

package/src/core/domain/ports.ts

@@ -30,6 +30,13 @@ export interface TurnRequest {
 	 * starts a turn on someone's behalf gets theirs from `IDENTITY.speakerFor`.
 	 */
 	speaker: Speaker;
+	/**
+	 * Where the request came from, as the transport that carried it knows: the browser origin of a
+	 * web chat connection, such as `https://chat.example.com`. A channel with no such thing leaves it
+	 * out. Only a channel's transport sets it, never the message text or the model; a tool reads it
+	 * as `ToolTurn.origin`.
+	 */
+	origin?: string;
 	/**
 	 * Who the conversation belongs to, as the host records it: `private` to one principal, or
 	 * `shared` by whoever its claim admits, which it is taken to be when absent. A private

package/src/core/routing/conversation-turns.ts

@@ -29,6 +29,12 @@ export interface ConversationTurnInput {
 	text: string;
 	/** Who the turn is for; its tier limits the tools. */
 	speaker: Speaker;
+	/**
+	 * Where the request came from, as the claim's transport knows it, such as a web chat
+	 * connection's browser origin; tools read it as `ToolTurn.origin`. Leave it out for a turn the
+	 * transport gives none, and never fill it from message text.
+	 */
+	origin?: string;
 	/** Files and images the message carries. */
 	attachments?: TurnAttachments;
 	/** The turn's tools; by default the plugins' `agentSelection`, read at the turn. */
@@ -184,6 +190,7 @@ export function conversationTurns(
 								},
 								text: input.text,
 								speaker,
+								...(input.origin === undefined ? {} : { origin: input.origin }),
 								...(conversation ? { conversation } : {}),
 								...(input.attachments
 									? { attachments: input.attachments }

package/src/core/runtime/pi-agent-runtime.ts

@@ -71,10 +71,10 @@ export class PiAgentRuntime implements AgentRuntime {
 	readonly #tiers: ToolTiers;
 	readonly #factory: SessionFactory;
 	readonly #sessions: ConversationSessions;
-	/** The tier and speaker of each conversation's running turn. */
+	/** The tier, speaker and origin of each conversation's running turn. */
 	readonly #turns = new Map<
 		ChannelKey,
-		{ tier: Tier; speaker: Speaker; withheld: boolean }
+		{ tier: Tier; speaker: Speaker; origin?: string; withheld: boolean }
 	>();
 	/** Each conversation's turn in progress, which the owner may steer or stop. */
 	readonly #running = new Map<ChannelKey, SteerableRun>();
@@ -87,6 +87,7 @@ export class PiAgentRuntime implements AgentRuntime {
 		this.#tiers = options.toolTiers ?? toolTiers();
 		this.#factory = new SessionFactory(options, {
 			speaker: (channel) => this.#turns.get(channel)?.speaker,
+			origin: (channel) => this.#turns.get(channel)?.origin,
 			withholdsMemory: (channel) => this.#turns.get(channel)?.withheld === true,
 			runTask: (scope, task) => this.#runTask(scope, task),
 		});
@@ -192,7 +193,12 @@ export class PiAgentRuntime implements AgentRuntime {
 				loadsMemory(registered),
 		);
 		this.#memoryTurns.set(key, markPrivateMemory);
-		this.#turns.set(key, { tier, speaker: request.speaker, withheld });
+		this.#turns.set(key, {
+			tier,
+			speaker: request.speaker,
+			...(request.origin === undefined ? {} : { origin: request.origin }),
+			withheld,
+		});
 		const missing = wanted.filter((name) => !registered.has(name));
 		if (missing.length > 0) {
 			logger.warn(

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

@@ -73,6 +73,8 @@ import {
 export interface SessionFactoryDeps {
 	/** The person the conversation's running turn is for. */
 	speaker(channel: ChannelKey): Speaker | undefined;
+	/** Where the conversation's running turn came from, as its transport reported it. */
+	origin(channel: ChannelKey): string | undefined;
 	/** Whether the conversation's running turn loads no memory, as the agent server's option keeps a speaker out of it. */
 	withholdsMemory(channel: ChannelKey): boolean;
 	/**
@@ -355,6 +357,7 @@ export class SessionFactory {
 				return state.memory;
 			},
 			speaker: () => this.#deps.speaker(turnKey),
+			origin: () => this.#deps.origin(turnKey),
 			runTask: (task) =>
 				this.#deps.runTask({ turn: turnKey, home: channel }, task),
 		};

package/src/core/sessions.ts

@@ -92,6 +92,12 @@ export interface SessionContext {
 	attachmentDir?: string;
 	/** The person the session's running turn is for; undefined between turns. */
 	speaker(): Speaker | undefined;
+	/**
+	 * Where the running turn's request came from, as `TurnRequest.origin` says; undefined between
+	 * turns and for a turn whose transport gives none. A context built before 0.9.10 has no such
+	 * method, which reads as undefined.
+	 */
+	origin?(): string | undefined;
 	/** Runs a task beside this session, under its confirmation gate. */
 	runTask(task: TransientTask): Promise<string>;
 }

package/src/core/tool-turn.ts

@@ -15,11 +15,13 @@ export function toolTurn(
 	context: SessionContext,
 	signal: AbortSignal | undefined,
 ): ToolTurn {
+	const origin = context.origin?.();
 	return {
 		speaker: context.speaker(),
 		channel: context.turnChannel,
 		agent: context.agent,
 		signal,
+		...(origin === undefined ? {} : { origin }),
 		...(context.workspace ? { workspace: context.workspace } : {}),
 		attachFile: attachReplyFile,
 		attachment: async (file) => {

package/src/testing.ts

@@ -270,6 +270,8 @@ export interface TestPluginResult {
 		/** `workspace` gives the session a workspace and scratch dir, as an agent's session has. */
 		options?: {
 			speaker?: Speaker;
+			/** Where the turn's request came from, as `ToolTurn.origin` shows it to the tool. */
+			origin?: string;
 			channel?: ChannelKey;
 			workspace?: SessionContext["workspace"];
 		},
@@ -640,6 +642,7 @@ export async function testPlugin(
 				...(runOptions?.workspace ? { workspace: runOptions.workspace } : {}),
 				attachmentDir: ownerAttachmentDir(attachmentDir, channel),
 				speaker: () => runOptions?.speaker,
+				origin: () => runOptions?.origin,
 				runTask: async () => {
 					throw new Error("test session cannot run tasks");
 				},