@rexvane/piweb 0.3.1

package/src/lib/app-root.ts

@@ -0,0 +1,4 @@
+import path from "node:path";
+
+/** The launchers set this explicitly; direct `next` invocations still use their working directory. */
+export const APP_ROOT = path.resolve(process.env.PI_WEB_ROOT ?? process.cwd());

package/src/lib/auth.ts

@@ -0,0 +1,51 @@
+const BASIC_PREFIX = "Basic ";
+
+/** 恒定时间字符串比较（长度不同也走完全程，不早退） */
+export function equalText(left: string, right: string): boolean {
+	const max = Math.max(left.length, right.length);
+	let mismatch = left.length ^ right.length;
+	for (let i = 0; i < max; i += 1) {
+		mismatch |= (left.charCodeAt(i) || 0) ^ (right.charCodeAt(i) || 0);
+	}
+	return mismatch === 0;
+}
+
+export function validBasicAuthorization(header: string | null, password: string): boolean {
+	if (!header?.startsWith(BASIC_PREFIX)) return false;
+	try {
+		const decoded = Buffer.from(header.slice(BASIC_PREFIX.length), "base64").toString("utf8");
+		const separator = decoded.indexOf(":");
+		if (separator < 0) return false;
+		return equalText(decoded.slice(0, separator), "pi") && equalText(decoded.slice(separator + 1), password);
+	} catch {
+		return false;
+	}
+}
+
+export function isSafeOrigin(request: Request): boolean {
+	const origin = request.headers.get("origin");
+	if (!origin) return true;
+	try {
+		const originUrl = new URL(origin);
+		const expectedHost = request.headers.get("host") || new URL(request.url).host;
+		return originUrl.host.toLowerCase() === expectedHost.toLowerCase();
+	} catch {
+		return false;
+	}
+}
+
+export function isSafeHost(request: Request, passwordConfigured: boolean): boolean {
+	if (passwordConfigured) return true;
+	try {
+		const host = request.headers.get("host") || new URL(request.url).host;
+		const parsed = new URL(`http://${host}`);
+		return !parsed.username && !parsed.password && parsed.host.toLowerCase() === host.toLowerCase() && isLoopbackHostname(parsed.hostname);
+	} catch {
+		return false;
+	}
+}
+
+export function isLoopbackHostname(hostname: string): boolean {
+	const host = hostname.trim().toLowerCase().replace(/^\[|\]$/g, "");
+	return host === "localhost" || host === "::1" || host === "0:0:0:0:0:0:0:1" || /^127(?:\.\d{1,3}){3}$/.test(host);
+}

package/src/lib/command-validation.ts

