pi-agent-browser-native 0.2.16 → 0.2.18

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## Unreleased
 
+## 0.2.18 - 2026-05-03
+
+### Fixed
+- persist oversized parse-failure spill files when Pi provides a session directory without a session file
+- isolate the opt-in real-upstream download contract test from the user's global Downloads folder and avoid killing unrelated `agent-browser` processes
+
+### Changed
+- clarified the README and repo guidance for the current published package state
+- marked the completed implementation plan as superseded so current design guidance stays canonical
+- tightened the implicit-session idle-timeout helper to return milliseconds as a number and convert to an environment string only at the process boundary
+
+## 0.2.17 - 2026-05-03
+
+### Fixed
+- close the active extension-managed `piab-*` browser session when the originating `pi` process quits, while preserving managed browser continuity across `/reload` and resumable session transitions
+- added lifecycle regression coverage for quit-time managed-session cleanup and reload-time preservation
+
+### Changed
+- clarified that the managed-session idle timeout is now an abnormal-exit backstop, not the primary cleanup path for normal `pi` exits
+
 ## 0.2.16 - 2026-05-02
 
 ### Fixed

package/README.md

@@ -4,9 +4,9 @@ Native `pi` integration for [`agent-browser`](https://agent-browser.dev/).
 
 ## Status
 
-Early working scaffold.
+Published pre-1.0 package.
 
-The package scaffold, native `agent_browser` tool, local typecheck/test setup, and release/package verification workflow are in place.
+The native `agent_browser` tool, local verification workflow, package-content checks, and release checks are in place. Package install is the default path; checkout loading is for development and validation.
 
 ## Goal
 
@@ -45,7 +45,7 @@ A native `pi` integration can improve on the current skill by adding:
 
 ## Install and try
 
-The product direction is package-first. Prefer the package source once a release exists, while keeping the local-checkout flow for current development and pre-release validation.
+The product direction is package-first. Prefer the package source for normal use; keep the local-checkout flow for development and pre-release validation.
 
 ### Preferred package install
 
@@ -263,7 +263,7 @@ These calls return plain text and stay stateless: the extension does not inject
 Current cautions:
 - passing `--profile` is an explicit upstream choice; this extension does not add its own profile-cloning or isolation layer
 - launch-scoped flags like `--profile`, `--session-name`, `--cdp`, `--state`, and `--auto-connect` are for the first command that launches a session; if the implicit session is already active, retry that call with `sessionMode: "fresh"` or provide an explicit `--session ...` for the new launch
-- implicit `piab-*` sessions are extension-managed convenience sessions; they stay alive across `pi` shutdown/reload so later default calls can keep following the active managed browser on `/reload` or `/resume`, rely on the configured idle timeout to reduce stale background daemons, store persisted-session large snapshot spill files under a private session-scoped artifact directory with a bounded per-session budget so `details.fullOutputPath` and metadata-only `details.artifactManifest` survive reload/resume without unbounded growth, and still clean up process-private temp spill artifacts on shutdown
+- implicit `piab-*` sessions are extension-managed convenience sessions; they stay alive across `/reload` and resumable session transitions so later default calls can keep following the active managed browser on `/reload` or `/resume`, close when the originating `pi` process quits, rely on the configured idle timeout only as an abnormal-exit backstop, store persisted-session large snapshot spill files under a private session-scoped artifact directory with a bounded per-session budget so `details.fullOutputPath` and metadata-only `details.artifactManifest` survive reload/resume without unbounded growth, and still clean up process-private temp spill artifacts on shutdown
 - `sessionMode: "fresh"` without an explicit `--session` rotates that extension-managed session to the new browser so later auto calls keep using it
 - for local Unix launches, the wrapper uses a short private socket directory under `/tmp` so extension-generated session names do not trip upstream Unix socket-path limits in longer cwd/session-name combinations
 - for direct headless local Chrome launches to `chat.com`, `chatgpt.com`, and `chat.openai.com`, the extension injects a normal Chrome user agent when the caller did not explicitly provide `--user-agent`; this keeps the default headless workflow usable without forcing `--headed` or `--auto-connect`

package/docs/ARCHITECTURE.md

@@ -87,8 +87,9 @@ V1 ownership rule:
 - extension-managed sessions should be reusable during an active `pi` session and across `/reload` / `/resume`, while still being cleaned up predictably
 
 Practical policy:
-- preserve the current extension-managed session across normal `pi` shutdown/reload so persisted sessions can keep following the live browser after `/reload` or `/resume`
-- set an idle timeout on extension-managed sessions so abandoned daemons self-clean after inactivity
+- preserve the current extension-managed session across `/reload` and resumable session transitions so persisted sessions can keep following the live browser after `/reload` or `/resume`
+- close the active extension-managed session when the originating `pi` process quits, while leaving explicit caller-provided sessions alone
+- set an idle timeout on extension-managed sessions as a backstop for abnormal exits or cleanup failures
 - clean up process-private temp spill artifacts on shutdown, but keep persisted-session snapshot spill files in a private session-scoped artifact directory with a bounded per-session budget so `details.fullOutputPath` stays usable after reload/resume without unbounded growth
 - reconstruct the current extension-managed session from persisted tool details on resume/reload so later default calls keep following the active managed browser
 - if an unnamed fresh launch replaces an active extension-managed session, best-effort close the old managed session after the switch succeeds

package/docs/TOOL_CONTRACT.md

@@ -213,8 +213,9 @@ If `agent-browser` is not on `PATH`, fail with a message that:
 - derive the base implicit session name from the official `pi` session id plus a cwd hash so same-named checkouts do not collide
 - respect explicit upstream `--session` with minimal interference
 - treat the extension-managed session as convenience state owned by the wrapper
-- preserve the current extension-managed session across normal `pi` shutdown/reload so persisted sessions can keep following the live browser on `/reload` or `/resume`
-- set an idle timeout on extension-managed sessions so abandoned daemons eventually self-clean
+- preserve the current extension-managed session across `/reload` and resumable session transitions so persisted sessions can keep following the live browser on `/reload` or `/resume`
+- close the active extension-managed session when the originating `pi` process quits, while leaving explicit caller-provided sessions alone
+- set an idle timeout on extension-managed sessions as a backstop for abnormal exits or cleanup failures
 - clean up process-private temp spill artifacts on shutdown, while keeping persisted-session snapshot spill files in a private session-scoped artifact directory so `details.fullOutputPath` survives reload/restart and the oldest spill files are evicted if the per-session artifact budget is exceeded
 - reconstruct the current extension-managed session and latest `artifactManifest` from persisted tool details on resume/reload so later default calls keep following the active managed browser and can continue reporting artifact retention state
 - when an unnamed `sessionMode: "fresh"` launch succeeds, make it the new extension-managed session so later default calls keep using it

package/extensions/agent-browser/index.ts

@@ -1216,17 +1216,12 @@ function buildSessionDetailFields(sessionName: string | undefined, usedImplicitS
 function getPersistentSessionArtifactStore(ctx: {
 	sessionManager: {
 		getSessionDir?: () => string;
-		getSessionFile?: () => string | undefined;
 		getSessionId: () => string | undefined;
 	};
 }): PersistentSessionArtifactStore | undefined {
-	const sessionFile = typeof ctx.sessionManager.getSessionFile === "function" ? ctx.sessionManager.getSessionFile() : undefined;
 	const sessionDir = typeof ctx.sessionManager.getSessionDir === "function" ? ctx.sessionManager.getSessionDir() : undefined;
 	const sessionId = ctx.sessionManager.getSessionId();
-	if (!sessionFile || !sessionDir || !sessionId) {
-		return undefined;
-	}
-	return { sessionDir, sessionId };
+	return sessionDir && sessionId ? { sessionDir, sessionId } : undefined;
 }
 
 async function preserveParseFailureOutput(options: {
@@ -1360,7 +1355,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 	const ephemeralSessionSeed = createEphemeralSessionSeed();
 	const hasBraveApiKey = hasUsableBraveApiKey();
 	const toolPromptGuidelines = buildToolPromptGuidelines({ includeBraveSearch: hasBraveApiKey });
-	const implicitSessionIdleTimeoutMs = getImplicitSessionIdleTimeoutMs();
+	const implicitSessionIdleTimeoutMs = String(getImplicitSessionIdleTimeoutMs());
 	const implicitSessionCloseTimeoutMs = getImplicitSessionCloseTimeoutMs();
 	let managedSessionActive = false;
 	let managedSessionBaseName = createImplicitSessionName(undefined, process.cwd(), ephemeralSessionSeed);
@@ -1385,7 +1380,17 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 		artifactManifest = restoreArtifactManifestFromBranch(ctx.sessionManager.getBranch());
 	});
 
-	pi.on("session_shutdown", async () => {
+	pi.on("session_shutdown", async (event) => {
+		if (event?.reason === "quit") {
+			await managedSessionExecutionQueue.run(async () => {
+				if (!managedSessionActive) return;
+				await closeManagedSession({
+					cwd: managedSessionCwd,
+					sessionName: managedSessionName,
+					timeoutMs: implicitSessionCloseTimeoutMs,
+				});
+			});
+		}
 		managedSessionActive = false;
 		sessionTabTargets = new Map<string, OrderedSessionTabTarget>();
 		sessionTabTargetUpdateOrder = 0;

package/extensions/agent-browser/lib/runtime.ts

@@ -421,12 +421,10 @@ function parseTimeoutMs(rawValue: string | undefined, minimumValue: number): num
 	return parsedValue;
 }
 
-export function getImplicitSessionIdleTimeoutMs(env: NodeJS.ProcessEnv = process.env): string {
-	return String(
-		parseTimeoutMs(env[IMPLICIT_SESSION_IDLE_TIMEOUT_ENV], 0) ??
-			parseTimeoutMs(env[AGENT_BROWSER_IDLE_TIMEOUT_ENV], 0) ??
-			DEFAULT_IMPLICIT_SESSION_IDLE_TIMEOUT_MS,
-	);
+export function getImplicitSessionIdleTimeoutMs(env: NodeJS.ProcessEnv = process.env): number {
+	return parseTimeoutMs(env[IMPLICIT_SESSION_IDLE_TIMEOUT_ENV], 0) ??
+		parseTimeoutMs(env[AGENT_BROWSER_IDLE_TIMEOUT_ENV], 0) ??
+		DEFAULT_IMPLICIT_SESSION_IDLE_TIMEOUT_MS;
 }
 
 export function getImplicitSessionCloseTimeoutMs(env: NodeJS.ProcessEnv = process.env): number {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-agent-browser-native",
-  "version": "0.2.16",
+  "version": "0.2.18",
   "description": "pi extension that exposes agent-browser as a native tool for browser automation",
   "type": "module",
   "author": "Mitch Fultz (https://github.com/fitchmultz)",