pi-roundtable 0.1.0 → 0.2.1

package/src/core/discord/stop-button.ts

@@ -1,5 +1,14 @@
-import { ActionRowBuilder, ButtonBuilder, ButtonStyle } from "discord.js";
+import {
+	ActionRowBuilder,
+	ButtonBuilder,
+	ButtonStyle,
+	type Interaction,
+	MessageFlags,
+} from "discord.js";
+import type { ConversationPort } from "../contract/channels.ts";
+import { channelKey } from "../contract/surface.ts";
 import { messages } from "../i18n/index.ts";
+import type { CommandGuard, InteractionModule } from "./interaction-module.ts";
 
 export const STOP_BUTTON_ID = "roundtable:stop";
 
@@ -18,3 +27,37 @@ export function stopPanel() {
 		],
 	};
 }
+
+export interface StopButtonOptions {
+	guard: Pick<CommandGuard, "isOwner">;
+	/** Stops the running turn of the channel the button was pressed in, through its claim. */
+	conversations: Pick<ConversationPort, "stop">;
+}
+
+/**
+ * Answers a press of the stop button: only the owner stops the channel's turn, and the answer,
+ * visible only to whoever pressed, says whether one was running.
+ */
+export function stopButtonModule(
+	options: StopButtonOptions,
+): InteractionModule {
+	return {
+		commands: () => [],
+		handle: async (interaction: Interaction) => {
+			if (!interaction.isButton() || interaction.customId !== STOP_BUTTON_ID)
+				return false;
+			const owner = options.guard.isOwner(interaction);
+			const stopped =
+				owner &&
+				options.conversations.stop(
+					channelKey("discord", interaction.channelId),
+				);
+			const text = messages();
+			let content = text.stopIdle;
+			if (!owner) content = text.stopOwnerOnly;
+			else if (stopped) content = text.stopDone;
+			await interaction.reply({ content, flags: MessageFlags.Ephemeral });
+			return true;
+		},
+	};
+}

package/src/core/domain/attachment.ts