@@ -0,0 +1,116 @@
+import type { AgentCommand, ImageAttachment, ToolPreset } from "./types";
+
+const COMMANDS = new Set<AgentCommand["cmd"]>([
+	"prepare",
+	"prompt",
+	"steer",
+	"followUp",
+	"abort",
+	"compact",
+	"setModel",
+	"setThinkingLevel",
+	"setToolPreset",
+	"setActiveTools",
+	"rename",
+	"fork",
+	"cycleModel",
+	"navigate",
+	"clearQueue",
+	"extensionUiResponse",
+	"reload",
+]);
+const TOOL_PRESETS = new Set<ToolPreset>(["readonly", "standard", "full"]);
+const STREAMING_BEHAVIORS = new Set(["steer", "followUp"]);
+const IMAGE_TYPES = new Set(["image/jpeg", "image/png", "image/webp", "image/gif"]);
+const MAX_TEXT = 1_000_000;
+const MAX_IMAGES = 20;
+const MAX_IMAGE_BASE64 = 28_000_000; // dsh: 单图 20MB
+const MAX_IMAGES_BASE64 = 268_000_000; // dsh: 单条消息图片总量 200MB
+
+export type CommandParseResult = { ok: true; command: AgentCommand } | { ok: false; error: string };
+
+function optionalText(value: unknown, field: string): string | undefined {
+	if (value === undefined) return undefined;
+	if (typeof value !== "string") throw new Error(`${field} must be a string`);
+	if (value.length > MAX_TEXT) throw new Error(`${field} is too long`);
+	return value;
+}
+
+function parseImages(value: unknown): ImageAttachment[] | undefined {
+	if (value === undefined) return undefined;
+	if (!Array.isArray(value) || value.length > MAX_IMAGES) throw new Error(`images must contain at most ${MAX_IMAGES} items`);
+	let total = 0;
+	return value.map((raw) => {
+		if (!raw || typeof raw !== "object") throw new Error("invalid image");
+		const image = raw as Record<string, unknown>;
+		if (image.type !== "image" || typeof image.data !== "string" || typeof image.mimeType !== "string") {
+			throw new Error("invalid image");
+		}
+		if (!IMAGE_TYPES.has(image.mimeType)) throw new Error(`unsupported image type ${image.mimeType}`);
+		if (image.data.length === 0 || image.data.length > MAX_IMAGE_BASE64 || !/^[A-Za-z0-9+/]*={0,2}$/.test(image.data)) {
+			throw new Error("invalid or oversized image data");
+		}
+		total += image.data.length;
+		if (total > MAX_IMAGES_BASE64) throw new Error("image attachments are too large");
+		return { type: "image", data: image.data, mimeType: image.mimeType };
+	});
+}
+
+export function parseAgentCommand(value: unknown): CommandParseResult {
+	try {
+		if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("command must be an object");
+		const raw = value as Record<string, unknown>;
+		if (typeof raw.cmd !== "string" || !COMMANDS.has(raw.cmd as AgentCommand["cmd"])) throw new Error("unknown command");
+
+		const command: AgentCommand = {
+			cmd: raw.cmd as AgentCommand["cmd"],
+			text: optionalText(raw.text, "text"),
+			instructions: optionalText(raw.instructions, "instructions"),
+			provider: optionalText(raw.provider, "provider"),
+			modelId: optionalText(raw.modelId, "modelId"),
+			level: optionalText(raw.level, "level"),
+			entryId: optionalText(raw.entryId, "entryId"),
+			images: parseImages(raw.images),
+		};
+
+		if (raw.preset !== undefined) {
+			if (typeof raw.preset !== "string" || !TOOL_PRESETS.has(raw.preset as ToolPreset)) throw new Error("invalid tool preset");
+			command.preset = raw.preset as ToolPreset;
+		}
+		if (raw.behavior !== undefined) {
+			if (typeof raw.behavior !== "string" || !STREAMING_BEHAVIORS.has(raw.behavior)) throw new Error("invalid streaming behavior");
+			command.behavior = raw.behavior as "steer" | "followUp";
+		}
+		if (raw.direction !== undefined) {
+			if (raw.direction !== "forward" && raw.direction !== "backward") throw new Error("invalid cycle direction");
+			command.direction = raw.direction;
+		}
+		if (raw.names !== undefined) {
+			// setActiveTools 的目标工具名列表：数量与长度上限防滥用（未知名字由 agent-manager 求交集丢弃）
+			if (!Array.isArray(raw.names) || raw.names.length === 0 || raw.names.length > 64 || raw.names.some((n) => typeof n !== "string" || !n || n.length > 100)) {
+				throw new Error("names must be a non-empty array of tool names");
+			}
+			command.names = raw.names as string[];
+		}
+
+		if (raw.requestId !== undefined) command.requestId = optionalText(raw.requestId, "requestId");
+		if (raw.value !== undefined) command.value = optionalText(raw.value, "value");
+		if (raw.confirmed !== undefined) {
+			if (typeof raw.confirmed !== "boolean") throw new Error("confirmed must be a boolean");
+			command.confirmed = raw.confirmed;
+		}
+		if (raw.cancelled !== undefined) {
+			if (typeof raw.cancelled !== "boolean") throw new Error("cancelled must be a boolean");
+			command.cancelled = raw.cancelled;
+		}
+		if (command.cmd === "extensionUiResponse" && !command.requestId) throw new Error("requestId is required");
+		if (command.cmd === "setModel" && (!command.provider || !command.modelId)) throw new Error("provider and modelId are required");
+		if (command.cmd === "setThinkingLevel" && !command.level) throw new Error("level is required");
+		if (command.cmd === "setToolPreset" && !command.preset) throw new Error("preset is required");
+		if (command.cmd === "setActiveTools" && !command.names) throw new Error("names are required");
+		if (command.cmd === "navigate" && !command.entryId) throw new Error("entryId is required");
+		return { ok: true, command };
+	} catch (error) {
+		return { ok: false, error: error instanceof Error ? error.message : "invalid command" };
+	}
+}

