@gavin-hu/my-pi-agent 0.12.0 → 0.13.0

package/lib/requirements.ts

@@ -15,7 +15,8 @@
  */
 
 import { join } from "node:path";
-import { type JsonReadResult, SHARED_CONFIG_FILE } from "./config.ts";
+import { configSection, configValueAt, type JsonReadResult, SHARED_CONFIG_FILE } from "./config.ts";
+import type { WebSearchProviderEvent } from "./events.ts";
 import { getPiInvocation, type PiInvocation } from "./pi-invocation.ts";
 
 /** How a check came out. Only `missing` is worth interrupting a session for. */
@@ -73,7 +74,51 @@ export interface NotifyCheck {
 	hint: string;
 }
 
-export type RequirementCheck = BinaryCheck | ModuleCheck | StateCheck | InvocationCheck | NotifyCheck;
+/**
+ * The resolved `web_search` provider, as `web-access` publishes it.
+ *
+ * The provider list, each provider's configuration test, and the `auto` rule live
+ * in `web-access`, so the check reads a published summary rather than rebuilding
+ * any of it here; the payload never carries the key itself.
+ */
+export interface ProviderCheck {
+	kind: "provider";
+	enables: string;
+	hint: string;
+}
+
+/**
+ * A config switch whose "off" value trades a safety net away.
+ *
+ * A prerequisite table can already say "this is missing"; this says "you turned
+ * this protection off", which is the other way an extension ends up degraded
+ * without anything being absent. The value is read from `bytefly.json` (global,
+ * then project, project wins), so the check needs no extension to publish
+ * anything — the switch is the whole fact.
+ */
+export interface SafetyCheck {
+	kind: "safety";
+	/** The `bytefly.json` section that owns the switch. */
+	section: string;
+	/** The key path inside that section. */
+	keyPath: readonly string[];
+	/** The value that means the net is off. */
+	off: boolean;
+	/** What the switch protects, for the passing case. */
+	enables: string;
+	/** What is true once it is off, for the degraded case. */
+	disabled: string;
+	hint: string;
+}
+
+export type RequirementCheck =
+	| BinaryCheck
+	| ModuleCheck
+	| StateCheck
+	| InvocationCheck
+	| NotifyCheck
+	| ProviderCheck
+	| SafetyCheck;
 
 /** What an extension needs, split by how badly it needs it. */
 export interface ExtensionRequirements {
@@ -138,7 +183,22 @@ function gitCheck(enables: string): BinaryCheck {
 export const REQUIREMENTS: Readonly<Record<string, ExtensionRequirements>> = {
 	worktree: {
 		requires: [gitCheck("worktree isolation")],
-		notes: ["`.worktreeinclude` symlinks need symlink support (Windows Developer Mode)."],
+		optional: [
+			{
+				kind: "safety",
+				section: "worktree",
+				keyPath: ["guard", "blockPowershell"],
+				off: false,
+				enables: "`powershell` is refused while the session is isolated",
+				disabled: "`powershell` runs unguarded, with its relative paths against the main checkout",
+				hint: "set `worktree.guard.blockPowershell` back to true, or use `bash`, which is re-rooted and guarded.",
+			},
+		],
+		notes: [
+			"`.worktreeinclude` symlinks need symlink support (Windows Developer Mode).",
+			"Your own `!` shell is not re-rooted or guarded; only the model's own tools are.",
+			"Commands whose git behavior cannot be verified pass through unless `worktree.guard.blockUnparsableCommands` is set.",
+		],
 	},
 	rewind: {
 		requires: [gitCheck("rewind snapshots")],
@@ -164,7 +224,7 @@ export const REQUIREMENTS: Readonly<Record<string, ExtensionRequirements>> = {
 	},
 	job: {
 		notes: [
-			"Windows: no POSIX `EXIT` trap, so a reattached job's status stays `unknown`.",
+			"Windows: a job cannot be detached (`detached: true` is refused and `job.detachedByDefault` is inert), and a job reported only after its process is gone stays `unknown` — there is no shell `EXIT` trap.",
 			"`ps` is used for the pid-reuse guard and is POSIX-only.",
 		],
 	},
@@ -175,7 +235,14 @@ export const REQUIREMENTS: Readonly<Record<string, ExtensionRequirements>> = {
 		],
 	},
 	"web-access": {
-		optional: [{ kind: "module", name: "unpdf", enables: "PDF text extraction in `web_fetch`", hint: pdfGuidance() }],
+		optional: [
+			{ kind: "module", name: "unpdf", enables: "PDF text extraction in `web_fetch`", hint: pdfGuidance() },
+			{
+				kind: "provider",
+				enables: "`web_search` through the configured provider",
+				hint: "set `web-access.search.provider` and its `endpoint`/`apiKeyEnv`/`apiKey` in bytefly.json, or export the key variable.",
+			},
+		],
 	},
 	"file-browse": {
 		optional: [gitCheck("the branch chip and the diff view")],
@@ -253,6 +320,14 @@ export interface ProbeSeams {
 	notify?: () => { enabled: boolean; method: string } | undefined;
 	/** Whether stdout is a terminal, which the OSC methods need; defaults to true. */
 	isTTY?: boolean;
+	/** The search provider `web-access` resolved for this session, when it published one. */
+	searchProvider?: () => WebSearchProviderEvent | undefined;
+	/** Read an environment variable; defaults to the process environment. */
+	env?: (name: string) => string | undefined;
+	/** Probe a URL's reachability; only called when `refresh` is true. */
+	reach?: (url: string) => Promise<{ ok: boolean; error?: string }>;
+	/** True when the caller asked for an explicit refresh, which is when a probe may touch the network. */
+	refresh?: boolean;
 }
 
 /**
@@ -292,13 +367,140 @@ async function probeCode(invocation: PiInvocation, seams: ProbeSeams): Promise<n
 	}
 }
 
+/**
+ * The findings for the `web_search` provider check.
+ *
+ * Up to three separate facts, because they have three different fixes: which
+ * provider is in use, whether its key variable is set, and — only on an explicit
+ * refresh — whether its configurable endpoint answers.
+ */
+async function providerFindings(
+	extension: string,
+	check: ProviderCheck,
+	failSeverity: FindingSeverity,
+	seams: ProbeSeams,
+): Promise<Finding[]> {
+	const facts = seams.searchProvider?.();
+	if (!facts) {
+		return [
+			{
+				extension,
+				check: "web-access.search.provider",
+				severity: "info",
+				detail: "web-access has not reported a search provider in this session",
+			},
+		];
+	}
+
+	const findings: Finding[] = [];
+	findings.push({
+		extension,
+		check: "web-access.search.provider",
+		severity: facts.configured ? "ok" : failSeverity,
+		detail: facts.configured
+			? `resolved to ${facts.provider} (${facts.reason})`
+			: `resolved to ${facts.provider} (${facts.reason}), which is not configured — ${check.enables}`,
+		...(!facts.configured ? { hint: check.hint } : {}),
+	});
+
+	const env = seams.env ?? ((name: string) => process.env[name]);
+	if (facts.apiKeyEnv && !facts.keyConfigured) {
+		const present = (env(facts.apiKeyEnv) ?? "").trim() !== "";
+		findings.push({
+			extension,
+			check: facts.apiKeyEnv,
+			severity: present ? "ok" : failSeverity,
+			detail: present
+				? `${facts.apiKeyEnv} is set — the ${facts.provider} API key`
+				: `the API key for ${facts.provider} is missing — ${facts.apiKeyEnv} is not set`,
+			...(present ? {} : { hint: `export ${facts.apiKeyEnv}, or set web-access.search.apiKey in bytefly.json.` }),
+		});
+	}
+
+	// Reachability is the one probe that touches the network, so it runs only when
+	// the caller asked for an explicit refresh.
+	if (seams.refresh === true && facts.endpoint !== null) {
+		const reach = seams.reach;
+		if (!reach) {
+			findings.push({
+				extension,
+				check: facts.endpoint,
+				severity: "info",
+				detail: "no reachability probe is available in this context",
+			});
+		} else {
+			const outcome = await reach(facts.endpoint).catch((error: unknown) => ({
+				ok: false,
+				error: error instanceof Error ? error.message : String(error),
+			}));
+			findings.push({
+				extension,
+				check: facts.endpoint,
+				severity: outcome.ok ? "ok" : failSeverity,
+				detail: outcome.ok
+					? `${facts.endpoint} answered`
+					: `${facts.endpoint} did not answer (${outcome.error ?? "no response"})`,
+				...(outcome.ok
+					? {}
+					: { hint: "check web-access.search.endpoint in bytefly.json, or that the SearXNG server is running." }),
+			});
+		}
+	}
+
+	return findings;
+}
+
+/**
+ * The effective value of one config leaf, global then project. An absent or
+ * unparseable document contributes nothing — the malformed-JSON check owns that
+ * case — so this returns `undefined` rather than a guess.
+ */
+function configLeaf(check: SafetyCheck, seams: ProbeSeams): { value: unknown; path: string } | undefined {
+	const candidates = [
+		join(seams.dirs.agentDir, SHARED_CONFIG_FILE),
+		join(seams.dirs.cwd, seams.dirs.configDirName, SHARED_CONFIG_FILE),
+	];
+	let found: { value: unknown; path: string } | undefined;
+	for (const path of candidates) {
+		const result = seams.readJson(path);
+		if (result.state !== "ok") continue;
+		const section = configSection(result.value, check.section);
+		const value = configValueAt(section, check.keyPath);
+		if (value !== undefined) found = { value, path };
+	}
+	return found;
+}
+
+/** The findings for a switch whose off value trades a safety net away. */
+function safetyFindings(
+	extension: string,
+	check: SafetyCheck,
+	failSeverity: FindingSeverity,
+	seams: ProbeSeams,
+): Finding[] {
+	const leaf = configLeaf(check, seams);
+	const label = [check.section, ...check.keyPath].join(".");
+	if (leaf?.value === check.off) {
+		return [
+			{
+				extension,
+				check: label,
+				severity: failSeverity,
+				detail: `is ${String(check.off)} in ${leaf.path} — ${check.disabled}`,
+				hint: check.hint,
+			},
+		];
+	}
+	return [{ extension, check: label, severity: "ok", detail: check.enables }];
+}
+
 /** Run one check. `failSeverity` comes from which list the check sits in. */
 async function runCheck(
 	extension: string,
 	check: RequirementCheck,
 	failSeverity: FindingSeverity,
 	seams: ProbeSeams,
-): Promise<Finding> {
+): Promise<Finding[]> {
 	switch (check.kind) {
 		case "binary": {
 			const invocation = check.invocation?.() ?? {
@@ -306,91 +508,109 @@ async function runCheck(
 				args: [...(check.probeArgs ?? ["--version"])],
 			};
 			const code = await probeCode(invocation, seams);
-			return code === 0
-				? { extension, check: check.name, severity: "ok", detail: check.enables }
-				: {
-						extension,
-						check: check.name,
-						severity: failSeverity,
-						detail: `not found on PATH — ${check.enables}`,
-						hint: check.hint,
-					};
+			return [
+				code === 0
+					? { extension, check: check.name, severity: "ok", detail: check.enables }
+					: {
+							extension,
+							check: check.name,
+							severity: failSeverity,
+							detail: `not found on PATH — ${check.enables}`,
+							hint: check.hint,
+						},
+			];
 		}
 		case "module": {
 			const load = seams.loadModule ?? defaultLoadModule;
 			try {
 				await load(check.name);
 			} catch {
-				return {
-					extension,
-					check: check.name,
-					severity: failSeverity,
-					detail: `not installed — ${check.enables}`,
-					hint: check.hint,
-				};
+				return [
+					{
+						extension,
+						check: check.name,
+						severity: failSeverity,
+						detail: `not installed — ${check.enables}`,
+						hint: check.hint,
+					},
+				];
 			}
-			return { extension, check: check.name, severity: "ok", detail: check.enables };
+			return [{ extension, check: check.name, severity: "ok", detail: check.enables }];
 		}
 		case "state": {
 			const path = join(scopeDir(check.scope, seams.dirs), check.file);
 			const result = seams.readJson(path);
-			if (result.state === "ok") return { extension, check: path, severity: "ok", detail: check.enables };
+			if (result.state === "ok") return [{ extension, check: path, severity: "ok", detail: check.enables }];
 			if (result.state === "absent") {
-				return {
+				return [
+					{
+						extension,
+						check: path,
+						severity: failSeverity,
+						detail: `missing — ${check.enables}`,
+						hint: check.hint,
+					},
+				];
+			}
+			return [
+				{
 					extension,
 					check: path,
 					severity: failSeverity,
-					detail: `missing — ${check.enables}`,
+					detail: `unreadable (${result.error}) — ${check.enables}`,
 					hint: check.hint,
-				};
-			}
-			return {
-				extension,
-				check: path,
-				severity: failSeverity,
-				detail: `unreadable (${result.error}) — ${check.enables}`,
-				hint: check.hint,
-			};
+				},
+			];
 		}
 		case "invocation": {
 			const invocation = seams.invocation?.() ?? getPiInvocation(["--version"]);
 			// Reusing the running interpreter cannot fail: the process is running.
 			const code = invocation.command === process.execPath ? 0 : await probeCode(invocation, seams);
-			return code === 0
-				? { extension, check: invocation.command, severity: "ok", detail: check.enables }
-				: {
-						extension,
-						check: invocation.command,
-						severity: failSeverity,
-						detail: `cannot be run — ${check.enables}`,
-						hint: check.hint,
-					};
+			return [
+				code === 0
+					? { extension, check: invocation.command, severity: "ok", detail: check.enables }
+					: {
+							extension,
+							check: invocation.command,
+							severity: failSeverity,
+							detail: `cannot be run — ${check.enables}`,
+							hint: check.hint,
+						},
+			];
 		}
 		case "notify": {
 			const notify = seams.notify?.();
 			if (!notify?.enabled) {
-				return { extension, check: "notify.method", severity: "ok", detail: "notifications are off" };
+				return [{ extension, check: "notify.method", severity: "ok", detail: "notifications are off" }];
 			}
 			const env = { platform: seams.platform, isTTY: seams.isTTY ?? true };
 			if (canDeliver(notify.method, env)) {
-				return {
+				return [
+					{
+						extension,
+						check: "notify.method",
+						severity: "ok",
+						detail:
+							notify.method === "auto"
+								? "auto picks a route from the environment"
+								: `"${notify.method}" delivers on ${seams.platform}`,
+					},
+				];
+			}
+			return [
+				{
 					extension,
 					check: "notify.method",
-					severity: "ok",
-					detail:
-						notify.method === "auto"
-							? "auto picks a route from the environment"
-							: `"${notify.method}" delivers on ${seams.platform}`,
-				};
-			}
-			return {
-				extension,
-				check: "notify.method",
-				severity: failSeverity,
-				detail: `"${notify.method}" cannot deliver on ${seams.platform} — ${check.enables}`,
-				hint: check.hint,
-			};
+					severity: failSeverity,
+					detail: `"${notify.method}" cannot deliver on ${seams.platform} — ${check.enables}`,
+					hint: check.hint,
+				},
+			];
 		}
+		case "provider":
+			return providerFindings(extension, check, failSeverity, seams);
+		case "safety":
+			return safetyFindings(extension, check, failSeverity, seams);
 	}
 }
 
@@ -461,8 +681,8 @@ export async function probeExtension(extension: string, seams: ProbeSeams): Prom
 	}
 
 	const findings: Finding[] = [];
-	for (const check of spec.requires ?? []) findings.push(await runCheck(extension, check, "missing", seams));
-	for (const check of spec.optional ?? []) findings.push(await runCheck(extension, check, "degraded", seams));
+	for (const check of spec.requires ?? []) findings.push(...(await runCheck(extension, check, "missing", seams)));
+	for (const check of spec.optional ?? []) findings.push(...(await runCheck(extension, check, "degraded", seams)));
 	findings.push(...configFindings(extension, spec, seams));
 	for (const note of spec.notes ?? []) {
 		findings.push({ extension, check: "platform", severity: "info", detail: note });

package/lib/tui/README.md

@@ -0,0 +1,91 @@
+# lib/tui — the shared terminal design system
+
+The primitives every interactive surface in this package draws with: rules,
+rows, columns, gauges, panes, glyphs, color roles, and the tool-transcript kit.
+The module-by-module inventory is the `tui/` row of [`../README.md`](../README.md);
+this file is the conventions those modules exist to make easy.
+
+Pi's [Terminal UI](https://github.com/earendil-works/pi/tree/main/packages/coding-agent/docs/tui.md)
+and [Themes](https://github.com/earendil-works/pi/tree/main/packages/coding-agent/docs/themes.md)
+docs are normative. Follow Pi's built-in design system and do not invent a
+private visual language; a surface that re-derives chrome, glyphs, or scroll math
+instead of importing it is the bug this directory exists to prevent.
+
+## Host before custom code
+
+Reach down the ladder in order and stop at the first rung that works:
+`ctx.ui.select` / `confirm` / `input` / `editor`, then `notify` / `setStatus` /
+`setWidget`, then the pi-tui components. Reach for `ctx.ui.custom()` or a
+tool/entry renderer only when a surface needs its own layout or input, and never
+build a second terminal renderer.
+
+## Block grammar
+
+- Match the built-in block grammar: one leading blank line per transcript block,
+  nothing trailing (the host owns spacing).
+- Frame screens with a plain `─` rule, not box corners.
+- Compact by default, expand for detail: label-first one-line widgets, with more
+  revealed on demand or on a dedicated screen.
+
+## Primitives
+
+Reach for a `lib/tui/` primitive before composing your own: `plainRule` /
+`titleRule` for a heading, `listRow` / `checkbox` for a list, `gaugeBar` for a
+meter, `emptyState` for an empty screen, `splitRow` / `fitCells` for two columns,
+`LinePane` for a scrollable log, and `ListCursor` / `IdCursor` for selection.
+
+## Color is a role
+
+Resolve colors through a [`tokens.ts`](./tokens.ts) role
+(`paint(theme, role, text)`), never a literal ANSI sequence, hex value, or Pi
+token named inline; a theme swap must re-skin every surface. Use the shared
+`selectionMarker`, `GLYPHS`, `SEPARATORS`, and `STATUS_KEYS` instead of retyping
+their literals, and `screenHint` / Pi's `keyHint` for the hint row.
+
+## Width is columns
+
+Width is terminal columns, not string length. Use `visibleWidth`,
+`truncateToWidth`, and `wrapTextWithAnsi`; every returned line must fit the
+width, and width arithmetic starts from `Math.max(1, width)`. Size from the live
+viewport — `titleRule`, `viewportRows`, `fitRows`, and `ListCursor`, fed by a
+`ViewportRowsSource` (number or getter) with a sensible fallback — so a resize is
+picked up. List screens stay docked; only the plan review uses
+`FULL_SCREEN_OVERLAY`.
+
+## Sanitize at the boundary
+
+Run model- or file-authored text through `sanitizeLine` before it reaches a
+widget or the terminal: it neutralizes control characters and then collapses the
+text to one line. `stripControlChars` alone is for multi-line text that must keep
+its newlines.
+
+## Keyboard first
+
+Use `matchesKey` / `Key`, give every mouse interaction a keyboard path, and keep
+the shared bindings: Esc closes, `j` / `k` and arrows scroll, `g` / `G` and
+Home/End jump.
+
+## Components are derived and cheap
+
+Implement `Component` with `invalidate()`, update an instance in place, read live
+state on each render, and call `requestRender()` only after state changes. Never
+hold themed strings in state unless `invalidate()` rebuilds them. A widget is
+derived from state, never authoritative.
+
+Pi renders the whole tree every frame, so a component that derives its lines from
+another one memoizes them with `RenderCache` (keyed on width and the source
+lines' identity) and drops the memo in `invalidate()`. Re-deriving every line per
+frame is what makes a long transcript feel slow.
+
+## Focus
+
+Reserve the name `focused` for a real focus `get` / `set` pair. Pi's `setFocus`
+duck-types a focusable with `"focused" in component` and then assigns a boolean
+there, so any other member of that name — a method, say — is silently shadowed
+and the first call throws at runtime.
+
+## Tests
+
+A module here gets a sibling `<module>.test.ts` covering fields, width bounds,
+ordering, and glyphs — never literal column padding. An extension's screen test
+is the `tui.test.ts` beside its `tui.ts`.

package/lib/tui/glyphs.ts

@@ -30,6 +30,7 @@ export const GLYPHS = {
 	jobsFailure: "✗",
 	stopped: "⊘",
 	browse: "◉",
+	delegation: "↳",
 	wechat: "✆",
 	gaugeFull: "▰",
 	gaugeEmpty: "▱",

package/lib/web/layout.ts

@@ -14,15 +14,25 @@
  *
  * The shell is a definite full-height column so the panes scroll inside it; the
  * 860px breakpoint drops that back to normal page scroll for narrow screens.
+ *
+ * The sidebar scrolls on its own box rather than on the `.bf-panel` it holds:
+ * a `<details>` lays its content out in a block wrapper with no definite
+ * height that takes no part in the element's flex layout, so a flex child there
+ * keeps its content height and the sidebar would only clip it. A page that
+ * needs pinned chrome above its own scroll pane (file-browse) fills that
+ * wrapper absolutely and scrolls an inner region instead.
  */
 
+/** Viewport width, in px, at and below which the sidebar becomes a disclosure. */
+export const SIDEBAR_COLLAPSE_MAX = 860;
+
 export const WEB_LAYOUT_CSS = `.bf-app{display:flex;flex-direction:column;height:100vh;min-height:0;overflow:hidden;background:var(--canvas);color:var(--text);font:var(--fs-base)/var(--lh-normal) var(--font-ui)}
 .bf-app__header{position:sticky;top:0;z-index:2;flex:0 0 auto;background:var(--surface);border-bottom:1px solid var(--border)}
 .bf-app__body{flex:1 1 auto;min-height:0;display:grid;grid-template-columns:260px minmax(0,1fr)}
-.bf-app__sidebar{display:flex;flex-direction:column;min-width:0;min-height:0;overflow:hidden;background:var(--surface);border-right:1px solid var(--border)}
+.bf-app__sidebar{display:flex;flex-direction:column;min-width:0;min-height:0;overflow-x:hidden;overflow-y:auto;background:var(--surface);border-right:1px solid var(--border)}
 .bf-app__main{min-width:0;min-height:0;display:flex;flex-direction:column;overflow:auto;padding:var(--space-5) var(--space-6)}
 .bf-app__footer{flex:0 0 auto;border-top:1px solid var(--border);color:var(--muted);font-size:var(--fs-sm);padding:var(--space-3) var(--space-6)}
-@media (max-width:860px){
+@media (max-width:${SIDEBAR_COLLAPSE_MAX}px){
 .bf-app{height:auto;min-height:100vh;overflow:visible}
 .bf-app__body{flex:none;grid-template-columns:1fr}
 .bf-app__sidebar{display:block;position:static;max-height:none;overflow:visible;border-right:0;border-bottom:1px solid var(--border)}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gavin-hu/my-pi-agent",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Personal Pi customizations, packaged as a Pi package: worktree isolation and rewind snapshots, question, todo, goal, plan, subagent, job, watch, web-access, file-browse, file-open, document, memory, wechat, and bytefly.",
   "keywords": [
     "pi-package",
@@ -59,14 +59,14 @@
     "url": "https://github.com/gavin-hu/my-pi-agent.git"
   },
   "files": [
-    "assets/**",
     "extensions/**",
     "lib/**",
     "themes/**",
     "!**/*.test.ts"
   ],
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": true
   },
   "pi": {
     "extensions": [
@@ -103,6 +103,8 @@
     "check:serial": "bun run format:check && bun run typecheck && bun run test:serial",
     "release:notes": "bun run scripts/release-notes.ts",
     "config:migrate": "bun run scripts/migrate-config.ts",
+    "compat:versions": "bun run scripts/peer-versions.ts",
+    "bench:render": "bun run scripts/render-bench.ts",
     "screenshot:plan": "bun run scripts/plan-review-shot.ts",
     "screenshot:tools": "bun run scripts/tool-renderings.ts gallery assets/tool-renderings.png",
     "screenshot:tool-pngs": "bun run scripts/tool-renderings.ts tools assets/tools",

package/themes/bytefly-dark.json

@@ -9,7 +9,7 @@
     "borderMuted": "#5a626b",
     "text": "#c9d1d9",
     "muted": "#8b949e",
-    "dim": "#6e7681",
+    "dim": "#7d8590",
     "blue": "#58a6ff",
     "green": "#3fb950",
     "red": "#f85149",