@@ -27,13 +27,17 @@ export interface ModelImage {
 
 /** Everything a turn carries besides its text. */
 export interface TurnAttachments {
-	files: StoredAttachment[];
-	images: ModelImage[];
-	failures: AttachmentFailure[];
+	readonly files: readonly StoredAttachment[];
+	readonly images: readonly ModelImage[];
+	readonly failures: readonly AttachmentFailure[];
 }
 
-export const NO_ATTACHMENTS: TurnAttachments = Object.freeze({
-	files: [],
-	images: [],
-	failures: [],
-}) as TurnAttachments;
+export const NO_ATTACHMENTS: Readonly<{
+	files: readonly StoredAttachment[];
+	images: readonly ModelImage[];
+	failures: readonly AttachmentFailure[];
+}> = Object.freeze({
+	files: Object.freeze([]),
+	images: Object.freeze([]),
+	failures: Object.freeze([]),
+});

package/src/core/domain/conversation.ts

@@ -1,7 +1,5 @@
 import type { InboundMessage } from "../contract/channels.ts";
 import type { ChannelKey } from "../sessions.ts";
-import type { AgentRunError } from "./errors.ts";
-import type { ProfileId } from "./profile.ts";
 
 export { QUEUED_MARK, STEERED_MARK } from "../contract/channels.ts";
 export type { ChannelKey, InboundMessage };
@@ -21,14 +19,15 @@ export interface HeldCall {
 }
 
 export interface PendingConfirmation {
-	profile: ProfileId;
+	/** The id of the TurnSelection whose turn held the calls; the caller resolves it on replay. */
+	selectionId: string;
 	heldAt: Date;
 	calls: HeldCall[];
 }
 
 export type TurnResult =
 	| { ok: true; text: string; thinking?: string }
-	| { ok: false; error: AgentRunError; stopped?: true };
+	| { ok: false; error: Error; stopped?: true };
 
 export interface OutboundReply {
 	/** The assistant's thinking for this turn, posted as a quiet line before the card. */

package/src/core/domain/owner-prompts.ts

@@ -1,6 +1,6 @@
 import type { Tier } from "../speakers.ts";
 /**
- * The owner answering inside a running turn: a card in the turn's channel that only he may
+ * The owner answering inside a running turn: a card in the turn's channel that only they may
  * answer. Unanswered cards expire; a stopped turn cancels its open cards.
  */
 export type Approval = "approved" | "declined" | "expired" | "cancelled";
@@ -16,19 +16,19 @@ export interface OwnerQuestion {
 	options: readonly AskOption[];
 	/** More than one option may be chosen. */
 	multi: boolean;
-	/** He may write an answer of his own besides the options. */
+	/** They may write an answer of their own besides the options. */
 	allowOther: boolean;
 }
 
 export interface OwnerAnswer {
 	/** The chosen options' labels, in the order they were offered. */
 	choices: string[];
-	/** What he wrote himself, if anything. */
+	/** What they wrote himself, if anything. */
 	text?: string;
 }
 
 export interface OwnerPrompts {
-	/** Asks him to approve an action; `signal` cancels the card when the turn stops. */
+	/** Asks them to approve an action; `signal` cancels the card when the turn stops. */
 	confirm(
 		title: string,
 		message: string,
@@ -36,7 +36,7 @@ export interface OwnerPrompts {
 		/** The lowest tier that may approve; the owner only when absent. */
 		minTier?: Tier,
 	): Promise<Approval>;
-	/** Asks him a question; undefined when it expired or was cancelled. */
+	/** Asks them a question; undefined when it expired or was cancelled. */
 	ask(
 		title: string,
 		question: OwnerQuestion,

package/src/core/domain/ports.ts

@@ -1,36 +1,14 @@
 import type { AgentTurnScope, TurnSelection } from "../sessions.ts";
 import type { Speaker } from "../speakers.ts";
 import type { TurnAttachments } from "./attachment.ts";
-import type {
-	ChannelKey,
-	InboundMessage,
-	OutboundReply,
-	PendingConfirmation,
-	TranscriptEntry,
-	TurnResult,
-} from "./conversation.ts";
-
-export interface ChatSurface {
-	start(onMessage: (message: InboundMessage) => void): Promise<void>;
-	sendReply(channel: ChannelKey, reply: OutboundReply): Promise<void>;
-	/** Shows the typing indicator until the returned function is called. */
-	startTyping(channel: ChannelKey): () => void;
-	/**
-	 * Shows the owner a stop button once the turn has run a few seconds, until the returned
-	 * function is called.
-	 */
-	showStop(channel: ChannelKey): () => void;
-	/** Adds or removes the bot's reaction on a message; failures are logged, never thrown. */
-	react(channel: ChannelKey, messageId: string, emoji: string): Promise<void>;
-	unreact(channel: ChannelKey, messageId: string, emoji: string): Promise<void>;
-}
+import type { ChannelKey } from "./conversation.ts";
 
 export type { AgentTurnScope };
 
 export interface TurnRequest {
 	/** Where the turn's message arrived and its attachments are saved. */
 	channel: ChannelKey;
-	/** The turn's tools; the owner's conversations pick a profile's, an agent's are the agent union. */
+	/** The caller's choice of tools for the turn, such as an agent's union. */
 	selection: TurnSelection;
 	text: string;
 	/** Files and images the message carries; none when absent. */
@@ -41,43 +19,21 @@ export interface TurnRequest {
 	agent?: AgentTurnScope;
 	/** The person the turn is for: who wrote the message, or who set up the work. */
 	speaker?: Speaker;
-	/** The owner's own chat turn, which his next messages may steer. */
+	/**
+	 * The conversation's kind, fixed when its session is made: the string a claim's `startFresh`
+	 * returns, which picks the persona of a non-agent conversation. "owner" when absent.
+	 */
+	kind?: string;
+	/** The owner's own chat turn, which their next messages may steer. */
 	steerable?: boolean;
 	/**
 	 * The owner started the turn by writing in its channel, or it delivers a dispatch's report,
-	 * so it may ask him there on cards: approvals of held actions and ask_user questions. A
+	 * so it may ask them there on cards: approvals of held actions and ask_user questions. A
 	 * schedule's turn is not.
 	 */
 	interactive?: boolean;
 }
 
-export interface AgentRuntime {
-	runTurn(request: TurnRequest): Promise<TurnResult>;
-	/** Held actions of a conversation: a channel, or an agent's session key. */
-	pendingConfirmation(channel: ChannelKey): PendingConfirmation | undefined;
-	recentTranscript(
-		channel: ChannelKey,
-		limit: number,
-	): Promise<TranscriptEntry[]>;
-	/** Archives a conversation (a channel, or an agent's session key) and drops its held actions; call between turns. */
-	startFresh(channel: ChannelKey): Promise<void>;
-	/** Like `startFresh`, but removes the conversation and every archive of it for good; call between turns. */
-	deleteConversation(channel: ChannelKey): Promise<void>;
-	/**
-	 * Adds the message to the conversation's running turn when that turn is steerable and holds
-	 * no actions; false when the message must wait for its own turn.
-	 */
-	steer(
-		channel: ChannelKey,
-		text: string,
-		attachments: TurnAttachments,
-		/** The message's author; a turn another speaker started takes no steering from them. */
-		speakerId?: string,
-	): Promise<boolean>;
-	/** Aborts the conversation's running turn and drops what was steered into it; false when none runs. */
-	stop(channel: ChannelKey): boolean;
-}
-
 /** The judge's question and answer shapes. */
 export type {
 	ChoiceAnswer,

package/src/core/freeze.ts

@@ -0,0 +1,9 @@
+/** Freeze shared protocol data recursively, including symbol-keyed schema metadata. */
+export function freeze<T extends object>(value: T): Readonly<T> {
+	for (const key of Reflect.ownKeys(value)) {
+		const child: unknown = (value as Record<PropertyKey, unknown>)[key];
+		if (child && typeof child === "object" && !Object.isFrozen(child))
+			freeze(child);
+	}
+	return Object.freeze(value);
+}