Feature/chat view

.gitignore

@@ -1,6 +1,7 @@
 # Personal planning docs (reagan_ prefix per CLAUDE.md) — never committed
 reagan_*
 app/reagan_*
+app/docs/PRODUCT_*.md
 
 # Dependencies
 node_modules/

app/forge.config.ts

@@ -55,6 +55,15 @@ const runNpm = (args: string[], cwd: string): void => {
   execFileSync(process.platform === 'win32' ? 'npm.cmd' : 'npm', args, { cwd, stdio: 'inherit' });
 };
 
+function isViteOutputPath(file: string): boolean {
+  const normalized = file.split(path.sep).join('/');
+  if (normalized === '/.vite' || normalized.startsWith('/.vite/')) return true;
+  if (normalized === '.vite' || normalized.startsWith('.vite/')) return true;
+  if (!path.isAbsolute(file)) return false;
+  const rel = path.relative(__dirname, file).split(path.sep).join('/');
+  return rel === '.vite' || rel.startsWith('.vite/');
+}
+
 // ---------------------------------------------------------------------------
 // Forge configuration
 // ---------------------------------------------------------------------------
@@ -68,32 +77,13 @@ const config: ForgeConfig = {
     name: 'Browser Use',
     executableName: 'browser-use-desktop',
 
-    // Exclude dev-only files from the packaged app.asar. Without this,
-    // Forge ships src/, tests/, personal planning .md files, Vite
-    // source configs, CI configs, README, etc. — the DMG balloons and
-    // users get dev notes. Paths arrive with a leading slash.
-    ignore: [
-      /^\/src($|\/)/,                             // TS source; compiled output is in .vite/build
-      /^\/tests($|\/)/,
-      /^\/scripts($|\/)/,
-      /^\/python($|\/)/,                          // daemon removed; defensive
-      /^\/harnessless($|\/)/,
-      /^\/\.github($|\/)/,
-      /^\/\.claude($|\/)/,
-      /^\/\.vscode($|\/)/,
-      /^\/coverage($|\/)/,
-      /^\/reagan_.*$/,                            // personal planning docs
-      /^\/.*\.md$/,                               // all markdown (README, docs, etc.)
-      /^\/tsconfig.*\.json$/,
-      /^\/eslint\.config\.(ts|mts|js|mjs|cjs)$/,
-      /^\/vite\..*\.(ts|mts)$/,                   // dev-time vite configs
-      /^\/forge\.config\.(ts|js)$/,
-      /^\/playwright\.config\.(ts|js)$/,
-      /^\/knip\.json$/,
-      /^\/\.env(\..+)?$/,                         // never ship .env to users
-      /^\/Taskfile\.ya?ml$/,
-      /^\/.+\.map$/,                              // sourcemaps
-    ],
+    // The Vite plugin expects packaged app contents to come only from .vite.
+    // Production externals are installed back into the build path in the
+    // packageAfterPrune hook below, and app-update.yml is copied as a resource.
+    ignore: (file) => {
+      if (!file) return false;
+      return !isViteOutputPath(file);
+    },
 
     // macOS bundle identity — only set when credentials are available.
     // Real Developer ID signing only runs via @electron/osx-sign when

app/package.json

@@ -123,16 +123,19 @@
     "dotenv": "^17.4.2",
     "electron-squirrel-startup": "^1.0.1",
     "electron-updater": "^6.8.3",
+    "immer": "^11.1.8",
     "keytar": "^7.9.0",
     "node-cache": "^5.1.2",
     "node-pty": "^1.1.0",
+    "prism-react-renderer": "^2.4.1",
     "qrcode": "^1.5.4",
     "react": "^19.2.5",
     "react-dom": "^19.2.5",
     "react-markdown": "^10.1.0",
     "remark-breaks": "^4.0.0",
     "remark-gfm": "^4.0.1",
     "ws": "^8.20.0",
-    "zod": "^4.3.6"
+    "zod": "^4.3.6",
+    "zustand": "^5.0.13"
   }
 }

app/src/main/hl/engines/browserHarnessEnv.ts

@@ -15,5 +15,10 @@ export function applyBrowserHarnessEnv(ctx: SpawnContext, env: NodeJS.ProcessEnv
   env.CDP_REPL_PORT = env.CDP_REPL_PORT ?? browserHarnessReplPort(ctx.sessionId, ctx.targetId);
   env.CDP_REPL_LOG = env.CDP_REPL_LOG ?? path.join(ctx.harnessDir, `browser-harness-js-${ctx.sessionId}.log`);
   env.BU_SESSION_ID = ctx.sessionId;
+  // Watched session outputs dir — any file written here triggers a `file_output`
+  // event in runEngine. The Page.captureScreenshot wrapper in repl.ts auto-saves
+  // PNGs into this dir so screenshots surface in the chat instead of being
+  // dumped as base64 into stdout.
+  env.BU_OUTPUTS_DIR = path.join(ctx.harnessDir, 'outputs', ctx.sessionId);
   return env;
 }

