dsh-browser-plus 0.5.0 → 0.5.1

package/lib/browser-electron/entry.js

@@ -30,7 +30,7 @@ export const Config = z.object({
     // meaning "the documented defaults" while an explicit [] still denies all.
     writeRoots: z.array(z.string()).default(defaultWriteRoots()),
     readRoots: z.array(z.string()).default(defaultWriteRoots()),
-    chromeWorld: z.union(['main', 'isolated']).default('main'),
+    chromeWorld: z.union(['main', 'isolated']).default('isolated'),
     userAgent: z.string(),
     maskAutomation: z.boolean().default(true),
 });
@@ -40,7 +40,10 @@ export function apply(ctx, config) {
     // child is disposed with the fiber, mirroring the shell's lifetime.
     const host = config.viewHost
         ?? new RemoteElectronViewHost(defaultHostMainPath(), {
-            chromeWorld: config.chromeWorld,
+            // `?? 'isolated'` 不只是为了类型：入口可能拿到**未经 schema 解析**的配置
+            // （测试探针、其它调用方直接调 apply），那时缺省值不会自动出现，
+            // 而 remote-host 把 undefined 当成「不加 --chrome-world」→ 子进程退回 main ✗。
+            chromeWorld: config.chromeWorld ?? 'isolated',
             maskAutomation: config.maskAutomation,
             ...config.userAgent === undefined ? {} : { userAgent: config.userAgent },
         });

package/lib/browser-electron/host-main.d.ts

@@ -9,7 +9,8 @@
  *   <- { id, op: 'ping' } | { id, op: 'createView', viewId, key?, label? } |
  *      { id, op: 'destroyView', viewId } | { id, op: 'showView', viewId } |
  *      { id, op: 'label', viewId, label } | { id, op: 'listWindows' } |
- *      { id, op: 'command', viewId, method, params }
+ *      { id, op: 'command', viewId, method, params } |
+ *      { id, op: 'printToPdf', viewId, options }
  *   -> { id, ok: true, result? } | { id, ok: false, err }
  *
  * The parent never parses stderr, so diagnostics may go there freely.

package/lib/browser-electron/host-main.js

@@ -9,7 +9,8 @@
  *   <- { id, op: 'ping' } | { id, op: 'createView', viewId, key?, label? } |
  *      { id, op: 'destroyView', viewId } | { id, op: 'showView', viewId } |
  *      { id, op: 'label', viewId, label } | { id, op: 'listWindows' } |
- *      { id, op: 'command', viewId, method, params }
+ *      { id, op: 'command', viewId, method, params } |
+ *      { id, op: 'printToPdf', viewId, options }
  *   -> { id, ok: true, result? } | { id, ok: false, err }
  *
  * The parent never parses stderr, so diagnostics may go there freely.
@@ -265,6 +266,12 @@ function saveBookmarksToDisk() {
  * would silently reset the moment the user visited another site.
  */
 let chromeBookmarkBar = false;
+/**
+ * Where the human parked the floating orb. Remembered in the chrome prefs file
+ * rather than in the page: a page-side position is per ORIGIN and would jump
+ * back to the corner on the next site.
+ */
+let chromeOrbPosition;
 let chromePrefsFile;
 function loadPrefsFromDisk() {
     try {
@@ -273,6 +280,13 @@ function loadPrefsFromDisk() {
         if (typeof parsed !== 'object' || parsed === null)
             return;
         chromeBookmarkBar = parsed.bookmarkBar === true;
+        const orb = parsed.orbPosition;
+        if (typeof orb === 'object' && orb !== null) {
+            const { x, y } = orb;
+            if (typeof x === 'number' && typeof y === 'number' && Number.isFinite(x) && Number.isFinite(y)) {
+                chromeOrbPosition = { x: Math.round(x), y: Math.round(y) };
+            }
+        }
     }
     catch { /* first run, or an unreadable file */ }
 }
@@ -280,7 +294,10 @@ function savePrefsToDisk() {
     if (chromePrefsFile === undefined)
         return;
     try {
-        writeFileSync(chromePrefsFile, JSON.stringify({ bookmarkBar: chromeBookmarkBar }, null, 2), 'utf8');
+        writeFileSync(chromePrefsFile, JSON.stringify({
+            bookmarkBar: chromeBookmarkBar,
+            ...chromeOrbPosition !== undefined ? { orbPosition: chromeOrbPosition } : {},
+        }, null, 2), 'utf8');
     }
     catch { /* read-only profile */ }
 }
@@ -484,6 +501,13 @@ const taskViewIds = new Map();
 const taskThumbnails = new Map();
 const taskThumbnailVersions = new Map();
 const taskStates = new Map();
+/**
+ * The Agent's todo list per task, mirrored from the DSH session projection by the
+ * parent (see `setTaskTodos`). Kept here so the visible surface can be handed the
+ * current plan the moment it becomes visible — the list itself never rides in a
+ * task summary, because summaries reach every page's main world.
+ */
+const taskTodos = new Map();
 const thumbnailTimers = new Map();
 const thumbnailDirty = new Set();
 let thumbnailCaptureInFlight = false;
@@ -574,6 +598,17 @@ function makeWindow() {
  * the page and swallow clicks in the top 84px (the chrome is drawn there today).
  */
 const CHROME_FRAME_HEIGHT = 84;
+/** Height of the bookmark bar when it is shown. It becomes part of the chrome frame. */
+const BOOKMARK_BAR_HEIGHT = 34;
+/**
+ * How tall the chrome frame is right now: tab strip + toolbar, plus the bookmark
+ * bar when it is on. The page view starts below ALL of it, so a site's
+ * `position: fixed` header can never end up hidden under the bar — the same
+ * reason the toolbar itself lives in a view instead of a page padding.
+ */
+function chromeFrameHeight() {
+    return CHROME_FRAME_HEIGHT + (chromeBookmarkBar ? BOOKMARK_BAR_HEIGHT : 0);
+}
 let chromeFrame;
 /** Why the frame view could not be created, if it could not. Published to the chrome. */
 let chromeFrameError = '';
@@ -689,8 +724,22 @@ function handleChromeAction(view, viewId, chromeToken, params) {
                 workspacePanels = { tasks: action.tasks, trail: action.trail };
                 if (workspacePanels.tasks && visibleTaskKey !== undefined)
                     scheduleVisibleTaskThumbnail(visibleTaskKey);
+                // Opening the panel is the moment the other rows become visible, so hand
+                // the surface every image we already have for them.
+                if (workspacePanels.tasks) {
+                    pushCachedTaskThumbnails();
+                    pushCachedTaskTodos();
+                }
                 queueChromePatch({ op: 'panels.set', panels: workspacePanels });
             }
+            else if (action.type === 'orb-move'
+                && typeof action.x === 'number'
+                && typeof action.y === 'number'
+                && Number.isFinite(action.x)
+                && Number.isFinite(action.y)) {
+                chromeOrbPosition = { x: Math.round(action.x), y: Math.round(action.y) };
+                savePrefsToDisk();
+            }
             else if (action.type === 'set-control-owner'
                 && typeof action.taskKey === 'string'
                 && (action.control === 'agent' || action.control === 'human')
@@ -721,6 +770,9 @@ function handleChromeAction(view, viewId, chromeToken, params) {
                 // The bar is a profile-wide preference, so the host owns it and the
                 // chrome reads it back from the bootstrap / patch stream.
                 chromeBookmarkBar = action.visible;
+                // 书签栏现在占的是帧视图的高度，所以开关一变就得重排：
+                // 只发 patch 的话，帧还是 84px 高、页面视图还从 84 开始 —— 书签栏就会压住页面。
+                layoutViews();
                 savePrefsToDisk();
                 queueChromePatch({ op: 'bookmarkbar.set', visible: chromeBookmarkBar });
             }
@@ -920,7 +972,7 @@ function ensureChromeFrame() {
         }
         catch { /* already attached */ }
         win.contentView.addChildView(frame);
-        frame.setBounds({ x: 0, y: 0, width: win.getContentSize()[0] ?? 0, height: CHROME_FRAME_HEIGHT });
+        frame.setBounds({ x: 0, y: 0, width: win.getContentSize()[0] ?? 0, height: chromeFrameHeight() });
         // HIDDEN until the frame's chrome can drive the page. A visible frame sits on
         // top of the page view, so a person's clicks land on it — and the frame's
         // chrome can only do the things it can do *in its own document* today: its
@@ -974,11 +1026,12 @@ function layoutViews() {
         try {
             // Below the chrome frame: the page viewport is genuinely smaller now, so a
             // sticky/fixed header lands at the top of the page instead of under the chrome.
+            const frameHeight = chromeFrameHeight();
             entry.webContentsView.setBounds({
                 x: 0,
-                y: CHROME_FRAME_HEIGHT,
+                y: frameHeight,
                 width: width ?? 0,
-                height: Math.max(0, (height ?? 0) - CHROME_FRAME_HEIGHT),
+                height: Math.max(0, (height ?? 0) - frameHeight),
             });
         }
         catch { /* destroyed */ }
@@ -998,7 +1051,7 @@ function raiseChromeFrame() {
     catch { /* not attached */ }
     try {
         win.contentView.addChildView(chromeFrame);
-        chromeFrame.setBounds({ x: 0, y: 0, width: win.getContentSize()[0] ?? 0, height: CHROME_FRAME_HEIGHT });
+        chromeFrame.setBounds({ x: 0, y: 0, width: win.getContentSize()[0] ?? 0, height: chromeFrameHeight() });
     }
     catch { /* destroyed */ }
 }
@@ -1297,6 +1350,7 @@ function chromeWorkspaceState(selectedTaskKey = visibleTaskKey) {
         trail: activeTraceForTask(selectedTaskKey),
         bookmarks: chromeBookmarks,
         bookmarkBar: chromeBookmarkBar,
+        ...chromeOrbPosition !== undefined ? { orbPosition: chromeOrbPosition } : {},
         frameError: chromeFrameError,
         windowProbe: (() => {
             const win = window;
@@ -1329,7 +1383,10 @@ function chromeBootstrapScript(selectedTaskKey = visibleTaskKey) {
 function chromePatchScript(operations) {
     const patch = createPatch(chromeEpoch, ++chromeRevision, operations);
     return ';window.__dshChromePatch = ' + JSON.stringify(patch)
-        + ';try { window.__dshChromeApply?.(window.__dshChromePatch) } catch {}';
+        + ';try { window.__dshChromeApply?.(window.__dshChromePatch) } catch {}'
+        // 补丁里含 Agent 的计划（task.todos），而默认主世界下页面脚本读得到 window ——
+        // 应用完立刻把这份明文抹掉，别让它一直挂在页面上。
+        + ';try { delete window.__dshChromePatch } catch { window.__dshChromePatch = undefined }';
 }
 function resetChromeDelivery() {
     chromeEpoch += 1;
@@ -1425,6 +1482,51 @@ function queueFrameAddress() {
         url = '';
     runChromeScript(frame, `window.__dshChromeAddress && window.__dshChromeAddress(${JSON.stringify(url)})`);
 }
+/**
+ * Replay every task's last known image to the visible surface.
+ *
+ * A task's picture never travels in the task summaries: those are injected into
+ * every visited page's main world, and the picture is screen content. So a
+ * chrome surface only ever learns an image from a targeted 'task.thumbnail'
+ * patch, and the capture path queues those for the VISIBLE task alone. Without
+ * this replay, the surface that shows the panel paints its own task's image and
+ * a placeholder for every other one — even for tasks the human already looked
+ * at, which is exactly what the panel looked like before this existed.
+ *
+ * Safe by construction: the patches go to {@link chromeSurfaces}, i.e. the
+ * visible task's page and the chrome frame, which are the only surfaces that
+ * can show the panel in the first place.
+ */
+/** Store one task's plan and push it to the surface that shows the panel. */
+function updateTaskTodos(key, todos) {
+    if (!Array.isArray(todos))
+        return;
+    const clean = [];
+    for (const item of todos) {
+        const entry = item;
+        if (typeof entry?.content !== 'string' || entry.content === '')
+            continue;
+        const status = entry.status === 'completed' || entry.status === 'in_progress' ? entry.status : 'pending';
+        clean.push({ content: entry.content.slice(0, 160), status });
+        if (clean.length >= 40)
+            break;
+    }
+    taskTodos.set(key, clean);
+    queueChromePatch({ op: 'task.todos', key, todos: clean });
+}
+/**
+ * Hand every known plan to the visible surface. The orb is always on screen, so
+ * a surface that has just become visible has never seen any of them.
+ */
+function pushCachedTaskTodos() {
+    for (const [key, todos] of taskTodos)
+        queueChromePatch({ op: 'task.todos', key, todos });
+}
+function pushCachedTaskThumbnails() {
+    for (const [key, dataUrl] of taskThumbnails) {
+        queueChromePatch({ op: 'task.thumbnail', key, version: taskThumbnailVersions.get(key) ?? 0, dataUrl });
+    }
+}
 function scheduleVisibleTaskThumbnail(taskKey, delayMs = 360) {
     if (taskKey !== visibleTaskKey)
         return;
@@ -1525,6 +1627,10 @@ function switchVisibleTask(taskKey) {
     // changed with it. Queued after the bootstrap: resetChromeDelivery() inside
     // pushVisibleChromeState() drops anything queued before it.
     queueTabsSet();
+    // 新露出来的那个表面此前没收到过别的任务的图像（补丁只发给可见表面），所以把
+    // 宿主手里已有的图都补给它 —— 否则切过去之后面板里除了当前任务全是占位符。
+    pushCachedTaskThumbnails();
+    pushCachedTaskTodos();
     // 必须在 pushVisibleChromeState() **之后**排队：它里面的 resetChromeDelivery() 会把
     // 先排的东西丢掉（切标签就是走这条路）。导航走 applyPageChrome，不会播。
     queueChromePatch({ op: 'reveal' });
@@ -1609,6 +1715,10 @@ function applyPageChrome(view, viewId) {
         // (whose own chrome is not on screen but whose title belongs in the strip).
         queueTabsSet();
         scheduleVisibleTaskThumbnail(taskKey, 550);
+        // 每一次真导航都会重跑整个 chrome 脚本，页面侧那份 todo 缓存跟着归零。
+        // 缩略图有 scheduleVisibleTaskThumbnail 兜住，计划没有对应物 —— 漏了它，
+        // Agent 一导航球上就只剩状态圆点（这是本轮功能的卖点场景，必现）。
+        pushCachedTaskTodos();
     }
 }
 /** Install human browser chrome without creating or reparenting a child view. */
@@ -1706,6 +1816,7 @@ async function handle(op, msg) {
                         if (trail !== undefined)
                             operations.push({ op: 'trail.append', taskKey: entryView.taskKey, entry: trail });
                         scheduleVisibleTaskThumbnail(entryView.taskKey);
+                        pushCachedTaskTodos();
                     }
                     if (operations.length > 0)
                         queueChromePatch(...operations);
@@ -2015,6 +2126,7 @@ async function handle(op, msg) {
                             clearTimeout(thumbnailTimer);
                         thumbnailTimers.delete(entry.taskKey);
                         taskThumbnails.delete(entry.taskKey);
+                        taskTodos.delete(entry.taskKey);
                         taskThumbnailVersions.delete(entry.taskKey);
                         thumbnailDirty.delete(entry.taskKey);
                         thumbnailLastCapturedAt.delete(entry.taskKey);
@@ -2093,8 +2205,16 @@ async function handle(op, msg) {
                     frame.webContents.debugger.attach('1.3');
                 }
                 catch { /* already attached */ }
+                // 隔离模式（默认）下，帧里的 chrome 也住在它自己的世界 —— 读它必须带上下文，
+                // 否则读的是帧的主世界（那里什么都没有）。
+                const frameContextId = CHROME_WORLD === 'isolated' ? await ensureChromeContext(frame) : undefined;
                 frame.webContents.debugger
-                    .sendCommand('Runtime.evaluate', { expression, returnByValue: true, awaitPromise: true })
+                    .sendCommand('Runtime.evaluate', {
+                    expression,
+                    returnByValue: true,
+                    awaitPromise: true,
+                    ...frameContextId === undefined ? {} : { contextId: frameContextId },
+                })
                     .then((result) => {
                     // The client resolves with `msg.result`, so the value goes in there.
                     const value = result?.result?.value;
@@ -2126,6 +2246,31 @@ async function handle(op, msg) {
                 reply(msg.id, { ok: true });
                 return;
             }
+            case 'focusWindow': {
+                const viewId = msg.viewId;
+                if (viewId === undefined)
+                    throw new Error('focusWindow missing viewId');
+                if (!views.has(viewId))
+                    throw new Error(`focusWindow: unknown view ${viewId}`);
+                const win = ensureWindow();
+                // The same three steps capture uses: a minimized window has to be
+                // restored, and a window behind another one only comes forward on focus.
+                try {
+                    if (!win.isVisible())
+                        win.show();
+                }
+                catch { /* closing */ }
+                try {
+                    win.restore();
+                }
+                catch { /* not minimized */ }
+                try {
+                    win.focus();
+                }
+                catch { /* closing */ }
+                reply(msg.id, { ok: true });
+                return;
+            }
             case 'label': {
                 const viewId = msg.viewId;
                 const label = msg.label;
@@ -2173,6 +2318,14 @@ async function handle(op, msg) {
                 reply(msg.id, { ok: true, result: { task: task ?? null } });
                 return;
             }
+            case 'setTaskTodos': {
+                const key = msg.key;
+                if (typeof key !== 'string' || msg.todos === undefined)
+                    throw new Error('setTaskTodos missing key or todos');
+                updateTaskTodos(key, msg.todos);
+                reply(msg.id, { ok: true, result: {} });
+                return;
+            }
             case 'updateTask': {
                 const key = msg.key;
                 if (typeof key !== 'string' || msg.task === undefined)
@@ -2198,6 +2351,31 @@ async function handle(op, msg) {
                 reply(msg.id, { ok: true, result });
                 return;
             }
+            case 'chromeWorldEval': {
+                // Run a snippet in the world the *page's* injected chrome lives in.
+                //
+                // In isolated mode the chrome's globals are not reachable from the page
+                // world, and creating a world with the same name from outside yields a
+                // different, empty context — so the host, which owns the real one, has to
+                // resolve it here. In main mode this is a plain page-world evaluate.
+                const viewId = msg.viewId;
+                if (viewId === undefined)
+                    throw new Error('chromeWorldEval missing viewId');
+                const entry = views.get(viewId);
+                if (entry === undefined)
+                    throw new Error(`chromeWorldEval: unknown view ${viewId}`);
+                if (typeof msg.expression !== 'string')
+                    throw new Error('chromeWorldEval missing expression');
+                const contextId = CHROME_WORLD === 'isolated' ? await ensureChromeContext(entry.webContentsView) : undefined;
+                const result = await entry.webContentsView.webContents.debugger.sendCommand('Runtime.evaluate', {
+                    expression: msg.expression,
+                    returnByValue: true,
+                    awaitPromise: true,
+                    ...contextId === undefined ? {} : { contextId },
+                });
+                reply(msg.id, { ok: true, result });
+                return;
+            }
             case 'capture': {
                 const viewId = msg.viewId;
                 if (viewId === undefined)
@@ -2289,6 +2467,25 @@ async function handle(op, msg) {
                 reply(msg.id, { ok: true, result: { base64, width: 0, height: 0 } });
                 return;
             }
+            case 'printToPdf': {
+                const viewId = msg.viewId;
+                if (viewId === undefined)
+                    throw new Error('printToPdf missing viewId');
+                const entry = views.get(viewId);
+                if (entry === undefined)
+                    throw new Error(`printToPdf: unknown view ${viewId}`);
+                // Electron's debugger does not implement CDP `Page.printToPDF`; this
+                // native path is the one that actually produces a document.
+                const options = (msg.options ?? {});
+                // `printToPDF` and its option type are Electron's; Electron is an optional
+                // dependency (CI installs with --omit=optional, so neither the type nor the
+                // `Electron` namespace exists there). Name the shape locally instead of
+                // reaching for the namespace, and let this child — which only ever runs
+                // inside Electron — be the one that calls it.
+                const data = await entry.webContentsView.webContents.printToPDF(options);
+                reply(msg.id, { ok: true, result: { base64: data.toString('base64') } });
+                return;
+            }
             case 'download': {
                 const viewId = msg.viewId;
                 const url = msg.url;