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

package/extensions/bytefly/picker/runtime.ts

@@ -7,8 +7,15 @@
  * reads `items()` on every render, so it stays a derived view of this state.
  */
 
-import { getPackageResourcePattern, getResourcePattern } from "./resources.ts";
-import { nextGlobalPackages, nextProjectPackages, nextProjectTopLevelList, nextTopLevelList } from "./toggle.ts";
+import { getDisplayName, getPackageResourcePattern, getResourcePattern } from "./resources.ts";
+import {
+	clearProjectPackages,
+	clearProjectTopLevelList,
+	nextGlobalPackages,
+	nextProjectPackages,
+	nextProjectTopLevelList,
+	nextTopLevelList,
+} from "./toggle.ts";
 import type { Discovery, ResourceItem, SettingsStore, WriteScope } from "./types.ts";
 
 export interface RuntimeDeps {
@@ -26,6 +33,8 @@ export interface ExtensionsPickerRuntime {
 	projectAvailable(): boolean;
 	isDirty(): boolean;
 	toggle(item: ResourceItem): Promise<void>;
+	/** Drop `item`'s project override in Project scope; a no-op when it has none. */
+	clearOverride(item: ResourceItem): Promise<void>;
 	onChange(listener: () => void): () => void;
 }
 
@@ -34,6 +43,11 @@ function storeFor(discovery: Discovery, scope: WriteScope): SettingsStore {
 	return scope === "global" ? discovery.stores.global : discovery.stores.project;
 }
 
+/** Whether two rows name the same resource, for an inherited-state lookup. */
+function sameResource(left: ResourceItem, right: ResourceItem): boolean {
+	return left.metadata.source === right.metadata.source && left.path === right.path;
+}
+
 export function createExtensionsPickerRuntime(deps: RuntimeDeps): ExtensionsPickerRuntime {
 	const { discovery, cwd, agentDir } = deps;
 	let scope: WriteScope = "global";
@@ -72,6 +86,27 @@ export function createExtensionsPickerRuntime(deps: RuntimeDeps): ExtensionsPick
 		store.setProjectPackages(nextProjectPackages(store.packages(), item, enabled, cwd, agentDir));
 	};
 
+	/**
+	 * Drop `item`'s project override, reporting whether anything was written. An
+	 * absent override returns `false` without touching the store, so a stray key
+	 * press cannot dirty the file.
+	 */
+	const clearFromStore = (item: ResourceItem): boolean => {
+		const store = storeFor(discovery, "project");
+		if (item.metadata.origin === "top-level") {
+			const paths = store.projectSettings().extensions ?? [];
+			const next = clearProjectTopLevelList(paths, item, cwd, agentDir);
+			if (next === paths) return false;
+			store.setProjectExtensionPaths(next);
+			return true;
+		}
+		const packages = store.packages();
+		const next = clearProjectPackages(packages, item, cwd, agentDir);
+		if (next === packages) return false;
+		store.setProjectPackages(next);
+		return true;
+	};
+
 	return {
 		scope: () => scope,
 		setScope: (next) => {
@@ -100,6 +135,30 @@ export function createExtensionsPickerRuntime(deps: RuntimeDeps): ExtensionsPick
 			dirty = true;
 			emit();
 		},
+		clearOverride: async (item) => {
+			if (scope !== "project") {
+				deps.onError?.("Overrides are cleared in Project scope; switch with Tab.");
+				return;
+			}
+			const store = storeFor(discovery, "project");
+			try {
+				if (!clearFromStore(item)) {
+					deps.onError?.(`No project override for ${getDisplayName(item)}.`);
+					return;
+				}
+				await store.flush();
+				for (const error of store.drainErrors()) deps.onError?.(error.error.message);
+			} catch (error) {
+				deps.onError?.(error instanceof Error ? error.message : String(error));
+				return;
+			}
+			// With the override gone the row shows the inherited state again; a
+			// project-only resource has no global twin and keeps its value.
+			const inherited = views.global.find((entry) => sameResource(entry, item));
+			if (inherited) item.enabled = inherited.enabled;
+			dirty = true;
+			emit();
+		},
 		onChange: (listener) => {
 			listeners.add(listener);
 			return () => listeners.delete(listener);

package/extensions/bytefly/picker/toggle.ts

@@ -143,3 +143,59 @@ export function nextProjectPackages(
 	}
 	return updated;
 }
+
+/**
+ * Remove the project top-level override a toggle wrote for `item`.
+ *
+ * Drops the `+`/`-` entry for the item's target patterns, and the bare path
+ * entry {@link nextProjectTopLevelList} adds beside it for an inherited personal
+ * resource. Returns `current` unchanged — the same array — when no override is
+ * present, so a caller can tell "nothing to clear" without comparing contents.
+ */
+export function clearProjectTopLevelList(
+	current: string[],
+	item: ResourceItem,
+	cwd: string,
+	agentDir: string,
+): string[] {
+	const inherited = getItemScope(item) === "user";
+	const pattern = inherited ? item.path : getResourcePatternForScope(item, "project", cwd, agentDir);
+	const patterns = getTopLevelOverridePatterns(item, "project", cwd, agentDir);
+	const isOverride = (entry: string): boolean =>
+		(entry.startsWith("!") || entry.startsWith("+") || entry.startsWith("-")) &&
+		patterns.has(getPatternEntryTarget(entry));
+	if (!current.some(isOverride)) return current;
+	return current.filter((entry) => !isOverride(entry) && !(inherited && entry === pattern));
+}
+
+/**
+ * Remove the project package filter a toggle wrote for `item`.
+ *
+ * An entry the toggle created with `autoload: false` is dropped once it holds no
+ * filters, and one that predates the toggle collapses back to its plain source,
+ * mirroring {@link nextProjectPackages}. Returns `packages` unchanged — the same
+ * array — when the item has no project filter.
+ */
+export function clearProjectPackages(
+	packages: PackageSource[],
+	item: ResourceItem,
+	cwd: string,
+	agentDir: string,
+): PackageSource[] {
+	const index = packages.findIndex((entry) =>
+		packageSourceMatches(item, typeof entry === "string" ? entry : entry.source, "project", cwd, agentDir),
+	);
+	const entry = index === -1 ? undefined : packages[index];
+	if (entry === undefined || typeof entry === "string") return packages;
+
+	const pattern = getPackageResourcePattern(item);
+	const filters = entry.extensions ?? [];
+	if (!filters.some((filter) => getPatternEntryTarget(filter) === pattern)) return packages;
+
+	const updated = [...packages];
+	const remaining = filters.filter((filter) => getPatternEntryTarget(filter) !== pattern);
+	if (remaining.length > 0) updated[index] = { ...entry, extensions: remaining };
+	else if (entry.autoload === false) updated.splice(index, 1);
+	else updated[index] = entry.source;
+	return updated;
+}

package/extensions/bytefly/update/check.ts

@@ -0,0 +1,59 @@
+/**
+ * The one registry read the update check makes.
+ *
+ * A fixed, unauthenticated GET of the published `latest` document for this
+ * package. It is deliberately not `web-access`'s page runner: there are no
+ * redirects to follow, no HTML to extract, and no cache shared with a tool, and
+ * extensions may not import one another. Every failure mode — a non-ok status, a
+ * body that is not JSON, a payload without a real version, a network error, an
+ * abort — resolves to `undefined`, so the caller has one branch and the session
+ * never sees an error from a check nobody asked for.
+ */
+
+import { parseVersion } from "./version.ts";
+
+/** The published document holding the version npm's `latest` tag points at. */
+export const LATEST_VERSION_URL = "https://registry.npmjs.org/@gavin-hu%2Fmy-pi-agent/latest";
+
+/** How long the request may take before it is abandoned. */
+export const UPDATE_TIMEOUT_MS = 5_000;
+
+/** The subset of a `fetch` response this check reads. */
+export interface LatestResponse {
+	readonly ok: boolean;
+	json(): Promise<unknown>;
+}
+
+/** The fetch seam: narrow enough that a test needs no real response object. */
+export type FetchLike = (
+	url: string,
+	init: { signal: AbortSignal; headers: Record<string, string> },
+) => Promise<LatestResponse>;
+
+export interface UpdateCheckDeps {
+	/** Replace the network call; defaults to the platform `fetch`. */
+	fetch?: FetchLike;
+	/** Override {@link UPDATE_TIMEOUT_MS}. */
+	timeoutMs?: number;
+}
+
+/** The latest published version, or `undefined` when it cannot be read. */
+export async function fetchLatestVersion(deps: UpdateCheckDeps = {}): Promise<string | undefined> {
+	const request: FetchLike = deps.fetch ?? ((url, init) => globalThis.fetch(url, init));
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), deps.timeoutMs ?? UPDATE_TIMEOUT_MS);
+	try {
+		const response = await request(LATEST_VERSION_URL, {
+			signal: controller.signal,
+			headers: { accept: "application/json" },
+		});
+		if (!response.ok) return undefined;
+		const body = (await response.json()) as { version?: unknown } | undefined;
+		const version = typeof body?.version === "string" ? body.version.trim() : "";
+		return parseVersion(version) ? version : undefined;
+	} catch {
+		return undefined;
+	} finally {
+		clearTimeout(timer);
+	}
+}