package/src/lib/enter-behavior.ts

@@ -0,0 +1,40 @@
+/**
+ * 繁忙时 Enter 的发送方式：steer（插话，当前工具跑完就送达）/ queue（排队，本轮结束后发送）。
+ * 存 localStorage；用 useSyncExternalStore 让输入卡和设置面板同步（改设置立刻反映到提示文案）。
+ */
+import { useSyncExternalStore } from "react";
+
+export type EnterBehavior = "steer" | "queue";
+
+const KEY = "piweb.enterBehavior";
+/** 默认插话：与 pi 终端的 Enter 一致，也是 Claude Code 排队消息「尽快送达」的行为 */
+export const DEFAULT_ENTER_BEHAVIOR: EnterBehavior = "steer";
+const listeners = new Set<() => void>();
+
+export function getEnterBehavior(): EnterBehavior {
+	if (typeof window === "undefined") return DEFAULT_ENTER_BEHAVIOR;
+	const v = localStorage.getItem(KEY);
+	return v === "queue" || v === "steer" ? v : DEFAULT_ENTER_BEHAVIOR;
+}
+
+export function setEnterBehavior(v: EnterBehavior): void {
+	localStorage.setItem(KEY, v);
+	for (const l of listeners) l();
+}
+
+export function otherBehavior(v: EnterBehavior): EnterBehavior {
+	return v === "steer" ? "queue" : "steer";
+}
+
+function subscribe(l: () => void): () => void {
+	listeners.add(l);
+	window.addEventListener("storage", l);
+	return () => {
+		listeners.delete(l);
+		window.removeEventListener("storage", l);
+	};
+}
+
+export function useEnterBehavior(): EnterBehavior {
+	return useSyncExternalStore(subscribe, getEnterBehavior, () => DEFAULT_ENTER_BEHAVIOR);
+}

package/src/lib/extension-ui.ts

