lsd-pi 1.2.4 → 1.3.6

package/src/resources/extensions/browser-tools/tools/state-persistence.ts

@@ -3,93 +3,36 @@ import { Type } from "@sinclair/typebox";
 import type { ToolDeps } from "../state.js";
 
 /**
- * State persistence tools — save/restore cookies, localStorage, sessionStorage.
+ * State persistence — save/restore cookies, localStorage, sessionStorage.
  */
 
 const STATE_DIR = ".gsd/browser-state";
 
 export function registerStatePersistenceTools(pi: ExtensionAPI, deps: ToolDeps): void {
-	// -------------------------------------------------------------------------
-	// browser_save_state
-	// -------------------------------------------------------------------------
 	pi.registerTool({
-		name: "browser_save_state",
-		label: "Browser Save State",
+		name: "browser_state",
+		label: "Browser State",
 		description:
-			"Save cookies, localStorage, and sessionStorage to disk so authenticated sessions survive browser restarts. " +
-			"State files are written to .gsd/browser-state/ and should be gitignored (may contain auth tokens). " +
-			"Never displays secret values in output.",
+			"Save or restore browser state (cookies, localStorage, sessionStorage) to persist sessions across browser restarts. " +
+			"State files written to .gsd/browser-state/ (should be gitignored).",
 		parameters: Type.Object({
-			name: Type.Optional(
-				Type.String({ description: "Name for the state file (default: 'default'). Used as the filename stem." }),
-			),
+			action: Type.Union([
+				Type.Literal("save"),
+				Type.Literal("restore"),
+			], { description: "'save' — persist current state, 'restore' — load previously saved state" }),
+			name: Type.Optional(Type.String({ description: "State file name (default: 'default'). Used as filename stem." })),
 		}),
 
 		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
 			try {
-				const { context: ctx, page: p } = await deps.ensureBrowser();
-				const name = deps.sanitizeArtifactName(params.name ?? "default", "default");
-
-				const { mkdir, writeFile } = await import("node:fs/promises");
-				const path = await import("node:path");
-				const stateDir = path.resolve(process.cwd(), STATE_DIR);
-				await mkdir(stateDir, { recursive: true });
-
-				// 1. Playwright storageState: cookies + localStorage
-				const storageState = await ctx.storageState();
-
-				// 2. sessionStorage: must be extracted per-origin via page.evaluate
-				const sessionStorageData: Record<string, Record<string, string>> = {};
-				try {
-					const origin = new URL(p.url()).origin;
-					const ssData = await p.evaluate(() => {
-						const data: Record<string, string> = {};
-						for (let i = 0; i < sessionStorage.length; i++) {
-							const key = sessionStorage.key(i);
-							if (key) data[key] = sessionStorage.getItem(key) ?? "";
-						}
-						return data;
-					});
-					if (Object.keys(ssData).length > 0) {
-						sessionStorageData[origin] = ssData;
-					}
-				} catch {
-					// Page may not have a valid origin (about:blank, etc.)
+				if (params.action === "save") {
+					return await saveState(deps, params.name ?? "default");
+				} else {
+					return await restoreState(deps, params.name ?? "default");
 				}
-
-				const combined = {
-					storageState,
-					sessionStorage: sessionStorageData,
-					savedAt: new Date().toISOString(),
-					url: p.url(),
-				};
-
-				const filePath = path.join(stateDir, `${name}.json`);
-				await writeFile(filePath, JSON.stringify(combined, null, 2));
-
-				// Ensure .gitignore covers the state dir
-				const gitignorePath = path.resolve(process.cwd(), STATE_DIR, ".gitignore");
-				await writeFile(gitignorePath, "*\n!.gitignore\n").catch(() => { /* best-effort — .gitignore may already exist or dir may be read-only */ });
-
-				const cookieCount = storageState.cookies?.length ?? 0;
-				const localStorageOrigins = storageState.origins?.length ?? 0;
-				const sessionStorageOrigins = Object.keys(sessionStorageData).length;
-
-				return {
-					content: [{
-						type: "text",
-						text: `State saved: ${filePath}\nCookies: ${cookieCount}\nlocalStorage origins: ${localStorageOrigins}\nsessionStorage origins: ${sessionStorageOrigins}`,
-					}],
-					details: {
-						path: filePath,
-						cookieCount,
-						localStorageOrigins,
-						sessionStorageOrigins,
-					},
-				};
 			} catch (err: any) {
 				return {
-					content: [{ type: "text", text: `Save state failed: ${err.message}` }],
+					content: [{ type: "text" as const, text: `State '${params.action}' failed: ${err.message}` }],
 					details: { error: err.message },
 					isError: true,
 				};
@@ -97,106 +40,85 @@ export function registerStatePersistenceTools(pi: ExtensionAPI, deps: ToolDeps):
 		},
 	});
 
-	// -------------------------------------------------------------------------
-	// browser_restore_state
-	// -------------------------------------------------------------------------
-	pi.registerTool({
-		name: "browser_restore_state",
-		label: "Browser Restore State",
-		description:
-			"Restore cookies, localStorage, and sessionStorage from a previously saved state file. " +
-			"Injects cookies via context.addCookies() and storage via page.evaluate(). " +
-			"For full fidelity, restore before navigating to the target site.",
-		parameters: Type.Object({
-			name: Type.Optional(
-				Type.String({ description: "Name of the state file to restore (default: 'default')." }),
-			),
-		}),
-
-		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
-			try {
-				const { context: ctx, page: p } = await deps.ensureBrowser();
-				const name = deps.sanitizeArtifactName(params.name ?? "default", "default");
-
-				const { readFile } = await import("node:fs/promises");
-				const path = await import("node:path");
-				const filePath = path.join(process.cwd(), STATE_DIR, `${name}.json`);
-
-				let raw: string;
-				try {
-					raw = await readFile(filePath, "utf-8");
-				} catch {
-					return {
-						content: [{ type: "text", text: `State file not found: ${filePath}` }],
-						details: { error: "file_not_found", path: filePath },
-						isError: true,
-					};
-				}
-
-				const combined = JSON.parse(raw);
-				const storageState = combined.storageState;
-				const sessionStorageData: Record<string, Record<string, string>> = combined.sessionStorage ?? {};
-
-				// 1. Restore cookies
-				let cookieCount = 0;
-				if (storageState?.cookies?.length) {
-					await ctx.addCookies(storageState.cookies);
-					cookieCount = storageState.cookies.length;
-				}
-
-				// 2. Restore localStorage via page.evaluate
-				let localStorageOrigins = 0;
-				if (storageState?.origins?.length) {
-					for (const origin of storageState.origins) {
-						try {
-							await p.evaluate((items: Array<{ name: string; value: string }>) => {
-								for (const { name, value } of items) {
-									localStorage.setItem(name, value);
-								}
-							}, origin.localStorage ?? []);
-							localStorageOrigins++;
-						} catch {
-							// Origin mismatch — localStorage can only be set on matching origin
-						}
-					}
+	async function saveState(deps: ToolDeps, name: string) {
+		const { context: ctx, page: p } = await deps.ensureBrowser();
+		name = deps.sanitizeArtifactName(name, "default");
+		const { mkdir, writeFile } = await import("node:fs/promises");
+		const path = await import("node:path");
+		const stateDir = path.resolve(process.cwd(), STATE_DIR);
+		await mkdir(stateDir, { recursive: true });
+
+		const storageState = await ctx.storageState();
+		const sessionStorageData: Record<string, Record<string, string>> = {};
+		try {
+			const origin = new URL(p.url()).origin;
+			const ssData = await p.evaluate(() => {
+				const data: Record<string, string> = {};
+				for (let i = 0; i < sessionStorage.length; i++) {
+					const key = sessionStorage.key(i);
+					if (key) data[key] = sessionStorage.getItem(key) ?? "";
 				}
-
-				// 3. Restore sessionStorage via page.evaluate
-				let sessionStorageOrigins = 0;
-				for (const [_origin, data] of Object.entries(sessionStorageData)) {
-					try {
-						await p.evaluate((items: Record<string, string>) => {
-							for (const [key, value] of Object.entries(items)) {
-								sessionStorage.setItem(key, value);
-							}
-						}, data);
-						sessionStorageOrigins++;
-					} catch {
-						// Origin mismatch
-					}
-				}
-
-				return {
-					content: [{
-						type: "text",
-						text: `State restored from: ${filePath}\nCookies: ${cookieCount}\nlocalStorage origins: ${localStorageOrigins}\nsessionStorage origins: ${sessionStorageOrigins}\nSaved at: ${combined.savedAt ?? "unknown"}`,
-					}],
-					details: {
-						path: filePath,
-						cookieCount,
-						localStorageOrigins,
-						sessionStorageOrigins,
-						savedAt: combined.savedAt,
-						savedUrl: combined.url,
-					},
-				};
-			} catch (err: any) {
-				return {
-					content: [{ type: "text", text: `Restore state failed: ${err.message}` }],
-					details: { error: err.message },
-					isError: true,
-				};
+				return data;
+			});
+			if (Object.keys(ssData).length > 0) sessionStorageData[origin] = ssData;
+		} catch { /* Page may not have a valid origin */ }
+
+		const combined = { storageState, sessionStorage: sessionStorageData, savedAt: new Date().toISOString(), url: p.url() };
+		const filePath = path.join(stateDir, `${name}.json`);
+		await writeFile(filePath, JSON.stringify(combined, null, 2));
+
+		const gitignorePath = path.resolve(process.cwd(), STATE_DIR, ".gitignore");
+		await writeFile(gitignorePath, "*\n!.gitignore\n").catch(() => { /* best-effort */ });
+
+		return {
+			content: [{ type: "text" as const, text: `State saved: ${filePath}\nCookies: ${storageState.cookies?.length ?? 0}\nlocalStorage origins: ${storageState.origins?.length ?? 0}\nsessionStorage origins: ${Object.keys(sessionStorageData).length}` }],
+			details: { path: filePath, cookieCount: storageState.cookies?.length ?? 0, localStorageOrigins: storageState.origins?.length ?? 0, sessionStorageOrigins: Object.keys(sessionStorageData).length },
+		};
+	}
+
+	async function restoreState(deps: ToolDeps, name: string) {
+		const { context: ctx, page: p } = await deps.ensureBrowser();
+		name = deps.sanitizeArtifactName(name, "default");
+		const { readFile } = await import("node:fs/promises");
+		const path = await import("node:path");
+		const filePath = path.join(process.cwd(), STATE_DIR, `${name}.json`);
+
+		let raw: string;
+		try { raw = await readFile(filePath, "utf-8"); } catch {
+			return { content: [{ type: "text" as const, text: `State file not found: ${filePath}` }], details: { error: "file_not_found", path: filePath }, isError: true };
+		}
+
+		const combined = JSON.parse(raw);
+		const storageState = combined.storageState;
+		const sessionStorageData: Record<string, Record<string, string>> = combined.sessionStorage ?? {};
+
+		let cookieCount = 0;
+		if (storageState?.cookies?.length) {
+			await ctx.addCookies(storageState.cookies);
+			cookieCount = storageState.cookies.length;
+		}
+
+		let localStorageOrigins = 0;
+		if (storageState?.origins?.length) {
+			for (const origin of storageState.origins) {
+				try {
+					await p.evaluate((items: Array<{ name: string; value: string }>) => { for (const { name, value } of items) localStorage.setItem(name, value); }, origin.localStorage ?? []);
+					localStorageOrigins++;
+				} catch { /* Origin mismatch */ }
 			}
-		},
-	});
+		}
+
+		let sessionStorageOrigins = 0;
+		for (const [_origin, data] of Object.entries(sessionStorageData)) {
+			try {
+				await p.evaluate((items: Record<string, string>) => { for (const [key, value] of Object.entries(items)) sessionStorage.setItem(key, value); }, data);
+				sessionStorageOrigins++;
+			} catch { /* Origin mismatch */ }
+		}
+
+		return {
+			content: [{ type: "text" as const, text: `State restored from: ${filePath}\nCookies: ${cookieCount}\nlocalStorage origins: ${localStorageOrigins}\nsessionStorage origins: ${sessionStorageOrigins}` }],
+			details: { path: filePath, cookieCount, localStorageOrigins, sessionStorageOrigins, savedAt: combined.savedAt, savedUrl: combined.url },
+		};
+	}
 }

package/src/resources/extensions/browser-tools/utils.ts

@@ -625,7 +625,7 @@ export function formatVersionedRef(version: number, key: string): string {
 }
 
 export function staleRefGuidance(refDisplay: string, reason: string): string {
-	return `Ref ${refDisplay} could not be resolved (${reason}). The ref is likely stale after DOM/navigation changes. Call browser_snapshot_refs again to refresh refs.`;
+	return `Ref ${refDisplay} could not be resolved (${reason}). The ref is likely stale after DOM/navigation changes. Call browser_ref with action='snapshot' to refresh refs.`;
 }
 
 // ---------------------------------------------------------------------------

package/src/resources/extensions/mac-tools/index.ts

@@ -204,9 +204,7 @@ export default function (pi: ExtensionAPI) {
 			"List all running macOS applications. Returns an array of { name, bundleId, pid, isActive } " +
 			"for user-facing apps (regular activation policy). Set includeBackground to true to also " +
 			"include accessory/background apps.",
-		promptGuidelines: [
-			"Use to discover what apps are running before interacting with them.",
-		],
+		promptGuidelines: [] as string[],
 		parameters: Type.Object({
 			includeBackground: Type.Optional(Type.Boolean({ description: "Include background/accessory apps (default: false)" })),
 		}),
@@ -235,9 +233,6 @@ export default function (pi: ExtensionAPI) {
 			"Launch a macOS application by name or bundle ID. " +
 			"Returns { launched, name, bundleId, pid } on success. " +
 			"Provide either 'name' (e.g. 'TextEdit') or 'bundleId' (e.g. 'com.apple.TextEdit').",
-		promptGuidelines: [
-			"Use app name for well-known apps; use bundleId when the name is ambiguous.",
-		],
 		parameters: Type.Object({
 			name: Type.Optional(Type.String({ description: "Application name (e.g. 'TextEdit', 'Safari')" })),
 			bundleId: Type.Optional(Type.String({ description: "Bundle identifier (e.g. 'com.apple.TextEdit')" })),
@@ -310,9 +305,7 @@ export default function (pi: ExtensionAPI) {
 			"Quit a running macOS application. " +
 			"Returns { quit, name } on success. Errors if the app is not running. " +
 			"Provide either 'name' or 'bundleId'.",
-		promptGuidelines: [
-			"Use to clean up apps launched during automation — don't leave apps running unnecessarily.",
-		],
+		promptGuidelines: [] as string[],
 		parameters: Type.Object({
 			name: Type.Optional(Type.String({ description: "Application name" })),
 			bundleId: Type.Optional(Type.String({ description: "Bundle identifier" })),
@@ -349,9 +342,7 @@ export default function (pi: ExtensionAPI) {
 			"The windowId can be used with getWindowInfo for detailed inspection or with screenshotWindow for capture. " +
 			"Returns an empty array (not error) if the app is running but has no visible windows. " +
 			"Errors if the app is not running.",
-		promptGuidelines: [
-			"Use to get windowId values needed by mac_screenshot.",
-		],
+		promptGuidelines: [] as string[],
 		parameters: Type.Object({
 			app: Type.String({ description: "Application name (e.g. 'TextEdit') or bundle identifier (e.g. 'com.apple.TextEdit')" }),
 		}),
@@ -393,8 +384,7 @@ export default function (pi: ExtensionAPI) {
 			"The 'app' param accepts an app name (e.g. 'Finder') or bundle ID (e.g. 'com.apple.Finder').",
 		promptGuidelines: [
 			"Prefer for targeted element search — use role/title/value criteria to narrow results.",
-			"Use mode:focused to check the current focus target without search criteria.",
-			"Use mac_get_tree instead of mode:tree when you just need to understand app structure.",
+			"Use mac_get_tree instead of mode:tree for quick structure inspection.",
 		],
 		parameters: Type.Object({
 			app: Type.String({ description: "Application name or bundle identifier" }),
@@ -524,9 +514,7 @@ export default function (pi: ExtensionAPI) {
 			"Each line: `role \"title\" [value]` with 2-space indent per depth level. " +
 			"Omits title/value when nil or empty.",
 		promptGuidelines: [
-			"Use for understanding app UI structure — start with low limits and increase if needed.",
 			"Prefer mac_find search mode when you know what you're looking for.",
-			"Check the truncation note to know if the tree was cut short.",
 		],
 		parameters: Type.Object({
 			app: Type.String({ description: "Application name or bundle identifier" }),
@@ -581,8 +569,7 @@ export default function (pi: ExtensionAPI) {
 			"Finds the first element matching the given criteria (role, title, value, identifier) and clicks it. " +
 			"At least one criterion is required. Returns the clicked element's attributes.",
 		promptGuidelines: [
-			"Verify the click worked by reading the resulting state with mac_find or mac_read.",
-			"Use mac_find first to discover the right role/title/value criteria before clicking.",
+			"Use mac_find first to discover the right criteria before clicking.",
 		],
 		parameters: Type.Object({
 			app: Type.String({ description: "Application name or bundle identifier" }),
@@ -638,8 +625,7 @@ export default function (pi: ExtensionAPI) {
 			"Returns the actual value after setting (read-back verification). " +
 			"At least one criterion is required.",
 		promptGuidelines: [
-			"Read back the value after typing to verify — the return value includes actual content.",
-			"Target text fields/areas by role (AXTextArea, AXTextField) for reliability.",
+			"Target text fields by role (AXTextArea, AXTextField) for reliability.",
 		],
 		parameters: Type.Object({
 			app: Type.String({ description: "Application name or bundle identifier" }),
@@ -697,9 +683,7 @@ export default function (pi: ExtensionAPI) {
 			"Returns the screenshot as an image content block for visual analysis, alongside text metadata " +
 			"(dimensions and format). Requires Screen Recording permission — use mac_check_permissions to verify.",
 		promptGuidelines: [
-			"Use for visual verification when accessibility attributes aren't sufficient.",
-			"Prefer nominal resolution unless retina detail is needed — retina doubles payload size.",
-			"Requires Screen Recording permission — run mac_check_permissions first if screenshot fails.",
+			"Prefer nominal resolution; retina doubles payload. Run mac_check_permissions if it fails.",
 		],
 		parameters: Type.Object({
 			windowId: Type.Number({ description: "Window ID from mac_list_windows output" }),
@@ -747,9 +731,7 @@ export default function (pi: ExtensionAPI) {
 			"Finds the first element matching the given criteria and reads the named attribute(s). " +
 			"AXValue subtypes (CGPoint, CGSize, CGRect, CFRange) are automatically unpacked to structured dicts. " +
 			"Use 'attribute' for a single attribute or 'attributes' for multiple. At least one search criterion is required.",
-		promptGuidelines: [
-			"Use to verify state after actions — read AXValue to confirm text was typed, AXEnabled to check if a button is active.",
-		],
+		promptGuidelines: [] as string[],
 		parameters: Type.Object({
 			app: Type.String({ description: "Application name or bundle identifier" }),
 			attribute: Type.Optional(Type.String({ description: "Single attribute name to read (e.g. 'AXValue', 'AXPosition', 'AXRole')" })),
@@ -824,8 +806,13 @@ export default function (pi: ExtensionAPI) {
 
 	// -----------------------------------------------------------------
 	// System prompt injection — mac-tools usage guidelines
+	// Only inject when mac tools are actually active.
 	// -----------------------------------------------------------------
 	pi.on("before_agent_start", async (event) => {
+		const activeTools = new Set(pi.getActiveTools());
+		const hasMacTools = [...activeTools].some((name) => name.startsWith("mac_"));
+		if (!hasMacTools) return;
+
 		const guidelines = `
 
 [SYSTEM CONTEXT — Mac Tools]
@@ -834,18 +821,16 @@ export default function (pi: ExtensionAPI) {
 
 You have mac-tools for controlling native macOS applications (Finder, TextEdit, Safari, Xcode, etc.) via Accessibility APIs.
 
-**Mac-tools vs browser-tools:** Use mac-tools for native macOS apps. Use browser-tools for web pages inside a browser. If you need to interact with a website in Safari or Chrome, use browser-tools — mac-tools controls the browser's native UI chrome (menus, tabs, address bar), not web page content.
+**Mac-tools vs browser-tools:** Use mac-tools for native macOS apps. Use browser-tools for web pages inside a browser.
 
-**Permissions:** If any mac tool returns a permission error, run \`mac_check_permissions\` to diagnose. Accessibility and Screen Recording permissions are granted in System Settings > Privacy & Security.
+**Permissions:** If any mac tool returns a permission error, run \`mac_check_permissions\` to diagnose.
 
 **Interaction pattern — discover → act → verify:**
-1. **Discover** the UI structure with \`mac_find\` (search for specific elements) or \`mac_get_tree\` (see overall layout)
-2. **Act** with \`mac_click\` (press buttons/menus) or \`mac_type\` (enter text into fields)
-3. **Verify** the result with \`mac_read\` (check attribute values) or \`mac_screenshot\` (visual confirmation)
-
-**Tree queries:** Start with default limits (mac_get_tree: maxDepth:3, maxCount:50). Increase only if the element you need isn't visible in the output. Large trees waste context.
+1. **Discover** with \`mac_find\` or \`mac_get_tree\`
+2. **Act** with \`mac_click\` or \`mac_type\`
+3. **Verify** with \`mac_read\` or \`mac_screenshot\`
 
-**Screenshots:** Use \`mac_screenshot\` only when visual verification is genuinely needed — the image payload is large. Prefer \`mac_read\` or \`mac_find\` for checking text values and element state.`;
+Start with default tree limits (maxDepth:3, maxCount:50). Use \`mac_screenshot\` sparingly — the payload is large.`;
 
 		return { systemPrompt: event.systemPrompt + guidelines };
 	});

package/src/resources/extensions/memory/index.ts

@@ -93,9 +93,29 @@ function truncateEntrypointContent(raw: string): {
  * @param memoryDir  Absolute path to the project's memory directory.
  * @param entrypointContent  The (possibly truncated) contents of MEMORY.md.
  */
-function buildMemoryPrompt(memoryDir: string, entrypointContent: string): string {
+function buildMemoryPrompt(memoryDir: string, entrypointContent: string, hasMemories: boolean): string {
 	const sections: string[] = [];
 
+	if (!hasMemories) {
+		// Slim prompt when no memories exist — just enough to know the system is there
+		// and how to save the first memory. Full instructions are deferred until needed.
+		sections.push(`# Memory
+
+You have a persistent, file-based memory system at \`${memoryDir}\`.
+This directory already exists — write to it directly with the file write tool.
+
+If the user explicitly asks you to remember something, save it immediately. If they ask you to forget, find and remove it.
+
+To save a memory:
+1. Write a markdown file to the memory directory with YAML frontmatter (name, description, type: user|feedback|project|reference)
+2. Add a one-line pointer to MEMORY.md: \`- [Title](file.md) — one-line hook\`
+
+Your MEMORY.md is currently empty.`);
+		return sections.join('\n\n');
+	}
+
+	// ── Full prompt when memories exist ──
+
 	// ── Header ──
 	sections.push(`# Memory
 
@@ -196,7 +216,7 @@ export default function memoryExtension(pi: ExtensionAPI) {
 			entrypointContent = content;
 		}
 
-		const prompt = buildMemoryPrompt(memoryDir, entrypointContent);
+		const prompt = buildMemoryPrompt(memoryDir, entrypointContent, !!entrypointContent.trim());
 
 		return {
 			systemPrompt: event.systemPrompt + '\n\n' + prompt,