package/extensions/bytefly/update/format.ts

@@ -0,0 +1,32 @@
+/**
+ * Wording for the update check: the header marker and the one transcript notice.
+ *
+ * Both read the same two facts — the version this session loaded and the version
+ * the registry publishes — and neither adds a third. The marker is the shortest
+ * honest form (`↑0.12.0`), and the notice names the command instead of printing
+ * a changelog link the notice renderer cannot open.
+ */
+
+import { noticeMessage, type NoticeMessage } from "../../../lib/notice.ts";
+import { GLYPHS } from "../../../lib/tui/glyphs.ts";
+
+/** The header marker: an up arrow and the newest version, e.g. `↑0.12.0`. */
+export function updateMarker(latest: string): string {
+	return `${GLYPHS.update}${latest}`;
+}
+
+/** The single notice a session posts when a newer version is published. */
+export function updateNotice(current: string, latest: string): NoticeMessage {
+	return noticeMessage({
+		content: `bytefly ${latest} is available (current ${current}). Run \`pi update --extensions\` to update.`,
+		details: {
+			source: "bytefly",
+			title: `${latest} is available`,
+			severity: "info",
+			items: [
+				{ label: "current", detail: `v${current}` },
+				{ label: "update", detail: "pi update --extensions" },
+			],
+		},
+	});
+}