@@ -0,0 +1,134 @@
+/**
+ * extension-ui：把 pi 扩展的界面请求（select / confirm / input / notify / setStatus）
+ * 桥接到浏览器——与 pi 自己的 RPC 模式（extension_ui_request / extension_ui_response）同一套语义。
+ * 没有页面在看时（无订阅者）select/input 返回 undefined、confirm 返回 false，与 pi 的 noOp 行为一致。
+ */
+import { randomUUID } from "node:crypto";
+import type { WebEvent } from "./types";
+
+type UiMethod = Extract<WebEvent, { type: "extension_ui" }>["method"];
+type UiEvent = Extract<WebEvent, { type: "extension_ui" }>;
+
+interface PendingUi {
+	request: UiEvent;
+	resolve: (response: { value?: string; confirmed?: boolean; cancelled?: boolean }) => void;
+	timer?: ReturnType<typeof setTimeout>;
+	removeAbortListener?: () => void;
+}
+
+export interface ExtensionUiBridge {
+	/** 供 AgentSession.bindExtensions 的 uiContext（只实现 Web 能承接的部分，其余 no-op） */
+	uiContext: Record<string, unknown>;
+	/** 浏览器应答 */
+	respond(requestId: string, response: { value?: string; confirmed?: boolean; cancelled?: boolean }): boolean;
+	/** 当前仍待应答的请求，不含已答/取消/过期请求。 */
+	getPendingRequests(): UiEvent[];
+	/** 会话销毁：把挂起的对话框全部按取消结束 */
+	dispose(): void;
+	/** 扩展通过 setStatus 设的状态文本（页脚展示） */
+	statuses: Map<string, string>;
+}
+
+const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
+
+export function createExtensionUiBridge(opts: {
+	publish: (evt: WebEvent) => void;
+	hasViewers: () => boolean;
+}): ExtensionUiBridge {
+	const pending = new Map<string, PendingUi>();
+	const statuses = new Map<string, string>();
+	let disposed = false;
+
+	const ask = <T,>(
+		request: Omit<UiEvent, "type" | "id" | "ts">,
+		dialogOpts: { signal?: AbortSignal; timeout?: number } | undefined,
+		fallback: T,
+		parse: (r: { value?: string; confirmed?: boolean; cancelled?: boolean }) => T,
+	): Promise<T> => {
+		// 没有浏览器在看：不能永远挂着扩展，按 pi 的 noOp 语义立即返回默认值
+		if (disposed || !opts.hasViewers() || dialogOpts?.signal?.aborted) return Promise.resolve(fallback);
+		const id = randomUUID();
+		return new Promise<T>((resolve) => {
+			const finish = (r: { value?: string; confirmed?: boolean; cancelled?: boolean } | null) => {
+				const entry = pending.get(id);
+				if (!entry) return;
+				pending.delete(id);
+				if (entry.timer) clearTimeout(entry.timer);
+				entry.removeAbortListener?.();
+				opts.publish({ type: "extension_ui_resolved", id, ts: Date.now() });
+				resolve(r ? parse(r) : fallback);
+			};
+			const event: UiEvent = { type: "extension_ui", id, ...request, timeout: dialogOpts?.timeout, ts: Date.now() };
+			const entry: PendingUi = { request: event, resolve: (r) => finish(r) };
+			const timeout = dialogOpts?.timeout ?? DEFAULT_TIMEOUT_MS;
+			entry.timer = setTimeout(() => finish(null), timeout);
+			entry.timer.unref?.();
+			const onAbort = () => finish(null);
+			dialogOpts?.signal?.addEventListener("abort", onAbort, { once: true });
+			entry.removeAbortListener = () => dialogOpts?.signal?.removeEventListener("abort", onAbort);
+			pending.set(id, entry);
+			opts.publish(event);
+		});
+	};
+
+	const uiContext: Record<string, unknown> = {
+		select: (title: string, options: string[], o?: { signal?: AbortSignal; timeout?: number }) =>
+			ask<string | undefined>({ method: "select", title, options }, o, undefined, (r) => (r.cancelled ? undefined : r.value)),
+		confirm: (title: string, message: string, o?: { signal?: AbortSignal; timeout?: number }) =>
+			ask<boolean>({ method: "confirm", title, message }, o, false, (r) => (r.cancelled ? false : r.confirmed === true)),
+		input: (title: string, placeholder?: string, o?: { signal?: AbortSignal; timeout?: number }) =>
+			ask<string | undefined>({ method: "input", title, placeholder }, o, undefined, (r) => (r.cancelled ? undefined : r.value)),
+		notify: (message: string, type?: "info" | "warning" | "error") => {
+			opts.publish({ type: "extension_ui", id: randomUUID(), method: "notify", message, notifyType: type ?? "info", ts: Date.now() });
+		},
+		setStatus: (key: string, text: string | undefined) => {
+			if (text === undefined) statuses.delete(key);
+			else statuses.set(key, text);
+			opts.publish({ type: "extension_ui", id: randomUUID(), method: "setStatus", statusKey: key, statusText: text, ts: Date.now() });
+		},
+		setWorkingMessage: (message?: string) => {
+			opts.publish({ type: "extension_ui", id: randomUUID(), method: "setWorkingMessage", message, ts: Date.now() });
+		},
+		// 终端专属能力：Web 无对应物，按 pi 的 noOp 处理
+		onTerminalInput: () => () => {},
+		setWorkingVisible: () => {},
+		setWorkingIndicator: () => {},
+		setHiddenThinkingLabel: () => {},
+		setWidget: () => {},
+		setFooter: () => {},
+		setHeader: () => {},
+		setTitle: () => {},
+		custom: async () => undefined,
+		pasteToEditor: () => {},
+		setEditorText: () => {},
+		getEditorText: () => "",
+		editor: async () => undefined,
+		addAutocompleteProvider: () => {},
+		setEditorComponent: () => {},
+		getEditorComponent: () => undefined,
+		getAllThemes: () => [],
+		getTheme: () => undefined,
+		setTheme: () => {},
+		getToolsExpanded: () => false,
+		setToolsExpanded: () => {},
+	};
+
+	return {
+		uiContext,
+		statuses,
+		getPendingRequests: () => [...pending.values()].map(({ request }) => ({ ...request, options: request.options ? [...request.options] : undefined })),
+		respond(requestId, response) {
+			const entry = pending.get(requestId);
+			if (!entry) return false;
+			entry.resolve(response);
+			return true;
+		},
+		dispose() {
+			disposed = true;
+			for (const entry of pending.values()) entry.resolve({ cancelled: true });
+			pending.clear();
+		},
+	};
+}
+
+export type { UiMethod };