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

package/extensions/wechat/status-screen.ts

@@ -24,7 +24,7 @@ import { peerLabel } from "./format.ts";
 import type { BotCredentials } from "./types.ts";
 
 /** User-facing connection word; the internal `BridgeState` stays running/stopped. */
-export type StatusConnection = "open" | "expired" | "closed";
+export type StatusConnection = "open" | "expired" | "paused" | "closed";
 
 /**
  * What the status screen closed with: a global action, a peer history request,
@@ -69,7 +69,7 @@ const MAX_PEER_ROWS = 5;
 
 /** The connection word for a bridge status, or `closed` when there is none. */
 export function connectionOf(status: BridgeStatus | undefined): StatusConnection {
-	return status?.open ? "open" : status?.expired ? "expired" : "closed";
+	return status?.paused ? "paused" : status?.open ? "open" : status?.expired ? "expired" : "closed";
 }
 
 /** Build the view from the stored account and the live bridge status. */
@@ -146,6 +146,8 @@ function connectionText(connection: StatusConnection): string {
 			return "open";
 		case "expired":
 			return "expired";
+		case "paused":
+			return "paused";
 		case "closed":
 			return "closed";
 	}
@@ -158,6 +160,8 @@ function connectionRole(connection: StatusConnection): TuiRole {
 			return "ok";
 		case "expired":
 			return "bad";
+		case "paused":
+			return "warn";
 		case "closed":
 			return "meta";
 	}