package/extensions/bytefly/update/register.ts

@@ -0,0 +1,72 @@
+/**
+ * The update check's lifecycle: read the published version once per interactive
+ * session, record it when it is newer, and announce it once per load.
+ *
+ * The request is fired without awaiting. Pi awaits `session_start` handlers, so
+ * a slow registry would otherwise hold the first prompt; Pi's own version check
+ * is asynchronous for the same reason. Every result that is not a strictly newer
+ * version is silent, and a generation counter keeps a request that resolves
+ * after shutdown from writing into the next session's state.
+ *
+ * `/bytefly` and `doctor` do not report this: an available update is not a
+ * prerequisite problem, and the header plus one notice are the whole surface.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import pkg from "../../../package.json";
+import { isOffline } from "../../../lib/env.ts";
+import { fetchLatestVersion } from "./check.ts";
+import { updateNotice } from "./format.ts";
+import type { UpdateSource } from "./state.ts";
+import { isNewerVersion } from "./version.ts";
+
+/** Test seams; production uses the registry read and `PI_OFFLINE`. */
+export interface UpdateDeps {
+	/** Replace the registry read; a rejection counts as no answer. */
+	fetchLatest?: () => Promise<string | undefined>;
+	/** Replace the `PI_OFFLINE` check. */
+	isOffline?: () => boolean;
+	/** Called once a newer version is recorded, so a mounted surface repaints. */
+	onUpdate?: () => void;
+}
+
+/**
+ * Register the check. `updates` is the same store the header reads, so recording
+ * a version and calling `onUpdate` is what puts the marker on screen.
+ */
+export function registerUpdate(pi: ExtensionAPI, updates: UpdateSource, deps: UpdateDeps = {}): void {
+	const readLatest = deps.fetchLatest ?? (() => fetchLatestVersion());
+	const offline = deps.isOffline ?? isOffline;
+	// A session is announced at most once per load, even if `session_start` fires
+	// again after a resume or a session replacement.
+	let announced = false;
+	let generation = 0;
+
+	const check = async (token: number): Promise<void> => {
+		try {
+			const latest = await readLatest();
+			if (latest === undefined || token !== generation) return;
+			if (announced || !isNewerVersion(latest, pkg.version)) return;
+			announced = true;
+			updates.set(latest);
+			deps.onUpdate?.();
+			pi.sendMessage(updateNotice(pkg.version, latest));
+		} catch {
+			// A background check never surfaces an error: the session does not know it ran.
+		}
+	};
+
+	pi.on("session_start", (_event, ctx) => {
+		// The marker lives in bytefly's header and the notice in a transcript, so a
+		// non-interactive run has nothing to draw and makes no request.
+		if (ctx.mode !== "tui") return;
+		if (announced || offline()) return;
+		void check(generation);
+	});
+
+	pi.on("session_shutdown", () => {
+		// Invalidate any request still in flight and drop what this session found.
+		generation++;
+		updates.set();
+	});
+}

