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

package/extensions/todo/nudge.ts

@@ -18,12 +18,15 @@ import { TODO_TOOL } from "../../lib/tool-names.ts";
 import { currentTodo, hasOpenTodos } from "./state.ts";
 import type { Todo } from "./types.ts";
 
+/** Tools that run a command, where reading and writing look the same by name. */
+const SHELL_TOOL_NAMES: ReadonlySet<string> = new Set(["bash", "powershell"]);
+
 /**
  * Tools whose calls mean the working tree may have changed: the built-in
- * writers and shells. Kept explicit so a reader or an MCP tool that does not
+ * writers and the shells. Kept explicit so a reader or an MCP tool that does not
  * declare a hint cannot force a continuation.
  */
-export const MUTATING_TOOL_NAMES: ReadonlySet<string> = new Set(["write", "edit", "bash", "powershell"]);
+export const MUTATING_TOOL_NAMES: ReadonlySet<string> = new Set(["write", "edit", ...SHELL_TOOL_NAMES]);
 
 /**
  * Whether a finished tool call counts as work for lag detection. The `todo`
@@ -37,22 +40,68 @@ export function isMutatingTool(toolName: string, annotations?: ToolAnnotations):
 }
 
 /**
- * Whether a reminder is due: work happened since the last update, no reminder
- * was sent for it yet, and the list still has an unfinished item.
+ * Whether a finished tool call can have changed files, as opposed to a shell
+ * command that may only have read them. The reminder for a run that never
+ * started a list needs this: three `rg` calls are investigation, not unplanned
+ * work, and a shell call cannot be told apart from one that wrote. So it is a
+ * mutating call that is not a shell.
+ */
+export function isFileWrite(toolName: string, annotations?: ToolAnnotations): boolean {
+	if (toolName === TODO_TOOL || SHELL_TOOL_NAMES.has(toolName)) return false;
+	return isMutatingTool(toolName, annotations);
+}
+
+/**
+ * Successful mutating calls needed before a run with no list at all is worth a
+ * reminder. A plan that was never started has no item to fall behind, and a
+ * false positive costs a whole extra model request, so one edit is not enough
+ * evidence that the work needed a list.
+ */
+export const EMPTY_LIST_MUTATIONS = 3;
+
+/** What the current turn knows about its work and the list. */
+export interface NudgeState {
+	/** Successful mutating calls since the turn began or the list was last written. */
+	mutations: number;
+	/** How many of those can change files, as opposed to a shell command that may have read. */
+	writes: number;
+	/** Whether the model wrote or cleared the list since the turn began. */
+	touched: boolean;
+	/** Whether a reminder was already sent this turn. */
+	nudged: boolean;
+	/** The current list. */
+	todos: Todo[];
+}
+
+/**
+ * Whether a reminder is due. With an unfinished item, one mutation is enough.
+ * With no list at all, the turn must also have written something: repeated
+ * inspection with no file change is not unplanned work. A list the model wrote
+ * or cleared this turn is its own answer, so an explicit clear is never
+ * second-guessed.
  */
