@gavin-hu/my-pi-agent 0.16.0 → 0.18.0

package/lib/http/router.ts

@@ -1,16 +1,30 @@
 /**
- * The request-envelope helpers both loopback routers apply before a route runs:
- * the request target, and the `Host` allowlist.
+ * The request-envelope helpers both servers apply before a route runs: the
+ * request target, and the `Host` allowlist.
  *
- * Both surfaces bind `127.0.0.1`, so a `Host` naming anything else is a
- * DNS-rebinding attempt against a local page. How strictly a missing `Host` is
- * treated is the caller's decision: the browse server accepts one, because its
- * router is also driven directly from tests and a plain `GET` with no header is
- * not a rebinding, while the review server fails closed.
+ * A server answers to the names it was bound on and nothing else, so a `Host`
+ * naming anything else is a DNS-rebinding attempt against a page the owner
+ * opened. How strictly a missing `Host` is treated is the caller's decision: the
+ * browse server accepts one, because its router is also driven directly from
+ * tests and a plain `GET` with no header is not a rebinding, while the review
+ * server fails closed.
  */
 
-/** The `Host` names a loopback interface, with or without a port. */
-const LOCAL_HOST = /^(127\.0\.0\.1|localhost|\[::1\])(:\d+)?$/i;
+/** The names a loopback-bound server answers to. */
+export const LOOPBACK_HOSTS: readonly string[] = ["127.0.0.1", "localhost", "[::1]"];
+
+/** The host name in a `Host` header, without its port, lowercased. */
+export function hostHeaderName(host: string): string {
+	const text = host.trim().toLowerCase();
+	if (text.startsWith("[")) {
+		const end = text.indexOf("]");
+		return end > 0 ? text.slice(0, end + 1) : text;
+	}
+	const first = text.indexOf(":");
+	// No colon, or an unbracketed IPv6 address whose colons are not a port.
+	if (first <= 0 || first !== text.lastIndexOf(":")) return text;
+	return /^\d+$/.test(text.slice(first + 1)) ? text.slice(0, first) : text;
+}
 
 /** A request target split into the parts a router matches on. */
 export interface ParsedRequestUrl {
@@ -35,18 +49,31 @@ export function parseRequestUrl(rawUrl: string): ParsedRequestUrl | undefined {
 }
 
 /**
- * Whether the request's `Host` names this loopback server.
+ * Whether the request's `Host` names one of the hosts this server answers to.
  *
  * With `required: false`, only a present, non-empty foreign name is refused, so
  * a header-less request from another caller still routes. With `required: true`,
  * a missing or non-string `Host` is refused too, so the guard cannot be skipped
  * by omitting the header.
  */
-export function isLocalHostHeader(
+export function isAllowedHostHeader(
 	headers: Record<string, string | string[] | undefined>,
-	options: { required: boolean },
+	options: { hosts: readonly string[]; required: boolean },
 ): boolean {
 	const host = headers.host;
 	if (typeof host !== "string" || host === "") return !options.required;
-	return LOCAL_HOST.test(host);
+	const name = hostHeaderName(host);
+	return options.hosts.some((allowed) => hostHeaderName(allowed) === name);
+}
+
+/**
+ * Whether the request's `Host` names this loopback server. A caller that binds
+ * anything other than loopback passes its own names to
+ * {@link isAllowedHostHeader} instead.
+ */
+export function isLocalHostHeader(
+	headers: Record<string, string | string[] | undefined>,
+	options: { required: boolean },
+): boolean {
+	return isAllowedHostHeader(headers, { hosts: LOOPBACK_HOSTS, required: options.required });
 }

package/lib/http/server.ts

@@ -1,14 +1,15 @@
 /**
- * The socket seam shared by the two loopback servers: bind, write a response
- * out, and close.
+ * The socket seam shared by the browser servers: bind, write a response out,
+ * and close.
  *
  * Everything here is behavior a caller cannot get right by accident: a bind on
- * `127.0.0.1` only, an accept-level `error` listener so a transient failure
- * cannot take the host down, a `HEAD` that sends headers and no body, a `filePath`
- * response streamed instead of buffered, a `stream` response opened as an event
- * stream, and a close that is safe to call twice and drops keep-alive
- * connections. What each server does *around* this — which frames an event
- * stream carries, request bodies, session settling — stays with that server.
+ * an address the caller names (loopback unless it asked for more), an
+ * accept-level `error` listener so a transient failure cannot take the host
+ * down, a `HEAD` that sends headers and no body, a `filePath` response streamed
+ * instead of buffered, a `stream` response opened as an event stream, and a
+ * close that is safe to call twice and drops keep-alive connections. What each
+ * server does *around* this — which frames an event stream carries, request
+ * bodies, session settling — stays with that server.
  */
 
 import { createReadStream } from "node:fs";
@@ -16,15 +17,19 @@ import type { IncomingMessage, Server, ServerResponse } from "node:http";
 import type { ServeResponse } from "./response.ts";
 
 /**
- * Bind `server` to `127.0.0.1:port` and resolve the port it actually bound
- * (`0` asks the OS to pick one). Rejects when the bind fails, so a caller that
- * wants a fallback can retry with another port.
+ * Bind `server` to `host:port` and resolve the port it actually bound (`0` asks
+ * the OS to pick one). Rejects when the bind fails, so a caller that wants a
+ * fallback can retry with another port.
+ *
+ * `host` is the address the caller is about to print, never a wildcard by
+ * default: a review shared on a LAN opens exactly one address, so the link the
+ * owner sees is the whole surface.
  */
-export async function bindLoopback(server: Server, port: number): Promise<number> {
+export async function bindHost(server: Server, host: string, port: number): Promise<number> {
 	await new Promise<void>((resolve, reject) => {
 		const onError = (error: Error) => reject(error);
 		server.once("error", onError);
-		server.listen(port, "127.0.0.1", () => {
+		server.listen(port, host, () => {
 			server.off("error", onError);
 			resolve();
 		});
@@ -37,6 +42,15 @@ export async function bindLoopback(server: Server, port: number): Promise<number
 	return typeof address === "object" && address ? address.port : port;
 }
 
+/**
+ * Bind `server` to `127.0.0.1:port` and resolve the port it actually bound
+ * (`0` asks the OS to pick one). Rejects when the bind fails, so a caller that
+ * wants a fallback can retry with another port.
+ */
+export async function bindLoopback(server: Server, port: number): Promise<number> {
+	return bindHost(server, "127.0.0.1", port);
+}
+
 /**
  * Write one routed response: headers first, then no body for `HEAD`, the file
  * for a `filePath` response, or the buffered body.

package/lib/interaction.ts

@@ -20,6 +20,9 @@ import type { ExtensionContext, ExtensionUIContext } from "@earendil-works/pi-co
 /** The host run modes, derived because the package does not export the union. */
 export type InteractionMode = ExtensionContext["mode"];
 
+/** The two languages a remote prompt is rendered in. */
+export type InteractionLanguage = "zh" | "en";
+
 /** The `ctx.ui` property a remote transport marks with the channel that owns its turn. */
 export const INTERACTION_TURN_KEY = "isRemoteTurn";
 
@@ -59,6 +62,14 @@ export interface InteractionChannel {
 	post(text: string, signal?: AbortSignal): Promise<void>;
 	/** Send a local file to the human; resolves true when delivered. */
 	postFile(path: string, name: string, signal?: AbortSignal): Promise<boolean>;
+	/** The language this channel renders prompts in, when it knows one. */
+	language?(): InteractionLanguage;
+	/**
+	 * Widen the bound on the prompts asked inside the returned scope: use it for a
+	 * dialog the human must read something before answering. Returns the restore,
+	 * and a transport with no such policy omits the method.
+	 */
+	setPromptTimeout?(ms: number): () => void;
 }
 
 /** The slice of an extension context {@link remoteChannel} reads. */
@@ -85,6 +96,11 @@ export function isRemoteTurn(ctx: UIContextCarrier): boolean {
 	return remoteChannel(ctx) !== undefined;
 }
 
+/** The remote channel's prompt language, or undefined for a local turn. */
+export function remoteLanguage(ctx: UIContextCarrier): InteractionLanguage | undefined {
+	return remoteChannel(ctx)?.language?.();
+}
+
 /** Whether a full-screen `ctx.ui.custom` component may be used for this turn. */
 export function supportsCustomUI(ctx: UIContextCarrier): boolean {
 	return ctx.mode === "tui" && !isRemoteTurn(ctx);
@@ -105,6 +121,12 @@ export interface AskHumanOptions<T> {
 	 * attachment may never be opened (a phone client can hide a file bubble).
 	 */
 	note?: string;
+	/**
+	 * How long a remote channel may wait for the answer before dismissing the
+	 * dialog. Raise it when the human has to read an artifact first; the channel's
+	 * own bound applies when it is omitted or unsupported.
+	 */
+	timeoutMs?: number;
 }
 
 /**
@@ -138,5 +160,10 @@ export async function askHuman<T>(
 			// The preface is best-effort; the dialogs still run.
 		}
 	}
-	return options.dialogs();
+	const restore = options.timeoutMs === undefined ? undefined : channel?.setPromptTimeout?.(options.timeoutMs);
+	try {
+		return await options.dialogs();
+	} finally {
+		restore?.();
+	}
 }

package/lib/notice.ts

@@ -11,8 +11,10 @@
  *
  * `content` is what the model reads; `details` is never sent to the model and
  * is the renderer's whole input, so a producer states the facts once and the
- * renderer decides the look. Value-only: constants and pure functions, no
- * state.
+ * renderer decides the look. `burstText` is the one assembly of that content for
+ * a burst of pending outcomes, so a job completion, a watch match, and a bus
+ * message are laid out by the same code. Value-only: constants and pure
+ * functions, no state.
  */
 
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
@@ -68,6 +70,31 @@ export function noticeMessage(input: NoticeInput): NoticeMessage {
 	return { customType: NOTICE_TYPE, content: input.content, display: true, details: input.details };
 }
 
+/** The parts of one burst of pending outcomes, as the model reads them. */
+export interface BurstTextInput {
+	/** The marker embedded in the injected context, e.g. `[BACKGROUND JOBS]`. */
+	marker: string;
+	/** The counted headline without its colon, e.g. `2 background jobs finished`. */
+	headline: string;
+	/** One line per outcome, already formatted by the caller. */
+	lines: readonly string[];
+	/** A trailing count of the rows the caller left out, e.g. `… 3 more matches`. */
+	more?: string;
+	/** How to read the rest, e.g. 'Run `job logs <id>` for output.'. */
+	hint?: string;
+}
+
+/**
+ * The model-facing text of a burst: marker, counted headline, one line per
+ * outcome, and the caller's own tail. The joins and the colon live here so a
+ * `job` completion, a `watch` match, and a bus message read alike; the wording,
+ * the cap, and the hint stay with the extension that knows them.
+ */
+export function burstText(input: BurstTextInput): string {
+	const { marker, headline, lines, more, hint } = input;
+	return [marker, `${headline}:`, ...lines, ...(more ? [more] : []), ...(hint ? [hint] : [])].join("\n");
+}
+
 /** Whether a conversation message is a notice. */
 export function isNotice(message: AgentMessage): message is NoticeEntry {
 	return message.role === "custom" && (message as { customType?: string }).customType === NOTICE_TYPE;

package/lib/plan-entry.ts

@@ -25,8 +25,8 @@ export const PLAN_ENTER_REQUEST = "my-pi-agent/plan-mode/enter";
 /** One clause describing the read-only guarantee, reused across prompts. */
 export const READ_ONLY_SUMMARY =
 	"write and edit are disabled, bash is limited to read-only git commands, and other mutating tools are blocked; " +
-	"subagent delegation is forced read-only, and the only file write is write_plan (under .pi/plans, or the agent " +
-	"directory outside a repository)";
+	"subagent delegation is forced read-only, and the only file write is write_plan (a plan file in the agent " +
+	"directory)";
 
 /**
  * The consent question, as the user sees it. Shown by `enter_plan_mode` and by
@@ -36,6 +36,11 @@ export const PLAN_CONSENT =
 	`Plan mode is read-only exploration: ${READ_ONLY_SUMMARY}. ` +
 	"Enter plan mode to investigate and propose an approach before making changes?";
 
+/** The short remote consent; the full read-only summary stays in the tool docs. */
+export const PLAN_CONSENT_SHORT =
+	"Enter read-only plan mode? Writes and mutating tools are disabled until you approve a plan.";
+export const PLAN_CONSENT_SHORT_ZH = "进入只读 plan 模式？批准计划前会禁用写入和修改。";
+
 /** What a caller sends on {@link PLAN_ENTER_REQUEST}. */
 export interface PlanEnterRequest {
 	/** The caller's context; `plan` uses it for the footer status. */

package/lib/plans/sections.ts

@@ -0,0 +1,172 @@
+/**
+ * Plan-document sections (pure).
+ *
+ * One fence-aware scan of a plan's markdown, and one rewrite of a section in
+ * place. Two features need it: plan mode, whose review screen navigates by
+ * section and whose `set_plan_steps` rewrites `## Steps`, and the split, which
+ * writes and replaces `## Team` at approval. A second scanner would disagree
+ * about a heading inside a fence, so both go through this module.
+ *
+ * The scan is deliberately smaller than CommonMark: a heading is up to three
+ * leading spaces, a space after the hashes, and an optional closing run; a fence
+ * is three backticks or tildes anywhere a fence may start. Inside a fence
+ * nothing is a heading, which is what keeps a `# comment` in a shell example out
+ * of the outline. Every section keeps its raw source lines, so a caller can edit
+ * exactly what it read.
+ */
+
+/** A heading-delimited chunk of a plan, for navigation and in-place edits. */
+export interface PlanSection {
+	/** Plain heading text, or `""` for the content before the first heading. */
+	title: string;
+	/** The section's markdown, including its heading line. */
+	text: string;
+	/** 0-based source line of the section's heading (0 for the preamble). */
+	line: number;
+	/** Heading level, or 0 for the preamble before the first heading. */
+	level: number;
+}
+
+/**
+ * A markdown heading outside a fence, capturing its level and text: up to three
+ * leading spaces, a space after the hashes, and a closing hash run only when a
+ * space separates it. Shared with the block model, so the section split and the
+ * browser outline read a heading line the same way, and `## C#` keeps its title.
+ */
+export const HEADING = /^ {0,3}(#{1,6})\s+(.*?)(?:\s+#+)?\s*$/;
+
+/**
+ * A markdown code-fence opener or closer (backticks or tildes). Shared with the
+ * block model: a tab-indented fence is prose for both parsers, never code for one
+ * and prose for the other.
+ */
+export const FENCE = /^ {0,3}(`{3,}|~{3,})/;
+
+/**
+ * A heading or step label as the review surfaces compare it: inline emphasis and
+ * code removed, whitespace collapsed. Exported so a renderer labels an outline
+ * entry the same way {@link extractSections} labels its section, which is what
+ * lets the browser mark a changed section.
+ */
+export function normalizeHeadingText(text: string): string {
+	return text
+		.replace(/\*\*([^*]+)\*\*/g, "$1")
+		.replace(/\*([^*]+)\*/g, "$1")
+		.replace(/(?<![A-Za-z0-9_])_([^_]+)_(?![A-Za-z0-9_])/g, "$1")
+		.replace(/`([^`]+)`/g, "$1")
+		.replace(/\s+/g, " ")
+		.trim();
+}
+
+/**
+ * Sections of a plan, split at heading lines outside code fences. The content
+ * before the first heading is a section titled `""`. Pi's `Markdown` renderer
+ * exposes no source-line map, so the review screen renders these chunks
+ * separately to know where each section begins.
+ */
+export function extractSections(plan: string): PlanSection[] {
+	const sections: PlanSection[] = [];
+	let current: PlanSection | undefined;
+	let fence: string | undefined;
+
+	const flush = (): void => {
+		if (current && (current.title !== "" || current.text.trim() !== "")) sections.push(current);
+		current = undefined;
+	};
+
+	plan.split("\n").forEach((line, index) => {
+		const fenceMatch = line.match(FENCE);
+		if (fenceMatch) {
+			if (fence === undefined) fence = fenceMatch[1][0];
+			else if (fence === fenceMatch[1][0]) fence = undefined;
+		} else if (fence === undefined) {
+			const heading = line.match(HEADING);
+			if (heading) {
+				flush();
+				current = { title: normalizeHeadingText(heading[2]), text: line, line: index, level: heading[1].length };
+				return;
+			}
+		}
+		if (current === undefined) current = { title: "", text: line, line: 0, level: 0 };
+		else current.text += `\n${line}`;
+	});
+
+	flush();
+	return sections;
+}
+
+/**
+ * The index one past a section's last line: the next heading at its level or
+ * shallower, outside a fence, or the end of the document.
+ */
+function sectionEnd(lines: readonly string[], start: number): number {
+	const level = lines[start].match(HEADING)?.[1].length ?? 2;
+	let fence: string | undefined;
+	for (let index = start + 1; index < lines.length; index++) {
+		const line = lines[index];
+		const fenceMatch = line.match(FENCE);
+		if (fenceMatch) {
+			if (fence === undefined) fence = fenceMatch[1][0];
+			else if (fence === fenceMatch[1][0]) fence = undefined;
+			continue;
+		}
+		if (fence !== undefined) continue;
+		const heading = line.match(HEADING);
+		if (heading && heading[1].length <= level) return index;
+	}
+	return lines.length;
+}
+
+/**
+ * Replace a level-2 section's body, or remove the section, or append one.
+ *
+ * `body` is the section's markdown after its heading, without the heading line —
+ * the caller keeps the heading text so a refinement cannot rename the section
+ * that other code looks for. An empty `body` removes the whole section, which is
+ * how a team stops existing; a missing section with a body appends one, so the
+ * write is idempotent rather than order-dependent.
+ */
+export function replaceSection(plan: string, title: string, body: string | undefined): string {
+	const lines = plan.split("\n");
+	const wanted = normalizeHeadingText(title).toLowerCase();
+	const sections = extractSections(plan);
+	const found = sections.find(
+		(candidate) => candidate.level === 2 && normalizeHeadingText(candidate.title).toLowerCase() === wanted,
+	);
+
+	if (!found) {
+		if (body === undefined) return plan;
+		const prefix = plan.trim() === "" ? "" : `${plan.replace(/\s+$/, "")}\n\n`;
+		return `${prefix}## ${title}\n${body.replace(/\s+$/, "")}\n`;
+	}
+
+	const end = sectionEnd(lines, found.line);
+	const head = lines.slice(0, found.line);
+	const tail = lines.slice(end);
+	if (body === undefined) {
+		// Drop the blank line that separated the section from what follows, so a
+		// removed section leaves one gap rather than two.
+		const joined = [...head, ...tail];
+		return (
+			joined
+				.join("\n")
+				.replace(/\n{3,}/g, "\n\n")
+				.replace(/\s+$/, "") + (plan.endsWith("\n") ? "\n" : "")
+		);
+	}
+	const replacement = [`## ${title}`, "", ...body.replace(/\s+$/, "").split("\n")];
+	// Keep one blank line between the rewritten section and whatever followed it.
+	const gap = tail.length > 0 && tail[0].trim() !== "" ? [""] : [];
+	return [...head, ...replacement, ...gap, ...tail].join("\n");
+}
+
+/** The `## Team` section's body, without its heading or surrounding blank lines. */
+export function teamSectionBody(plan: string): string | undefined {
+	const lines = plan.split("\n");
+	const section = extractSections(plan).find(
+		(candidate) => candidate.level === 2 && normalizeHeadingText(candidate.title).toLowerCase() === "team",
+	);
+	if (!section) return undefined;
+	const body = lines.slice(section.line + 1, sectionEnd(lines, section.line)).join("\n");
+	return body.replace(/^(?:[ \t]*\n)+/, "").replace(/\s+$/, "");
+}

package/lib/plans/setting.ts

@@ -0,0 +1,52 @@
+/**
+ * The switch that turns the split on, and the words the user flips it with.
+ *
+ * It lives in `lib/` because three places must agree: the settings row that
+ * writes it, plan approval that reads it, and the bus that refuses a join while
+ * it is off. A second copy of the key would mean a panel row that changes
+ * nothing — the failure this module exists to prevent.
+ *
+ * Off by default: the split changes what approval means and adds work nobody
+ * asked for, so it ships closed and an existing user upgrades into the single
+ * flow they already know.
+ */
+
+import { asBoolean, configValueAt, loadConfigSection } from "../config.ts";
+
+/** The shared document's section and key that hold the switch. */
+export const SPLIT_SECTION = "plan";
+export const SPLIT_KEY = "split";
+export const SPLIT_DEFAULT = false;
+
+/** The settings-panel row, so a refusal can name what the user flips. */
+export const SPLIT_SETTING_ID = "plan.split";
+export const SPLIT_SETTING_LABEL = "Split plans into slices";
+
+/** The section's shape and its default, so a loader and its documentation agree. */
+export interface SplitConfig {
+	split: boolean;
+}
+
+export const DEFAULT_SPLIT_CONFIG: SplitConfig = { split: SPLIT_DEFAULT };
+
+/** Read the section over `base`, ignoring a value that is not a boolean. */
+export function normalizeSplitConfig(raw: Record<string, unknown> | undefined, base: SplitConfig): SplitConfig {
+	return { split: asBoolean(configValueAt(raw, [SPLIT_KEY]), base.split) };
+}
+
+/**
+ * Whether this repository (or the user's global config) has the split on.
+ *
+ * The project file is read at `root` when the caller knows it: a split belongs to
+ * the repository, so a session started in a subdirectory must honour what the
+ * repository turned on. Without a root the session's cwd is used, which is what a
+ * caller outside a repository has.
+ */
+export function splitEnabled(cwd: string, root?: string): boolean {
+	return loadConfigSection(root ?? cwd, SPLIT_SECTION, DEFAULT_SPLIT_CONFIG, normalizeSplitConfig).split;
+}
+
+/** The one line a refusal or a note uses to say the switch is off and where it lives. */
+export const SPLIT_OFF_NOTE =
+	`Parallel slices are off (${SPLIT_SETTING_ID}). ` +
+	`Enable "${SPLIT_SETTING_LABEL}" in /bytefly settings to split a plan.`;