package/extensions/bytefly/update/state.ts

@@ -0,0 +1,28 @@
+/**
+ * Where a surface reads the newest published version this load found.
+ *
+ * The check resolves after the session started, so the header cannot be handed
+ * the value up front: it reads through this store on every apply, and the
+ * update registration re-installs the header once the value arrives. The store
+ * is created once per load by the composition root — no module state — and
+ * cleared on shutdown, so a reload starts from nothing.
+ */
+
+/** The store the header reads and the update lifecycle writes. */
+export interface UpdateSource {
+	/** The newer published version, or `undefined` when none is known. */
+	latest(): string | undefined;
+	/** Record a version, or clear it with no argument. */
+	set(latest?: string): void;
+}
+
+/** A store holding at most one version. */
+export function createUpdateState(): UpdateSource {
+	let latest: string | undefined;
+	return {
+		latest: () => latest,
+		set(next) {
+			latest = next || undefined;
+		},
+	};
+}

package/extensions/bytefly/update/version.ts

@@ -0,0 +1,83 @@
+/**
+ * Version comparison for the update check.
+ *
+ * The registry answers with whatever string the published manifest carries, so
+ * both sides of the comparison are untrusted input: a payload that does not
+ * parse is never an upgrade. Only the parts that decide ordering are read — the
+ * numeric core and the prerelease identifiers — and build metadata is ignored,
+ * as semver says it must be for precedence.
+ */
+
+/** A version split into the parts that decide precedence. */
+export interface ParsedVersion {
+	/** Major, minor, and patch; a missing segment is 0. */
+	readonly core: readonly [number, number, number];
+	/** Prerelease identifiers, empty for a release version. */
+	readonly pre: readonly string[];
+}
+
+/** `[v]X[.Y[.Z]][-pre][+build]`, with no leading zeros left to interpretation. */
+const VERSION_SHAPE = /^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+
+/** Whether a prerelease identifier is a dot-separated, non-empty semver identifier run. */
+function isPrerelease(value: string): boolean {
+	return value.split(".").every((identifier) => identifier.length > 0 && /^[0-9A-Za-z-]+$/.test(identifier));
+}
+
+/** Parse a version string, or `undefined` when it is not one. */
+export function parseVersion(value: string): ParsedVersion | undefined {
+	const match = VERSION_SHAPE.exec(value.trim());
+	if (!match) return undefined;
+	const prerelease = match[4];
+	if (prerelease !== undefined && !isPrerelease(prerelease)) return undefined;
+	return {
+		core: [Number(match[1]), Number(match[2] ?? 0), Number(match[3] ?? 0)],
+		pre: prerelease === undefined ? [] : prerelease.split("."),
+	};
+}
+
+/** `a`'s precedence relative to `b`: negative, zero, or positive. */
+function compareCore(a: ParsedVersion, b: ParsedVersion): number {
+	for (const index of [0, 1, 2] as const) {
+		const difference = a.core[index] - b.core[index];
+		if (difference !== 0) return difference;
+	}
+	return 0;
+}
+
+/**
+ * Prerelease precedence, per semver: identifiers are compared left to right,
+ * numeric ones numerically and below alphanumeric ones, a longer set wins over
+ * its own prefix, and any prerelease sits below the release it leads to.
+ */
+function comparePre(a: ParsedVersion, b: ParsedVersion): number {
+	if (a.pre.length === 0 || b.pre.length === 0) {
+		return b.pre.length - a.pre.length;
+	}
+	for (let index = 0; index < Math.max(a.pre.length, b.pre.length); index++) {
+		const left = a.pre[index];
+		const right = b.pre[index];
+		if (left === undefined) return -1;
+		if (right === undefined) return 1;
+		const leftNumeric = /^\d+$/.test(left);
+		const rightNumeric = /^\d+$/.test(right);
+		if (leftNumeric && rightNumeric) {
+			const difference = Number(left) - Number(right);
+			if (difference !== 0) return difference;
+			continue;
+		}
+		if (leftNumeric) return -1;
+		if (rightNumeric) return 1;
+		if (left !== right) return left < right ? -1 : 1;
+	}
+	return 0;
+}
+
+/** Whether `candidate` is a strictly newer version than `current`; false when either does not parse. */
+export function isNewerVersion(candidate: string, current: string): boolean {
+	const next = parseVersion(candidate);
+	const loaded = parseVersion(current);
+	if (!next || !loaded) return false;
+	const core = compareCore(next, loaded);
+	return core !== 0 ? core > 0 : comparePre(next, loaded) > 0;
+}