app/src/main/hl/engines/runEngine.ts

@@ -13,7 +13,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { engineLogger } from '../../logger';
 import { resolveAuth, loadOpenAIKey, loadClaudeSubscriptionType, loadBrowserCodeConfig } from '../../identity/authStore';
-import { helpersPath, skillPath } from '../harness';
+import { helpersPath, skillPath, skillMetaFromPath as resolveSkillMetaFromPath } from '../harness';
 import { get as getAdapter } from './registry';
 import { spawnCli } from './cliSpawn';
 import { registerResourceOwner, unregisterResourceOwner } from '../../resourceMonitor';
@@ -454,12 +454,20 @@ export async function runEngine(opts: RunEngineOptions): Promise<void> {
       if (!stat.isFile()) return;
       if (seenOutputs.get(filename) === stat.size) return;
       seenOutputs.set(filename, stat.size);
+      const mime = mimeFromExt(filename);
+      engineLogger.info('engines.run.outputs.fileDetected', {
+        sessionId: opts.sessionId,
+        filename,
+        absPath: filePath,
+        bytes: stat.size,
+        mime,
+      });
       opts.onEvent({
         type: 'file_output',
         name: filename,
         path: filePath,
         size: stat.size,
-        mime: mimeFromExt(filename),
+        mime,
       });
     });
   } catch (err) {
@@ -484,18 +492,9 @@ export async function runEngine(opts: RunEngineOptions): Promise<void> {
   //    reads. Harness edits are emitted by the file watcher above, using actual
   //    file content as the source of truth instead of provider-specific tool
   //    metadata.
+  // Shared resolver - keep path <-> skill-id conversion in one place (see harness.ts).
   function skillMetaFromPath(resolved: string): { domain: string; topic: string } | null {
-    const rel = path.relative(opts.harnessDir, resolved).split(path.sep).join('/');
-    if (rel.startsWith('domain-skills/') && rel.endsWith('.md')) {
-      return { domain: 'domain', topic: rel.slice('domain-skills/'.length, -'.md'.length) };
-    }
-    if (rel.startsWith('interaction-skills/') && rel.endsWith('.md')) {
-      return { domain: 'interaction', topic: rel.slice('interaction-skills/'.length, -'.md'.length) };
-    }
-    if (rel.startsWith('skills/') && rel.endsWith('/SKILL.md')) {
-      return { domain: 'user', topic: rel.slice('skills/'.length, -'/SKILL.md'.length) };
-    }
-    return null;
+    return resolveSkillMetaFromPath(resolved, opts.harnessDir);
   }
 
   function skillMetaFromSkillId(id: string): { domain: string; topic: string } | null {

app/src/main/hl/harness.ts

@@ -65,6 +65,57 @@ export function browserHarnessJsDir(): string { return path.join(harnessDir(), '
 export function agentSkillDir(): string { return path.join(harnessDir(), 'agent-skill'); }
 export function userSkillsDir(): string { return path.join(harnessDir(), 'skills'); }
 
+/**
+ * Skill IDs are `<domain>/<topic>` strings (e.g. `user/fun/page-word-count`,
+ * `domain/github/repo`, `interaction/cookies`). The on-disk layout differs per
+ * domain - these helpers are the single source of truth for the conversion so
+ * the engine post-processor and any IPC handler stay aligned.
+ */
+export interface SkillId { domain: string; topic: string }
+
+function sanitizeSkillTopic(rawTopic: string): string | null {
+  const topic = rawTopic.replace(/\.md$/i, '').replace(/\\/g, '/');
+  if (!topic || topic.startsWith('/') || path.isAbsolute(rawTopic)) return null;
+  const segments = topic.split('/');
+  if (segments.some((segment) => !segment || segment === '.' || segment === '..' || /^[A-Za-z]:/.test(segment))) {
+    return null;
+  }
+  return segments.join('/');
+}
+
+export function skillPathFromMeta(meta: SkillId, rootDir: string = harnessDir()): string | null {
+  const topic = sanitizeSkillTopic(meta.topic);
+  if (!topic) return null;
+  if (meta.domain === 'user') return path.join(rootDir, 'skills', topic, 'SKILL.md');
+  if (meta.domain === 'domain') return path.join(rootDir, 'domain-skills', topic + '.md');
+  if (meta.domain === 'interaction') return path.join(rootDir, 'interaction-skills', topic + '.md');
+  return null;
+}
+
+export function skillMetaFromPath(resolved: string, rootDir: string = harnessDir()): SkillId | null {
+  const rel = path.relative(rootDir, resolved).split(path.sep).join('/');
+  if (rel.startsWith('domain-skills/') && rel.endsWith('.md')) {
+    return { domain: 'domain', topic: rel.slice('domain-skills/'.length, -'.md'.length) };
+  }
+  if (rel.startsWith('interaction-skills/') && rel.endsWith('.md')) {
+    return { domain: 'interaction', topic: rel.slice('interaction-skills/'.length, -'.md'.length) };
+  }
+  if (rel.startsWith('skills/') && rel.endsWith('/SKILL.md')) {
+    return { domain: 'user', topic: rel.slice('skills/'.length, -'/SKILL.md'.length) };
+  }
+  return null;
+}
+
+export function skillIdToPath(skillId: string, rootDir: string = harnessDir()): string | null {
+  const cleaned = skillId.trim().replace(/['"]+$/g, '').replace(/\\/g, '/');
+  if (!cleaned || cleaned.startsWith('--') || cleaned.startsWith('/') || path.isAbsolute(skillId)) return null;
+  const parts = cleaned.split('/');
+  if (parts.some((part) => !part)) return null;
+  if (parts.length < 2) return null;
+  const [domain, ...rest] = parts;
+  return skillPathFromMeta({ domain, topic: rest.join('/') }, rootDir);
+}
+
 /**
  * Ensure `<userData>/harness/` exists and contains the stock files.
  * - Writes helpers.js if missing OR if the on-disk version predates the

app/src/main/hl/stock/AGENTS.md

@@ -185,14 +185,36 @@ Verify after every meaningful browser action:
 For screenshots:
 
 ```bash
+# Internal screenshot (for your own vision — not shown to the user):
 browser-harness-js <<'EOF'
 await connectToAssignedTarget()
 const { data } = await session.Page.captureScreenshot({ format: 'png' })
-await Bun.write('/tmp/browser-use-shot.png', Buffer.from(data, 'base64'))
-return '/tmp/browser-use-shot.png'
+// inspect `data` (base64 PNG) however you need; do NOT save unless the user
+// explicitly asked to see the screenshot.
+EOF
+
+# User-facing screenshot (renders inline in the chat):
+browser-harness-js <<'EOF'
+await connectToAssignedTarget()
+const { data } = await session.Page.captureScreenshot({ format: 'png' })
+await Bun.write(`${process.env.BU_OUTPUTS_DIR}/screenshot-${Date.now()}.png`, Buffer.from(data, 'base64'))
 EOF
 ```
 
+**When a screenshot is worth showing the user:** save to `$BU_OUTPUTS_DIR` when
+the user genuinely benefits from seeing the page. Use your own judgment — these
+are guideposts, not rules:
+- Confirming a delegated task finished (a post went up, a message sent, a form
+  submitted, a checkout completed).
+- Mid-progress check-in on a long task, so the user knows you haven't stalled.
+- Something unexpected or interesting showed up that's worth flagging visually.
+- You're stuck on a captcha, login wall, or page state you can't resolve, and
+  showing it helps the user see what you see.
+
+Don't save screenshots you took purely to look at the page yourself (finding
+a selector, checking element state, verifying navigation) — those clutter the
+chat without giving the user new information.
+
 ## Uploads And Outputs
 
 - Uploads from the user appear under `./uploads/<session_id>/`.

app/src/main/hl/stock/agent-skill/agent-skill

@@ -292,7 +292,10 @@ function validateEntry(entry) {
   const errors = [];
   const warnings = [];
   if (!entry.title.trim()) errors.push('missing title');
-  if (!entry.description.trim() && !String(data.description || '').trim()) errors.push('missing description');
+  // Description MUST come from frontmatter - falling back to the first
+  // paragraph used to mask broken skills and surface raw markdown (H2 hooks,
+  // code fences) anywhere the description was rendered.
+  if (!String(data.description || '').trim()) errors.push('missing frontmatter description (add `description: ...` to the front-matter block)');
   if (entry.bytes > 100_000) warnings.push('skill is large; move examples/templates/scripts into support files');
   if (!/(^|\n)#{1,3}\s+/m.test(entry.content)) warnings.push('no markdown section headings found');
   if (!/(when|use|run|step|verify|check|done|success)/i.test(entry.content)) {