@herbertgao/pi-extensions 2026.8.1 → 2026.8.3

package/node_modules/@narumitw/pi-btw/src/settings.ts

@@ -0,0 +1,237 @@
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { mkdir, open, rename, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { BTW_THINKING_LEVELS, type BtwThinkingLevel } from "./side-thread.js";
+
+export const BTW_SETTINGS_FILE = "pi-btw.json";
+export const DEFAULT_REMEMBER_THINKING_LEVEL_CHANGES = true;
+const MAX_SETTINGS_BYTES = 64 * 1024;
+
+export interface BtwSettings {
+	model?: string;
+	thinkingLevel?: BtwThinkingLevel;
+	rememberThinkingLevelChanges?: boolean;
+}
+
+export type BtwSettingsLoadResult =
+	| { kind: "missing" }
+	| { kind: "invalid"; reason: string }
+	| { kind: "loaded"; settings: BtwSettings };
+
+export interface UpdateBtwSettingsOptions {
+	settingsPath?: string;
+	signal?: AbortSignal;
+	beforeRename?: (temporaryPath: string, settingsPath: string) => Promise<void>;
+}
+
+type SettingsDocument = Record<string, unknown>;
+
+const mutationQueues = new Map<string, Promise<void>>();
+
+export function btwSettingsPath(): string {
+	return join(getAgentDir(), BTW_SETTINGS_FILE);
+}
+
+export function normalizeBtwSettings(value: unknown): BtwSettings | undefined {
+	if (!isSettingsDocument(value)) return undefined;
+
+	const settings: BtwSettings = {};
+	if (Object.hasOwn(value, "model")) {
+		const model = Reflect.get(value, "model");
+		if (typeof model !== "string" || !parseBtwModelReference(model)) return undefined;
+		settings.model = model;
+	}
+	if (Object.hasOwn(value, "thinkingLevel")) {
+		const thinkingLevel = Reflect.get(value, "thinkingLevel");
+		if (!isBtwThinkingLevel(thinkingLevel)) return undefined;
+		settings.thinkingLevel = thinkingLevel;
+	}
+	if (Object.hasOwn(value, "rememberThinkingLevelChanges")) {
+		const remember = Reflect.get(value, "rememberThinkingLevelChanges");
+		if (typeof remember !== "boolean") return undefined;
+		settings.rememberThinkingLevelChanges = remember;
+	}
+	return settings;
+}
+
+export function parseBtwModelReference(
+	reference: string,
+): { provider: string; modelId: string } | undefined {
+	if (/[\s\p{Cc}]/u.test(reference)) return undefined;
+	const separator = reference.indexOf("/");
+	if (separator <= 0 || separator === reference.length - 1) return undefined;
+	return { provider: reference.slice(0, separator), modelId: reference.slice(separator + 1) };
+}
+
+export function effectiveRememberThinkingLevelChanges(settings: BtwSettings): boolean {
+	return settings.rememberThinkingLevelChanges ?? DEFAULT_REMEMBER_THINKING_LEVEL_CHANGES;
+}
+
+export async function readBtwSettings(
+	settingsPath = btwSettingsPath(),
+): Promise<BtwSettingsLoadResult> {
+	await awaitBtwSettingsWrites(settingsPath);
+	return readBtwSettingsUncoordinated(settingsPath);
+}
+
+export function updateBtwSettings(
+	patch: Partial<Pick<BtwSettings, "thinkingLevel" | "rememberThinkingLevelChanges">>,
+	options: UpdateBtwSettingsOptions = {},
+): Promise<BtwSettings> {
+	const settingsPath = options.settingsPath ?? btwSettingsPath();
+	return enqueueMutation(settingsPath, async () => {
+		options.signal?.throwIfAborted();
+		const current = await readSettingsDocumentForUpdate(settingsPath);
+		const updated: SettingsDocument = { ...current, ...patch };
+		const settings = normalizeBtwSettings(updated);
+		if (!settings) throw invalidSettingsError(settingsPath, "invalid settings shape");
+		await publishSettings(settingsPath, updated, options.signal, options.beforeRename);
+		return settings;
+	});
+}
+
+export async function awaitBtwSettingsWrites(settingsPath = btwSettingsPath()): Promise<void> {
+	await mutationQueues.get(settingsPath);
+}
+
+function enqueueMutation<T>(settingsPath: string, mutation: () => Promise<T>): Promise<T> {
+	const previous = mutationQueues.get(settingsPath) ?? Promise.resolve();
+	const result = previous.then(mutation, mutation);
+	const settled = result.then(
+		() => undefined,
+		() => undefined,
+	);
+	mutationQueues.set(settingsPath, settled);
+	void settled.finally(() => {
+		if (mutationQueues.get(settingsPath) === settled) mutationQueues.delete(settingsPath);
+	});
+	return result;
+}
+
+async function readBtwSettingsUncoordinated(settingsPath: string): Promise<BtwSettingsLoadResult> {
+	let contents: string;
+	try {
+		contents = await readSettingsContents(settingsPath);
+	} catch (error: unknown) {
+		if (isNodeError(error) && error.code === "ENOENT") return { kind: "missing" };
+		return { kind: "invalid", reason: `${settingsPath}: ${formatError(error)}` };
+	}
+
+	try {
+		const settings = normalizeBtwSettings(JSON.parse(contents) as unknown);
+		return settings
+			? { kind: "loaded", settings }
+			: { kind: "invalid", reason: `${settingsPath}: invalid settings shape` };
+	} catch {
+		return { kind: "invalid", reason: `${settingsPath}: invalid JSON` };
+	}
+}
+
+async function readSettingsDocumentForUpdate(settingsPath: string): Promise<SettingsDocument> {
+	let contents: string;
+	try {
+		contents = await readSettingsContents(settingsPath);
+	} catch (error: unknown) {
+		if (isNodeError(error) && error.code === "ENOENT") return {};
+		throw invalidSettingsError(settingsPath, formatError(error));
+	}
+
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(contents) as unknown;
+	} catch {
+		throw invalidSettingsError(settingsPath, "invalid JSON");
+	}
+	if (!isSettingsDocument(parsed) || !normalizeBtwSettings(parsed)) {
+		throw invalidSettingsError(settingsPath, "invalid settings shape");
+	}
+	return parsed;
+}
+
+async function readSettingsContents(settingsPath: string): Promise<string> {
+	const flags = constants.O_RDONLY | (constants.O_NONBLOCK ?? 0);
+	const handle = await open(settingsPath, flags);
+	try {
+		const descriptorStats = await handle.stat();
+		if (!descriptorStats.isFile()) throw new Error("settings path is not a regular file");
+		if (descriptorStats.size > MAX_SETTINGS_BYTES) {
+			throw new Error(`settings file exceeds ${MAX_SETTINGS_BYTES} bytes`);
+		}
+
+		const buffer = Buffer.alloc(MAX_SETTINGS_BYTES + 1);
+		let offset = 0;
+		while (offset < buffer.byteLength) {
+			const { bytesRead } = await handle.read(buffer, offset, buffer.byteLength - offset, offset);
+			if (bytesRead === 0) break;
+			offset += bytesRead;
+		}
+		if (offset > MAX_SETTINGS_BYTES) {
+			throw new Error(`settings file exceeds ${MAX_SETTINGS_BYTES} bytes`);
+		}
+		try {
+			return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(
+				buffer.subarray(0, offset),
+			);
+		} catch {
+			throw new Error("settings file is not valid UTF-8");
+		}
+	} finally {
+		await handle.close();
+	}
+}
+
+async function publishSettings(
+	settingsPath: string,
+	document: SettingsDocument,
+	signal?: AbortSignal,
+	beforeRename?: (temporaryPath: string, settingsPath: string) => Promise<void>,
+): Promise<void> {
+	signal?.throwIfAborted();
+	const contents = `${JSON.stringify(document, null, 2)}\n`;
+	if (Buffer.byteLength(contents, "utf8") > MAX_SETTINGS_BYTES) {
+		throw new Error(`settings document exceeds ${MAX_SETTINGS_BYTES} bytes`);
+	}
+	const directory = dirname(settingsPath);
+	await mkdir(directory, { recursive: true });
+	signal?.throwIfAborted();
+	const temporaryPath = join(
+		directory,
+		`.${basename(settingsPath)}.${process.pid}.${randomUUID()}.tmp`,
+	);
+	try {
+		await writeFile(temporaryPath, contents, {
+			encoding: "utf8",
+			flag: "wx",
+			mode: 0o600,
+			signal,
+		});
+		await beforeRename?.(temporaryPath, settingsPath);
+		signal?.throwIfAborted();
+		await rename(temporaryPath, settingsPath);
+	} catch (error) {
+		await rm(temporaryPath, { force: true }).catch(() => undefined);
+		throw error;
+	}
+}
+
+function isSettingsDocument(value: unknown): value is SettingsDocument {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isBtwThinkingLevel(value: unknown): value is BtwThinkingLevel {
+	return BTW_THINKING_LEVELS.includes(value as BtwThinkingLevel);
+}
+
+function invalidSettingsError(settingsPath: string, reason: string): Error {
+	return new Error(`pi-btw settings at ${settingsPath} are invalid: ${reason}`);
+}
+
+function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+	return error instanceof Error && "code" in error;
+}
+
+function formatError(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}