package/extensions/document/README.md

@@ -44,7 +44,7 @@ them along. Then ask the model to read a document, or call the tool directly:
 
 ## Tool
 
-`read_doc` — `exposure: "direct"`, active by default, read-only, closed-world
+`read_doc` — direct exposure, active by default, read-only, closed-world
 (no network).
 
 | Parameter | Type | Meaning |
@@ -226,7 +226,7 @@ config defaults, and error listing all derive from it.
 | Aspect | Contract |
 |---|---|
 | Registration | `document(pi)` in `index.ts` calls `registerDocTool(pi)`, which registers `read_doc`. The factory only registers; no parser loads until a read needs it. |
-| Tool | `read_doc`, `exposure: "direct"`, `defaultActive: true`, default (`parallel`) execution, `annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }`, TypeBox `parameters` and `outputSchema`, and `renderCall`/`renderResult` (reuse `context.lastComponent`; read `context.cwd` and `context.isError`). |
+| Tool | `read_doc`, direct exposure and active on registration (the defaults), default (`parallel`) execution, `annotations: { readOnlyHint: true, openWorldHint: false }`, TypeBox `parameters` and `outputSchema`, and `renderCall`/`renderResult` (reuse `context.lastComponent`; read `context.cwd` and `context.isError`). |
 | State | None persisted. Per-result state lives in the tool-result `details` / `structuredContent`; the renderer reads only that. |
 | Lifecycle | No `session_start` / `session_shutdown` hooks: each read imports a parser, runs it, and holds no long-lived resources. |
 | Host seams | `resolveEffectiveCwd` (`lib/env.ts`), `isInsideReal` / `realPathOfNearest` (`lib/path.ts`), `loadConfigSection` (`lib/config.ts`), `stripControlChars` / `sanitize` / `formatTokens` (`lib/format.ts`), `SEPARATORS` (`lib/tui/glyphs.ts`). |

package/extensions/document/tool.ts

@@ -79,9 +79,7 @@ export function registerDocTool(pi: ExtensionAPI, deps: DocToolDeps = {}): void
 		],
 		parameters: DocParams,
 		outputSchema: DocOutput,