-export function shouldNudge(dirty: boolean, nudged: boolean, todos: Todo[]): boolean {
-	return dirty && !nudged && hasOpenTodos(todos);
+export function shouldNudge({ mutations, writes, touched, nudged, todos }: NudgeState): boolean {
+	if (nudged || mutations <= 0) return false;
+	if (hasOpenTodos(todos)) return true;
+	return todos.length === 0 && !touched && writes > 0 && mutations >= EMPTY_LIST_MUTATIONS;
 }
 
 /** Marker on the injected reminder, so it is recognizable and filterable. */
 export const TODO_NUDGE_MARKER = "[TODO SYNC]";
 
 /**
- * Model-facing reminder injected before settlement. Points at the item the list
- * currently considers active, so the model can correct it without rereading the
- * whole list.
+ * Model-facing reminder injected before settlement. For a list with unfinished
+ * work it points at the item the list currently considers active, so the model
+ * can correct it without rereading the whole list; for no list at all it asks
+ * for one.
  */
 export function formatNudge(todos: Todo[]): string {
+	if (todos.length === 0) {
+		return (
+			`${TODO_NUDGE_MARKER} Work happened but no todo list was recorded. ` +
+			"Call the todo tool with the steps of this work, then continue."
+		);
+	}
 	const current = currentTodo(todos);
 	const item = current ? (current.activeForm ?? current.content) : undefined;
 	const pointer = item ? ` The list still points at "${item}".` : "";

package/extensions/todo/runtime.ts

@@ -4,10 +4,10 @@
  *
  * The list is reconstructed from the active branch on session start and tree
  * navigation, and the persistent widget mirrors it whenever it changes. Only
- * interactive (`tui`) sessions get a widget; the widget's row budget and
- * whether a finished list stays visible come from the todo config. The same
- * runtime carries the lag-tracking flags the `agent_before_settle` reminder
- * reads, so they reset with the session and the branch.
+ * interactive (`tui`) sessions get a widget; whether a finished list stays
+ * visible comes from the todo config. The same runtime carries the lag-tracking
+ * counters the `agent_before_settle` reminder reads, so they reset with the
+ * session and the branch.
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
@@ -27,8 +27,8 @@ export interface TodoRuntime {
 	reconstruct(ctx: ExtensionContext): void;
 	/** Apply the widget config (loaded per session). */
 	setConfig(config: TodoConfig): void;
-	/** Record that a mutating tool ran since the last update. */
-	noteWork(): void;
+	/** Record a successful mutating call; `fileWrite` marks one that can change files. */
+	noteWork(fileWrite?: boolean): void;
 	/** Whether a lag reminder is due and has not been sent for it yet. */
 	nudgeDue(): boolean;
 	/** Mark the current lag as reminded, activating the injected reminder. */
@@ -53,11 +53,15 @@ export function createTodoRuntime(pi?: Pick<ExtensionAPI, "events">): TodoRuntim
 	let lastTuiCtx: ExtensionContext | undefined;
 	// True while a dock screen owns the editor slot; the rail stays hidden.
 	let suppressed = false;
-	// Lag tracking: `dirty` is set when a mutating tool runs and cleared by a
-	// todo update, `nudged` caps the reminder to one per user turn, and
-	// `nudgeActive` marks an injected reminder as current so `context` keeps it
-	// for the continuation and drops it on the next user turn.
-	let dirty = false;
+	// Lag tracking: `mutations` counts successful mutating calls since the list
+	// was last written and `writes` how many of those can change files,
+	// `touched` records that the model wrote or cleared the list this turn (so an
+	// explicit clear is not second-guessed), `nudged` caps the reminder to one per
+	// user turn, and `nudgeActive` marks an injected reminder as current so
+	// `context` keeps it for the continuation and drops it on the next user turn.
+	let mutations = 0;
+	let writes = 0;
+	let touched = false;
 	let nudged = false;
 	let nudgeActive = false;
 	// Screens watching the list (for example the open `/todos` screen) so they
@@ -104,13 +108,17 @@ export function createTodoRuntime(pi?: Pick<ExtensionAPI, "events">): TodoRuntim
 			todos = next;
 			// A todo update is the model syncing the list, so the lag is cleared.
 			// `nudged` is not: the reminder stays capped at one per user turn.
-			dirty = false;
+			mutations = 0;
+			writes = 0;
+			touched = true;
 			syncWidget(ctx);
 			notify();
 		},
 		reconstruct: (ctx) => {
 			todos = reconstructTodos(ctx.sessionManager.getBranch());
-			dirty = false;
+			mutations = 0;
+			writes = 0;
+			touched = false;
 			nudged = false;
 			nudgeActive = false;
 			syncWidget(ctx);
@@ -119,10 +127,11 @@ export function createTodoRuntime(pi?: Pick<ExtensionAPI, "events">): TodoRuntim
 		setConfig: (next) => {
 			config = next;
 		},
-		noteWork: () => {
-			dirty = true;
+		noteWork: (fileWrite = false) => {
+			mutations++;
+			if (fileWrite) writes++;
 		},
-		nudgeDue: () => shouldNudge(dirty, nudged, todos),
+		nudgeDue: () => shouldNudge({ mutations, writes, touched, nudged, todos }),
 		markNudged: () => {
 			nudged = true;
 			nudgeActive = true;
@@ -132,7 +141,9 @@ export function createTodoRuntime(pi?: Pick<ExtensionAPI, "events">): TodoRuntim
 		},
 		isNudgeActive: () => nudgeActive,
 		resetNudge: () => {
-			dirty = false;
+			mutations = 0;
+			writes = 0;
+			touched = false;
 			nudged = false;
 		},
 		onChange: (listener) => {

package/extensions/web-access/README.md

@@ -96,7 +96,7 @@ and unknown keys are ignored.
 {
   "search": {
     "provider": "auto",                                    // "auto" | "duckduckgo" | "searxng" | "brave"
-    "endpoint": "http://localhost:8080",                   // SearXNG base URL; "" means SearXNG is unavailable
+    "endpoint": "",                                        // SearXNG base URL, e.g. "http://localhost:8080"; "" means SearXNG is unavailable
     "language": "auto",                                     // SearXNG: "auto" (zh-CN for Han, else en) | language code
     "safeSearch": 0,                                        // SearXNG: 0 off, 1 moderate, 2 strict
     "categories": "general",                                // SearXNG categories
@@ -264,9 +264,9 @@ the content type and size.
 
 | Integration point | Value |
 |---|---|
-| Tools | `web_search`, `web_fetch`; `exposure: "direct"`, both `defaultActive: true` |
+| Tools | `web_search`, `web_fetch`; direct exposure, active on registration (the defaults, so not declared) |
 | Execution mode | `web_search`: `sequential`; `web_fetch`: default |
-| Annotations | both `readOnlyHint: true`, `openWorldHint: true`, `destructiveHint: false` |
+| Annotations | both `readOnlyHint: true`, `openWorldHint: true`; a read-only tool declares no `destructiveHint` |
 | Output | `outputSchema` (`WebSearchOutput` / `WebFetchOutput`) plus matching `structuredContent` |
 | State | none in the session branch; one fetch page cache per registration (`web_search` keeps a per-instance throttle) |
 | Lifecycle | the factory only registers (`index.ts`); `registerFetchTool` owns the page cache and clears it on `session_start` and idempotent `session_shutdown` |

package/extensions/web-access/fetch/tool.ts

@@ -191,9 +191,7 @@ export function registerFetchTool(pi: ExtensionAPI, deps: FetchToolDeps = {}): v
 		],
 		parameters: WebFetchParams,
 		outputSchema: WebFetchOutput,
-		exposure: "direct",
-		defaultActive: true,
-		annotations: { readOnlyHint: true, openWorldHint: true, destructiveHint: false },
+		annotations: { readOnlyHint: true, openWorldHint: true },
 		// The page cache is shared in-memory state created per registration, so
 		// sibling calls must not run concurrently (matches web_search's throttle).
 		executionMode: "sequential",

package/extensions/web-access/search/tool.ts

@@ -46,9 +46,7 @@ export function registerSearchTool(pi: ExtensionAPI, deps: SearchDeps = {}): voi
 		],
 		parameters: WebSearchParams,
 		outputSchema: WebSearchOutput,
-		exposure: "direct",
-		defaultActive: true,
-		annotations: { readOnlyHint: true, openWorldHint: true, destructiveHint: false },
+		annotations: { readOnlyHint: true, openWorldHint: true },
 		executionMode: "sequential",
 
 		async execute(_toolCallId, params, signal, onUpdate, ctx) {

package/extensions/wechat/README.md

@@ -272,7 +272,7 @@ overridden by the project `<cwd>/.pi/bytefly.json` (project wins):
   "maxInboundChars": 8000, // inbound text longer than this is truncated
   "typingIndicator": true,   // show typing while a turn is generated
   "remotePrompts": true,     // answer interactive dialogs on WeChat during a WeChat turn
-  "pollHoldMs": 0            // experimental: ask the server for a shorter long-poll hold
+  // "pollHoldMs": 3000      // experimental: request a shorter long-poll hold; unset by default
 }
 ```
 
@@ -392,8 +392,9 @@ never touches the stored cursor.
   supplies a `context_token` only then).
 - Slash commands are fixed built-ins; there is no user-defined snippet or action
   list yet, and `/new`, `/stop`, `/status`, and `/help` are registered.
-- There is no pause. The bridge runs whenever an account is stored, and
-  `/wechat logout` is the only way to stop it (and it discards the credentials).
+- Pause is runtime-local. `/wechat pause` stops polling and releases the lock,
+  but a reload, `/new`, or restart builds a fresh running bridge; only
+  `/wechat logout` stops it persistently (and discards the credentials).
 
 ## Non-goals
 
@@ -406,7 +407,7 @@ sessions are in-process).
 | Integration point | Detail |
 |---|---|
 | Command | `pi.registerCommand("wechat", …)` — `login`, `new`, `status`, `pause`, `resume`, `doctor`, `stop <peer>`, `reset <peer>`, `history <peer> [n]`, `allow [peer]`, `logout`, `help`; bare `/wechat` opens the control screen. |
-| Tools | `send_wechat` — owner-only proactive text; registered at factory time with `exposure: "direct"`, `executionMode: "sequential"`, `openWorldHint: true`. |
+| Tools | `send_wechat` — owner-only proactive text; registered at factory time with direct exposure (the default), `executionMode: "sequential"`, `openWorldHint: true`. |
 | Events | `session_start` (record the live context, auto-start the bridge when an account exists); `session_shutdown` (idempotent stop). No host run events: peer turns are not the host session's runs. |
 | Sessions | `openPeerSession` creates one SDK `AgentSession` per peer (`createAgentSession`, `SessionManager.continueRecent` under `<agent-dir>/wechat/sessions/<peer>/`), inheriting the host's model and thinking level. `DefaultResourceLoader` standard discovery minus this bridge (`withoutWechatExtensions`), so a peer session cannot start a second poller, plus a short channel contract appended to the system prompt so the model knows it is answering in a phone chat window. When `peers[<id>].tools` is set, only those names stay active. |
 | Turn ownership | `peer-worker.ts`: a serial queue per peer, `session.prompt()`/`session.abort()`, `getLastAssistantText()` for the answer, and one idle sweep per session. `concurrency` defaults to 1 so a forwarded dialog has one owner. |

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.4",
+  "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",