package/node_modules/@narumitw/pi-btw/src/side-thread.ts

@@ -0,0 +1,238 @@
+import type {
+	Api,
+	AssistantMessage,
+	Context,
+	Message,
+	Model,
+	ProviderHeaders,
+	SimpleStreamOptions,
+	UserMessage,
+} from "@earendil-works/pi-ai";
+
+export const BTW_THINKING_LEVELS = [
+	"off",
+	"minimal",
+	"low",
+	"medium",
+	"high",
+	"xhigh",
+	"max",
+] as const;
+
+export type BtwThinkingLevel = (typeof BTW_THINKING_LEVELS)[number];
+
+export interface SideQuestionAuth {
+	apiKey?: string;
+	headers?: ProviderHeaders;
+	env?: Record<string, string>;
+}
+
+export type CompleteSimpleFunction = <TApi extends Api>(
+	model: Model<TApi>,
+	context: Context,
+	options?: SimpleStreamOptions,
+) => Promise<AssistantMessage>;
+
+export type SideThreadTurn =
+	| {
+			kind: "answered";
+			question: string;
+			answer: string;
+			response: AssistantMessage;
+	  }
+	| {
+			kind: "error";
+			question: string;
+			answer: string;
+	  };
+
+export interface SideThread {
+	conversationContext: string;
+	turns: SideThreadTurn[];
+}
+
+export function createSideThread(conversationContext: string): SideThread {
+	return { conversationContext, turns: [] };
+}
+
+export function buildSideThreadMessages(thread: SideThread, question: string): Message[] {
+	const answeredTurns = thread.turns.filter(
+		(turn): turn is Extract<SideThreadTurn, { kind: "answered" }> => turn.kind === "answered",
+	);
+	const messages: Message[] = [];
+
+	if (answeredTurns.length === 0) {
+		messages.push(createUserMessage(buildUserPrompt(question, thread.conversationContext)));
+		return messages;
+	}
+
+	const [first, ...rest] = answeredTurns;
+	messages.push(
+		createUserMessage(buildUserPrompt(first.question, thread.conversationContext)),
+		first.response,
+	);
+	for (const turn of rest) {
+		messages.push(createUserMessage(buildFollowUpPrompt(turn.question)), turn.response);
+	}
+	messages.push(createUserMessage(buildFollowUpPrompt(question)));
+	return messages;
+}
+
+export interface CompleteSideThreadTurnOptions {
+	thread: SideThread;
+	model: Model<Api>;
+	question: string;
+	thinkingLevel: BtwThinkingLevel;
+	auth: SideQuestionAuth;
+	signal?: AbortSignal;
+	completeSimple: CompleteSimpleFunction;
+}
+
+export type CompleteSideThreadTurnResult =
+	| { kind: "answered"; response: AssistantMessage; answer: string }
+	| { kind: "aborted" }
+	| { kind: "error"; message: string };
+
+export async function completeSideThreadTurn({
+	thread,
+	model,
+	question,
+	thinkingLevel,
+	auth,
+	signal,
+	completeSimple,
+}: CompleteSideThreadTurnOptions): Promise<CompleteSideThreadTurnResult> {
+	if (signal?.aborted) return { kind: "aborted" };
+	try {
+		const response = await completeSimple(
+			model,
+			{ systemPrompt: SYSTEM_PROMPT, messages: buildSideThreadMessages(thread, question) },
+			buildStreamOptions(auth, thinkingLevel, signal),
+		);
+		if (signal?.aborted || response?.stopReason === "aborted") return { kind: "aborted" };
+		if (!isAssistantMessage(response)) {
+			return { kind: "error", message: "The side model returned a malformed response." };
+		}
+		if (response.stopReason === "error") {
+			return {
+				kind: "error",
+				message: response.errorMessage ?? "The side model returned an error.",
+			};
+		}
+
+		const answer = extractAssistantText(response) || "No response received.";
+		thread.turns.push({ kind: "answered", question, answer, response });
+		return { kind: "answered", response, answer };
+	} catch (error: unknown) {
+		if (signal?.aborted) return { kind: "aborted" };
+		return { kind: "error", message: formatError(error) };
+	}
+}
+
+export interface CompleteSideQuestionOptions {
+	model: Model<Api>;
+	question: string;
+	conversationContext: string;
+	thinkingLevel: BtwThinkingLevel;
+	auth: SideQuestionAuth;
+	signal?: AbortSignal;
+	completeSimple: CompleteSimpleFunction;
+}
+
+export async function completeSideQuestion({
+	model,
+	question,
+	conversationContext,
+	thinkingLevel,
+	auth,
+	signal,
+	completeSimple,
+}: CompleteSideQuestionOptions): Promise<AssistantMessage> {
+	return completeSimple(
+		model,
+		{
+			systemPrompt: SYSTEM_PROMPT,
+			messages: [createUserMessage(buildUserPrompt(question, conversationContext))],
+		},
+		buildStreamOptions(auth, thinkingLevel, signal),
+	);
+}
+
+export function extractAssistantText(response: AssistantMessage): string {
+	return response.content
+		.filter(
+			(content): content is { type: "text"; text: string } =>
+				content !== null &&
+				typeof content === "object" &&
+				content.type === "text" &&
+				typeof content.text === "string",
+		)
+		.map((content) => content.text)
+		.join("\n")
+		.trim();
+}
+
+function isAssistantMessage(value: unknown): value is AssistantMessage {
+	if (value === null || typeof value !== "object") return false;
+	const candidate = value as Partial<AssistantMessage>;
+	return (
+		candidate.role === "assistant" &&
+		Array.isArray(candidate.content) &&
+		typeof candidate.stopReason === "string"
+	);
+}
+
+export function buildUserPrompt(question: string, conversationContext: string): string {
+	return [
+		"Answer this side question without modifying the main conversation.",
+		"",
+		"<side_question>",
+		question,
+		"</side_question>",
+		"",
+		"<conversation_context>",
+		conversationContext || "No prior conversation context was available.",
+		"</conversation_context>",
+	].join("\n");
+}
+
+export function buildFollowUpPrompt(question: string): string {
+	return [
+		"Continue the same side conversation.",
+		"",
+		"<side_question>",
+		question,
+		"</side_question>",
+	].join("\n");
+}
+
+function createUserMessage(text: string): UserMessage {
+	return {
+		role: "user",
+		content: [{ type: "text", text }],
+		timestamp: Date.now(),
+	};
+}
+
+function buildStreamOptions(
+	auth: SideQuestionAuth,
+	thinkingLevel: BtwThinkingLevel,
+	signal?: AbortSignal,
+): SimpleStreamOptions {
+	const options: SimpleStreamOptions = {
+		apiKey: auth.apiKey,
+		headers: auth.headers,
+		env: auth.env,
+		signal,
+	};
+	if (thinkingLevel !== "off") options.reasoning = thinkingLevel;
+	return options;
+}
+
+function formatError(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+const SYSTEM_PROMPT = `You answer quick side questions for a coding-agent user.
+
+Use the provided conversation context only as background. Answer the user's side question directly and concisely. Do not claim to have changed files, run tools, or affected the main task. If the context is insufficient, say what is unknown and give the best next step.`;

package/node_modules/@narumitw/pi-btw/src/text.ts

@@ -0,0 +1,10 @@
+export function sanitizeSingleLine(text: string): string {
+	return [...text.replace(/[\r\n\t]/gu, " ")]
+		.filter((character) => {
+			const code = character.charCodeAt(0);
+			return code > 31 && (code < 127 || code > 159);
+		})
+		.join("")
+		.replace(/ +/gu, " ")
+		.trim();
+}