-		exposure: "direct",
-		defaultActive: true,
-		annotations: { readOnlyHint: true, openWorldHint: false, destructiveHint: false },
+		annotations: { readOnlyHint: true, openWorldHint: false },
 
 		async execute(_toolCallId, params, signal, onUpdate, ctx) {
 			const args = params as DocArgs;

package/extensions/file-open/README.md

@@ -28,12 +28,14 @@ pi install ./                               # install the package for a user
 ## What it does
 
 - Opens a file or directory with the OS-native application: `open` on macOS,
-  `cmd /c start` on Windows, `xdg-open` on Linux.
+  `explorer` on Windows, `xdg-open` on Linux.
 - Reveals it in the file manager instead with `-r` (or `reveal: true`): `open -R`
   on macOS, `explorer /select,` on Windows, and the containing directory on
   Linux, which has no "select" verb.
 - Unwraps the editor's `@` file-mention prefix and surrounding quotes, so
   `/open @src/app.ts` and `/open @"my file.txt"` both work.
+- Reports a launcher that cannot be started, and (on macOS and Linux) a launcher
+  that exits non-zero because no handler accepted the target.
 - Resolves relative paths against the effective working directory, so under the
   `worktree` extension `/open .` opens the isolated worktree.
 - Launches the handler detached, so it outlives the Pi session.
@@ -47,14 +49,17 @@ pi install ./                               # install the package for a user
 
 The `-r` flag must come first. A missing path is reported through a notification
 and nothing is launched. An empty argument means the working directory. The
-command needs an interactive terminal UI.
+command first reports `Opening <path>` (or `Revealing <path>`); a launcher that
+starts but then fails adds a `Could not open` error notification. The command
+needs an interactive terminal UI.
 
 ## Tool
 
 `open_path` — `exposure: "codemode"`, inactive by default, not read-only,
-open-world (`openWorldHint: true` because it starts an OS process). It is
-listed by the `codemode` tool and reachable through `ctx.executeTool`; it is not
-declared to the model unless activated.
+open-world (`openWorldHint: true` because it starts an OS process). It is listed
+by the `codemode` tool for a script to call as `tools.open_path(...)`, and an
+extension can reach it through `ctx.executeTool`; it is not declared to the
+model unless activated.
 
 | Parameter | Type | Meaning |
 |---|---|---|
@@ -68,10 +73,11 @@ Result (`details` / `structuredContent`):
 | `target` | The absolute path that was handled. |
 | `reveal` | Whether it was revealed rather than opened. |
 
-The model-facing `content` is `Opened <target>` or `Revealed <target>`. A path
-that does not exist is thrown as an error naming the resolved path; a launch
-failure is reported through `ctx.ui.notify` because the handler runs detached,
-and the tool result still names the target.
+The model-facing `content` is `Opened <target>` or `Revealed <target>` — the
+handler was started, not proof that it succeeded. A path that does not exist is
+thrown as an error naming the resolved path; a launcher that cannot be started,
+or (on macOS and Linux) exits non-zero, is reported through `ctx.ui.notify`
+because the handler runs detached, and the tool result still names the target.
 
 ## Behaviour by mode
 
@@ -94,12 +100,18 @@ JSON, and print modes; a codemode script can call it in any of them. Only the
 - **Not confined.** Unlike `read_doc`, the tool opens any path on the machine:
   confinement would defeat its purpose of showing the user a file wherever it
   lives. Relative paths resolve against the effective worktree root.
-- **Best-effort launch.** A missing handler or a refused launch is reported, not
-  retried.
+- **Best-effort launch.** A launcher that cannot be started is reported, and so
+  is a non-zero exit on macOS and Linux, where `open` and `xdg-open` return a
+  failure status when no handler accepts the target. Windows `explorer` can exit
+  non-zero after a successful open, so only a failure to start is reported
+  there. Nothing is retried.
 
 ## Limitations
 
 - Reveal has no native meaning on Linux, so it opens the containing directory.
+- On Windows a refused target is not reported: `explorer` does not relay the
+  failure and its exit status is unreliable, so `/open` and `open_path` can only
+  report that the launcher started.
 - A launch that the OS accepts but the user never sees (a backgrounded app, a
   hidden window) is not detected: `spawn` reports only that the process started.
 - `-r` is parsed only as the first token of `/open`, so a path that genuinely
@@ -115,7 +127,7 @@ JSON, and print modes; a codemode script can call it in any of them. Only the
 | Command | `/open [path]` and `/open -r [path]`; reports through `ctx.ui.notify`. |
 | State | None persisted, and none needed: every call is independent. |
 | Lifecycle | No `session_start` / `session_shutdown` hooks; the factory holds no long-lived resources. |
-| Host seams | `resolveEffectiveCwd` and `isExtensionEnabled` (`lib/env.ts`), `stripControlChars` (`lib/format.ts`), `spawn` / `open` / `xdg-open` / `cmd` / `explorer` (via the injected launcher in `open.ts`). |
+| Host seams | `resolveEffectiveCwd` and `isExtensionEnabled` (`lib/env.ts`), `stripControlChars` (`lib/format.ts`), `spawn` / `open` / `xdg-open` / `explorer` (via the injected launcher in `open.ts`). |
 | Config | None. |
 
 ## Design notes
@@ -123,8 +135,11 @@ JSON, and print modes; a codemode script can call it in any of them. Only the
 `buildCommand` and `normalizeTarget` are pure and `openTarget` takes an injected
 launcher, so the command for each platform is asserted without a process and a
 test launches nothing. The launch is best-effort: `spawn` reports a missing
-handler asynchronously, so the failure goes to `onError` (and a notification)
-rather than being thrown from a synchronous call the tool could catch.
+launcher asynchronously and the child reports its exit, so both failures go to
+`onError` (and a notification) rather than being thrown from a synchronous call
+the tool could catch. `exitMeansFailure` opts Windows out because `explorer` can
+exit non-zero after a successful open. Windows opens through `explorer` rather
+than `cmd /c start` so cmd cannot re-parse a path containing `%`.
 
 The tool is `codemode`-exposed, matching how it was configured before the move:
 opening a native app is a side effect the user should trigger, so it stays out
@@ -135,7 +150,7 @@ of the model's active tool set unless a script explicitly reaches for it.
 | Module | Responsibility |
 |---|---|
 | `index.ts` | The extension factory: registers `open_path` and the `/open` command, resolves the target, and routes a launch failure to `ctx.ui.notify`. |
-| `open.ts` | `normalizeTarget` and `buildCommand` (pure), `resolveTarget` (existence check), and `openTarget` with the injectable launcher. |
+| `open.ts` | `normalizeTarget` and `buildCommand` (pure), `resolveTarget` (existence check), and `openTarget` with the injectable launcher, which reports a start failure and a meaningful non-zero exit. |
 | `schema.ts` | `TOOL_NAME`, the TypeBox `parameters` / `outputSchema`, and the `OpenPathArgs` / `OpenPathResult` types. |
 | `open.test.ts` | Pure-module tests for normalization, resolution, per-platform commands, and the launcher seam. |
 | `extension.test.ts` | Extension-surface tests: registration, disabling, the tool call, and the command. |

package/extensions/file-open/index.ts

@@ -25,8 +25,9 @@ export default function fileOpen(pi: ExtensionAPI, deps: FileOpenDeps = {}): voi
 
 	/**
 	 * Resolve `raw` against the effective root and hand it to the native
-	 * handler. A launch failure is reported through `ctx.ui.notify` because the
-	 * handler runs detached; the target is returned for the caller's message.
+	 * handler. A start failure, or a non-zero exit where the platform reports
+	 * one, goes through `ctx.ui.notify` because the handler runs detached; the
+	 * target is returned for the caller's message.
 	 */
 	const launch = (mode: OpenMode, raw: string, ctx: ExtensionContext): string => {
 		const root = resolveEffectiveCwd(ctx.cwd);
@@ -84,7 +85,7 @@ export default function fileOpen(pi: ExtensionAPI, deps: FileOpenDeps = {}): voi
 			const rest = trimmed.replace(/^-r\b\s*/, "").trim();
 			try {
 				const target = launch(reveal ? "reveal" : "open", rest, ctx);
-				ctx.ui.notify(`${reveal ? "Revealed" : "Opened"} ${target}`, "info");
+				ctx.ui.notify(`${reveal ? "Revealing" : "Opening"} ${target}`, "info");
 			} catch (error) {
 				ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
 			}