@@ -193,6 +197,9 @@ export function statusBody(view: StatusView, theme: Theme, width: number, select
 	if (view.connection === "expired") {
 		lines.push("");
 		lines.push(clip(`  ${paint(theme, "bad", "Session expired — press l to log in again.")}`, target));
+	} else if (view.connection === "paused") {
+		lines.push("");
+		lines.push(clip(`  ${paint(theme, "warn", "Paused — press p to resume polling.")}`, target));
 	} else if (view.connection === "closed" && view.account) {
 		lines.push("");
 		lines.push(clip(`  ${paint(theme, "meta", "Not connected — press l to log in again.")}`, target));
@@ -251,6 +258,8 @@ export interface StatusActions {
 	reset(peer: string): string;
 	/** Withdraw the waiting prompt; returns the line to flash. */
 	cancelPrompt(): string;
+	/** Pause or resume polling; async because it settles the poll loop first. */
+	togglePause(): string | Promise<string>;
 }
 
 export interface StatusScreenOptions {
@@ -325,6 +334,27 @@ export class StatusScreenComponent implements Component {
 			this.setFlash(undefined);
 			return;
 		}
+		if (data === "p" || data === "P") {
+			if (!view.bridge) {
+				this.setFlash("WeChat is not running.");
+				return;
+			}
+			const outcome = this.options.actions?.togglePause();
+			if (!outcome) {
+				this.setFlash("Pause is unavailable here.");
+				return;
+			}
+			if (typeof outcome === "string") {
+				this.setFlash(outcome);
+				return;
+			}
+			this.setFlash(view.connection === "paused" ? "Resuming…" : "Pausing…");
+			void outcome.then(
+				(line) => this.setFlash(line),
+				() => this.setFlash("Pause action failed."),
+			);
+			return;
+		}
 		if (data === "a" || data === "A") {
 			this.options.onClose({ kind: "allow" });
 			return;

package/extensions/wechat/tools.ts

@@ -68,8 +68,6 @@ export function registerTools(pi: ExtensionAPI, deps: ToolDeps): void {
 		],
 		parameters: WechatSendParams,
 		outputSchema: WechatSendResult,
-		exposure: "direct",
-		defaultActive: true,
 		annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
 		executionMode: "sequential",
 

package/lib/README.md

@@ -16,7 +16,7 @@ belongs in that extension instead — see `extensions/web-access/http.ts` and
 | Module | Responsibility |
 |---|---|
 | [`browser.ts`](./browser.ts) | Cross-platform default-browser opener shared by `file-browse` and `plan`: pure `browserCommand(url, platform)` plus best-effort `openInBrowser(url, { platform, spawn })` with an injectable spawn. |
-| [`config.ts`](./config.ts) | Config loading, two ways: `loadConfigFile` for a whole file, and the shared `bytefly.json` (`SHARED_CONFIG_FILE`) via `configSection` / `loadConfigSection` (global, then project), plus the atomic `writeConfigFile` / `writeConfigSection`. Includes `clampInteger` / `clampNumber` / `cleanString` / `asRecord` / `readJson` / `readJsonResult`. |
+| [`config.ts`](./config.ts) | Config loading, two ways: `loadConfigFile` for a whole file, and the shared `bytefly.json` (`SHARED_CONFIG_FILE`) via `configSection` / `configValueAt` / `loadConfigSection` (global, then project), plus the atomic `writeConfigFile` / `writeConfigSection` / `writeConfigValue` / `writeConfigValueAt` (the last two edit one leaf, flat or nested, preserving siblings and metadata). Includes `clampInteger` / `clampNumber` / `cleanString` / `asRecord` / `readJson` / `readJsonResult`. |
 | [`env.ts`](./env.ts) | Env-var contracts shared across extensions: the worktree environment (`ENV_ROOT`, `worktreeRoot`, `resolveEffectiveCwd`) used by worktree, file-browse, job, and rewind, plus `isExtensionEnabled` / `ENV_DISABLED_EXTENSIONS` for the package-wide disable list. |
 | [`escape.ts`](./escape.ts) | `escapeHtml`: the single HTML text/attribute escape used by the browse page renderers and the Markdown and syntax highlighters. |
 | [`events.ts`](./events.ts) | Inter-extension `pi.events` channels and payloads: `JOB_FINISHED_CHANNEL` and `JobFinishedEvent`, published by `job` and consumed by bytefly's notify capability. |
@@ -32,6 +32,7 @@ belongs in that extension instead — see `extensions/web-access/http.ts` and
 | [`rails.ts`](./rails.ts) | Above-editor widget ordering (`goal` → `todo`) and dock-screen suppression, carried on `pi.events`. |
 | [`requirements.ts`](./requirements.ts) | Per-extension runtime prerequisite table plus a pure `probeExtension(seams)` over injected seams (exec, config reads, optional imports): bytefly's doctor surface reports on it and the extensions that own a dependency format their errors from it. |
 | [`shell.ts`](./shell.ts) | Shell escape rule shared by the worktree isolation guard and plan mode's read-only git guard: `SHELL_ESCAPABLE`, `isShellEscapable`, `hasShellEscape`. |
+| [`todo-state.ts`](./todo-state.ts) | The published `todo` state replayed from the session branch: `ExistingTodo` and `lastTodos(entries)` (the last valid list, skipping a rejected call), so `plan` can merge an approved plan's steps into it and `goal` can name the items still open when a goal is marked achieved — with no extension importing another's modules. |
 | [`tool-names.ts`](./tool-names.ts) | Tool names and one parameter name that more than one extension must agree on, so an orchestrating `ctx.executeTool()` call or schema probe breaks the build on a rename. |
 | [`web/`](./web/) | The Bytefly web brand system shared by the browser surfaces: [`web/tokens.ts`](./web/tokens.ts) (palette derived from the Bytefly terminal themes, scales, and the `tok-*` map), [`web/base.ts`](./web/base.ts), [`web/components.ts`](./web/components.ts), [`web/layout.ts`](./web/layout.ts), [`web/runtime.ts`](./web/runtime.ts) (`WEB_THEME_STORAGE_KEY`, `THEME_JS`, `THEME_TOGGLE_JS`), [`web/markup.ts`](./web/markup.ts), and the [`web/index.ts`](./web/index.ts) barrel. |
 

package/lib/config.ts

@@ -139,6 +139,22 @@ export function configSection(
 	return asRecord(raw?.[key]);
 }
 
+/**
+ * The value at `path` in a document or section, or `undefined` when a step is
+ * absent or not an object. A one-element path reads a top-level key, so this
+ * also answers "is this setting stated here" for the flat case. `raw` may be an
+ * untrusted JSON value or an already-normalized config object.
+ */
+export function configValueAt(raw: unknown, path: readonly string[]): unknown {
+	let current: unknown = raw;
+	for (const key of path) {
+		const record = asRecord(current);
+		if (!record) return undefined;
+		current = record[key];
+	}
+	return current;
+}
+
 /** Options for {@link loadConfigSection}. */
 export interface SectionOptions {
 	/** Agent directory override; `worktree` resolves it explicitly. */
@@ -197,12 +213,38 @@ function readEditableDocument(path: string): Record<string, unknown> {
  * malformed document.
  */
 export function writeConfigValue(path: string, section: string, key: string, value: unknown): void {
+	writeConfigValueAt(path, section, [key], value);
+}
+
+/**
+ * Set the leaf at `keyPath` in one top-level section, with the same guarantees
+ * as {@link writeConfigValue}: siblings, other sections, and metadata survive,
+ * and the file and the section are created when absent. Intermediate objects
+ * are created as needed; a non-object in the way is replaced, because a refused
+ * edit would leave a hand-written typo unfixable from the screen. Refuses a
+ * malformed document and an empty path.
+ */
+export function writeConfigValueAt(path: string, section: string, keyPath: readonly string[], value: unknown): void {
+	if (keyPath.length === 0) throw new Error(`Cannot update ${path}: empty key path`);
 	const document = readEditableDocument(path);
 	const current = configSection(document, section) ?? {};
-	document[section] = { ...current, [key]: value };
+	document[section] = setPath(current, keyPath, value);
 	writeConfigFile(path, document);
 }
 
+/** Copy `source` with the leaf at `path` replaced; every sibling key is kept. */
+function setPath(source: Record<string, unknown>, path: readonly string[], value: unknown): Record<string, unknown> {
+	const [head] = path;
+	const next = { ...source };
+	if (head === undefined) return next;
+	if (path.length === 1) {
+		next[head] = value;
+		return next;
+	}
+	next[head] = setPath(asRecord(source[head]) ?? {}, path.slice(1), value);
+	return next;
+}
+
 /**
  * Delete one key from one top-level section, preserving its siblings and the
  * rest of the document. An emptied section is removed rather than left as `{}`.

package/lib/env.ts

@@ -16,6 +16,9 @@ export const ENV_ROOT = "PI_WORKTREE_ROOT";
  */
 export const ENV_DISABLED_EXTENSIONS = "PI_DISABLED_EXTENSIONS";
 
+/** Env var that turns off Pi's automatic network activity, including our own. */
+export const ENV_OFFLINE = "PI_OFFLINE";
+
 /** False when `name` appears in `PI_DISABLED_EXTENSIONS`, true otherwise. */
 export function isExtensionEnabled(name: string): boolean {
 	const raw = process.env[ENV_DISABLED_EXTENSIONS];
@@ -29,6 +32,15 @@ export function isExtensionEnabled(name: string): boolean {
 	return !disabled.has(name.toLowerCase());
 }
 
+/**
+ * Whether `PI_OFFLINE` is on, read the way Pi reads it: `1`, `true`, or `yes`
+ * (case-insensitive). Any other value, including empty, is off.
+ */
+export function isOffline(): boolean {
+	const raw = process.env[ENV_OFFLINE]?.trim().toLowerCase();
+	return raw === "1" || raw === "true" || raw === "yes";
+}
+
 /** The active worktree root from the environment, when set and still on disk. */
 export function worktreeRoot(): string | undefined {
 	const root = process.env[ENV_ROOT];

package/lib/requirements.ts

@@ -61,7 +61,19 @@ export interface InvocationCheck {
 	hint: string;
 }
 
-export type RequirementCheck = BinaryCheck | ModuleCheck | StateCheck | InvocationCheck;
+/**
+ * The notification delivery bytefly is configured for.
+ *
+ * The configured method belongs to the notify capability, so it arrives through
+ * {@link ProbeSeams.notify}; whether this host can honour it is decided here.
+ */
+export interface NotifyCheck {
+	kind: "notify";
+	enables: string;
+	hint: string;
+}
+
+export type RequirementCheck = BinaryCheck | ModuleCheck | StateCheck | InvocationCheck | NotifyCheck;
 
 /** What an extension needs, split by how badly it needs it. */
 export interface ExtensionRequirements {
@@ -173,7 +185,8 @@ export const REQUIREMENTS: Readonly<Record<string, ExtensionRequirements>> = {
 	"file-open": {
 		notes: [
 			"The `/open` command and its notification need an interactive UI; the `open_path` tool works without one.",
-			"Launching the OS handler is best-effort: a failure is reported, and the tool result still names the target.",
+			"Launching the OS handler is best-effort: a launcher that fails to start, or exits non-zero on macOS and Linux, is reported; Windows `explorer` can exit non-zero after a successful open.",
+			"The tool result names the target even when the launch fails.",
 		],
 	},
 	memory: {
@@ -193,6 +206,13 @@ export const REQUIREMENTS: Readonly<Record<string, ExtensionRequirements>> = {
 	},
 	bytefly: {
 		configFiles: [SHARED_CONFIG_FILE],
+		optional: [
+			{
+				kind: "notify",
+				enables: "the configured notification delivery",
+				hint: 'set "notify.method" to "auto" in bytefly.json, or choose one this host can deliver.',
+			},
+		],
 		notes: [
 			"TUI only for the header, footer, and turn rule; `/bytefly` prints a listing and `/bytefly doctor` the report in RPC, JSON, and print modes.",
 			"The panel writes extension enablement through Pi's own settings; project scope requires a trusted project.",
@@ -229,6 +249,35 @@ export interface ProbeSeams {
 	loadModule?: (name: string) => Promise<unknown>;
 	/** Resolve the nested-pi command; defaults to {@link getPiInvocation}. */
 	invocation?: () => PiInvocation;
+	/** The notify capability's configured delivery, or absent when it is not in play. */
+	notify?: () => { enabled: boolean; method: string } | undefined;
+	/** Whether stdout is a terminal, which the OSC methods need; defaults to true. */
+	isTTY?: boolean;
+}
+
+/**
+ * Whether `method` can deliver on this host.
+ *
+ * `auto` inspects the environment itself, so it always can; the OSC methods need
+ * a terminal to write to; the rest are platform-specific. An unknown id counts
+ * as deliverable because bytefly's own loader already rejects one.
+ */
+export function canDeliver(method: string, env: { platform: NodeJS.Platform; isTTY: boolean }): boolean {
+	switch (method) {
+		case "auto":
+			return true;
+		case "osc777":
+		case "osc99":
+			return env.isTTY;
+		case "toast":
+			return env.platform === "win32";
+		case "osascript":
+			return env.platform === "darwin";
+		case "notify-send":
+			return env.platform === "linux";
+		default:
+			return true;
+	}
 }
 
 const defaultLoadModule = (name: string): Promise<unknown> => import(name);
@@ -317,6 +366,31 @@ async function runCheck(
 						hint: check.hint,
 					};
 		}
+		case "notify": {
+			const notify = seams.notify?.();
+			if (!notify?.enabled) {
+				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 {
+					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,
+			};
+		}
 	}
 }
 

package/lib/todo-state.ts

@@ -0,0 +1,62 @@
+/**
+ * The published `todo` state, read back from the session branch (pure).
+ *
+ * The todo list is a whole-list replacement stored in each `todo` tool result's
+ * `details`, so replaying the branch is how another extension reads it without
+ * importing the todo extension. `plan` merges an approved plan's steps into the
+ * last list, and `goal` mentions the items still open when a goal is marked
+ * achieved.
+ */
+
+import { TODO_TOOL } from "./tool-names.ts";
+
+/** One item in a `todo` list, as the todo tool stores it. */
+export interface ExistingTodo {
+	content: string;
+	status: "pending" | "in_progress" | "completed";
+	/** Present-continuous label the todo tool requires for an in-progress item. */
+	activeForm?: string;
+}
+
+/** Minimal shape of a session entry, used for runtime narrowing. */
+interface BranchEntryLike {
+	type?: string;
+	message?: {
+		role?: string;
+		toolName?: string;
+		details?: unknown;
+	};
+}
+
+function isStatus(value: unknown): value is ExistingTodo["status"] {
+	return value === "pending" || value === "in_progress" || value === "completed";
+}
+
+/**
+ * The last valid todo list written on the branch, or an empty list. A rejected
+ * call carries the unchanged list and is not a state write, so it is skipped;
+ * an entry that does not re-validate is ignored rather than wiping a good list.
+ */
+export function lastTodos(entries: Iterable<unknown>): ExistingTodo[] {
+	let todos: ExistingTodo[] = [];
+	for (const raw of entries) {
+		const entry = raw as BranchEntryLike;
+		if (entry?.type !== "message") continue;
+		const message = entry.message;
+		if (message?.role !== "toolResult" || message.toolName !== TODO_TOOL) continue;
+		const details = message.details as { todos?: unknown; error?: unknown } | undefined;
+		if (!details || details.error) continue;
+		if (!Array.isArray(details.todos)) continue;
+		todos = details.todos.flatMap((item): ExistingTodo[] => {
+			if (typeof item !== "object" || item === null) return [];
+			const value = item as { content?: unknown; status?: unknown; activeForm?: unknown };
+			if (typeof value.content !== "string" || !isStatus(value.status)) return [];
+			const content = value.content.trim();
+			if (!content) return [];
+			const activeForm =
+				typeof value.activeForm === "string" && value.activeForm.trim() ? value.activeForm.trim() : undefined;
+			return [activeForm ? { content, status: value.status, activeForm } : { content, status: value.status }];
+		});
+	}
+	return todos;
+}

package/lib/tui/glyphs.ts

@@ -48,6 +48,7 @@ export const GLYPHS = {
 	boxOff: "◻",
 	prev: "‹",
 	next: "›",
+	update: "↑",
 	prompt: "❯",
 } as const;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gavin-hu/my-pi-agent",
-  "version": "0.11.3",
+  "version": "0.12.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",