lsd-pi 1.2.4 → 1.3.6

package/dist/resources/extensions/browser-tools/tools/state-persistence.js

@@ -1,180 +1,117 @@
 import { Type } from "@sinclair/typebox";
 /**
- * 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, deps) {
-    // -------------------------------------------------------------------------
-    // browser_save_state
-    // -------------------------------------------------------------------------
     pi.registerTool({
-        name: "browser_save_state",
-        label: "Browser Save 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.",
+        name: "browser_state",
+        label: "Browser State",
+        description: "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 = {};
-                try {
-                    const origin = new URL(p.url()).origin;
-                    const ssData = await p.evaluate(() => {
-                        const data = {};
-                        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;
-                    }
+                if (params.action === "save") {
+                    return await saveState(deps, params.name ?? "default");
                 }
-                catch {
-                    // Page may not have a valid origin (about:blank, etc.)
+                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(() => { });
-                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) {
                 return {
-                    content: [{ type: "text", text: `Save state failed: ${err.message}` }],
+                    content: [{ type: "text", text: `State '${params.action}' failed: ${err.message}` }],
                     details: { error: err.message },
                     isError: true,
                 };
             }
         },
     });
-    // -------------------------------------------------------------------------
-    // 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;
-                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 = combined.sessionStorage ?? {};
-                // 1. Restore cookies
-                let cookieCount = 0;
-                if (storageState?.cookies?.length) {
-                    await ctx.addCookies(storageState.cookies);
-                    cookieCount = storageState.cookies.length;
+    async function saveState(deps, name) {
+        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 = {};
+        try {
+            const origin = new URL(p.url()).origin;
+            const ssData = await p.evaluate(() => {
+                const data = {};
+                for (let i = 0; i < sessionStorage.length; i++) {
+                    const key = sessionStorage.key(i);
+                    if (key)
+                        data[key] = sessionStorage.getItem(key) ?? "";
                 }
-                // 2. Restore localStorage via page.evaluate
-                let localStorageOrigins = 0;
-                if (storageState?.origins?.length) {
-                    for (const origin of storageState.origins) {
-                        try {
-                            await p.evaluate((items) => {
-                                for (const { name, value } of items) {
-                                    localStorage.setItem(name, value);
-                                }
-                            }, origin.localStorage ?? []);
-                            localStorageOrigins++;
-                        }
-                        catch {
-                            // Origin mismatch — localStorage can only be set on matching origin
-                        }
-                    }
-                }
-                // 3. Restore sessionStorage via page.evaluate
-                let sessionStorageOrigins = 0;
-                for (const [_origin, data] of Object.entries(sessionStorageData)) {
-                    try {
-                        await p.evaluate((items) => {
-                            for (const [key, value] of Object.entries(items)) {
-                                sessionStorage.setItem(key, value);
-                            }
-                        }, data);
-                        sessionStorageOrigins++;
-                    }
-                    catch {
-                        // Origin mismatch
-                    }
+                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(() => { });
+        return {
+            content: [{ type: "text", 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, name) {
+        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;
+        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 = 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) => { for (const { name, value } of items)
+                        localStorage.setItem(name, value); }, origin.localStorage ?? []);
+                    localStorageOrigins++;
                 }
-                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 { /* Origin mismatch */ }
             }
-            catch (err) {
-                return {
-                    content: [{ type: "text", text: `Restore state failed: ${err.message}` }],
-                    details: { error: err.message },
-                    isError: true,
-                };
+        }
+        let sessionStorageOrigins = 0;
+        for (const [_origin, data] of Object.entries(sessionStorageData)) {
+            try {
+                await p.evaluate((items) => { 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}` }],
+            details: { path: filePath, cookieCount, localStorageOrigins, sessionStorageOrigins, savedAt: combined.savedAt, savedUrl: combined.url },
+        };
+    }
 }

package/dist/resources/extensions/browser-tools/utils.js

@@ -463,7 +463,7 @@ export function formatVersionedRef(version, key) {
     return `@v${version}:${key}`;
 }
 export function staleRefGuidance(refDisplay, reason) {
-    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.`;
 }
 // ---------------------------------------------------------------------------
 // Compact state summary formatting

package/dist/resources/extensions/mac-tools/index.js

@@ -173,9 +173,7 @@ export default function (pi) {
         description: "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: [],
         parameters: Type.Object({
             includeBackground: Type.Optional(Type.Boolean({ description: "Include background/accessory apps (default: false)" })),
         }),
@@ -201,9 +199,6 @@ export default function (pi) {
         description: "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')" })),
@@ -272,9 +267,7 @@ export default function (pi) {
         description: "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: [],
         parameters: Type.Object({
             name: Type.Optional(Type.String({ description: "Application name" })),
             bundleId: Type.Optional(Type.String({ description: "Bundle identifier" })),
@@ -309,9 +302,7 @@ export default function (pi) {
             "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: [],
         parameters: Type.Object({
             app: Type.String({ description: "Application name (e.g. 'TextEdit') or bundle identifier (e.g. 'com.apple.TextEdit')" }),
         }),
@@ -348,8 +339,7 @@ export default function (pi) {
             "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" }),
@@ -470,9 +460,7 @@ export default function (pi) {
             "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" }),
@@ -522,8 +510,7 @@ export default function (pi) {
             "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" }),
@@ -573,8 +560,7 @@ export default function (pi) {
             "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" }),
@@ -625,9 +611,7 @@ export default function (pi) {
             "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" }),
@@ -672,9 +656,7 @@ export default function (pi) {
             "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: [],
         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')" })),
@@ -741,8 +723,13 @@ export default function (pi) {
     });
     // -----------------------------------------------------------------
     // 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]
@@ -751,18 +738,16 @@ export default function (pi) {
 
 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/dist/resources/extensions/memory/index.js

@@ -63,8 +63,26 @@ function truncateEntrypointContent(raw) {
  * @param memoryDir  Absolute path to the project's memory directory.
  * @param entrypointContent  The (possibly truncated) contents of MEMORY.md.
  */
-function buildMemoryPrompt(memoryDir, entrypointContent) {
+function buildMemoryPrompt(memoryDir, entrypointContent, hasMemories) {
     const sections = [];
+    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
 
@@ -151,7 +169,7 @@ export default function memoryExtension(pi) {
             const { content } = truncateEntrypointContent(entrypointContent);
             entrypointContent = content;
         }
-        const prompt = buildMemoryPrompt(memoryDir, entrypointContent);
+        const prompt = buildMemoryPrompt(memoryDir, entrypointContent, !!entrypointContent.trim());
         return {
             systemPrompt: event.systemPrompt + '\n\n' + prompt,
         };