@oh-my-pi/pi-coding-agent 17.2.11 → 17.2.12

package/src/slash-commands/builtin-collaboration.ts

@@ -0,0 +1,504 @@
+import { Spacer } from "@oh-my-pi/pi-tui";
+import { APP_NAME } from "@oh-my-pi/pi-utils";
+import { CollabGuestLink } from "../collab/guest";
+import { CollabHost } from "../collab/host";
+import type { SettingPath, SettingValue } from "../config/settings";
+import { settings } from "../config/settings";
+import { parseExportArgs } from "../export/html/args";
+import { shareSession } from "../export/share";
+import { theme } from "../modes/theme/theme";
+import type { InteractiveModeContext } from "../modes/types";
+import { extractLastCodeBlock, extractLastCommand } from "../modes/utils/copy-targets";
+import { urlHyperlinkAlways } from "../tui";
+import { copyToClipboard } from "../utils/clipboard";
+import { refreshStatusLine } from "./builtin-modes";
+import { CollabQrCodeComponent } from "./helpers/collab-qrcode";
+import { commandConsumed, errorMessage, parseSubcommand, usage } from "./helpers/parse";
+import type { SlashCommandSpec } from "./types";
+
+/** Scheme-less display form of a browser deep link: accent + underline, OSC-8 linked to the full URL. */
+function collabWebLinkClickable(webLink: string): string {
+	const display = theme.fg("accent", `\x1b[4m${webLink.replace(/^https?:\/\//, "")}\x1b[24m`);
+	return urlHyperlinkAlways(webLink, display);
+}
+
+/** Join hint printed by /collab: compact terminal link + clickable browser deep link. */
+function collabLinkHint(host: CollabHost, heading: string, view = false): string {
+	const bullet = theme.fg("accent", theme.format.bullet);
+	const link = view ? host.viewLink : host.link;
+	const webLink = view ? host.webViewLink : host.webLink;
+	return [
+		theme.fg("success", heading),
+		` ${bullet} ${theme.fg("muted", view ? "Watch from another terminal:" : "Join from another terminal:")} ${APP_NAME} join "${link}"`,
+		` ${bullet} ${theme.fg("muted", "or any web browser:")} ${collabWebLinkClickable(webLink)}`,
+		theme.fg(
+			"dim",
+			view
+				? "Anyone with this link can watch the session but cannot prompt the agent."
+				: "Anyone with the link can read the session and prompt the agent. Read-only link: /collab view",
+		),
+	].join("\n");
+}
+
+function showCollabQrCode(ctx: InteractiveModeContext, webLink: string): void {
+	try {
+		ctx.present([new Spacer(1), new CollabQrCodeComponent(webLink)]);
+	} catch (err) {
+		ctx.showError(`Failed to render collab QR code: ${errorMessage(err)}`);
+	}
+}
+
+function showCollabLink(ctx: InteractiveModeContext, host: CollabHost, heading: string, view = false): void {
+	ctx.showStatus(collabLinkHint(host, heading, view), { dim: false });
+	showCollabQrCode(ctx, view ? host.webViewLink : host.webLink);
+}
+
+export const BUILTIN_COLLABORATION_SLASH_COMMANDS: ReadonlyArray<SlashCommandSpec> = [
+	{
+		name: "advisor",
+		description: "Toggle the advisor (a second model that reviews each turn and injects notes)",
+		acpDescription: "Toggle advisor",
+		acpInputHint: "[on|off|status|dump [raw]|configure]",
+		subcommands: [
+			{ name: "on", description: "Enable the advisor" },
+			{ name: "off", description: "Disable the advisor" },
+			{ name: "status", description: "Show advisor status" },
+			{ name: "dump", description: "Copy the advisor's transcript to clipboard", usage: "[raw]" },
+			{ name: "configure", description: "Open the advisor configuration editor (TUI)" },
+		],
+		allowArgs: true,
+		getTuiAutocompleteDescription: runtime => {
+			const stats = runtime.ctx.session.getAdvisorStats();
+			if (stats.active && stats.advisors.length > 1) return `Advisor: on (${stats.advisors.length} advisors)`;
+			if (stats.active && stats.model) return `Advisor: on (${stats.model.provider}/${stats.model.id})`;
+			if (stats.configured) return "Advisor: configured, no model";
+			return "Advisor: off";
+		},
+		handle: async (command, runtime) => {
+			const { verb, rest } = parseSubcommand(command.args);
+			if (!verb || verb === "toggle") {
+				const active = runtime.session.toggleAdvisorEnabled();
+				const configured = runtime.session.isAdvisorEnabled();
+				if (active) {
+					await runtime.output("Advisor enabled.");
+				} else if (configured) {
+					await runtime.output("Advisor setting enabled, but no model is assigned to the 'advisor' role.");
+				} else {
+					await runtime.output("Advisor disabled.");
+				}
+				return commandConsumed();
+			}
+			if (verb === "on") {
+				const active = runtime.session.setAdvisorEnabled(true);
+				await runtime.output(
+					active ? "Advisor enabled." : "Advisor setting enabled, but no model is assigned to the 'advisor' role.",
+				);
+				return commandConsumed();
+			}
+			if (verb === "off") {
+				runtime.session.setAdvisorEnabled(false);
+				await runtime.output("Advisor disabled.");
+				return commandConsumed();
+			}
+			if (verb === "status") {
+				await runtime.output(runtime.session.formatAdvisorStatus());
+				return commandConsumed();
+			}
+			if (verb === "dump") {
+				const isRaw = rest.toLowerCase() === "raw";
+				const text = runtime.session.formatAdvisorHistoryAsText({ compact: !isRaw });
+				await runtime.output(text ?? "Advisor is not active for this session.");
+				return commandConsumed();
+			}
+			if (verb === "configure") {
+				await runtime.output(
+					"/advisor configure opens an interactive editor and is only available in the interactive TUI.",
+				);
+				return commandConsumed();
+			}
+			return usage("Usage: /advisor [on|off|status|dump [raw]|configure]", runtime);
+		},
+		handleTui: async (command, runtime) => {
+			const { verb, rest } = parseSubcommand(command.args);
+			if (!verb || verb === "toggle") {
+				const active = runtime.ctx.session.toggleAdvisorEnabled();
+				const configured = runtime.ctx.session.isAdvisorEnabled();
+				if (active) {
+					runtime.ctx.showStatus("Advisor enabled.");
+				} else if (configured) {
+					runtime.ctx.showStatus("Advisor setting enabled, but no model is assigned to the 'advisor' role.");
+				} else {
+					runtime.ctx.showStatus("Advisor disabled.");
+				}
+				refreshStatusLine(runtime.ctx);
+				runtime.ctx.editor.setText("");
+				return;
+			}
+			if (verb === "on") {
+				const active = runtime.ctx.session.setAdvisorEnabled(true);
+				runtime.ctx.showStatus(
+					active ? "Advisor enabled." : "Advisor setting enabled, but no model is assigned to the 'advisor' role.",
+				);
+				refreshStatusLine(runtime.ctx);
+				runtime.ctx.editor.setText("");
+				return;
+			}
+			if (verb === "off") {
+				runtime.ctx.session.setAdvisorEnabled(false);
+				runtime.ctx.showStatus("Advisor disabled.");
+				refreshStatusLine(runtime.ctx);
+				runtime.ctx.editor.setText("");
+				return;
+			}
+			if (verb === "status") {
+				await runtime.ctx.handleAdvisorStatusCommand();
+				runtime.ctx.editor.setText("");
+				return;
+			}
+			if (verb === "dump") {
+				const isRaw = rest.toLowerCase() === "raw";
+				runtime.ctx.handleAdvisorDumpCommand(isRaw);
+				runtime.ctx.editor.setText("");
+				return;
+			}
+			if (verb === "configure") {
+				runtime.ctx.showAdvisorConfigure();
+				runtime.ctx.editor.setText("");
+				return;
+			}
+			runtime.ctx.showStatus("Usage: /advisor [on|off|status|dump [raw]|configure]");
+			runtime.ctx.editor.setText("");
+		},
+	},
+	{
+		name: "export",
+		description: "Export session to HTML file",
+		inlineHint: "[--themes] [path]",
+		allowArgs: true,
+		handle: async (command, runtime) => {
+			try {
+				const { outputPath, useUserThemes } = parseExportArgs(command.args);
+				if (outputPath === "--copy" || outputPath === "clipboard" || outputPath === "copy") {
+					return usage("Use /dump to copy the session to clipboard.", runtime);
+				}
+				const filePath = await runtime.session.exportToHtml(outputPath, useUserThemes);
+				await runtime.output(`Session exported to: ${filePath}`);
+				return commandConsumed();
+			} catch (err) {
+				return usage(`Failed to export session: ${errorMessage(err)}`, runtime);
+			}
+		},
+		handleTui: async (command, runtime) => {
+			await runtime.ctx.handleExportCommand(command.text);
+			runtime.ctx.editor.setText("");
+		},
+	},
+	{
+		name: "dump",
+		description: "Copy session transcript to clipboard (and write LLM request JSON to tmp)",
+		acpDescription: "Return full transcript as plain text, with LLM request JSON path",
+		allowArgs: true,
+		handle: async (_command, runtime) => {
+			const text = runtime.session.formatSessionAsText();
+			if (!text) {
+				await runtime.output("No messages to dump yet.");
+				return commandConsumed();
+			}
+			let sidecarPath: string | undefined;
+			try {
+				sidecarPath = await runtime.session.dumpLlmRequestToTmpDir();
+			} catch {
+				// Sidecar is best-effort; the transcript is still output below.
+			}
+			const lines = [text];
+			if (sidecarPath)
+				lines.push(
+					"",
+					`LLM request JSON: ${sidecarPath}`,
+					"This file persists on disk and may contain raw context/secrets — treat accordingly.",
+				);
+			await runtime.output(lines.join("\n"));
+			return commandConsumed();
+		},
+		handleTui: async (_command, runtime) => {
+			await runtime.ctx.handleDumpCommand();
+			runtime.ctx.editor.setText("");
+		},
+	},
+	{
+		name: "share",
+		description: "Share session via an encrypted link (share server or secret gist)",
+		handle: async (_command, runtime) => {
+			try {
+				const result = await shareSession(runtime.sessionManager, {
+					serverUrl: runtime.settings.get("share.serverUrl"),
+					store: runtime.settings.get("share.store"),
+					state: runtime.session.state,
+					obfuscator: runtime.settings.get("share.redactSecrets") ? runtime.session.obfuscator : undefined,
+				});
+				const lines = [`Share URL: ${result.url}`];
+				if (result.gistUrl) lines.push(`Gist: ${result.gistUrl}`);
+				if (result.truncated) lines.push("Note: large content was trimmed to fit the share size limit.");
+				await runtime.output(lines.join("\n"));
+				return commandConsumed();
+			} catch (err) {
+				return usage(`Failed to share session: ${errorMessage(err)}`, runtime);
+			}
+		},
+		handleTui: async (_command, runtime) => {
+			await runtime.ctx.handleShareCommand();
+			runtime.ctx.editor.setText("");
+		},
+	},
+	{
+		name: "collab",
+		description: "Share this session live via a relay",
+		inlineHint: "[start|view|stop|status] [relayUrl]",
+		subcommands: [
+			{ name: "view", description: "Share a read-only link (guests can watch, not prompt)" },
+			{ name: "status", description: "Show link + participants" },
+			{ name: "stop", description: "Stop sharing" },
+		],
+		allowArgs: true,
+		getTuiAutocompleteDescription: runtime => {
+			if (runtime.ctx.collabHost) {
+				return `Collab: hosting (${Math.max(0, runtime.ctx.collabHost.participants.length - 1)} guests)`;
+			}
+			if (runtime.ctx.collabGuest?.readOnly) return "Collab: read-only guest";
+			if (runtime.ctx.collabGuest) return "Collab: guest";
+			return "Collab: off";
+		},
+		handleTui: async (command, runtime) => {
+			const ctx = runtime.ctx;
+			ctx.editor.setText("");
+			const args = command.args.trim();
+			const { verb, rest } = parseSubcommand(args);
+			if (verb === "stop") {
+				if (!ctx.collabHost) {
+					ctx.showStatus("Not hosting a collab session");
+					return;
+				}
+				await ctx.collabHost.stop("host stopped");
+				ctx.showStatus("Collab stopped");
+				return;
+			}
+			if (verb === "status") {
+				if (ctx.collabHost) {
+					const names = ctx.collabHost.participants.map(p =>
+						p.role === "host" ? `${p.name} (host)` : p.readOnly ? `${p.name} (view-only)` : p.name,
+					);
+					ctx.showStatus(`Collab: ${names.join(", ")} — ${collabWebLinkClickable(ctx.collabHost.webLink)}`);
+				} else if (ctx.collabGuest) {
+					ctx.showStatus(
+						ctx.collabGuest.readOnly
+							? "In a collab session as a read-only guest (/leave to exit)"
+							: "In a collab session as a guest (/leave to exit)",
+					);
+				} else {
+					ctx.showStatus("Not in a collab session");
+				}
+				return;
+			}
+			if (ctx.collabGuest) {
+				ctx.showError("Already in a collab session as a guest (/leave first)");
+				return;
+			}
+			const knownStartVerb = verb === "start" || verb === "view";
+			const view = verb === "view";
+			if (ctx.collabHost) {
+				showCollabLink(
+					ctx,
+					ctx.collabHost,
+					view ? "Read-only collab session active" : "Collab session active",
+					view,
+				);
+				return;
+			}
+			const explicitUrl = knownStartVerb ? rest : args;
+			const relayInput = explicitUrl || ctx.settings.get("collab.relayUrl") || "";
+			if (!relayInput) {
+				ctx.showError(
+					"No relay configured. Set collab.relayUrl in /settings or pass one: /collab relay.example.com",
+				);
+				return;
+			}
+			// Scheme-less relay args default to wss (ws:// must be spelled out for localhost).
+			const relayUrl = relayInput.includes("://") ? relayInput : `wss://${relayInput}`;
+			const webUrl = ctx.settings.get("collab.webUrl") || "";
+			const host = new CollabHost(ctx);
+			try {
+				await host.start(relayUrl, webUrl);
+			} catch (err) {
+				ctx.showError(`Failed to start collab session: ${errorMessage(err)}`);
+				return;
+			}
+			ctx.collabHost = host;
+			showCollabLink(ctx, host, "Collab session started!", view);
+		},
+	},
+	{
+		name: "join",
+		description: "Join a shared collab session",
+		inlineHint: "<link>",
+		allowArgs: true,
+		handleTui: async (command, runtime) => {
+			const ctx = runtime.ctx;
+			ctx.editor.setText("");
+			const link = command.args.trim();
+			if (!link) {
+				ctx.showError("Usage: /join <link>");
+				return;
+			}
+			if (ctx.collabHost) {
+				ctx.showError("Stop hosting first (/collab stop)");
+				return;
+			}
+			if (ctx.collabGuest) {
+				ctx.showError("Already in a collab session (/leave first)");
+				return;
+			}
+			try {
+				await new CollabGuestLink(ctx).join(link);
+			} catch (err) {
+				ctx.showError(`Failed to join collab session: ${errorMessage(err)}`);
+			}
+		},
+	},
+	{
+		name: "leave",
+		description: "Leave the collab session",
+		getTuiAutocompleteDescription: runtime => {
+			if (runtime.ctx.collabHost) return "Leave collab: hosting";
+			if (runtime.ctx.collabGuest) return "Leave collab: guest";
+			return "Leave collab: not in collab";
+		},
+		handleTui: async (_command, runtime) => {
+			const ctx = runtime.ctx;
+			ctx.editor.setText("");
+			if (ctx.collabGuest) {
+				await ctx.collabGuest.leave("left");
+				return;
+			}
+			if (ctx.collabHost) {
+				await ctx.collabHost.stop("host stopped");
+				ctx.showStatus("Collab stopped");
+				return;
+			}
+			ctx.showStatus("Not in a collab session");
+		},
+	},
+	{
+		name: "browser",
+		description: "Toggle browser headless vs visible mode",
+		acpInputHint: "[headless|visible]",
+		subcommands: [
+			{ name: "headless", description: "Switch to headless mode" },
+			{ name: "visible", description: "Switch to visible mode" },
+		],
+		allowArgs: true,
+		getTuiAutocompleteDescription: runtime => {
+			if (!runtime.ctx.settings.get("browser.enabled" as SettingPath)) return "Browser: disabled";
+			return runtime.ctx.settings.get("browser.headless" as SettingPath) ? "Browser: headless" : "Browser: visible";
+		},
+		handle: async (command, runtime) => {
+			const arg = command.args.toLowerCase();
+			const enabled = runtime.settings.get("browser.enabled" as SettingPath) as boolean;
+			if (!enabled) return usage("Browser tool is disabled (enable in settings).", runtime);
+			const current = runtime.settings.get("browser.headless" as SettingPath) as boolean;
+			let next = current;
+			if (!arg) next = !current;
+			else if (arg === "headless" || arg === "hidden") next = true;
+			else if (arg === "visible" || arg === "show" || arg === "headful") next = false;
+			else return usage("Usage: /browser [headless|visible]", runtime);
+			runtime.settings.set("browser.headless" as SettingPath, next as SettingValue<SettingPath>);
+			const tool = runtime.session.getToolByName("browser");
+			if (tool && "restartForModeChange" in tool) {
+				try {
+					await (tool as { restartForModeChange: () => Promise<void> }).restartForModeChange();
+				} catch (err) {
+					// Setting was already mutated; surface the restart failure so the
+					// user knows the browser is in an inconsistent state.
+					await runtime.output(
+						`Browser mode set to ${next ? "headless" : "visible"}, but restart failed: ${errorMessage(err)}`,
+					);
+					return commandConsumed();
+				}
+			}
+			await runtime.output(`Browser mode: ${next ? "headless" : "visible"}`);
+			return commandConsumed();
+		},
+		handleTui: async (command, runtime) => {
+			const arg = command.args.toLowerCase();
+			const current = settings.get("browser.headless" as SettingPath) as boolean;
+			let next = current;
+			if (!(settings.get("browser.enabled" as SettingPath) as boolean)) {
+				runtime.ctx.showWarning("Browser tool is disabled (enable in settings)");
+				runtime.ctx.editor.setText("");
+				return;
+			}
+			if (!arg) {
+				next = !current;
+			} else if (arg === "headless" || arg === "hidden") {
+				next = true;
+			} else if (arg === "visible" || arg === "show" || arg === "headful") {
+				next = false;
+			} else {
+				runtime.ctx.showStatus("Usage: /browser [headless|visible]");
+				runtime.ctx.editor.setText("");
+				return;
+			}
+			settings.set("browser.headless" as SettingPath, next as SettingValue<SettingPath>);
+			const tool = runtime.ctx.session.getToolByName("browser");
+			if (tool && "restartForModeChange" in tool) {
+				try {
+					await (tool as { restartForModeChange: () => Promise<void> }).restartForModeChange();
+				} catch (error) {
+					runtime.ctx.showWarning(`Failed to restart browser: ${errorMessage(error)}`);
+					runtime.ctx.editor.setText("");
+					return;
+				}
+			}
+			runtime.ctx.showStatus(`Browser mode: ${next ? "headless" : "visible"}`);
+			runtime.ctx.editor.setText("");
+		},
+	},
+	{
+		name: "copy",
+		description: "Pick text or code from the conversation to copy",
+		allowArgs: true,
+		handleTui: async (command, runtime) => {
+			const arg = command.args.trim().toLowerCase();
+			if (!arg) {
+				runtime.ctx.showCopySelector();
+				runtime.ctx.editor.setText("");
+				return;
+			}
+			if (arg === "code") {
+				const block = extractLastCodeBlock(runtime.ctx.session.messages);
+				if (!block) {
+					runtime.ctx.showStatus("No code block to copy.");
+					runtime.ctx.editor.setText("");
+					return;
+				}
+				await copyToClipboard(block.code);
+				runtime.ctx.showStatus("Copied code block to clipboard");
+				runtime.ctx.editor.setText("");
+				return;
+			}
+			if (arg === "cmd" || arg === "command") {
+				const lastCommand = extractLastCommand(runtime.ctx.session.messages);
+				if (!lastCommand) {
+					runtime.ctx.showStatus("No command to copy.");
+					runtime.ctx.editor.setText("");
+					return;
+				}
+				await copyToClipboard(lastCommand.code);
+				runtime.ctx.showStatus(`Copied ${lastCommand.kind === "bash" ? "bash command" : "eval code"} to clipboard`);
+				runtime.ctx.editor.setText("");
+				return;
+			}
+			runtime.ctx.showStatus("Usage: /copy [code|cmd]");
+			runtime.ctx.editor.setText("");
+		},
+	},
+];